@anionex/dsh-computer-use 0.1.0

package/src/config.ts

@@ -0,0 +1,196 @@
+/** Validated provider, observation, settlement, artifact, and app-policy configuration. */
+
+import z from '@deepseek-ai/schemastery'
+import type Schema from '@deepseek-ai/schemastery'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { ComputerUseError } from './errors.ts'
+
+/** Settings document namespace owned by this package. */
+export const COMPUTER_USE_SETTINGS_NAMESPACE = settingsNamespace('computer-use')
+
+/** One persisted application grant. Wildcards are intentionally unsupported. */
+export interface ComputerUseAppGrant {
+  bundleId: string
+  read?: boolean
+  control?: boolean
+}
+
+/** Host-owned policy for foreground activation, keyboard routing, target-process input, and the visible Agent cursor. */
+export interface ComputerUseInteractionConfig {
+  focusPolicy?: 'preserve' | 'activate'
+  keyboardPolicy?: 'preserve' | 'activate'
+  pointerInputPolicy?: 'deny' | 'targeted'
+  cursorVisualization?: 'hidden' | 'visible'
+  cursorMotionMs?: number
+  cursorAutoHideMs?: number
+}
+
+/** User-facing configuration; schema defaults are repeated by {@link resolveConfig}. `observationTtlMs: 0` disables observation expiry. */
+export interface ComputerUseConfig {
+  observationTtlMs?: number
+  confirmationTtlMs?: number
+  actionTimeoutMs?: number
+  settleMs?: number
+  maxSettleMs?: number
+  maxNodes?: number
+  maxDepth?: number
+  maxTextBytes?: number
+  maxScreenshotBytes?: number
+  artifactRoot?: string
+  helper?: {
+    path?: string
+    allowSourceBuild?: boolean
+  }
+  interaction?: ComputerUseInteractionConfig
+  allowAllApps?: boolean
+  grants?: ComputerUseAppGrant[]
+}
+
+/** Configuration schema used by Cordis and the Settings provider. */
+export const Config: Schema<ComputerUseConfig> = z.object({
+  observationTtlMs: z.number().default(0),
+  confirmationTtlMs: z.number().default(300000),
+  actionTimeoutMs: z.number().default(15000),
+  settleMs: z.number().default(250),
+  maxSettleMs: z.number().default(5000),
+  maxNodes: z.number().default(500),
+  maxDepth: z.number().default(14),
+  maxTextBytes: z.number().default(64000),
+  maxScreenshotBytes: z.number().default(33554432),
+  artifactRoot: z.string().default('.dsh-computer-use/artifacts'),
+  helper: z.object({
+    path: z.string(),
+    allowSourceBuild: z.boolean().default(false),
+  }),
+  interaction: z.object({
+    focusPolicy: z.union(['preserve', 'activate']).default('preserve'),
+    keyboardPolicy: z.union(['preserve', 'activate']).default('preserve'),
+    pointerInputPolicy: z.union(['deny', 'targeted']).default('targeted'),
+    cursorVisualization: z.union(['hidden', 'visible']).default('visible'),
+    cursorMotionMs: z.number().default(180),
+    cursorAutoHideMs: z.number().default(0),
+  }),
+  allowAllApps: z.boolean().default(false),
+  grants: z.array(z.object({
+    bundleId: z.string(),
+    read: z.boolean().default(false),
+    control: z.boolean().default(false),
+  })).default([]),
+})
+
+/** Fully defaulted configuration consumed at runtime. */
+export interface ResolvedComputerUseConfig {
+  observationTtlMs: number
+  confirmationTtlMs: number
+  actionTimeoutMs: number
+  settleMs: number
+  maxSettleMs: number
+  maxNodes: number
+  maxDepth: number
+  maxTextBytes: number
+  maxScreenshotBytes: number
+  artifactRoot: string
+  helper: {
+    path?: string
+    allowSourceBuild: boolean
+  }
+  interaction: {
+    focusPolicy: 'preserve' | 'activate'
+    keyboardPolicy: 'preserve' | 'activate'
+    pointerInputPolicy: 'deny' | 'targeted'
+    cursorVisualization: 'hidden' | 'visible'
+    cursorMotionMs: number
+    cursorAutoHideMs: number
+  }
+  allowAllApps: boolean
+  grants: Array<{
+    bundleId: string
+    read: boolean
+    control: boolean
+  }>
+}
+
+function integer(name: string, value: number, min: number, max: number): number {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', `${name} must be an integer between ${min} and ${max}`)
+  }
+  return value
+}
+
+function option<T extends string>(name: string, value: string, allowed: readonly T[]): T {
+  if (!allowed.includes(value as T)) {
+    throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', `${name} must be one of ${allowed.join(', ')}`)
+  }
+  return value as T
+}
+
+/** Validate and normalize one raw config object. */
+export function resolveConfig(config: ComputerUseConfig = {}): ResolvedComputerUseConfig {
+  const observationTtl = config.observationTtlMs ?? 0
+  const observationTtlMs = observationTtl === 0 ? 0 : integer('observationTtlMs', observationTtl, 1000, 86400000)
+  const confirmationTtlMs = integer('confirmationTtlMs', config.confirmationTtlMs ?? 300000, 1000, 900000)
+  const actionTimeoutMs = integer('actionTimeoutMs', config.actionTimeoutMs ?? 15000, 1000, 120000)
+  const settleMs = integer('settleMs', config.settleMs ?? 250, 0, 10000)
+  const maxSettleMs = integer('maxSettleMs', config.maxSettleMs ?? 5000, 100, 60000)
+  if (settleMs > maxSettleMs) {
+    throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', 'settleMs must be no greater than maxSettleMs')
+  }
+  const maxNodes = integer('maxNodes', config.maxNodes ?? 500, 10, 5000)
+  const maxDepth = integer('maxDepth', config.maxDepth ?? 14, 1, 64)
+  const maxTextBytes = integer('maxTextBytes', config.maxTextBytes ?? 64000, 1024, 1048576)
+  const maxScreenshotBytes = integer('maxScreenshotBytes', config.maxScreenshotBytes ?? 33554432, 1024, 268435456)
+  const artifactRoot = (config.artifactRoot ?? '.dsh-computer-use/artifacts').trim()
+  if (artifactRoot.length === 0 || artifactRoot.startsWith('/') || artifactRoot.split(/[\\/]+/u).includes('..')) {
+    throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', 'artifactRoot must be a non-empty workspace-relative path without ..')
+  }
+  const helperPath = config.helper?.path?.trim()
+  if (helperPath !== undefined && helperPath.length === 0) {
+    throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', 'helper.path must not be empty')
+  }
+  const focusPolicy = option('interaction.focusPolicy', config.interaction?.focusPolicy ?? 'preserve', ['preserve', 'activate'] as const)
+  const keyboardPolicy = option('interaction.keyboardPolicy', config.interaction?.keyboardPolicy ?? 'preserve', ['preserve', 'activate'] as const)
+  const pointerInputPolicy = option('interaction.pointerInputPolicy', config.interaction?.pointerInputPolicy ?? 'targeted', ['deny', 'targeted'] as const)
+  const cursorVisualization = option('interaction.cursorVisualization', config.interaction?.cursorVisualization ?? 'visible', ['hidden', 'visible'] as const)
+  const cursorMotionMs = integer('interaction.cursorMotionMs', config.interaction?.cursorMotionMs ?? 180, 0, 2000)
+  const cursorAutoHideMs = integer('interaction.cursorAutoHideMs', config.interaction?.cursorAutoHideMs ?? 0, 0, 30000)
+  const allowAllApps = config.allowAllApps ?? false
+  const seen = new Set<string>()
+  const grants = (config.grants ?? []).map((grant) => {
+    const bundleId = grant.bundleId.trim()
+    if (bundleId.length === 0 || bundleId === '*' || bundleId.includes('*')) {
+      throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', 'grants[].bundleId must be one exact non-wildcard bundle id')
+    }
+    if (seen.has(bundleId)) {
+      throw new ComputerUseError('COMPUTER_PROVIDER_FAILURE', `duplicate app grant for ${bundleId}`)
+    }
+    seen.add(bundleId)
+    const control = grant.control ?? false
+    return { bundleId, read: (grant.read ?? false) || control, control }
+  })
+  return {
+    observationTtlMs,
+    confirmationTtlMs,
+    actionTimeoutMs,
+    settleMs,
+    maxSettleMs,
+    maxNodes,
+    maxDepth,
+    maxTextBytes,
+    maxScreenshotBytes,
+    artifactRoot,
+    helper: {
+      ...(helperPath === undefined ? {} : { path: helperPath }),
+      allowSourceBuild: config.helper?.allowSourceBuild ?? false,
+    },
+    interaction: {
+      focusPolicy,
+      keyboardPolicy,
+      pointerInputPolicy,
+      cursorVisualization,
+      cursorMotionMs,
+      cursorAutoHideMs,
+    },
+    allowAllApps,
+    grants,
+  }
+}

