@crosshands/runtime 0.1.5 → 0.2.0

package/src/diagnostics/record.ts

@@ -0,0 +1,262 @@
+import {
+  COMPUTER_OPERATIONS,
+  ComputerError,
+  type ComputerOperationName,
+  type MutationResult,
+  type ReferenceBindings,
+  type SnapshotResult
+} from '@crosshands/contract'
+
+export const DIAGNOSTIC_RECORD_VERSION = 1 as const
+
+const ERROR_DETAIL_KEYS = new Set([
+  'mismatches',
+  'cause',
+  'expectedProviderProtocol',
+  'receivedProviderProtocol',
+  'expectedPublicContract',
+  'receivedPublicContract'
+])
+
+export type DiagnosticPlatform = 'darwin' | 'win32' | 'linux'
+
+export type DiagnosticError = {
+  code: string
+  message: string
+  retry: boolean
+  remediation: string
+  details?: Record<string, string | number | boolean | string[]>
+}
+
+export type DiagnosticTarget = {
+  appId: string
+  pid?: number
+  windowId?: string
+  snapshotId?: string
+  kind?: string
+  ref?: string
+}
+
+export type DiagnosticTimings = {
+  queue: number
+  inspect: number
+  dispatch: number
+  total: number
+}
+
+export type DiagnosticRequestResult =
+  | {
+      type: 'mutation'
+      dispatched: boolean
+      outcome: { state: string; reason?: string }
+    }
+  | {
+      type: 'observation'
+      snapshotId?: string
+      elementCount?: number
+      focusedElementRef?: string | null
+      screenshot: boolean
+      issues: Array<{ code: string; retry: boolean; remediation: string; message?: string }>
+    }
+  | {
+      type: 'lookup'
+      appCount?: number
+      windowCount?: number
+      permissions?: Record<string, string>
+    }
+  | ({ type: 'error' } & DiagnosticError)
+
+export type DiagnosticEnvelope = {
+  v: typeof DIAGNOSTIC_RECORD_VERSION
+  ts: string
+  session: string
+  brokerGeneration: string
+  providerGeneration?: string
+  desktopEpoch: number
+  platform: DiagnosticPlatform
+}
+
+export type DiagnosticRecord =
+  | (DiagnosticEnvelope & { kind: 'broker.start' })
+  | (DiagnosticEnvelope & { kind: 'broker.stop'; reason: string })
+  | (DiagnosticEnvelope & { kind: 'helper.start' })
+  | (DiagnosticEnvelope & {
+      kind: 'helper.crash'
+      requestId?: string
+      operation?: string
+      error: DiagnosticError
+    })
+  | (DiagnosticEnvelope & { kind: 'helper.restart'; previousGeneration?: string })
+  | (DiagnosticEnvelope & {
+      kind: 'client.handshake'
+      accepted: boolean
+      requestId: string
+      code?: string
+    })
+  | (DiagnosticEnvelope & {
+      kind: 'request'
+      requestId: string
+      operation: string
+      mutation: boolean
+      ms: DiagnosticTimings
+      target?: DiagnosticTarget
+      result: DiagnosticRequestResult
+    })
+
+export type DiagnosticsSink = {
+  emit(record: DiagnosticRecord): void
+  close(): Promise<void>
+}
+
+export function diagnosticPlatform(
+  platform: NodeJS.Platform = process.platform
+): DiagnosticPlatform {
+  if (platform === 'darwin' || platform === 'win32' || platform === 'linux') return platform
+  return 'linux'
+}
+
+export function emitDiagnostic(sink: DiagnosticsSink | undefined, record: DiagnosticRecord): void {
+  try {
+    sink?.emit(record)
+  } catch {
+    // Diagnostics must not fail computer-use.
+  }
+}
+
+export function diagnosticError(cause: unknown): DiagnosticError {
+  if (cause instanceof ComputerError) {
+    const json = cause.toJSON()
+    return {
+      code: json.code,
+      message: json.message,
+      retry: json.retry,
+      remediation: json.remediation,
+      ...diagnosticErrorDetails(json.details)
+    }
+  }
+  return {
+    code: 'provider_unavailable',
+    message: cause instanceof Error ? cause.message : 'Request failed',
+    retry: true,
+    remediation: 'run_doctor'
+  }
+}
+
+export function diagnosticTarget(
+  input: unknown,
+  bindings: ReferenceBindings | undefined
+): DiagnosticTarget | undefined {
+  const appId = bindings?.appId ?? inputAppId(input)
+  if (appId === undefined) return undefined
+  const selector = inputSelector(input)
+  return {
+    appId,
+    ...(bindings?.process.pid === undefined ? {} : { pid: bindings.process.pid }),
+    ...(bindings?.window.id === undefined ? {} : { windowId: bindings.window.id }),
+    ...(bindings?.snapshotId === undefined ? {} : { snapshotId: bindings.snapshotId }),
+    ...(selector.kind === undefined ? {} : { kind: selector.kind }),
+    ...(selector.ref === undefined ? {} : { ref: selector.ref })
+  }
+}
+
+export function diagnosticRequestResult(
+  operation: ComputerOperationName,
+  result: unknown,
+  dispatched: boolean | undefined
+): DiagnosticRequestResult {
+  if (COMPUTER_OPERATIONS[operation].mutation) {
+    const { outcome } = result as MutationResult
+    return {
+      type: 'mutation',
+      dispatched: dispatched ?? true,
+      outcome: {
+        state: outcome.state,
+        ...('reason' in outcome && typeof outcome.reason === 'string'
+          ? { reason: outcome.reason }
+          : {})
+      }
+    }
+  }
+  if (operation === 'getAppState') {
+    const observation = result as SnapshotResult
+    return {
+      type: 'observation',
+      snapshotId: observation.snapshot.id,
+      elementCount: observation.snapshot.elementCount,
+      focusedElementRef: observation.snapshot.focusedElementRef,
+      screenshot: observation.screenshot !== null,
+      issues: observation.issues.map((issue) => {
+        const recorded: {
+          code: string
+          retry: boolean
+          remediation: string
+          message?: string
+        } = {
+          code: issue.code,
+          retry: issue.retry,
+          remediation: issue.remediation
+        }
+        if (issue.message !== undefined) recorded.message = issue.message
+        return recorded
+      })
+    }
+  }
+  if (operation === 'listApps') {
+    return { type: 'lookup', appCount: (result as { apps: readonly unknown[] }).apps.length }
+  }
+  if (operation === 'listWindows') {
+    return {
+      type: 'lookup',
+      windowCount: (result as { windows: readonly unknown[] }).windows.length
+    }
+  }
+  if (operation === 'capabilities' || operation === 'permissions') {
+    const permissions = (result as { permissions: Record<string, string> }).permissions
+    return { type: 'lookup', permissions }
+  }
+  return { type: 'lookup' }
+}
+
+function diagnosticErrorDetails(
+  details: unknown
+): { details: NonNullable<DiagnosticError['details']> } | Record<string, never> {
+  if (details === null || typeof details !== 'object' || Array.isArray(details)) return {}
+  const result: NonNullable<DiagnosticError['details']> = {}
+  for (const [key, value] of Object.entries(details as Record<string, unknown>)) {
+    if (!ERROR_DETAIL_KEYS.has(key)) continue
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      result[key] = value
+    } else if (Array.isArray(value) && value.every((entry) => typeof entry === 'string')) {
+      result[key] = value
+    }
+  }
+  return Object.keys(result).length > 0 ? { details: result } : {}
+}
+
+function inputAppId(input: unknown): string | undefined {
+  if (input === null || typeof input !== 'object') return undefined
+  const app = (input as { app?: unknown }).app
+  return typeof app === 'string' && app.length > 0 ? app : undefined
+}
+
+function inputSelector(input: unknown): { kind?: string; ref?: string } {
+  if (input === null || typeof input !== 'object') return {}
+  const record = input as { target?: unknown; from?: unknown }
+  const selector = record.target ?? record.from
+  if (selector === null || typeof selector !== 'object') return {}
+  const target = selector as { kind?: unknown; elementIndex?: unknown; ref?: unknown }
+  let kind = typeof target.kind === 'string' ? target.kind : undefined
+  let ref: string | undefined
+  if (typeof target.elementIndex === 'number') ref = `element:${target.elementIndex}`
+  if (typeof target.ref === 'string') {
+    ref = target.ref
+  } else if (target.ref !== null && typeof target.ref === 'object') {
+    const bound = target.ref as { kind?: unknown; ref?: unknown }
+    if (typeof bound.kind === 'string') kind = bound.kind
+    if (typeof bound.ref === 'string') ref = bound.ref
+  }
+  return {
+    ...(kind === undefined ? {} : { kind }),
+    ...(ref === undefined ? {} : { ref })
+  }
+}

