Run local usage services in a supervised backend process (#40792)

* Move local usage services into a supervised backend process

* Own usage recovery and worker retirement lifetimes

* Preserve answered usage data during background refresh

* Run independent usage scans concurrently in the backend

* Limit backend startup paths to the delegated usage service

* Show usage failures through backend recovery

* Include usage failure strings in the English catalog

* Keep usage update details beside refresh failures

* Resolve usage freshness failure from the final producer snapshot

* Retain the forced refresh completion requirement

* Keep managed backend failures out of application crash reports

* Preserve usage recovery boundaries across backend reconnects

* Match the backend RPC cancellation signal in the usage seam proof

* Avoid serializing backend requests before port delivery

* Keep receiving request validation in the boundary schemas

* test: align usage transport coverage with renderer project

* fix: preserve unknown usage state and renderer retirement

* fix(usage): revalidate tracking before scan admission

* fix(usage): retry failed backend startup on demand

* test(usage): isolate stale backend ownership checks
This commit is contained in:
Brennan Benson
2026-11-11 16:39:52 -08:00
committed by GitHub
parent 890ad4d8aa
commit 175f10e32b
85 changed files with 4898 additions and 789 deletions
+96
View File
@@ -0,0 +1,96 @@
import { MessageChannel, type MessagePort } from 'node:worker_threads'
import { afterEach, expect, it, vi } from 'vitest'
import { BackendPortRpc, type BackendPort } from './backend-port-rpc'
const connections: BackendPortRpc[] = []
const ports: MessagePort[] = []
function adapt(port: MessagePort): BackendPort {
ports.push(port)
return {
postMessage: (message) => port.postMessage(message),
onMessage(listener) {
port.on('message', listener)
return () => {
port.off('message', listener)
}
},
onClose(listener) {
port.on('close', listener)
return () => {
port.off('close', listener)
}
},
close: () => port.close()
}
}
function pair(invoke: (method: string, params: unknown, signal: AbortSignal) => Promise<unknown>) {
const channel = new MessageChannel()
const server = new BackendPortRpc(adapt(channel.port1), 'backend-1', invoke)
const client = new BackendPortRpc(adapt(channel.port2), 'renderer-1', async () => null)
connections.push(server, client)
return { client, server }
}
afterEach(() => {
connections.splice(0).forEach((connection) => connection.close())
ports.splice(0).forEach((port) => port.close())
})
it('transfers a report directly and rejects outstanding calls on document disconnect', async () => {
const started = Promise.withResolvers<AbortSignal>()
const release = Promise.withResolvers<unknown>()
const { client, server } = pair(async (method, params, signal) => {
if (method === 'snapshot') {
return { summary: { inputTokens: 123 }, selection: params }
}
started.resolve(signal)
return release.promise
})
await expect(client.call('snapshot', { range: '30d' })).resolves.toEqual({
summary: { inputTokens: 123 },
selection: { range: '30d' }
})
const pending = client.call('refresh')
const rejected = expect(pending).rejects.toThrow()
const signal = await started.promise
server.close()
await rejected
expect(signal.aborted).toBe(true)
release.resolve(null)
})
it('bounds pending requests and admits the next request after consumption', async () => {
{
const release = Promise.withResolvers<void>()
const { client, server } = pair(async () => {
await release.promise
return { inputTokens: 123 }
})
const calls = Array.from({ length: 32 }, () => client.call('snapshot'))
await expect(client.call('snapshot')).rejects.toThrow()
release.resolve()
expect(await Promise.all(calls)).toEqual(
Array.from({ length: 32 }, () => ({ inputTokens: 123 }))
)
await expect(client.call('snapshot')).resolves.toEqual({ inputTokens: 123 })
client.close()
server.close()
}
})
it('does not let an early acknowledgement bypass the in-flight request bound', async () => {
const channel = new MessageChannel()
const pending = Promise.withResolvers<unknown>()
const invoked = Promise.withResolvers<void>()
const disconnected = Promise.withResolvers<void>()
const invoke = vi.fn(async () => {
invoked.resolve()
return pending.promise
})
connections.push(
new BackendPortRpc(adapt(channel.port1), 'backend-1', invoke, () => disconnected.resolve())
)
ports.push(channel.port2)
channel.port2.postMessage({ id: '1', method: 'refresh' })
await invoked.promise
channel.port2.postMessage({ ack: '1' })
await disconnected.promise
expect(invoke).toHaveBeenCalledTimes(1)
pending.resolve(null)
})
+153
View File
@@ -0,0 +1,153 @@
import { BackendRequestSchema } from './backend-service-contract'
import { RuntimeRpcEnvelopeSchema } from './runtime-rpc-envelope'
export type BackendPort = {
postMessage(message: unknown): void
onMessage(listener: (message: unknown) => void): () => void
onClose(listener: () => void): () => void
close(): void
}
type Pending = { resolve(value: unknown): void; reject(error: Error): void }
const MAX_REQUESTS = 32
/** Responses retain a credit until consumed, bounding a slow document's native port queue. */
export class BackendPortRpc {
private readonly pending = new Map<string, Pending>()
private readonly admitted = new Map<string, boolean>()
private readonly lifetime = new AbortController()
private nextId = 1
private closed = false
private readonly detach: (() => void)[]
constructor(
private readonly port: BackendPort,
private readonly incarnation: string,
private readonly invoke: (
method: string,
params: unknown,
signal: AbortSignal
) => Promise<unknown>,
private readonly onDisconnect: () => void = () => {}
) {
this.detach = [
port.onMessage((message) => {
void this.receive(message).catch(() => this.close())
}),
port.onClose(() => this.close())
]
}
call(method: string, params?: unknown): Promise<unknown> {
if (this.closed) {
return Promise.reject(new Error('Orca disconnected. Try again after it reconnects.'))
}
if (this.pending.size >= MAX_REQUESTS) {
return Promise.reject(
new Error('Too many usage requests. Try again when the current requests finish.')
)
}
const id = String(this.nextId++)
return new Promise((resolve, reject) => {
this.pending.set(id, { resolve, reject })
try {
const request = { id, method, params }
this.port.postMessage(request)
} catch (error) {
this.pending.delete(id)
reject(error instanceof Error ? error : new Error(String(error)))
}
})
}
close(): void {
if (this.closed) {
return
}
this.closed = true
this.lifetime.abort()
for (const detach of this.detach) {
detach()
}
this.port.close()
for (const call of this.pending.values()) {
call.reject(new Error('Orca disconnected. Try again after it reconnects.'))
}
this.pending.clear()
this.admitted.clear()
this.onDisconnect()
}
private async receive(message: unknown): Promise<void> {
if (this.closed) {
return
}
if (
message &&
typeof message === 'object' &&
'ack' in message &&
typeof message.ack === 'string'
) {
if (this.admitted.get(message.ack) !== true) {
this.close()
return
}
this.admitted.delete(message.ack)
return
}
const response = RuntimeRpcEnvelopeSchema.safeParse(message)
if (response.success && !('_keepalive' in response.data)) {
const reply = response.data
const call = this.pending.get(reply.id)
if (!call) {
return
}
this.pending.delete(reply.id)
this.port.postMessage({ ack: reply.id })
if (reply.ok) {
call.resolve(reply.result)
} else {
call.reject(Object.assign(new Error(reply.error.message), { code: reply.error.code }))
}
return
}
const parsed = BackendRequestSchema.safeParse(message)
if (
!parsed.success ||
this.admitted.size >= MAX_REQUESTS ||
this.admitted.has(parsed.data.id)
) {
this.close()
return
}
const request = parsed.data
this.admitted.set(request.id, false)
let reply
try {
reply = {
id: request.id,
ok: true,
result: await this.invoke(request.method, request.params, this.lifetime.signal),
_meta: { runtimeId: this.incarnation }
}
} catch (error) {
reply = {
id: request.id,
ok: false,
error: {
code: 'runtime_error',
message: error instanceof Error ? error.message : 'Usage operation failed. Try again.'
},
_meta: { runtimeId: this.incarnation }
}
}
if (!this.closed) {
try {
this.admitted.set(request.id, true)
this.port.postMessage(reply)
} catch {
this.close()
}
}
}
}
+75
View File
@@ -0,0 +1,75 @@
import { z } from 'zod'
import type { RuntimeRpcResponse } from './runtime-rpc-envelope'
import type { AutomationRunUsage } from './automations/history/automation-run'
export const BACKEND_PORT_REQUEST = 'backend:connect'
export const BACKEND_PORT_DELIVERY = 'backend:port'
export const BACKEND_CONNECTION_CHANGED = 'backend:connectionChanged'
export const BACKEND_UTILITY_PROCESS_NAME = 'Orca backend'
export type BackendConnectionPurpose = 'demand' | 'recovery'
export type BackendConnectionStatus = { connected: boolean; unavailable?: boolean }
export type BackendConnectionDetail = { initial?: boolean; unavailable?: boolean }
export type BackendConnectionListener = (
connected: boolean,
detail?: BackendConnectionDetail
) => void
export const UsageProviderSchema = z.enum([
'claudeUsage',
'codexUsage',
'openCodeUsage',
'museUsage'
])
export type UsageProviderKey = z.infer<typeof UsageProviderSchema>
export const UsageActionSchema = z.enum([
'getScanState',
'setEnabled',
'refresh',
'getSnapshot',
'getSummary',
'getDaily',
'getBreakdown',
'getRecentSessions'
])
export type UsageAction = z.infer<typeof UsageActionSchema>
export type BackendResponse = RuntimeRpcResponse<unknown>
export const BackendBootstrapSchema = z
.object({
protocol: z.literal(1),
requiredCapabilities: z.array(z.string().max(128)).max(32),
services: z.tuple([z.literal('usage')]),
build: z.string().max(256),
paths: z.object({
userData: z.string().min(1)
}),
appPath: z.string().min(1),
isPackaged: z.boolean()
})
.strip()
export type BackendBootstrap = z.infer<typeof BackendBootstrapSchema>
export const BACKEND_CAPABILITIES = [
'usage',
'usage.catalog',
'usage.claudeProfileDirs',
'usage.telemetry'
] as const
export const BackendRequestSchema = z
.object({
id: z.string().min(1).max(128),
method: z.string().min(1).max(128),
params: z.unknown().optional()
})
.strip()
export type AutomationUsageInput = {
worktreeId: string | null
terminalSessionId: string | null
startedAt: number | null
completedAt: number | null
}
export type AutomationUsageClient = {
getAutomationRunUsage(input: AutomationUsageInput): Promise<AutomationRunUsage>
}