package/src/confirmations.ts

@@ -0,0 +1,128 @@
+/** One-use just-in-time confirmation tokens for sensitive Computer Use actions. */
+
+import { createHash, randomUUID } from 'node:crypto'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { Context } from '@deepseek-ai/cordis'
+import { approvalPolicy } from './approval-policy.ts'
+import type { ResolvedComputerUseConfig } from './config.ts'
+import { ComputerUseError } from './errors.ts'
+import {
+  ComputerConfirmationToken,
+  type ComputerActionRequest,
+  type ComputerAppIdentity,
+  type ComputerConfirmRequest,
+  type ComputerConfirmation,
+  type ComputerObservationId,
+} from './types.ts'
+
+interface ConfirmationRecord {
+  app: ComputerAppIdentity
+  observationId: ComputerObservationId
+  actionHash: string
+  expiresAt: number
+}
+
+function stable(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`
+  const record = value as Record<string, unknown>
+  return `{${Object.keys(record).sort().filter(key => record[key] !== undefined).map(key => `${JSON.stringify(key)}:${stable(record[key])}`).join(',')}}`
+}
+
+function actionHash(action: Omit<ComputerActionRequest, 'confirmationToken'> | ComputerActionRequest): string {
+  const { confirmationToken: _token, ...rest } = action as ComputerActionRequest
+  return createHash('sha256').update(stable(rest)).digest('hex')
+}
+
+/** Issues, validates, consumes, and releases scoped sensitive-action tokens. */
+export class ComputerConfirmationManager {
+  private readonly records = new Map<Agent, Map<ComputerConfirmationToken, ConfirmationRecord>>()
+
+  constructor(
+    private readonly ctx: Context,
+    private readonly config: () => ResolvedComputerUseConfig,
+  ) {}
+
+  /** Request user approval and mint one token bound to the exact action. */
+  async confirm(
+    agent: Agent,
+    app: ComputerAppIdentity,
+    request: ComputerConfirmRequest,
+    callId: import('@deepseek-ai/dsh-llm').CallId | undefined,
+    signal: AbortSignal,
+  ): Promise<ComputerConfirmation> {
+    if (approvalPolicy(this.ctx, agent) === 'never') {
+      throw new ComputerUseError(
+        'COMPUTER_CONFIRMATION_REQUIRED',
+        'sensitive action confirmation is blocked because approval prompts are disabled in this Session (approval/policy: never); do not execute the action, and ask the user to switch the permission preset to one with approval ask or run it manually',
+      )
+    }
+    const outcome = await this.ctx.approval.request({
+      agent,
+      toolName: 'computer_confirm',
+      ...(callId === undefined ? {} : { callId }),
+      reason: `${request.reason} Target: ${request.target}.${request.dataSummary === undefined ? '' : ` Data: ${request.dataSummary}.`}`,
+      signal,
+    })
+    if (outcome === 'cancelled') throw new ComputerUseError('COMPUTER_CANCELLED', 'sensitive action confirmation was cancelled')
+    if (outcome !== 'allowed-once') {
+      throw new ComputerUseError('COMPUTER_CONFIRMATION_REQUIRED', `sensitive action was not confirmed (${outcome})`)
+    }
+    const token = ComputerConfirmationToken(randomUUID())
+    const expiresAt = Date.now() + this.config().confirmationTtlMs
+    let agentRecords = this.records.get(agent)
+    if (agentRecords === undefined) {
+      agentRecords = new Map()
+      this.records.set(agent, agentRecords)
+    }
+    agentRecords.set(token, {
+      app,
+      observationId: request.action.observationId,
+      actionHash: actionHash(request.action),
+      expiresAt,
+    })
+    return { token, observationId: request.action.observationId, app, expiresAt: new Date(expiresAt).toISOString() }
+  }
+
+  /** Require and consume the one matching token when an action is marked sensitive. */
+  consume(agent: Agent, app: ComputerAppIdentity, action: ComputerActionRequest): void {
+    if (action.sensitive !== true) {
+      if (action.confirmationToken !== undefined) {
+        throw new ComputerUseError('COMPUTER_CONFIRMATION_REQUIRED', 'confirmationToken is valid only when sensitive is true')
+      }
+      return
+    }
+    const token = action.confirmationToken
+    if (token === undefined) {
+      throw new ComputerUseError('COMPUTER_CONFIRMATION_REQUIRED', 'sensitive action requires a token from computer_confirm')
+    }
+    const agentRecords = this.records.get(agent)
+    const record = agentRecords?.get(token)
+    if (record === undefined) {
+      throw new ComputerUseError('COMPUTER_CONFIRMATION_REQUIRED', 'confirmation token is unknown, expired, or already consumed')
+    }
+    agentRecords?.delete(token)
+    if (record.expiresAt < Date.now()) {
+      throw new ComputerUseError('COMPUTER_CONFIRMATION_REQUIRED', 'confirmation token expired')
+    }
+    if (record.app.bundleId !== app.bundleId || record.app.pid !== app.pid
+      || record.observationId !== action.observationId || record.actionHash !== actionHash(action)) {
+      throw new ComputerUseError('COMPUTER_CONFIRMATION_REQUIRED', 'confirmation token does not match this app, observation, or action')
+    }
+  }
+
+  /** Invalidate one pending token after target identity changes before input. */
+  invalidate(agent: Agent, token: ComputerConfirmationToken | undefined): void {
+    if (token !== undefined) this.records.get(agent)?.delete(token)
+  }
+
+  /** Release every pending token owned by one Agent. */
+  releaseAgent(agent: Agent): void {
+    this.records.delete(agent)
+  }
+
+  /** Release all pending tokens on provider teardown or generation replacement. */
+  clear(): void {
+    this.records.clear()
+  }
+}

package/src/diff.ts

@@ -0,0 +1,52 @@
+/** Accessibility-tree diff projection for model-context efficiency. */
+
+import type { ComputerElement } from './types.ts'
+
+function identity(element: ComputerElement): string {
+  const frame = element.frame === undefined
+    ? ''
+    : `${Math.round(element.frame.x)},${Math.round(element.frame.y)},${Math.round(element.frame.width)},${Math.round(element.frame.height)}`
+  return [element.role, element.subrole ?? '', element.title ?? '', element.label ?? '', frame].join('|')
+}
+
+function summary(element: ComputerElement, includeIndex: boolean): string {
+  const parts = [includeIndex ? `[${element.index}]` : undefined, element.role]
+  if (element.title !== undefined) parts.push(JSON.stringify(element.title))
+  else if (element.label !== undefined) parts.push(JSON.stringify(element.label))
+  if (element.value !== undefined) parts.push(`value=${JSON.stringify(element.value)}`)
+  if (element.enabled === false) parts.push('disabled')
+  if (element.focused === true) parts.push('focused')
+  if (element.selected === true) parts.push('selected')
+  return parts.filter((part): part is string => part !== undefined).join(' ')
+}
+
+function state(element: ComputerElement): string {
+  return JSON.stringify({
+    value: element.value,
+    enabled: element.enabled,
+    focused: element.focused,
+    selected: element.selected,
+    actions: element.actions,
+  })
+}
+
+/** Return a bounded full-to-full element diff whose current rows use current indexes. */
+export function diffElements(previous: readonly ComputerElement[], current: readonly ComputerElement[], maxBytes: number): string {
+  const before = new Map(previous.map(element => [identity(element), element]))
+  const after = new Map(current.map(element => [identity(element), element]))
+  const lines: string[] = []
+  for (const [key, element] of before) {
+    if (!after.has(key)) lines.push(`- ${summary(element, false)}`)
+  }
+  for (const [key, element] of after) {
+    const old = before.get(key)
+    if (old === undefined) lines.push(`+ ${summary(element, true)}`)
+    else if (state(old) !== state(element)) lines.push(`~ ${summary(element, true)}`)
+  }
+  if (lines.length === 0) return '(no accessibility changes)'
+  const text = lines.join('\n')
+  const bytes = Buffer.byteLength(text)
+  if (bytes <= maxBytes) return text
+  const suffix = '\n… diff truncated'
+  return `${Buffer.from(text).subarray(0, Math.max(0, maxBytes - Buffer.byteLength(suffix))).toString('utf8')}${suffix}`
+}

package/src/errors.ts

@@ -0,0 +1,39 @@
+/** Stable Computer Use failure codes returned across provider and Tool boundaries. */
+export type ComputerUseErrorCode =
+  | 'COMPUTER_UNSUPPORTED_PLATFORM'
+  | 'COMPUTER_PERMISSION_REQUIRED'
+  | 'COMPUTER_APP_NOT_FOUND'
+  | 'COMPUTER_STALE_OBSERVATION'
+  | 'COMPUTER_ELEMENT_UNAVAILABLE'
+  | 'COMPUTER_TARGET_UNAVAILABLE'
+  | 'COMPUTER_TARGET_AMBIGUOUS'
+  | 'COMPUTER_TARGET_LOW_CONFIDENCE'
+  | 'COMPUTER_TARGET_REBIND_REQUIRES_CONFIRMATION'
+  | 'COMPUTER_CONFIRMATION_REQUIRED'
+  | 'COMPUTER_ACTION_BLOCKED'
+  | 'COMPUTER_TIMEOUT'
+  | 'COMPUTER_CANCELLED'
+  | 'COMPUTER_PROVIDER_FAILURE'
+
+/** Error with a stable model-visible code and bounded public details. */
+export class ComputerUseError extends Error {
+  readonly code: ComputerUseErrorCode
+
+  /**
+   * @param code - Stable failure category.
+   * @param message - Bounded correction-oriented description without UI secrets.
+   * @param options - Optional original cause retained outside the model-facing message.
+   */
+  constructor(code: ComputerUseErrorCode, message: string, options?: ErrorOptions) {
+    super(`${code}: ${message}`, options)
+    this.name = 'ComputerUseError'
+    this.code = code
+  }
+}
+
+/** Convert an unknown failure into the provider-failure category without leaking unbounded native text. */
+export function computerUseError(error: unknown, fallback: string): ComputerUseError {
+  if (error instanceof ComputerUseError) return error
+  const message = error instanceof Error ? error.message : String(error)
+  return new ComputerUseError('COMPUTER_PROVIDER_FAILURE', `${fallback}: ${message.slice(0, 1000)}`, { cause: error })
+}

package/src/exposure.ts

@@ -0,0 +1,236 @@
+/** Agent-scoped progressive exposure for Computer Use execution Tools. */
+
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { Session } from '@deepseek-ai/dsh-session'
+import { defineTool, type ToolDefinition } from '@deepseek-ai/dsh-tools'
+import type { Context } from '@deepseek-ai/cordis'
+import { COMPUTER_USE_SKILL_CONTENT, COMPUTER_USE_SKILL_NAME } from './skill.ts'
+
+/** One global bootstrap retained until the current Agent loads the Skill. */
+export const COMPUTER_USE_ACTIVATE = 'computer_use_activate'
+
+const VISION_TOOL_NAMES = [
+  'vision_glance',
+  'vision_ground',
+  'vision_detect',
+  'vision_crop',
+  'vision_long_screenshot_ocr',
+  'vision_toolkit_activate',
+] as const
+
+const COMMAND_PREFIX = /^(?:(?:[A-Za-z_][A-Za-z0-9_]*=\S+)\s+)*(?:(?:\S*\/)?(?:sudo|env|nohup|time|command|exec)\s+(?:(?:-\S+|[A-Za-z_][A-Za-z0-9_]*=\S+)\s+)*)?/iu
+const OCR_COMMAND_PROBE = /^(?:which|type|command\s+-v)\b[^\n;&|]*\b(?:tesseract|screencapture)\b/iu
+const OCR_EXECUTABLE = /^(?:\S*\/)?(?:tesseract|screencapture)(?:\s|$)/iu
+const OCR_STACK_SETUP = /^(?:(?:\S*\/)?(?:brew|port|apt(?:-get)?|dnf|yum|pacman)\b[^\n]*(?:install|add)\b[^\n]*\btesseract(?:-ocr)?\b|(?:\S*\/)?(?:pip(?:3(?:\.\d+)*)?|uv\s+pip|poetry\s+add|pdm\s+add)\b[^\n]*(?:install|add)?[^\n]*\b(?:pytesseract|easyocr|ocrmypdf)\b)/iu
+const SCRIPTED_OCR_EXECUTABLE = /^(?:\S*\/)?(?:python(?:3(?:\.\d+)*)?|swift)(?:\s|$)/iu
+const SCRIPTED_OCR_MARKER = /(?:\bpytesseract\b|\beasyocr\b|\bocrmypdf\b|VNRecognizeTextRequest|\bimport\s+Vision\b)/iu
+const SHELL_META = /(?:&&|\|\||[;|\n])/u
+
+interface AgentExposure {
+  active: boolean
+  hideActivation?: () => void
+  toolDisposers: Array<() => void>
+  toolNames: string[]
+}
+
+/** Activation result returned to the model. */
+export interface ComputerUseActivationResult {
+  activated: boolean
+  tools: string[]
+}
+
+function renderJson(_args: unknown, value: unknown): ContentBlock[] {
+  return [{ type: 'text', text: JSON.stringify(value, null, 2) }]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function adHocOcrCommand(value: unknown): boolean {
+  if (!isRecord(value) || typeof value.command !== 'string') return false
+  const commands = value.command.split(SHELL_META)
+    .map(command => command.trimStart().replace(COMMAND_PREFIX, ''))
+  if (commands.some(command => OCR_COMMAND_PROBE.test(command)
+    || OCR_EXECUTABLE.test(command)
+    || OCR_STACK_SETUP.test(command))) return true
+  return SCRIPTED_OCR_MARKER.test(value.command)
+    && commands.some(command => SCRIPTED_OCR_EXECUTABLE.test(command))
+}
+
+function isSkillArguments(value: unknown): boolean {
+  return isRecord(value) && value.name === COMPUTER_USE_SKILL_NAME
+}
+
+function nativeSkillCall(raw: string): boolean {
+  try { return isSkillArguments(JSON.parse(raw)) } catch { return false }
+}
+
+function containsSkillContent(blocks: readonly unknown[]): boolean {
+  return blocks.some(block => isRecord(block)
+    && block.type === 'text'
+    && typeof block.text === 'string'
+    && block.text.includes(COMPUTER_USE_SKILL_CONTENT))
+}
+
+function isSkillResult(value: unknown): boolean {
+  return isRecord(value)
+    && value.name === COMPUTER_USE_SKILL_NAME
+    && value.content === COMPUTER_USE_SKILL_CONTENT
+}
+
+/** Whether durable Session history proves that the bundled Skill was loaded. */
+export function hasLoadedComputerUseSkill(session: Session): boolean {
+  const nativeCalls = new Set<string>()
+  for (const event of session.events) {
+    if (event.type === 'user/message') {
+      const source = event.data.source
+      if (source.kind === 'skill-invocation'
+        && source.name === COMPUTER_USE_SKILL_NAME
+        && containsSkillContent(event.data.content)) return true
+      continue
+    }
+    if (event.type === 'tool/call') {
+      if (event.data.name === 'skill' && nativeSkillCall(event.data.arguments)) nativeCalls.add(String(event.data.callId))
+      continue
+    }
+    if (event.type === 'tool/result') {
+      const [block] = event.data.message.content
+      if (block?.type === 'tool-result'
+        && block.isError !== true
+        && nativeCalls.has(String(block.toolCallId))
+        && containsSkillContent(block.content)) return true
+      continue
+    }
+    if (event.type === 'tool/code-dispatch'
+      && event.data.name === 'skill'
+      && event.data.isError === false
+      && isSkillArguments(event.data.arguments)
+      && containsSkillContent(event.data.content)) return true
+  }
+  return false
+}
+
+/** Owns one progressive Tool-exposure generation. */
+export class ComputerUseExposure {
+  readonly activationTool: ToolDefinition
+  private readonly states = new Map<Agent, AgentExposure>()
+  private installed = false
+
+  constructor(
+    private readonly ctx: Context,
+    private readonly createTools: () => ToolDefinition[],
+  ) {
+    this.activationTool = defineTool({
+      name: COMPUTER_USE_ACTIVATE,
+      description: `Activate the macOS Computer Use execution tools for this Agent after loading the ${COMPUTER_USE_SKILL_NAME} Skill. The Skill tool normally activates them automatically; call this only after a direct Skill invocation when the tools are still absent. This bootstrap disappears after success.`,
+      parameters: {},
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            activated: { type: 'boolean', required: true },
+            tools: { type: 'array', items: { type: 'string' }, required: true },
+          },
+        },
+        render: renderJson,
+      },
+      execute: (_args, exec): Promise<ComputerUseActivationResult> => {
+        if (exec.agent === undefined) throw new Error(`${COMPUTER_USE_ACTIVATE}: an Agent Session is required`)
+        if (!hasLoadedComputerUseSkill(exec.agent.session)) {
+          throw new Error(`${COMPUTER_USE_ACTIVATE}: load the ${COMPUTER_USE_SKILL_NAME} Skill first`)
+        }
+        return Promise.resolve(this.activate(exec.agent))
+      },
+      presentCall: () => ({ card: 'generic', title: 'Activate Computer Use', kind: 'execute' }),
+    })
+  }
+
+  /** Install lifecycle listeners and adopt existing Agents. */
+  install(): () => void {
+    if (this.installed) throw new Error('dsh-computer-use: progressive exposure is already installed')
+    this.installed = true
+    const effects = [
+      this.ctx.on('agent/created', ({ agent }) => { this.attach(agent) }),
+      this.ctx.on('agent/disposed', ({ agent }) => { this.detach(agent) }),
+      this.ctx.tools.guard((exec) => {
+        if (exec.name !== 'bash'
+          || exec.agent === undefined
+          || !hasLoadedComputerUseSkill(exec.agent.session)
+          || !adHocOcrCommand(exec.arguments)
+          || !VISION_TOOL_NAMES.some(name => this.ctx.tools.get(name, exec.agent) !== undefined)) return undefined
+        return 'Computer Use screenshot analysis must use the installed Vision Toolkit instead of a shell-built OCR stack. If vision_glance is absent, call the skill tool with {"name":"vision-tools"}; then pass the existing screenshot Artifact path to vision_glance, vision_ground, vision_detect, vision_crop, or vision_long_screenshot_ocr.'
+      }),
+      this.ctx.on('tools/result', (exec, result) => {
+        if (result.isError === false
+          && exec.name === 'skill'
+          && exec.agent !== undefined
+          && isSkillArguments(exec.arguments)
+          && isSkillResult(result.value)) this.activate(exec.agent)
+        return undefined
+      }),
+    ]
+    try {
+      for (const agent of this.ctx.agents.list()) this.attach(agent)
+    } catch (error) {
+      for (const dispose of effects.reverse()) dispose()
+      this.disposeStates()
+      this.installed = false
+      throw error
+    }
+    return () => {
+      if (!this.installed) return
+      this.installed = false
+      for (const dispose of effects.reverse()) dispose()
+      this.disposeStates()
+    }
+  }
+
+  private attach(agent: Agent): void {
+    if (this.states.has(agent)) return
+    this.states.set(agent, { active: false, toolDisposers: [], toolNames: [] })
+    if (hasLoadedComputerUseSkill(agent.session)) this.activate(agent)
+  }
+
+  private activate(agent: Agent): ComputerUseActivationResult {
+    this.attach(agent)
+    const state = this.states.get(agent)
+    if (state === undefined) throw new Error(`dsh-computer-use: Agent ${String(agent.id)} has no exposure state`)
+    if (state.active) return { activated: false, tools: [...state.toolNames] }
+    const definitions = this.createTools()
+    const toolDisposers: Array<() => void> = []
+    let hideActivation: (() => void) | undefined
+    try {
+      for (const definition of definitions) toolDisposers.push(agent.ctx.tools.register(definition))
+      hideActivation = agent.ctx.tools.restrict({ deny: [COMPUTER_USE_ACTIVATE] })
+    } catch (error) {
+      hideActivation?.()
+      for (const dispose of toolDisposers.reverse()) dispose()
+      throw error
+    }
+    state.active = true
+    state.hideActivation = hideActivation
+    state.toolDisposers = toolDisposers
+    state.toolNames = definitions.map(definition => definition.name)
+    return { activated: true, tools: [...state.toolNames] }
+  }
+
+  private detach(agent: Agent): void {
+    const state = this.states.get(agent)
+    if (state === undefined) return
+    this.states.delete(agent)
+    this.disposeState(state)
+  }
+
+  private disposeStates(): void {
+    for (const state of this.states.values()) this.disposeState(state)
+    this.states.clear()
+  }
+
+  private disposeState(state: AgentExposure): void {
+    state.hideActivation?.()
+    for (const dispose of state.toolDisposers.reverse()) dispose()
+  }
+}