package/src/diagnostics/writer.ts

@@ -0,0 +1,112 @@
+import { closeSync, fstatSync, fsyncSync, openSync, writeSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { ensurePrivateDirectory } from '../private-directory.js'
+import type { DiagnosticRecord, DiagnosticsSink } from './record.js'
+
+export const DEFAULT_DIAGNOSTICS_ROTATE_BYTES = 5 * 1024 * 1024
+
+export type JsonlFileWriterOptions = {
+  directory: string
+  generation: string
+  maxBytes?: number
+}
+
+export class JsonlFileWriter {
+  readonly directory: string
+  readonly generation: string
+  readonly #maxBytes: number
+  #part = 1
+  #started = false
+  #closed = false
+  #fd: number | undefined
+  #bytes = 0
+
+  constructor(options: JsonlFileWriterOptions) {
+    this.directory = options.directory
+    this.generation = options.generation
+    this.#maxBytes = options.maxBytes ?? DEFAULT_DIAGNOSTICS_ROTATE_BYTES
+  }
+
+  start(): void {
+    if (this.#started) return
+    ensurePrivateDirectory(this.directory)
+    this.#started = true
+  }
+
+  emit(record: Record<string, unknown>): void {
+    if (this.#closed) return
+    if (!this.#started) this.start()
+    const line = `${JSON.stringify(record)}\n`
+    const size = Buffer.byteLength(line)
+    if (this.#bytes > 0 && this.#bytes + size > this.#maxBytes) this.#rotate()
+    if (this.#fd === undefined) this.#open()
+    const fd = this.#fd
+    if (fd === undefined) return
+    writeSync(fd, line)
+    this.#bytes += size
+  }
+
+  async close(): Promise<void> {
+    if (this.#closed) return
+    this.#closed = true
+    this.#closeFile()
+  }
+
+  #filePath(): string {
+    const suffix = this.#part === 1 ? '' : `.${this.#part}`
+    return join(this.directory, `${this.generation}${suffix}.jsonl`)
+  }
+
+  #open(): void {
+    const fd = openSync(this.#filePath(), 'a', 0o600)
+    this.#fd = fd
+    this.#bytes = fstatSync(fd).size
+  }
+
+  #closeFile(): void {
+    const fd = this.#fd
+    this.#fd = undefined
+    if (fd === undefined) return
+    try {
+      fsyncSync(fd)
+    } finally {
+      closeSync(fd)
+    }
+  }
+
+  #rotate(): void {
+    this.#closeFile()
+    this.#part += 1
+  }
+}
+
+export type JsonlDiagnosticsWriterOptions = JsonlFileWriterOptions
+
+export class JsonlDiagnosticsWriter implements DiagnosticsSink {
+  readonly #file: JsonlFileWriter
+
+  constructor(options: JsonlDiagnosticsWriterOptions) {
+    this.#file = new JsonlFileWriter(options)
+  }
+
+  get directory(): string {
+    return this.#file.directory
+  }
+
+  get generation(): string {
+    return this.#file.generation
+  }
+
+  start(): void {
+    this.#file.start()
+  }
+
+  emit(record: DiagnosticRecord): void {
+    this.#file.emit(record)
+  }
+
+  close(): Promise<void> {
+    return this.#file.close()
+  }
+}

package/src/index.ts

@@ -1,6 +1,10 @@
 export * from './broker/broker.js'
 export * from './bundle-lifecycle.js'
+export * from './diagnostics/paths.js'
+export * from './diagnostics/record.js'
+export * from './diagnostics/writer.js'
 export * from './ipc/endpoint.js'
+export * from './private-directory.js'
 export * from './ipc/control-transport.js'
 export * from './ipc/framing.js'
 export * from './ipc/unix.js'

package/src/ipc/control-transport.ts

@@ -42,6 +42,12 @@ export type LocalControlRequest = {
   deadlineAt: number
 }
 
+export type ControlHandshakeEvent = {
+  accepted: boolean
+  requestId: string
+  code?: string
+}
+
 export type LocalControlServerOptions = {
   endpoint: BrokerEndpoint
   runtimeDirectory?: string
@@ -53,6 +59,7 @@ export type LocalControlServerOptions = {
   maxFrameBytes?: number
   maxFramesPerConnection?: number
   now?: () => number
+  onHandshake?: (event: ControlHandshakeEvent) => void
 }
 
 type ControlMessage = Record<string, unknown> & { type: string; requestId?: string }
@@ -254,6 +261,13 @@ export class LocalControlServer {
 
   async #authenticate(message: ControlMessage, socket: Socket): Promise<boolean> {
     const handshake = message as unknown as LocalControlHandshake
+    const note = (accepted: boolean, code?: string): void => {
+      this.#options.onHandshake?.({
+        accepted,
+        requestId: typeof handshake.requestId === 'string' ? handshake.requestId : '',
+        ...(code === undefined ? {} : { code })
+      })
+    }
     if (
       typeof handshake.requestId !== 'string' ||
       typeof handshake.token !== 'string' ||
@@ -265,6 +279,7 @@ export class LocalControlServer {
         socket,
         errorMessage(handshake.requestId, 'peer_rejected', 'Peer identity was rejected')
       )
+      note(false, 'peer_rejected')
       return false
     }
     const versions = negotiateVersionHandshake(handshake.versions)
@@ -278,6 +293,7 @@ export class LocalControlServer {
           versions.error
         )
       )
+      note(false, versions.error.code)
       return false
     }
     let accepted: boolean
@@ -297,8 +313,11 @@ export class LocalControlServer {
         socket,
         errorMessage(handshake.requestId, 'peer_rejected', 'Peer authentication failed')
       )
+      note(false, 'peer_rejected')
+      return false
     }
-    return accepted
+    note(true)
+    return true
   }
 
   async #handleRequest(socket: Socket, message: ControlMessage): Promise<void> {

package/src/ipc/endpoint.ts

@@ -12,6 +12,10 @@ export type BrokerEndpointOptions = {
   runtimeDirectory?: string
 }
 
+export function graphicalSessionKey(graphicalSessionId: string): string {
+  return createHash('sha256').update(graphicalSessionId).digest('hex').slice(0, 12)
+}
+
 export function brokerEndpoint(options: BrokerEndpointOptions): BrokerEndpoint {
   const key = createHash('sha256')
     .update(`${options.osIdentity}\0${options.graphicalSessionId}`)

package/src/private-directory.ts

@@ -0,0 +1,14 @@
+import { chmodSync, lstatSync, mkdirSync } from 'node:fs'
+
+export function ensurePrivateDirectory(directory: string): void {
+  mkdirSync(directory, { recursive: true, mode: 0o700 })
+  const info = lstatSync(directory)
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new Error('CrossHands directory is unsafe')
+  }
+  const uid = process.getuid?.()
+  if (uid !== undefined && info.uid !== uid) {
+    throw new Error('CrossHands directory has another owner')
+  }
+  if (process.platform !== 'win32') chmodSync(directory, 0o700)
+}