@crosshands/cli 0.1.6 → 0.2.0

package/dist/local-client.js

@@ -1,10 +1,10 @@
 import { spawn } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { chmod, lstat, mkdir, readFile } from 'node:fs/promises';
+import { lstat, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { CONTRACT_VERSIONS, createComputerError } from '@crosshands/contract';
-import { LocalControlClient, brokerEndpoint } from '@crosshands/runtime';
+import { LocalControlClient, brokerEndpoint, ensurePrivateDirectory, graphicalSessionKey } from '@crosshands/runtime';
+import { unwrapBrokerResult } from './broker-result.js';
 export function localClientPaths() {
     const uid = process.getuid?.();
     const osIdentity = process.env.CROSSHANDS_OS_IDENTITY ??
@@ -16,7 +16,7 @@ export function localClientPaths() {
         process.env.SECURITYSESSIONID ??
         process.env.SESSIONNAME ??
         `interactive:${osIdentity}`;
-    const sessionKey = createHash('sha256').update(graphicalSessionId).digest('hex').slice(0, 12);
+    const sessionKey = graphicalSessionKey(graphicalSessionId);
     const runtimeDirectory = process.env.CROSSHANDS_RUNTIME_DIR ?? defaultRuntimeDirectory(sessionKey);
     const identity = { osIdentity, graphicalSessionId };
     return {
@@ -48,14 +48,13 @@ function defaultRuntimeDirectory(sessionKey) {
     }
     return join(localAppData, 'CrossHands', 'runtime', sessionKey);
 }
-async function prepareRuntimeDirectory(path) {
-    await mkdir(path, { recursive: true, mode: 0o700 });
-    const info = await lstat(path);
-    if (!info.isDirectory() || info.isSymbolicLink())
-        throw createComputerError('provider_unavailable', 'CrossHands runtime path is unsafe');
-    if (process.getuid !== undefined && info.uid !== process.getuid())
-        throw createComputerError('provider_unavailable', 'CrossHands runtime path has another owner');
-    await chmod(path, 0o700);
+function prepareRuntimeDirectory(path) {
+    try {
+        ensurePrivateDirectory(path);
+    }
+    catch (cause) {
+        throw createComputerError('provider_unavailable', cause instanceof Error ? cause.message : 'CrossHands directory is unsafe');
+    }
 }
 async function readSecureToken(path) {
     const info = await lstat(path);
@@ -74,12 +73,21 @@ async function connect(paths) {
         identity: paths.identity
     });
 }
+export function brokerSpawnEnv(env) {
+    const next = { ...env };
+    delete next.CROSSHANDS_JEV;
+    for (const key of Object.keys(next)) {
+        if (key === 'TYPESAFE_API_KEY' || key.startsWith('TYPESAFE_'))
+            delete next[key];
+    }
+    return next;
+}
 function defaultSpawnBroker(entrypoint) {
     const child = spawn(process.execPath, [entrypoint, 'broker'], {
         detached: true,
         stdio: 'ignore',
         windowsHide: true,
-        env: process.env
+        env: brokerSpawnEnv(process.env)
     });
     child.unref();
 }
@@ -91,7 +99,7 @@ function brokerIsAbsent(cause) {
 }
 export async function createProductionBrokerClient(options = {}) {
     const paths = options.paths ?? localClientPaths();
-    await prepareRuntimeDirectory(paths.runtimeDirectory);
+    prepareRuntimeDirectory(paths.runtimeDirectory);
     try {
         const control = await connect(paths);
         return controlAdapter(control);
@@ -124,7 +132,7 @@ export async function createProductionBrokerClient(options = {}) {
 }
 function controlAdapter(control) {
     return {
-        request: async (operation, input) => control.request({ operation, input }, { deadlineMs: 30_000 }),
+        request: async (operation, input) => unwrapBrokerResult(await control.request({ operation, input }, { deadlineMs: 30_000 })),
         close: () => control.close()
     };
 }

package/dist/local-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"local-client.js","sourceRoot":"","sources":["../src/local-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"local-client.js","sourceRoot":"","sources":["../src/local-client.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crosshands/cli",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Agent-agnostic local computer-use CLI",
   "license": "MIT",
   "bin": {
@@ -23,8 +23,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@crosshands/contract": "0.1.6",
-    "@crosshands/runtime": "0.1.6"
+    "@crosshands/contract": "0.2.0",
+    "@crosshands/runtime": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "24.10.1",
@@ -32,9 +32,9 @@
     "vitest": "4.1.5"
   },
   "optionalDependencies": {
-    "@crosshands/platform-darwin": "0.1.6",
-    "@crosshands/platform-windows": "0.1.6",
-    "@crosshands/platform-linux": "0.1.6"
+    "@crosshands/platform-linux": "0.2.0",
+    "@crosshands/platform-windows": "0.2.0",
+    "@crosshands/platform-darwin": "0.2.0"
   },
   "engines": {
     "node": ">=22"

package/src/bin.ts

@@ -3,9 +3,7 @@
 import { stdin, stderr, stdout } from 'node:process'
 import { StringDecoder } from 'node:string_decoder'
 
-import { runBrokerHost } from './broker-host.js'
-import { runCli, type CliIo } from './index.js'
-import { createProductionBrokerClient } from './local-client.js'
+import type { CliIo } from './index.js'
 
 async function readStdin(): Promise<string> {
   const decoder = new StringDecoder('utf8')
@@ -25,9 +23,12 @@ async function readStdin(): Promise<string> {
 async function main(): Promise<number> {
   const argv = process.argv.slice(2)
   if (argv[0] === 'broker') {
+    const { runBrokerHost } = await import('./broker-host.js')
     await runBrokerHost()
     return 0
   }
+  const { runCli } = await import('./index.js')
+  const { createProductionBrokerClient } = await import('./local-client.js')
   const io: CliIo = {
     stdin: readStdin,
     stdout: (value) => stdout.write(value),

package/src/broker-host.ts

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto'
+
 import {
   CONTRACT_VERSIONS,
   createComputerError,
@@ -7,9 +9,13 @@ import {
   type ReferenceBindings
 } from '@crosshands/contract'
 import {
+  JsonlDiagnosticsWriter,
   LocalBroker,
   LocalControlServer,
+  diagnosticsDirectory,
+  emitDiagnostic,
   type BrokerEndpoint,
+  type ControlHandshakeEvent,
   type LocalControlIdentity,
   type LocalControlRequest,
   type StableAppIdentity,
@@ -25,6 +31,7 @@ type ProviderModule = {
     endpoint: BrokerEndpoint
     identity: LocalControlIdentity
     handler: (request: LocalControlRequest) => Promise<unknown>
+    onHandshake?: (event: ControlHandshakeEvent) => void
   }) => Promise<{ start(): Promise<void>; close(): Promise<void> }>
   inspectTarget?: (
     operation: ComputerOperationName,
@@ -76,9 +83,16 @@ export async function runBrokerHost(): Promise<void> {
   const providerModule = await loadProviderModule()
   const paths = localClientPaths()
   const peer = { ...paths.identity, verified: true, local: true }
+  const generation = `broker-${randomUUID()}`
+  const diagnostics = new JsonlDiagnosticsWriter({
+    directory: diagnosticsDirectory(paths.identity.graphicalSessionId),
+    generation
+  })
   const broker = new LocalBroker({
     identity: peer,
+    generation,
     providerFactory: () => providerModule.createProvider(),
+    diagnostics,
     ...(providerModule.inspectTarget === undefined
       ? {}
       : {
@@ -88,45 +102,61 @@ export async function runBrokerHost(): Promise<void> {
           ): Promise<TargetInspection | null> => providerModule.inspectTarget!(operation, input)
         })
   })
-  await broker.connect({ peer, versions: CONTRACT_VERSIONS })
-  const handler = async ({ payload, deadlineAt }: LocalControlRequest): Promise<unknown> => {
-    if (payload === null || typeof payload !== 'object') throw new Error('Invalid broker request')
-    const record = payload as Record<string, unknown>
-    if (typeof record.operation !== 'string') throw new Error('Missing operation')
-    const operation = record.operation as ComputerOperationName
-    let input: unknown
-    try {
-      input = parseOperationInput(operation, record.input)
-    } catch (cause) {
-      if (cause instanceof Error && cause.name === 'ZodError') {
-        throw createComputerError('invalid_argument', 'Invalid input for the selected operation')
+  try {
+    await broker.connect({ peer, versions: CONTRACT_VERSIONS })
+    const handler = async ({ payload, deadlineAt }: LocalControlRequest): Promise<unknown> => {
+      if (payload === null || typeof payload !== 'object') throw new Error('Invalid broker request')
+      const record = payload as Record<string, unknown>
+      if (typeof record.operation !== 'string') throw new Error('Missing operation')
+      const operation = record.operation as ComputerOperationName
+      let input: unknown
+      try {
+        input = parseOperationInput(operation, record.input)
+      } catch (cause) {
+        if (cause instanceof Error && cause.name === 'ZodError') {
+          throw createComputerError('invalid_argument', 'Invalid input for the selected operation')
+        }
+        throw cause
       }
-      throw cause
+      return broker.request({ operation, input, deadlineMs: Math.max(1, deadlineAt - Date.now()) })
     }
-    return broker.request({ operation, input, deadlineMs: Math.max(1, deadlineAt - Date.now()) })
+    const onHandshake = (event: ControlHandshakeEvent): void => {
+      emitDiagnostic(diagnostics, {
+        kind: 'client.handshake',
+        ...broker.diagnosticEnvelope(),
+        accepted: event.accepted,
+        requestId: event.requestId,
+        ...(event.code === undefined ? {} : { code: event.code })
+      })
+    }
+    const server =
+      paths.endpoint.transport === 'named-pipe'
+        ? await (providerModule.createControlServer?.({
+            endpoint: paths.endpoint,
+            identity: paths.identity,
+            handler,
+            onHandshake
+          }) ??
+            Promise.reject(
+              new Error('The Windows payload has no native DACL and peer-token control relay')
+            ))
+        : new LocalControlServer({
+            endpoint: paths.endpoint,
+            runtimeDirectory: paths.runtimeDirectory,
+            tokenFile: paths.tokenFile,
+            identity: paths.identity,
+            handler,
+            onHandshake
+          })
+    await server.start()
+    emitDiagnostic(diagnostics, { kind: 'broker.start', ...broker.diagnosticEnvelope() })
+    await new Promise<void>((resolve) => {
+      const stop = (): void => resolve()
+      process.once('SIGINT', stop)
+      process.once('SIGTERM', stop)
+    })
+    await server.close()
+  } finally {
+    await broker.close('signal')
   }
-  const server =
-    paths.endpoint.transport === 'named-pipe'
-      ? await (providerModule.createControlServer?.({
-          endpoint: paths.endpoint,
-          identity: paths.identity,
-          handler
-        }) ??
-          Promise.reject(
-            new Error('The Windows payload has no native DACL and peer-token control relay')
-          ))
-      : new LocalControlServer({
-          endpoint: paths.endpoint,
-          runtimeDirectory: paths.runtimeDirectory,
-          tokenFile: paths.tokenFile,
-          identity: paths.identity,
-          handler
-        })
-  await server.start()
-  await new Promise<void>((resolve) => {
-    const stop = (): void => resolve()
-    process.once('SIGINT', stop)
-    process.once('SIGTERM', stop)
-  })
-  await server.close()
 }

package/src/broker-result.ts

@@ -0,0 +1,14 @@
+export type BrokerResultEnvelope = {
+  requestId: string
+  result: unknown
+}
+
+export function isBrokerResultEnvelope(value: unknown): value is BrokerResultEnvelope {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
+  const record = value as Record<string, unknown>
+  return typeof record.requestId === 'string' && 'result' in record
+}
+
+export function unwrapBrokerResult(value: unknown): unknown {
+  return isBrokerResultEnvelope(value) ? value.result : value
+}

package/src/index.ts

@@ -5,6 +5,10 @@ import { dirname, resolve } from 'node:path'
 
 import type { ComputerOperationName } from '@crosshands/contract'
 
+import { unwrapBrokerResult } from './broker-result.js'
+import { dispatchPublicOperation } from './intent/dispatch.js'
+import { createCliJevLogger } from './intent/log.js'
+
 export type CliBrokerClient = {
   request(operation: ComputerOperationName, input: unknown): Promise<unknown>
   close(): Promise<void>
@@ -52,8 +56,10 @@ const ALLOWED: Record<string, readonly string[]> = {
   'get-app-state': [
     'json',
     'app',
+    'context',
     'window-id',
     'window-index',
+    'goal',
     'no-screenshot',
     'restore-window',
     'screenshot-output'
@@ -68,6 +74,7 @@ const ALLOWED: Record<string, readonly string[]> = {
     'click-count',
     'mouse-button',
     'modifiers',
+    'goal',
     'no-screenshot',
     'restore-window',
     'screenshot-output'
@@ -78,6 +85,7 @@ const ALLOWED: Record<string, readonly string[]> = {
     'context',
     'element-index',
     'action',
+    'goal',
     'no-screenshot',
     'restore-window',
     'screenshot-output'
@@ -91,6 +99,7 @@ const ALLOWED: Record<string, readonly string[]> = {
     'y',
     'direction',
     'pages',
+    'goal',
     'no-screenshot',
     'restore-window',
     'screenshot-output'
@@ -146,6 +155,7 @@ const ALLOWED: Record<string, readonly string[]> = {
     'element-index',
     'value',
     'value-stdin',
+    'goal',
     'no-screenshot',
     'restore-window',
     'screenshot-output'
@@ -165,7 +175,10 @@ const EXIT_CODES: Record<string, number> = {
   action_not_supported: 7,
   timeout: 8,
   version_incompatible: 9,
-  session_unavailable: 10
+  session_unavailable: 10,
+  goal_mismatch: 5,
+  policy_unavailable: 5,
+  intent_unavailable: 2
 }
 
 class CliError extends Error {
@@ -252,12 +265,6 @@ function contextToken(flags: Flags): string {
   return stringFlag(flags, 'context', true)!
 }
 
-function elementTarget(flags: Flags, name = 'element-index'): unknown {
-  const index = numberFlag(flags, name, { integer: true, min: 0 })
-  if (index === undefined) throw new CliError('invalid_argument', `Missing required --${name}`)
-  return { kind: 'element', elementIndex: index }
-}
-
 function chordTokens(raw: string): string[] {
   return raw.split('+')
 }
@@ -271,17 +278,32 @@ function parseClickModifiers(flags: Flags): string[] | undefined {
   return modifiers
 }
 
-function pointOrElement(flags: Flags): unknown {
+function optionalGoal(flags: Flags): { goal?: string } {
+  const goal = stringFlag(flags, 'goal')
+  return goal === undefined ? {} : { goal }
+}
+
+function actionTarget(flags: Flags, options: { coordinates?: boolean } = {}): unknown {
   const element = numberFlag(flags, 'element-index', { integer: true, min: 0 })
-  const x = numberFlag(flags, 'x')
-  const y = numberFlag(flags, 'y')
+  const allowCoordinates = options.coordinates === true
+  const x = allowCoordinates ? numberFlag(flags, 'x') : undefined
+  const y = allowCoordinates ? numberFlag(flags, 'y') : undefined
   const hasCoordinates = x !== undefined || y !== undefined
   if (element !== undefined && hasCoordinates)
     throw new CliError('invalid_argument', 'Choose an element index or coordinates, not both')
   if (element !== undefined) return { kind: 'element', elementIndex: element }
-  if (x === undefined || y === undefined)
-    throw new CliError('invalid_argument', 'Coordinates require both --x and --y')
-  return { kind: 'coordinate', x, y }
+  if (hasCoordinates) {
+    if (x === undefined || y === undefined)
+      throw new CliError('invalid_argument', 'Coordinates require both --x and --y')
+    return { kind: 'coordinate', x, y }
+  }
+  if (stringFlag(flags, 'goal') !== undefined) return { kind: 'intent' }
+  throw new CliError(
+    'invalid_argument',
+    allowCoordinates
+      ? 'Choose an element index, coordinates, or --goal'
+      : 'Missing required --element-index'
+  )
 }
 
 async function protectedText(flags: Flags, name: 'text' | 'value', io: CliIo): Promise<string> {
@@ -314,10 +336,19 @@ async function operationInput(command: string, flags: Flags, io: CliIo): Promise
     case 'list-windows':
       return { app: stringFlag(flags, 'app', true) }
     case 'get-app-state': {
+      const context = stringFlag(flags, 'context')
       const window = windowSelector(flags)
+      if (context !== undefined) {
+        return {
+          contextToken: context,
+          ...optionalGoal(flags),
+          ...observationFlags(flags)
+        }
+      }
       return {
         app: stringFlag(flags, 'app', true),
         ...(window === undefined ? {} : { window }),
+        ...optionalGoal(flags),
         ...observationFlags(flags)
       }
     }
@@ -329,7 +360,8 @@ async function operationInput(command: string, flags: Flags, io: CliIo): Promise
       const modifiers = parseClickModifiers(flags)
       return {
         ...common(),
-        target: pointOrElement(flags),
+        target: actionTarget(flags, { coordinates: true }),
+        ...optionalGoal(flags),
         ...(clickCount === undefined ? {} : { clickCount }),
         ...(button === undefined ? {} : { button }),
         ...(modifiers === undefined ? {} : { modifiers })
@@ -338,8 +370,9 @@ async function operationInput(command: string, flags: Flags, io: CliIo): Promise
     case 'perform-secondary-action':
       return {
         ...common(),
-        target: elementTarget(flags),
-        action: stringFlag(flags, 'action', true)
+        target: actionTarget(flags),
+        action: stringFlag(flags, 'action', true),
+        ...optionalGoal(flags)
       }
     case 'scroll': {
       const direction = stringFlag(flags, 'direction', true)!
@@ -348,8 +381,9 @@ async function operationInput(command: string, flags: Flags, io: CliIo): Promise
       const pages = numberFlag(flags, 'pages', { integer: true, min: 1 })
       return {
         ...common(),
-        target: pointOrElement(flags),
+        target: actionTarget(flags, { coordinates: true }),
         direction,
+        ...optionalGoal(flags),
         ...(pages === undefined ? {} : { pages })
       }
     }
@@ -403,8 +437,9 @@ async function operationInput(command: string, flags: Flags, io: CliIo): Promise
     case 'set-value':
       return {
         ...common(),
-        target: elementTarget(flags),
-        value: await protectedText(flags, 'value', io)
+        target: actionTarget(flags),
+        value: await protectedText(flags, 'value', io),
+        ...optionalGoal(flags)
       }
     default:
       throw new CliError('invalid_argument', `Unknown computer command: ${command}`)
@@ -428,19 +463,9 @@ function readiness(capabilities: unknown): string {
 }
 
 async function runDoctor(client: CliBrokerClient): Promise<unknown> {
-  const capabilities = await client.request('capabilities', {})
+  const capabilities = unwrapBrokerResult(await client.request('capabilities', {}))
   const permissions = await client.request('permissions', {})
-  const capabilityResult =
-    capabilities !== null && typeof capabilities === 'object' && 'result' in capabilities
-      ? (capabilities as Record<string, unknown>).result
-      : capabilities
-  return { readiness: readiness(capabilityResult), checks: { capabilities, permissions } }
-}
-
-function publicBrokerResult(value: unknown): unknown {
-  if (value !== null && typeof value === 'object' && 'requestId' in value && 'result' in value)
-    return (value as Record<string, unknown>).result
-  return value
+  return { readiness: readiness(capabilities), checks: { capabilities, permissions } }
 }
 
 function serializedError(cause: unknown): Record<string, unknown> {
@@ -524,6 +549,7 @@ async function exportScreenshot(value: unknown, destination: string): Promise<vo
 
 export async function runCli(argv: string[], io: CliIo, client: CliBrokerClient): Promise<number> {
   let json = false
+  const log = createCliJevLogger()
   try {
     if (argv[0] !== 'computer')
       throw new CliError('invalid_argument', 'Usage: crosshands computer <command> --json')
@@ -536,8 +562,13 @@ export async function runCli(argv: string[], io: CliIo, client: CliBrokerClient)
     const brokerResult =
       operation === 'doctor'
         ? await runDoctor(client)
-        : publicBrokerResult(
-            await client.request(operation, await operationInput(command, flags, io))
+        : unwrapBrokerResult(
+            await dispatchPublicOperation(
+              client,
+              operation,
+              await operationInput(command, flags, io),
+              { env: process.env, ...(log === undefined ? {} : { log }) }
+            )
           )
     const result = structuredClone(brokerResult)
     const screenshotOutput = stringFlag(flags, 'screenshot-output')
@@ -550,9 +581,14 @@ export async function runCli(argv: string[], io: CliIo, client: CliBrokerClient)
     if (!json) io.stderr(`${String(error.message)}\n`)
     return EXIT_CODES[String(error.code)] ?? 1
   } finally {
-    await client.close().catch(() => undefined)
+    await Promise.all([client.close().catch(() => undefined), log?.close().catch(() => undefined)])
   }
 }
 
-export { createProductionBrokerClient, localClientPaths } from './local-client.js'
+export { unwrapBrokerResult } from './broker-result.js'
+export { createProductionBrokerClient, localClientPaths, brokerSpawnEnv } from './local-client.js'
 export type { LocalClientPaths, ProductionClientOptions } from './local-client.js'
+export { dispatchPublicOperation } from './intent/dispatch.js'
+export { parseJevEnv } from './intent/env.js'
+export { createCliJevLogger, createJevLogger, hashGoal } from './intent/log.js'
+export type { JevLogger } from './intent/log.js'