@crosshands/runtime 0.1.5 → 0.2.0

package/src/broker/broker.ts

@@ -13,6 +13,18 @@ import {
   type TargetReference
 } from '@crosshands/contract'
 
+import {
+  DIAGNOSTIC_RECORD_VERSION,
+  diagnosticError,
+  diagnosticPlatform,
+  diagnosticRequestResult,
+  diagnosticTarget,
+  emitDiagnostic,
+  type DiagnosticEnvelope,
+  type DiagnosticRecord,
+  type DiagnosticsSink
+} from '../diagnostics/record.js'
+import { graphicalSessionKey } from '../ipc/endpoint.js'
 import { assertAppAllowed, type StableAppIdentity } from '../policy/policy.js'
 import { ProviderSupervisor } from '../providers/supervisor.js'
 
@@ -51,6 +63,7 @@ export type LocalBrokerOptions = {
     input: unknown
   ) => Promise<TargetInspection | null>
   publish?: (response: BrokerResponse) => Promise<void>
+  diagnostics?: DiagnosticsSink
   contextTtlMs?: number
   now?: () => number
 }
@@ -73,10 +86,6 @@ class SerialQueue {
   }
 }
 
-function isMutation(operation: ComputerOperationName): boolean {
-  return COMPUTER_OPERATIONS[operation].mutation
-}
-
 function assertedInputApp(input: unknown): void {
   if (input === null || typeof input !== 'object') return
   const app = (input as { app?: unknown }).app
@@ -169,6 +178,31 @@ function contextToken(input: unknown): string | undefined {
   return typeof token === 'string' ? token : undefined
 }
 
+function observationApp(input: unknown): string | undefined {
+  if (input === null || typeof input !== 'object') return undefined
+  const app = (input as Record<string, unknown>).app
+  return typeof app === 'string' && app.length > 0 ? app : undefined
+}
+
+function bindGetAppStateInput(
+  input: unknown,
+  resolve: (token: string) => InteractionContext
+): unknown {
+  if (input === null || typeof input !== 'object') return input
+  const record = input as Record<string, unknown>
+  const token = contextToken(record)
+  if (token === undefined || observationApp(record) !== undefined) return input
+  const context = resolve(token)
+  return {
+    app: context.appId,
+    window: { id: context.window.id },
+    ...(typeof record.captureScreenshot === 'boolean'
+      ? { captureScreenshot: record.captureScreenshot }
+      : {}),
+    ...(typeof record.restoreWindow === 'boolean' ? { restoreWindow: record.restoreWindow } : {})
+  }
+}
+
 function computerError(cause: unknown): { code?: string; message: string; toJSON?: () => unknown } {
   if (cause instanceof Error) return cause
   return { message: 'Unknown provider failure' }
@@ -225,21 +259,26 @@ export class BrokerClient {
 export class LocalBroker {
   readonly generation: string
   readonly #identity: BrokerPeer
+  readonly #session: string
   readonly #supervisor: ProviderSupervisor
   readonly #contexts: InteractionContextStore
   readonly #inspectTarget: LocalBrokerOptions['inspectTarget']
   readonly #publish: LocalBrokerOptions['publish']
+  readonly #diagnostics: DiagnosticsSink | undefined
   readonly #now: () => number
   readonly #queue = new SerialQueue()
   #desktopEpoch = 0
   #requestSequence = 0
+  #closed = false
 
   constructor(options: LocalBrokerOptions) {
     this.generation = options.generation ?? `broker-${randomUUID()}`
     this.#identity = options.identity
+    this.#session = graphicalSessionKey(options.identity.graphicalSessionId)
     this.#inspectTarget = options.inspectTarget
     this.#publish = options.publish
     this.#now = options.now ?? Date.now
+    this.#diagnostics = options.diagnostics
     this.#contexts = new InteractionContextStore({
       ...(options.contextTtlMs === undefined ? {} : { ttlMs: options.contextTtlMs }),
       now: this.#now
@@ -254,6 +293,20 @@ export class LocalBroker {
     return this.#desktopEpoch
   }
 
+  diagnosticEnvelope(): DiagnosticEnvelope {
+    return {
+      v: DIAGNOSTIC_RECORD_VERSION,
+      ts: new Date(this.#now()).toISOString(),
+      session: this.#session,
+      brokerGeneration: this.generation,
+      ...(this.#supervisor.generation === undefined
+        ? {}
+        : { providerGeneration: this.#supervisor.generation }),
+      desktopEpoch: this.#desktopEpoch,
+      platform: diagnosticPlatform()
+    }
+  }
+
   async connect(handshake: {
     peer: BrokerPeer
     versions: ContractVersions
@@ -274,9 +327,18 @@ export class LocalBroker {
     const versions = negotiateVersionHandshake(handshake.versions)
     if (!versions.ok) throw versions.error
     await this.#supervisor.start()
+    this.#emit({ kind: 'helper.start', ...this.diagnosticEnvelope() })
     return new BrokerClient(this)
   }
 
+  async close(reason = 'closed'): Promise<void> {
+    if (this.#closed) return
+    this.#closed = true
+    await this.#supervisor.close()
+    this.#emit({ kind: 'broker.stop', reason, ...this.diagnosticEnvelope() })
+    await this.#diagnostics?.close()
+  }
+
   issueContext(bindings: ReferenceBindings): InteractionContext {
     return this.#contexts.issue({
       ...bindings,
@@ -292,59 +354,78 @@ export class LocalBroker {
   }
 
   request(request: BrokerRequest): Promise<BrokerResponse> {
-    return this.#queue.run(() => this.#requestLocked(request))
+    const enqueuedAt = this.#now()
+    return this.#queue.run(() => this.#requestLocked(request, enqueuedAt))
   }
 
-  async #requestLocked(request: BrokerRequest): Promise<BrokerResponse> {
+  async #requestLocked(request: BrokerRequest, enqueuedAt: number): Promise<BrokerResponse> {
+    const startedAt = this.#now()
     const requestId = `broker-${++this.#requestSequence}`
     const deadlineAt = this.#now() + (request.deadlineMs ?? 30_000)
-    const mutation = isMutation(request.operation)
-    assertedInputApp(request.input)
-    let context: InteractionContext | undefined
-    let inspectionInput = request.input
-    if (mutation) {
-      const token = contextToken(request.input)
-      if (token === undefined) {
-        throw createComputerError(
-          'invalid_argument',
-          'Mutation requires a context token and target'
-        )
-      }
-      context = this.#contexts.resolve(token)
-      // Context-window and index shorthand do not carry an identity until the
-      // broker binds them. Inspect the bound form so native providers can
-      // re-resolve the exact process/window before dispatch.
-      inspectionInput = normalizeMutationInput(request.input, context, context)
+    const mutation = COMPUTER_OPERATIONS[request.operation].mutation
+    let inspectMs = 0
+    let dispatchMs = 0
+    let bindings: ReferenceBindings | undefined
+    let dispatched: boolean | undefined
+    let result: unknown
+    let cause: unknown
+    let input = request.input
+    if (request.operation === 'getAppState') {
+      input = bindGetAppStateInput(input, (token) => this.#contexts.resolve(token))
     }
-    const inspection = await this.#inspectTarget?.(request.operation, inspectionInput)
-    if (inspection !== undefined && inspection !== null) assertAppAllowed(inspection.appIdentity)
-
-    let providerInput = request.input
-    if (mutation) {
-      if (inspection === undefined || inspection === null) {
-        throw createComputerError('stale_target', 'Target identity could not be re-resolved')
+    assertedInputApp(input)
+    let context: InteractionContext | undefined
+    let inspectionInput = input
+    try {
+      if (mutation) {
+        const token = contextToken(request.input)
+        if (token === undefined) {
+          throw createComputerError(
+            'invalid_argument',
+            'Mutation requires a context token and target'
+          )
+        }
+        context = this.#contexts.resolve(token)
+        // Context-window and index shorthand do not carry an identity until the
+        // broker binds them. Inspect the bound form so native providers can
+        // re-resolve the exact process/window before dispatch.
+        inspectionInput = normalizeMutationInput(request.input, context, context)
       }
-      providerInput = normalizeMutationInput(request.input, context!, inspection.bindings)
-      const references = mutationReferences(providerInput)
-      if (references.length === 0) {
-        throw createComputerError('invalid_argument', 'Mutation requires a target selector')
+      const inspectStarted = this.#now()
+      const inspection = await this.#inspectTarget?.(request.operation, inspectionInput)
+      inspectMs = this.#now() - inspectStarted
+      if (inspection !== undefined && inspection !== null) {
+        assertAppAllowed(inspection.appIdentity)
+        bindings = inspection.bindings
       }
-      for (const reference of references) {
-        assertFreshReference(reference, context!, inspection.bindings, this.#now())
+
+      let providerInput = input
+      if (mutation) {
+        if (inspection === undefined || inspection === null) {
+          throw createComputerError('stale_target', 'Target identity could not be re-resolved')
+        }
+        providerInput = normalizeMutationInput(request.input, context!, inspection.bindings)
+        const references = mutationReferences(providerInput)
+        if (references.length === 0) {
+          throw createComputerError('invalid_argument', 'Mutation requires a target selector')
+        }
+        for (const reference of references) {
+          assertFreshReference(reference, context!, inspection.bindings, this.#now())
+        }
       }
-    }
 
-    try {
+      const dispatchStarted = this.#now()
       const providerResponse = await this.#supervisor.dispatch({
         requestId,
         operation: request.operation,
         input: providerInput,
         deadlineAt
       })
+      dispatchMs = this.#now() - dispatchStarted
+      dispatched = providerResponse.dispatched
       if (mutation) {
-        const dispatched = providerResponse.dispatched
         if (dispatched) this.#desktopEpoch += 1
-        const result =
+        const mutationResult =
           'error' in providerResponse
             ? {
                 outcome: dispatched
@@ -354,43 +435,108 @@ export class LocalBroker {
             : providerResponse.result
         const response = {
           requestId,
-          result: this.#publicResult(request.operation, result),
+          result: this.#publicResult(request.operation, mutationResult),
           desktopEpoch: this.#desktopEpoch,
           providerGeneration: this.#supervisor.generation ?? 'unknown'
         }
+        result = response.result
         await this.#publish?.(response)
         return response
       }
-      return this.#observationResponse(requestId, request.operation, providerResponse.result)
-    } catch (cause) {
-      const error = computerError(cause)
-      if (!mutation && error.code === 'provider_crashed') {
+      if ('error' in providerResponse) {
+        // Why: observations have no outcome envelope, so surface the provider's
+        // coded error directly. Validating the absent result instead would mask
+        // app_not_found and friends as an opaque schema failure.
+        throw createComputerError(
+          providerResponse.error.code,
+          providerResponse.error.message,
+          ...(providerResponse.error.details === undefined ? [] : [providerResponse.error.details])
+        )
+      }
+      const response = this.#observationResponse(
+        requestId,
+        request.operation,
+        providerResponse.result
+      )
+      result = response.result
+      return response
+    } catch (error) {
+      cause = error
+      const failed = computerError(error)
+      if (!mutation && failed.code === 'provider_crashed') {
+        this.#emit({
+          kind: 'helper.crash',
+          ...this.diagnosticEnvelope(),
+          requestId,
+          operation: request.operation,
+          error: diagnosticError(error)
+        })
+        const previousGeneration = this.#supervisor.generation
         await this.#supervisor.restart()
         this.#contexts.invalidateAll()
+        this.#emit({
+          kind: 'helper.restart',
+          ...this.diagnosticEnvelope(),
+          ...(previousGeneration === undefined ? {} : { previousGeneration })
+        })
+        const retryStarted = this.#now()
         const retry = await this.#supervisor.dispatch({
           requestId: `${requestId}-retry`,
           operation: request.operation,
           input: request.input,
           deadlineAt
         })
-        if ('error' in retry) throw Object.assign(new Error(retry.error.message), retry.error)
-        return this.#observationResponse(requestId, request.operation, retry.result)
+        dispatchMs += this.#now() - retryStarted
+        if ('error' in retry) {
+          cause = createComputerError(retry.error.code, retry.error.message, retry.error.details)
+          throw cause
+        }
+        dispatched = retry.dispatched
+        const response = this.#observationResponse(requestId, request.operation, retry.result)
+        cause = undefined
+        result = response.result
+        return response
       }
-      if (mutation && (error.code === 'provider_crashed' || error.code === 'timeout')) {
+      if (mutation && (failed.code === 'provider_crashed' || failed.code === 'timeout')) {
+        if (failed.code === 'provider_crashed') {
+          this.#emit({
+            kind: 'helper.crash',
+            ...this.diagnosticEnvelope(),
+            requestId,
+            operation: request.operation,
+            error: diagnosticError(error)
+          })
+        }
         this.#desktopEpoch += 1
         this.#contexts.invalidateAll()
+        dispatched = true
         const response = {
           requestId,
           result: this.#publicResult(request.operation, {
-            outcome: { state: 'indeterminate', reason: error.message }
+            outcome: { state: 'indeterminate', reason: failed.message }
           }),
           desktopEpoch: this.#desktopEpoch,
           providerGeneration: this.#supervisor.generation ?? 'unknown'
         }
+        cause = undefined
+        result = response.result
         await this.#publish?.(response)
         return response
       }
-      throw cause
+      throw error
+    } finally {
+      this.#emitRequest({
+        request,
+        requestId,
+        enqueuedAt,
+        startedAt,
+        inspectMs,
+        dispatchMs,
+        bindings,
+        dispatched,
+        result,
+        cause
+      })
     }
   }
 
@@ -436,4 +582,41 @@ export class LocalBroker {
     }
     return parseOperationOutput(operation, publicResult)
   }
+
+  #emit(record: DiagnosticRecord): void {
+    emitDiagnostic(this.#diagnostics, record)
+  }
+
+  #emitRequest(entry: {
+    request: BrokerRequest
+    requestId: string
+    enqueuedAt: number
+    startedAt: number
+    inspectMs: number
+    dispatchMs: number
+    bindings: ReferenceBindings | undefined
+    dispatched: boolean | undefined
+    result: unknown
+    cause: unknown
+  }): void {
+    const target = diagnosticTarget(entry.request.input, entry.bindings)
+    this.#emit({
+      kind: 'request',
+      ...this.diagnosticEnvelope(),
+      requestId: entry.requestId,
+      operation: entry.request.operation,
+      mutation: COMPUTER_OPERATIONS[entry.request.operation].mutation,
+      ms: {
+        queue: Math.max(0, entry.startedAt - entry.enqueuedAt),
+        inspect: entry.inspectMs,
+        dispatch: entry.dispatchMs,
+        total: Math.max(0, this.#now() - entry.enqueuedAt)
+      },
+      ...(target === undefined ? {} : { target }),
+      result:
+        entry.cause !== undefined
+          ? { type: 'error', ...diagnosticError(entry.cause) }
+          : diagnosticRequestResult(entry.request.operation, entry.result, entry.dispatched)
+    })
+  }
 }

package/src/diagnostics/paths.ts

@@ -0,0 +1,30 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import { graphicalSessionKey } from '../ipc/endpoint.js'
+
+export function diagnosticsDirectory(
+  graphicalSessionId: string,
+  options: { platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv } = {}
+): string {
+  const env = options.env ?? process.env
+  const override = env.CROSSHANDS_DIAGNOSTICS_DIR
+  if (typeof override === 'string' && override.length > 0) return override
+  const sessionKey = graphicalSessionKey(graphicalSessionId)
+  const platform = options.platform ?? process.platform
+  if (platform === 'darwin') {
+    return join(homedir(), 'Library', 'Logs', 'CrossHands', sessionKey)
+  }
+  if (platform === 'linux') {
+    const stateHome =
+      typeof env.XDG_STATE_HOME === 'string' && env.XDG_STATE_HOME.length > 0
+        ? env.XDG_STATE_HOME
+        : join(homedir(), '.local', 'state')
+    return join(stateHome, 'crosshands', sessionKey)
+  }
+  const localAppData =
+    typeof env.LOCALAPPDATA === 'string' && env.LOCALAPPDATA.length > 0
+      ? env.LOCALAPPDATA
+      : join(homedir(), 'AppData', 'Local')
+  return join(localAppData, 'CrossHands', 'logs', sessionKey)
+}