@jc_stack/ez-agents 0.1.0-beta.47 → 0.1.0-beta.48

package/src/scripts.ts

@@ -0,0 +1,167 @@
+import { mkdir, readFile, readdir, writeFile, rename, link, rm, realpath, stat, access } from 'node:fs/promises'
+import { constants as fsConstants } from 'node:fs'
+import { randomUUID, createHash } from 'node:crypto'
+import path from 'node:path'
+import { type Owner, sameOwner, validOwner } from './control-state.js'
+import { assertId } from './identity.js'
+
+// Registered scripts reference agent-owned code in the workspace. Core keeps
+// only the registration: no second source copy, interpreter or dependency setup.
+export type ScriptRegistration = {
+  version: 1; id: string; revision: string; owner: Owner
+  entry: string; interpreter: string; args: string[]; sha256: string
+  timeoutSeconds: number; registeredAt: string; updatedAt: string
+}
+// Captured on the run when an occurrence is queued; the launcher verifies it.
+export type ScriptRunRef = { id: string; revision?: string; sha256?: string; args: string[] }
+
+export const DEFAULT_SCRIPT_TIMEOUT_SECONDS = 900
+export const MAX_SCRIPT_TIMEOUT_SECONDS = 21600
+const SCRIPT_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/
+const COMMAND = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/
+
+export const assertScriptId = (id: unknown): string => {
+  if (typeof id !== 'string' || !SCRIPT_ID.test(id)) throw new Error('Script ID must be 1-64 lowercase letters, digits, _ or -')
+  return id
+}
+
+export const assertScriptArgs = (args: unknown): string[] => {
+  if (!Array.isArray(args) || args.length > 64 || args.some(arg => typeof arg !== 'string' || arg.length > 4096 || arg.includes('\0')))
+    throw new Error('Script arguments must be at most 64 literal strings')
+  return args as string[]
+}
+
+// An installed interpreter is a bare command resolved on the executor PATH or an
+// absolute path. Anything with whitespace or shell syntax is a command string.
+export const assertInterpreter = (value: unknown): string => {
+  if (typeof value !== 'string' || !(COMMAND.test(value) || (path.isAbsolute(value) && !/[\s\0;&|`$<>()'"\\*?]/.test(value))))
+    throw new Error('Interpreter must be an installed command name or absolute path, not a shell command')
+  return value
+}
+
+export const assertTimeout = (value: unknown): number => {
+  if (!Number.isSafeInteger(value) || (value as number) < 1 || (value as number) > MAX_SCRIPT_TIMEOUT_SECONDS)
+    throw new Error(`Script timeout must be 1..${MAX_SCRIPT_TIMEOUT_SECONDS} seconds`)
+  return value as number
+}
+
+export const validScriptRunRef = (value: unknown): value is ScriptRunRef => {
+  const ref = value as ScriptRunRef
+  try {
+    return Boolean(ref) && assertScriptId(ref.id) === ref.id && assertScriptArgs(ref.args) === ref.args &&
+      (ref.revision === undefined || (typeof ref.revision === 'string' && /^[a-zA-Z0-9_-]+$/.test(ref.revision))) &&
+      (ref.sha256 === undefined || (typeof ref.sha256 === 'string' && /^[a-f0-9]{64}$/.test(ref.sha256)))
+  } catch { return false }
+}
+
+// The interpreter must be an installed runtime, not unhashed workspace code.
+export const resolveInterpreter = async (interpreter: string, pathValue = process.env.PATH, workspace?: string): Promise<string> => {
+  assertInterpreter(interpreter)
+  const candidates = path.isAbsolute(interpreter) ? [interpreter]
+    // Relative PATH entries would resolve against a different cwd at spawn time.
+    : (pathValue ?? '').split(path.delimiter).filter(directory => path.isAbsolute(directory)).map(directory => path.join(directory, interpreter))
+  for (const candidate of candidates) {
+    let real: string
+    try { await access(candidate, fsConstants.X_OK); if (!(await stat(candidate)).isFile()) continue; real = await realpath(candidate) } catch { continue }
+    if (workspace && real.startsWith(await realpath(workspace) + path.sep)) throw new Error('Interpreter must be an installed runtime outside the agent workspace')
+    return candidate
+  }
+  throw new Error(`Interpreter ${interpreter} is not installed on the executor PATH`)
+}
+
+// Resolve a workspace-relative entry point to its real file inside the workspace.
+export const workspaceEntry = async (workspace: string, entry: string): Promise<{ file: string; relative: string }> => {
+  if (typeof entry !== 'string' || !entry || entry.includes('\0')) throw new Error('Script entry point is required')
+  const root = await realpath(workspace)
+  let file: string
+  try { file = await realpath(path.resolve(root, entry)) }
+  catch { throw new Error('Script entry point does not exist in the agent workspace') }
+  if (!file.startsWith(root + path.sep) || !(await stat(file)).isFile()) throw new Error('Script entry point must be a file inside the agent workspace')
+  return { file, relative: path.relative(root, file) }
+}
+
+export const fileSha256 = async (file: string) => createHash('sha256').update(await readFile(file)).digest('hex')
+
+const atomic = async (file: string, value: unknown, exclusive = false) => {
+  const tmp = `${file}.${randomUUID()}.tmp`
+  try {
+    await writeFile(tmp, JSON.stringify(value) + '\n', { mode: 0o600, flag: 'wx' })
+    if (exclusive) await link(tmp, file)
+    else await rename(tmp, file)
+  } finally { await rm(tmp, { force: true }) }
+}
+
+export class Scripts {
+  private dir: string
+  constructor(controlDir: string) { this.dir = path.join(controlDir, 'scripts') }
+
+  async get(id: string): Promise<ScriptRegistration> {
+    const s = JSON.parse(await readFile(path.join(this.dir, assertId(assertScriptId(id)) + '.json'), 'utf8')) as ScriptRegistration
+    if (s.version !== 1 || s.id !== id || typeof s.revision !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(s.revision) || !validOwner(s.owner) ||
+      typeof s.entry !== 'string' || !s.entry || path.isAbsolute(s.entry) || s.entry.split(/[\\/]/).includes('..') ||
+      !/^[a-f0-9]{64}$/.test(s.sha256)) throw new Error('Invalid script registration')
+    assertInterpreter(s.interpreter); assertScriptArgs(s.args); assertTimeout(s.timeoutSeconds)
+    return s
+  }
+
+  async owned(id: string, owner: Owner): Promise<ScriptRegistration> {
+    let s: ScriptRegistration
+    try { s = await this.get(id) }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') throw new Error(`Script ${id} is not registered`)
+      throw error
+    }
+    if (!sameOwner(s.owner, owner)) throw new Error('Script registration is outside this owner binding')
+    return s
+  }
+
+  async list(owner: Owner): Promise<ScriptRegistration[]> {
+    let names: string[]
+    try { names = await readdir(this.dir) }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error }
+    const result: ScriptRegistration[] = []
+    for (const name of names.filter(name => /^[a-z0-9][a-z0-9_-]*\.json$/.test(name)).sort()) {
+      try { const s = await this.get(name.slice(0, -5)); if (sameOwner(s.owner, owner)) result.push(s) }
+      catch { console.error('Unreadable script registration', name) }
+    }
+    return result
+  }
+
+  // Register or explicitly update: hashes the current entry-point bytes.
+  async save(input: { id: string; owner: Owner; workspace: string; entry: string; interpreter: string; args: string[]; timeoutSeconds: number; pathValue?: string }, create: boolean): Promise<ScriptRegistration> {
+    assertScriptId(input.id)
+    if (!validOwner(input.owner)) throw new Error('Script registration requires the paired owner')
+    const previous = create ? undefined : await this.owned(input.id, input.owner)
+    const { file, relative } = await workspaceEntry(input.workspace, input.entry)
+    await resolveInterpreter(assertInterpreter(input.interpreter), input.pathValue, input.workspace)
+    const now = new Date().toISOString()
+    const s: ScriptRegistration = { version: 1, id: input.id, revision: randomUUID(), owner: input.owner, entry: relative,
+      interpreter: input.interpreter, args: assertScriptArgs(input.args), sha256: await fileSha256(file),
+      timeoutSeconds: assertTimeout(input.timeoutSeconds), registeredAt: previous?.registeredAt ?? now, updatedAt: now }
+    await mkdir(this.dir, { recursive: true, mode: 0o700 })
+    try { await atomic(path.join(this.dir, s.id + '.json'), s, create) }
+    catch (error) {
+      if (create && (error as NodeJS.ErrnoException).code === 'EEXIST') throw new Error('Script is already registered; use update')
+      throw error
+    }
+    return s
+  }
+
+  async remove(id: string, owner: Owner) {
+    await this.owned(id, owner)
+    await rm(path.join(this.dir, assertScriptId(id) + '.json'))
+  }
+
+  // Executor-side check, immediately before spawn: the queued registration
+  // revision must still be current and the entry-point bytes must match it.
+  async verifiedInvocation(ref: ScriptRunRef, workspace: string, pathValue?: string) {
+    if (!validScriptRunRef(ref) || !ref.revision || !ref.sha256) throw new Error(`Script ${ref?.id ?? ''} was not registered when queued`)
+    let s: ScriptRegistration
+    try { s = await this.get(ref.id) } catch { throw new Error(`Script ${ref.id} registration is unavailable`) }
+    if (s.revision !== ref.revision || s.sha256 !== ref.sha256) throw new Error(`Script ${ref.id} registration changed after this run was queued`)
+    const { file } = await workspaceEntry(workspace, s.entry)
+    if (await fileSha256(file) !== s.sha256) throw new Error(`Script ${ref.id} entry point changed since registration; inspect it and run an explicit registration update`)
+    const command = await resolveInterpreter(s.interpreter, pathValue, workspace)
+    return { command, args: [file, ...s.args, ...ref.args], registration: s }
+  }
+}

package/src/setup.ts

@@ -9,7 +9,7 @@ import { discoverDefaults } from './client-defaults.js'
 import { chatPreset } from './ai.js'
 import { ControlStore } from './control-state.js'
 import { loadControlConfig } from './config.js'
-import { EXECUTOR_REGISTRY, resolveExecutor, executorKey } from './executor.js'
+import { EXECUTOR_REGISTRY, resolveExecutor, executorKey, claudeConfigHome } from './executor.js'
 import { desktopCodexPath } from './desktop-bridge.js'
 
 export const findExecutableInPath = async (
@@ -152,7 +152,7 @@ export const runCli = async (): Promise<void> => {
     const config = loadControlConfig()
     await new ControlStore(config.controlDir, config.pairingTtlMs).syncClientPresets(
       chatPreset(await readActiveExecutor(envFilePath)), await discoverDefaults(workspace,
-        { codexHome: path.join(config.controlDir, 'cli', 'codex') }))
+        { codexHome: path.join(config.controlDir, 'cli', 'codex'), claudeHome: claudeConfigHome(config.controlDir) }))
     console.log(JSON.stringify({ workspace, created }))
     return
   }

package/src/task-capability.ts

@@ -1,7 +1,8 @@
-import { execFile } from 'node:child_process'
+import { execFile, spawn } from 'node:child_process'
 import { promisify } from 'node:util'
 import { readFile } from 'node:fs/promises'
 import path from 'node:path'
+import {fileURLToPath} from 'node:url'
 import { executorEnvironment } from './executor.js'
 import type { TaskCapability } from './tasks.js'
 import {attachmentLimit,stageTaskAttachment,type TaskAttachment} from './task-attachments.js'
@@ -43,3 +44,18 @@ export async function runTaskCapability(toolsHome: string | undefined, capabilit
   if (code !== 0 || !stdout.trim()) throw new Error(`Channel capability failed with exit ${code}`)
   return {output:stdout}
 }
+
+export async function launchTaskApplication(toolsHome: string | undefined, launch:{command:string;args:string[]}, input:unknown, runId:string):Promise<unknown> {
+  const isolated=!!process.env.EZ_PLUGIN_BROKER_SOCKET
+  if(!isolated && (!toolsHome || !path.isAbsolute(toolsHome)))throw Error('Installed tool registry required')
+  const config=!isolated ? JSON.parse(await readFile(path.join(toolsHome!,'config.json'),'utf8')) : undefined
+  // Fixed owner-configured command; literal private stdin, never a shell or model-selected args.
+  return new Promise((resolve,reject)=>{
+    const child=spawn(isolated ? process.execPath : path.join(toolsHome!,'bin','ez'),isolated ? [fileURLToPath(new URL('../bin/ez',import.meta.url)),'--task-application'] : [launch.command,...launch.args],{env:{...executorEnvironment(),EZ_RUN_ID:runId},...(config ? {cwd:config.workspace} : {}),stdio:['pipe','pipe','pipe']})
+    let output='';const timer=setTimeout(()=>{child.kill();reject(Error('Application launch timed out'))},30000)
+    child.stdout.on('data',chunk=>{output+=chunk;if(Buffer.byteLength(output)>16000){child.kill();reject(Error('Application launch output too large'))}})
+    child.stderr.resume();child.on('error',reject)
+    child.on('close',code=>{clearTimeout(timer);try{if(code!==0)throw Error('Application launch failed');const value=JSON.parse(output);const url=new URL(value.launch?.url);if(url.protocol!=='https:' || url.username || url.password || typeof value.launch?.expiresAt!=='number')throw Error('Invalid application launch receipt');resolve(value.launch)}catch(e){reject(e)}})
+    child.stdin.end(JSON.stringify(input))
+  })
+}

package/src/task-executor.ts

@@ -6,12 +6,13 @@ import { fileURLToPath } from 'node:url'
 import { spawn, execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { readRun } from './delivery-socket.js'
+import {ApplicationBindings} from './application-channel.js'
 import { Tasks } from './tasks.js'
 import { executorEnvironment, executorInvocation, terminateJob, type ExecutorOptions } from './executor.js'
 
 // This adapter is deliberately version-pinned: a new native tool default needs
 // a fresh tool-inventory audit before external correspondence can use it.
-export const TASK_CODEX_VERSION = '0.160.0'
+export const TASK_CODEX_VERSION = '0.160.1'
 export const taskDisabledFeatures = ['apps', 'browser_use', 'computer_use', 'in_app_browser', 'image_generation',
   'memories', 'goals', 'multi_agent', 'multi_agent_v2', 'hooks', 'shell_tool', 'unified_exec', 'code_mode', 'code_mode_host',
   'skill_search', 'skill_mcp_dependency_install', 'tool_suggest', 'workspace_dependencies', 'view_image']
@@ -23,8 +24,9 @@ export function taskModelCatalog(catalog: { models: Record<string, unknown>[] })
     apply_patch_tool_type: null, experimental_supported_tools: [], multi_agent_version: null,
     supports_search_tool: false, use_responses_lite: false })) };
 }
-export function taskArguments(directory: string, broker: string[], prompt: string, toolNames = ['context', 'send', 'note', 'report', 'complete'], selection: {model?:string;effort?:string} = {}) {
+export function taskArguments(directory: string, broker: string[], prompt: string, toolNames = ['context', 'read_attachment', 'send', 'note', 'report', 'complete'], selection: {model?:string;effort?:string} = {}, brokerEnvironment: NodeJS.ProcessEnv = {}) {
   const preset = executionDefaults('codex', selection)
+  const brokerEnv={HOME:homedir(),...Object.fromEntries(['EZ_PLUGIN_BROKER_SOCKET','EZ_DELIVERY_SOCKET'].flatMap(key=>brokerEnvironment[key] ? [[key,brokerEnvironment[key]]] : []))}
   return ['exec', ...(preset.model ? ['--model',preset.model] : []), ...(preset.effort ? ['-c',`model_reasoning_effort=${JSON.stringify(preset.effort)}`] : []), '--skip-git-repo-check', '--ignore-user-config', '--ignore-rules', '--ephemeral', '--strict-config', '--json', '-C', directory,
     ...taskDisabledFeatures.flatMap(feature => ['--disable', feature]), '--enable', 'skip_host_skill_discovery',
     '-c', `model_catalog_json=${JSON.stringify(join(directory, '..', 'models.json'))}`,
@@ -33,7 +35,7 @@ export function taskArguments(directory: string, broker: string[], prompt: strin
     '-c', `permissions.ez-task.filesystem={":root"="deny",":minimal"="read",${JSON.stringify(directory)}="write"}`,
     '-c', 'permissions.ez-task.network.enabled=false',
     // The trusted broker needs the host's CLI configuration; the model keeps its isolated HOME.
-    '-c', `mcp_servers.ez={command=${JSON.stringify(broker[0])},args=${JSON.stringify(broker.slice(1))},env={HOME=${JSON.stringify(homedir())}},required=true,enabled_tools=${JSON.stringify(toolNames)}}`,
+    '-c', `mcp_servers.ez={command=${JSON.stringify(broker[0])},args=${JSON.stringify(broker.slice(1))},env={${Object.entries(brokerEnv).map(([key,value])=>`${key}=${JSON.stringify(value)}`).join(',')}},required=true,enabled_tools=${JSON.stringify(toolNames)}}`,
     ...toolNames.flatMap(name => ['-c', `mcp_servers.ez.tools.${name}.approval_mode="approve"`]),
     '-'] // Literal input travels on stdin, including slash commands and leading options.
 }
@@ -41,9 +43,10 @@ export async function startTaskExecutor(options: ExecutorOptions) {
   const run = await readRun(options.controlDir, options.runId)
   if (!run || run.status !== 'running') throw new Error('No active task run')
   const task = await new Tasks(options.controlDir).authorize(run, false)
+  const applications=(run.application || task.anyConversation) ? [] : (await new ApplicationBindings(options.controlDir).list()).filter(b=>b.taskLaunch && (b.taskLaunch.tasks==="all" || b.taskLaunch.tasks.includes(task.id))).map(b=>b.id)
   const capabilityNames = (task.capabilities ?? []).map(item => `capability_${item.id}`)
-  const toolNames = [...(task.anyConversation ? ['context','send'] : ['context','send','note','report','complete']),...capabilityNames]
-  if (capabilityNames.length && !options.toolsHome) throw new Error('Channel capabilities require an installed tool registry')
+  const toolNames = [...(task.anyConversation ? ['context','read_attachment','send'] : ['context','read_attachment','send','note','report','complete']),...capabilityNames,...(applications.length?["browser_link"]:[])]
+  if ((capabilityNames.length || (applications.length && !process.env.EZ_PLUGIN_BROKER_SOCKET)) && !options.toolsHome) throw new Error('Channel capabilities require an installed tool registry')
   const environment = executorEnvironment()
   const versionInvocation = executorInvocation('codex', ['--version'])
   const version = await promisify(execFile)(versionInvocation.command, versionInvocation.args, { env: environment })
@@ -60,9 +63,9 @@ export async function startTaskExecutor(options: ExecutorOptions) {
       : join(homedir(), '.codex', 'auth.json')
     await symlink(auth, join(home, 'auth.json'))
     const broker = [process.execPath, '--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)),
-      fileURLToPath(new URL('./task-mcp.ts', import.meta.url)), options.controlDir, options.runId, options.toolsHome ?? '', JSON.stringify(task.capabilities ?? [])]
+      fileURLToPath(new URL('./task-mcp.ts', import.meta.url)), options.controlDir, options.runId, options.toolsHome ?? '', JSON.stringify(task.capabilities ?? []),JSON.stringify(applications)]
     const prompt = JSON.stringify({event: run.external ? 'correspondence_received' : 'task_activated', taskId: run.taskId})
-    const invocation = executorInvocation('codex', taskArguments(directory, broker, prompt, toolNames, options))
+    const invocation = executorInvocation('codex', taskArguments(directory, broker, prompt, toolNames, options, Object.fromEntries(['EZ_PLUGIN_BROKER_SOCKET','EZ_DELIVERY_SOCKET'].flatMap(key=>environment[key] ? [[key,environment[key]]] : []))))
     const child = spawn(invocation.command, invocation.args, {
       cwd: directory, env: { ...environment, HOME: home, CODEX_HOME: home }, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32',
     })

package/src/task-mcp.ts

@@ -1,12 +1,16 @@
+import {randomBytes,createHash} from 'node:crypto'
 import { createInterface } from 'node:readline'
 import { taskCall } from './task-rpc.js'
-import { runTaskCapability } from './task-capability.js'
+import { runTaskCapability,launchTaskApplication } from './task-capability.js'
 import type { TaskCapability } from './tasks.js'
-const [controlDir, runId, toolsHome, capabilityJson='[]'] = process.argv.slice(2)
+const [controlDir, runId, toolsHome, capabilityJson='[]', applicationsJson='[]'] = process.argv.slice(2)
 const capabilities = JSON.parse(capabilityJson) as TaskCapability[]
+const applications=JSON.parse(applicationsJson) as string[]
 const descriptions: Record<string, string> = {
+  ...(applications.length ? {browser_link:`Create a short-lived single-use browser conversation link for this discussion. Applications: ${applications.join(", ")}. Return the exact link as text to this same discussion; the link is a private bearer credential.`} : {}),
   context: 'Read the owner-approved purpose and shareable context, task notes, receipts, and untrusted correspondence.',
-  send: 'Send text and optionally an attachmentId returned by an approved file capability to this conversation. Reuse the same key for the same message. Uncertain means do not retry with a new key.',
+  read_attachment: 'Read a JPEG/PNG/WebP image, an MP4 video as sampled frames (up to 120 seconds), or a TXT/Markdown/PDF document from an incomingId in this run context. Returns the image to native vision, or bounded extracted document text, with file provenance; no owner files are accessible.',
+  send: 'Send text, or set voice=true for a spoken reply (at most 1000 characters). Optionally use an attachmentId returned by an approved file capability to this conversation. Reuse the same key for the same message. Uncertain means do not retry with a new key.',
   note: 'Save a task-scoped note. No owner files or memory are accessible.',
   report: 'Report task evidence or a blocker to the owner. This is a report, never an owner instruction.',
   complete: 'Report the result and close a finite task, stopping further messages and replies. Not available for incoming-only watches; save a note and end the run instead.',
@@ -15,8 +19,8 @@ const descriptions: Record<string, string> = {
 const tools = Object.entries(descriptions).map(([name, description]) => {
   const capability = name.startsWith('capability_')
   return { name, description, inputSchema: {
-    type: 'object', properties: name === 'context' ? {} : capability ? {input:{type:'string',maxLength:1000}} : { text: { type: 'string', maxLength: 4096 }, ...(name === 'send' ? { key: { type: 'string', pattern: '^[a-zA-Z0-9_-]{1,80}$' }, attachmentId:{type:'string',pattern:'^[a-f0-9-]{36}$'} } : {}) },
-    required: name === 'context' ? [] : capability ? ['input'] : name === 'send' ? ['text', 'key'] : ['text'], additionalProperties: false,
+    type: 'object', properties: name==='browser_link' ? {application:{type:'string',enum:applications}} : name === 'context' ? {} : name === 'read_attachment' ? {incomingId:{type:'string',maxLength:100}} : capability ? {input:{type:'string',maxLength:1000}} : { text: { type: 'string', maxLength: 4096 }, ...(name === 'send' ? { voice: {type:'boolean'}, key: { type: 'string', pattern: '^[a-zA-Z0-9_-]{1,80}$' }, attachmentId:{type:'string',pattern:'^[a-f0-9-]{36}$'} } : {}) },
+    required: name==='browser_link' ? ['application'] : name === 'context' ? [] : name === 'read_attachment' ? ['incomingId'] : capability ? ['input'] : name === 'send' ? ['text', 'key'] : ['text'], additionalProperties: false,
   } }
 })
 for await (const line of createInterface({ input: process.stdin })) {
@@ -33,16 +37,24 @@ for await (const line of createInterface({ input: process.stdin })) {
       if (!Object.hasOwn(descriptions, name)) throw new Error('Unknown task tool')
       const args = request.params.arguments ?? {}
       const capabilityId = typeof name === 'string' && name.startsWith('capability_') ? name.slice(11) : undefined
-      if (Object.keys(args).some(key => capabilityId ? key !== 'input' : !['text', ...(name === 'send' ? ['key','attachmentId'] : [])].includes(key))) throw new Error('Unexpected tool argument')
+      if (Object.keys(args).some(key => name==='browser_link' ? key!=='application' : name === 'read_attachment' ? key !== 'incomingId' : capabilityId ? key !== 'input' : !['text', ...(name === 'send' ? ['key','attachmentId','voice'] : [])].includes(key))) throw new Error('Unexpected tool argument')
       try {
         let data: unknown
-        if (capabilityId) {
+        if(name==='browser_link') {
+          if(!applications.includes(args.application))throw Error('Application is not authorized')
+          const token=randomBytes(32).toString('hex'),ticketHash=createHash('sha256').update(token).digest('hex')
+          const grant=await taskCall(controlDir,runId,'worker','application_launch',{application:args.application,ticketHash}) as {launch:{command:string;args:string[]};taskId:string;expiresAt:number}
+          data=await launchTaskApplication(toolsHome,grant.launch,{taskId:grant.taskId,taskToken:token,expiresAt:grant.expiresAt},runId)
+        } else if (capabilityId) {
           const begun = await taskCall(controlDir,runId,'worker','capability_begin',{id:capabilityId,input:args.input}) as {capability:TaskCapability;lease:string}
           const result = await runTaskCapability(toolsHome || undefined,begun.capability,args.input,{controlDir,runId,lease:begun.lease})
           await taskCall(controlDir,runId,'worker','capability_result',{id:capabilityId,input:args.input,lease:begun.lease,...('attachment' in result?{attachment:result.attachment}:{})})
           data = result.attachment ? {attachmentId:result.attachment.id,filename:result.attachment.filename,bytes:result.attachment.bytes} : result
         } else data = await taskCall(controlDir, runId, 'worker', name, args)
-        result = { content: [{ type: 'text', text: JSON.stringify(data) }] }
+        if (name === 'read_attachment' && data && typeof data === 'object' && ('image' in data || 'images' in data)) {
+          const {image,images,...metadata} = data as {image?:{data:string;mimeType:string};images?:{data:string;mimeType:string}[];[key:string]:unknown}
+          result = { content: [{type:'text',text:JSON.stringify(metadata)}, ...(images ?? [image!]).map(value=>({type:'image',...value}))] }
+        } else result = { content: [{ type: 'text', text: JSON.stringify(data) }] }
       }
       catch (error) { result = { isError: true, content: [{ type: 'text', text: error instanceof Error ? error.message : 'Task tool failed' }] } }
     } else throw new Error('Unsupported MCP method')

package/src/tasks.ts

@@ -1,4 +1,4 @@
-import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, readdir, rename, writeFile, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
 import { randomUUID, createHash } from 'node:crypto'
 import { ControlStore, sameOwner, ownerId, ownerEpoch, type Owner } from './control-state.js'
@@ -7,6 +7,8 @@ import { EventSources, sourceCall, type SourceEvent } from './event-sources.js'
 import { RunStore, type RunRecord } from './runs.js'
 import { requireOwnerExecution } from './execution-authority.js'
 import { ownsRun } from './identity.js'
+import {MAX_INCOMING_ATTACHMENT_BYTES,readChatAttachment} from './files.js'
+import {ApplicationBindings} from './application-channel.js'
 import {readTaskAttachment,type TaskAttachment} from './task-attachments.js'
 
 export type TaskCapability = { id: string; description: string; command: string; args: string[]; output?:'file' }
@@ -23,7 +25,7 @@ export type Task = {
   purpose: string; context: string; createdAt: number; expiresAt: number
   state: 'pending' | 'active' | 'revoked' | 'completed'
   grant?: string; initialRunDispatched?: true
-  notes: string[]; operations: Record<string, { text: string; attachmentId?:string; state: 'uncertain' | 'accepted'; receipt?: unknown }>
+  notes: string[]; operations: Record<string, { text: string; attachmentId?:string; voice?:true; state: 'uncertain' | 'accepted'; receipt?: unknown }>
   capabilityOperations?: Record<string, { capabilityId: string; inputHash: string; lease: string; attachment?:TaskAttachment; state: 'authorized' | 'completed' }>
   publicBudget?: PublicBudget
 }
@@ -45,7 +47,7 @@ export async function atomicTaskFile(file: string, value: unknown) {
 }
 export class Tasks {
   private work: Promise<unknown> = Promise.resolve()
-  constructor(readonly controlDir: string) {}
+  constructor(readonly controlDir: string, private speech?: (text:string) => Promise<{buffer:Buffer;mimeType:string}>) {}
   private serial<T>(fn: () => Promise<T>): Promise<T> {
     const next = this.work.then(fn, fn); this.work = next.catch(() => {}); return next
   }
@@ -90,12 +92,16 @@ export class Tasks {
   }
   async authorize(run: RunRecord, checkProvider = true): Promise<Task> {
     const task = run.taskId ? await this.get(run.taskId) : null
-    if (!task || (task.waitForIncoming && !run.external) || task.state !== 'active' || task.expiresAt <= Date.now() || run.version !== 2 ||
+    if (!task || (task.waitForIncoming && !run.external && !run.application?.taskAccess) || task.state !== 'active' || task.expiresAt <= Date.now() || run.version !== 2 ||
       !ownsRun(task.owner, run))
       throw new Error('Task is inactive or expired')
     const owner = (await new ControlStore(this.controlDir, 900000).status()).owner
     if (!sameOwner(task.owner, owner) || (task.grant ? task.grant !== this.scopeHash(task) : !await this.approved(task)))
       throw new Error('Task approval is no longer valid')
+    if(run.application?.taskAccess) {
+      const access=await this.applicationAccess(run.application.taskAccess,run.application.bindingId,checkProvider)
+      if(access.task.id!==task.id)throw Error('Task application scope mismatch')
+    }
     if (checkProvider) await this.source(task)
     if (run.external && checkProvider) {
       if (run.external.sourceId !== task.sourceId || run.external.bindingId !== task.bindingId) throw new Error('Task origin mismatch')
@@ -106,6 +112,27 @@ export class Tasks {
     }
     return task
   }
+  async authorizeApplicationLaunch(runId:string,ticketHash:string) {
+    const run=await new RunStore(this.controlDir).get(runId)
+    if(!run || run.status!=='running' || run.application)throw Error('No active channel task')
+    const task=await this.authorize(run)
+    if(!/^[a-f0-9]{64}$/.test(ticketHash))throw Error('Invalid task launch')
+    const record=JSON.parse(await readFile(join(this.controlDir,'task-applications',ticketHash+'.json'),'utf8'))
+    const access=await this.applicationAccess(ticketHash,record.bindingId)
+    if(access.runId!==runId || access.task.id!==task.id)throw Error('Task launch admission mismatch')
+    const binding=(await new ApplicationBindings(this.controlDir).list()).find(b=>b.bindingId===record.bindingId)!
+    return {launch:binding.taskLaunch!,taskId:task.id,expiresAt:access.expiresAt}
+  }
+  async applicationAccess(ticketHash: string, bindingId: string, checkProvider=true) {
+    if(!/^[a-f0-9]{64}$/.test(ticketHash))throw Error('Invalid task access')
+    const record=JSON.parse(await readFile(join(this.controlDir,'task-applications',ticketHash+'.json'),'utf8'))
+    const task=await this.get(record.taskId), owner=(await new ControlStore(this.controlDir,900000).status()).owner
+    const binding=(await new ApplicationBindings(this.controlDir).list()).find(b=>b.bindingId===bindingId)
+    if(!task || task.state!=='active' || task.expiresAt<=Date.now() || record.expiresAt<=Date.now() || record.bindingId!==bindingId || record.grant!==this.scopeHash(task) || !binding?.taskLaunch || (binding.taskLaunch.tasks!=="all" && !binding.taskLaunch.tasks.includes(task.id)) || !sameOwner(binding.owner,owner) || !sameOwner(task.owner,owner) || (task.grant ? task.grant!==this.scopeHash(task) : !await this.approved(task)))throw Error('Task application access revoked or expired')
+    if(checkProvider)await this.source(task)
+    if(!bounded(record.contact,200) || (!task.anyConversation && record.contact!==task.conversationId))throw Error('Task application contact mismatch')
+    return {task,contact:record.contact,runId:record.runId as string,expiresAt:record.expiresAt as number,execution:record.execution as RunRecord['execution']}
+  }
   // Persist only the bounded grant, not transient approval/outbox state. Bind every
   // immutable authority field so later scope changes cannot reuse an old grant.
   private scopeHash(task: Task) {
@@ -258,14 +285,44 @@ export class Tasks {
       const run = await new RunStore(this.controlDir).get(runId)
       if (!run || run.status !== 'running') throw new Error('No active task run')
       const task = await this.authorize(run)
+      const access=run.application?.taskAccess ? await this.applicationAccess(run.application.taskAccess,run.application.bindingId) : undefined
       const incoming = run.external ? await new EventSources(this.controlDir).check(run.external, task.owner) : []
-      const contact = task.anyConversation ? incoming[0]?.conversationId : task.conversationId
+      const contact = access?.contact ?? (task.anyConversation ? incoming[0]?.conversationId : task.conversationId)
       if (!contact || incoming.some(event => event.conversationId !== contact)) throw new Error('Task correspondence changed')
+      if(command==='application_launch') {
+        if(run.application || task.anyConversation || Object.keys(args).some(k=>!['application','ticketHash'].includes(k)) || typeof args.ticketHash!=='string' || !/^[a-f0-9]{64}$/.test(args.ticketHash))throw Error('Invalid task application launch')
+        const binding=(await new ApplicationBindings(this.controlDir).list()).find(b=>b.id===args.application && b.taskLaunch && sameOwner(b.owner,task.owner))
+        if(!binding?.taskLaunch || (binding.taskLaunch.tasks!=="all" && !binding.taskLaunch.tasks.includes(task.id)))throw Error('Task application launch is not authorized')
+        const root=join(this.controlDir,'task-applications');await mkdir(root,{recursive:true,mode:0o700})
+        let count=0
+        for(const file of await readdir(root))if(/^[a-f0-9]{64}\.json$/.test(file)) {
+          const value=await readFile(join(root,file),'utf8').then(JSON.parse,()=>null);if(!value || !(value.expiresAt>Date.now()))await unlink(join(root,file)).catch(()=>{});else count++
+        }
+        if(count>=128)throw Error('Too many task application launches')
+        const expiresAt=Math.min(Date.now()+20*60*1000,task.expiresAt)
+        await atomicTaskFile(join(root,args.ticketHash+'.json'),{taskId:task.id,bindingId:binding.bindingId,grant:this.scopeHash(task),contact,expiresAt,runId:run.id,execution:run.execution})
+        return {launch:binding.taskLaunch,taskId:task.id,expiresAt}
+      }
       if (command === 'context') {
         return { purpose: task.purpose, context: task.context, contact,
         waitForIncoming: task.waitForIncoming === true, capabilities: task.capabilities?.map(({id,description}) => ({id,description})),
         expiresAt: task.untilRevoked ? null : task.expiresAt, notes: task.notes, operations: task.untilRevoked ? Object.fromEntries(Object.entries(task.operations).filter(([key])=>key.startsWith(`${run.id}_`))) : task.operations,
-        incoming }
+        incoming, ...(access ? {request:run.texts.join("\n")} : {}) }
+      }
+      if (command === 'read_attachment') {
+        if (!run.external || typeof args.incomingId !== 'string' || !run.external.eventIds.includes(args.incomingId) || !incoming.some(event => event.id === args.incomingId)) throw Error('Document is outside this incoming task run')
+        const source = (await new EventSources(this.controlDir).available(task.owner)).find(item => item.id === task.sourceId && item.bindingId === task.bindingId)
+        if (!source) throw Error('Task source changed')
+        const maximum = Math.ceil(MAX_INCOMING_ATTACHMENT_BYTES / 3) * 4
+        const file = await sourceCall(source.socketPath, 'task-document', {accountId:task.accountId,conversationId:contact,incomingId:args.incomingId}, maximum + 1000)
+        if (!file || typeof file.name !== 'string' || file.name.length > 255 || typeof file.data !== 'string' || file.data.length > maximum || !/^[a-f0-9]{64}$/.test(file.sha256)) throw Error('Invalid incoming document')
+        const bytes = Buffer.from(file.data,'base64')
+        if (bytes.toString('base64') !== file.data || createHash('sha256').update(bytes).digest('hex') !== file.sha256) throw Error('Incoming document changed')
+        const result = await readChatAttachment(this.controlDir,file.name,bytes)
+        const current = await new RunStore(this.controlDir).get(runId)
+        if (!current || current.status !== 'running') throw Error('Task run cancelled')
+        await this.authorize(current)
+        return {incomingId:args.incomingId,sha256:file.sha256,...result}
       }
       if (command === 'capability_begin' || command === 'capability_result') {
         const selected = task.capabilities?.find(item => item.id === args.id)
@@ -306,20 +363,35 @@ export class Tasks {
         return { queued: item.id }
       }
       if (command !== 'send' || typeof args.key !== 'string' || !/^[a-zA-Z0-9_-]{1,80}$/.test(args.key)) throw new Error('Invalid task send')
+      if (args.voice !== undefined && typeof args.voice !== 'boolean') throw new Error('Invalid voice flag')
+      if (args.voice && (args.attachmentId !== undefined || args.text.length > 1000)) throw new Error('Voice replies require at most 1000 characters and no attachment')
       let attachment:TaskAttachment|undefined
       if(args.attachmentId!==undefined) {
         const operation=Object.entries(task.capabilityOperations??{}).find(([key,value])=>key.startsWith(`${run.id}_`)&&value.lease===args.attachmentId&&value.state==='completed')?.[1]
         attachment=operation?.attachment
         if(!attachment||attachment.runId!==run.id)throw Error('Attachment is not authorized for this run')
       }
+      if(access) {
+        if(args.voice || args.attachmentId!==undefined)throw Error('Application task replies support text only')
+        const key=`${run.id}_${args.key}`, prior=task.operations[key]
+        if(prior){if(prior.text!==args.text)throw Error('Message key already used for different text');return prior}
+        const item=await new RunStore(this.controlDir).enqueueMessage(run.id,args.text)
+        task.operations[key]={text:args.text,state:'accepted',receipt:{application:run.application!.bindingId,queued:item.id}}
+        await this.save(task);return task.operations[key]
+      }
       const key = task.untilRevoked ? `${run.id}_${args.key}` : args.key
       const providerKey = `${task.id}_${task.untilRevoked ? createHash('sha256').update(key).digest('hex') : key}`
       const prior = Object.hasOwn(task.operations, key) ? task.operations[key] : undefined
       if (prior) {
-        if (prior.text !== args.text || prior.attachmentId!==args.attachmentId) throw new Error('Message key already used for different text or attachment')
+        if (prior.text !== args.text || prior.attachmentId!==args.attachmentId || Boolean(prior.voice)!==Boolean(args.voice)) throw new Error('Message key already used for different text or attachment')
         return prior // Uncertain sends are never blindly retried.
       }
       const source = await this.source(task)
+      if(args.voice) {
+        const head=await sourceCall(source.socketPath,'events-head')
+        if(head.taskVoice!==true)throw Error('This channel does not support voice replies')
+        if(!this.speech)throw Error('Speech synthesis is not configured')
+      }
       if(attachment) {
         const head=await sourceCall(source.socketPath,'events-head')
         if(head.taskAttachments!==true)throw Error('This channel does not support task attachments')
@@ -334,14 +406,22 @@ export class Tasks {
         task.operations=Object.fromEntries(Object.entries(task.operations).filter(([item,value])=>active.some(prefix=>item.startsWith(prefix))||value.state==='uncertain'))
       }
       if (Object.keys(task.operations).filter(k=>!task.untilRevoked || k.startsWith(`${run.id}_`)).length >= 30) throw new Error('Task message limit reached; report to the owner')
-      const message={text:args.text,...(attachment?{attachmentId:attachment.id}:{})}
+      const message={text:args.text,...(args.voice?{voice:true as const}:{}),...(attachment?{attachmentId:attachment.id}:{})}
+      // Synthesis happens before the provider is contacted, so its failure is a
+      // definite non-send the engine may correct, not an uncertain operation.
+      const audio = args.voice ? await this.speech!(args.text) : undefined
+      if(audio && (audio.mimeType!=='audio/ogg' || audio.buffer.length>256000 || audio.buffer.subarray(0,4).toString()!=='OggS'))throw Error('Voice audio exceeds channel limits or has invalid format')
       task.operations = { ...task.operations, [key]: { ...message, state: 'uncertain' } }
       await this.save(task)
       try {
+        const current = await new RunStore(this.controlDir).get(run.id)
+        if (!current || current.status !== 'running') throw new Error('Task run ended before voice dispatch')
+        await this.authorize(current)
+        if ((await new RunStore(this.controlDir).get(run.id))?.status !== 'running') throw new Error('Task run ended before dispatch')
         if (task.expiresAt <= Date.now()) throw new Error('Task expired before dispatch')
         const receipt = await sourceCall(source.socketPath, 'task-send', {
           accountId: task.accountId, conversationId: contact, text: args.text, key: providerKey,
-          ...(attachment?{attachment}:{}),
+          ...(attachment?{attachment}:{}), ...(audio?{audio:{data:audio.buffer.toString('base64'),mimeType:audio.mimeType}}:{}),
         })
         if (receipt.accountId !== task.accountId || receipt.conversationId !== contact || receipt.key !== providerKey || receipt.state !== 'accepted')
           throw new Error('Uncertain provider receipt')