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

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,14 +6,15 @@ 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.153.4'
+export const TASK_CODEX_VERSION = '0.160.1'
 export const taskDisabledFeatures = ['apps', 'browser_use', 'computer_use', 'in_app_browser', 'image_generation',
-  'memories', 'multi_agent', 'multi_agent_v2', 'hooks', 'shell_tool', 'unified_exec', 'code_mode', 'code_mode_host',
+  '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']
 // Model catalog defaults can override disabled feature flags (for example,
 // code-only tools and v2 collaboration). Use the audited direct-tool surface.
@@ -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')

package/src/updates/runtime.mjs

@@ -1,3 +1,4 @@
+import { latestCodexVersion } from '../install-tools.mjs';
 import { sharedIdentity } from '../plugins/shared.mjs';
 import * as fs from 'node:fs/promises';
 import { createWriteStream } from 'node:fs';
@@ -5,6 +6,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { spawn } from 'node:child_process';
 import { parseEnv } from 'node:util';
+import { tmpdir } from 'node:os';
 import { atomic, compose, snapshot, checkFolders } from '../plugins/manager.mjs';
 import { read, state, eligibility, jobPath, cleanupStaleBackups } from './control.mjs';
 import { bindUpdates } from './binding.mjs';
@@ -61,9 +63,42 @@ export async function relayServices(config) {
   const env = await fs.readFile(path.join(config.deploymentDir,'docker.env'),'utf8').catch(() => '');
   return parseEnv(env).EZ_EXECUTOR_TRANSPORT === 'local' ? ['relay','plugin-broker'] : ['relay'];
 }
-async function refreshBroker(config, run) {
-  if ((await relayServices(config)).includes('plugin-broker'))
-    await run('docker', [...relayArgs(config), 'restart', 'plugin-broker']);
+// Explicitly rebind single-file mounts after atomic replacement. Pin the running image
+// while recreating only the broker with this deployment's Compose identity.
+export async function refreshBroker(config, run=execute, image) {
+  if (!(await relayServices(config)).includes('plugin-broker')) return null;
+  const args=relayArgs(config);
+  if(image===undefined) {
+    const id=(await run('docker',[...args,'ps','-q','plugin-broker'],{stdoutOnly:true,timeout:15000})).trim();
+    if(!/^[a-f0-9]{12,64}$/i.test(id))throw Error('Expected one installed isolated broker');
+    image=(await run('docker',['inspect','--format','{{.Image}}',id],{stdoutOnly:true,timeout:15000})).trim();
+  }
+  if(!/^sha256:[a-f0-9]{64}$/.test(image))throw Error('Cannot pin broker image');
+  const temporary=await fs.mkdtemp(path.join(tmpdir(),'ez-broker-refresh-'));
+  try {
+    const pin=path.join(temporary,'image.env');
+    await fs.writeFile(pin,`EZ_RELAY_IMAGE=${image}\n`,{mode:0o600});
+    await run('docker',[...args,'--env-file',pin,'up','-d','--no-deps','--force-recreate','--no-build','--pull','never','--wait','--wait-timeout','90','plugin-broker']);
+    const current=(await run('docker',[...args,'ps','-q','plugin-broker'],{stdoutOnly:true,timeout:15000})).trim();
+    if(!/^[a-f0-9]{12,64}$/i.test(current)||(await run('docker',['inspect','--format','{{.Image}}',current],{stdoutOnly:true,timeout:15000})).trim()!==image)
+      throw Error('Recreated broker image does not match the intended installed image');
+    const hostConfig=config.hostConfig||path.join(config.deploymentDir,'host-executor.json');
+    const home=path.dirname(hostConfig)===config.deploymentDir
+      ? (await read(hostConfig)).agents?.find(agent=>agent.workspace===config.workspace)?.toolsHome : undefined;
+    if(typeof home!=='string'||!path.isAbsolute(home))throw Error('Missing broker registry binding');
+    const files=[hostConfig,path.join(home,'registry.json'),path.join(home,'config.json')];
+    const hashes=await Promise.all(files.map(async file=>digest(await fs.readFile(file))));
+    // Supply trusted read-only code so rollback can check an older image that
+    // predates this diagnostic. Its validators still come from that image.
+    const diagnostic=await fs.readFile(new URL('../../docker/broker-readiness.mjs',import.meta.url),'utf8');
+    const probe=JSON.parse(await run('docker',[...args,'exec','-T','plugin-broker','node','--import','/app/node_modules/tsx/dist/loader.mjs',
+      '--input-type=module','-e',diagnostic,...hashes],{stdoutOnly:true,timeout:60000}));
+    if(probe.version!==1||probe.ready!==true||probe.hostSha256!==hashes[0]||probe.registrySha256!==hashes[1]||probe.configSha256!==hashes[2])
+      throw Error('Invalid isolated broker readiness readback');
+    // A concurrent writer invalidates the readback; never silently accept it.
+    for(let i=0;i<files.length;i++)if(digest(await fs.readFile(files[i]))!==hashes[i])throw Error('Broker binding changed during verification');
+    return probe;
+  }finally {await fs.rm(temporary,{recursive:true,force:true});}
 }
 const healthCodes = new Set(['RELAY_UNREADABLE','RELAY_NOT_POLLING','RELAY_STALE','HOST_UNREADABLE','HOST_STALE','PLUGIN_BROKER_UNREADABLE']);
 async function healthEvidence(config,run) {
@@ -113,13 +148,15 @@ export async function perform(home,job,hooks) {
       await run(process.execPath,['--import',path.join(root,'node_modules/tsx/dist/loader.mjs'),path.join(root,'bin/ezenciel-agents.mjs'),'--version'],{cwd:root});
       try { await replaceGuidance(root, config.workspace, run); }
       catch(error) { console.error(`Workspace guidance replacement failed; upgrade continues: ${error.message}`); }
-      // Preserve operator-owned native CLI pins from the effective deployment.
-      // Building only the package defaults silently downgrades those clients.
+      // Resolve managed Codex at activation; old deployment pins cannot override latest.
+      // Preserve unrelated operator build arguments.
       const deployment=JSON.parse(await run('docker',[...relayArgs(config),'config','--format','json'],{stdoutOnly:true}));
       const args=deployment.services?.relay?.build?.args||{};
       if(typeof args!=='object'||Array.isArray(args))throw Error('Invalid relay build arguments');
-      const buildArgs=Object.keys(args).sort().flatMap(key=>{
-        const value=args[key];
+      job.codexVersion=await latestCodexVersion(run,job.packageManager);await save();
+      const effective={...args,CODEX_CLI_VERSION:job.codexVersion};
+      const buildArgs=Object.keys(effective).sort().flatMap(key=>{
+        const value=effective[key];
         if(!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)||typeof value!=='string'||value.includes('\0'))throw Error('Unresolved relay build argument');
         return ['--build-arg',`${key}=${value}`];
       });
@@ -140,7 +177,11 @@ export async function perform(home,job,hooks) {
       await textAtomic(envFile,env);
       await bindUpdates(home,path.join(config.deploymentDir,'host-executor.json'),root);
       await hooks.startHost(root);
-      await run('docker',[...relayArgs(config),'up','-d','--wait','--wait-timeout','90','--no-build',...(await relayServices(config))]);
+      await run('docker',[...relayArgs(config),'up','-d','--wait','--wait-timeout','90','--no-build','relay']);
+      if((await relayServices(config)).includes('plugin-broker')) {
+        const brokerImage=(await run('docker',['image','inspect','--format','{{.Id}}',image],{stdoutOnly:true})).trim();
+        job.brokerReadiness=await refreshBroker(config,run,brokerImage);
+      }
     } else {
       const old=next.old.record,r=await read(path.join(home,'registry.json'));
       const secrets=await read(path.join(home,'packages',job.target,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
@@ -160,7 +201,7 @@ export async function perform(home,job,hooks) {
       r.plugins[job.target]=candidate;
       for(const alias of Object.keys(candidate.manifest.commands))r.commands[alias]=job.target;
       await atomic(path.join(home,'registry.json'),r);
-      await refreshBroker(config,run);
+      job.brokerReadiness=await refreshBroker(config,run);
       job.runtimeVerified=running;
     }
     job.status='completed';job.endedAt=new Date().toISOString();await save();
@@ -192,12 +233,13 @@ export async function recover(home,job,hooks) {
         await textAtomic(path.join(config.deploymentDir,'docker.env'),job.rollback.env);
         await bindUpdates(home,path.join(config.deploymentDir,'host-executor.json'),job.rollback.packageRoot);
         await hooks.startHost(job.rollback.packageRoot);
-        if(!retained)await run('docker',[...relayArgs(config),'up','-d','--wait','--wait-timeout','90','--no-build',...(await relayServices(config))]);
+        if(!retained)await run('docker',[...relayArgs(config),'up','-d','--wait','--wait-timeout','90','--no-build','relay']);
+        job.rollbackBrokerReadiness=await refreshBroker(config,run,pinned);
       } else {
         const b=job.rollback;
         await run('docker',[...pluginArgs(b.record),'stop']);
         await atomic(b.record.compose,b.compose);await atomic(path.join(home,'registry.json'),b.registry);
-        await refreshBroker(config,run);
+        job.rollbackBrokerReadiness=await refreshBroker(config,run);
         if(b.running)await run('docker',[...pluginArgs(b.record),'up','-d','--wait','--wait-timeout','90','--no-build']);
       }
       job.status='rolled-back';

package/src/updates/supervisor.mjs

@@ -38,6 +38,20 @@ export async function idle(control) {
   const status=await callDeliverySocket(path.join(control,'delivery.sock'),{op:'status'},2000).catch(()=>null);
   return !status||status.running===0;
 }
+// Pause admission only after work is idle, and release it if a turn raced the
+// check. A queued upgrade must never hold the owner's chat behind a long turn.
+export async function withIdleUpgrade(control,job,signal,apply,{isIdle=idle,wait=sleep}={}) {
+  if(signal.aborted||!await isIdle(control))return;
+  const pause=path.join(control,'upgrade-pause.json');
+  await atomic(pause,{id:job.id});
+  try {
+    for(let n=0;n<3;n++) {
+      await wait(500);
+      if(signal.aborted||!await isIdle(control))return;
+    }
+    if(!signal.aborted)return await apply();
+  } finally {await fs.rm(pause,{force:true});}
+}
 export async function queueAutomatic(home,available) {
   const existing=await jobs(home);
   if(existing.some(job=>['queued','applying','recovery-required'].includes(job.status)))return null;
@@ -103,19 +117,15 @@ export async function supervise(deployment,signal,{discover=check}={}) {
       if(!isolated && child?.exitCode!==null&&child?.exitCode!==undefined)throw Error('Host transport exited; supervisor service should restart');
       const pending=(await jobs(home)).find(j=>j.status==='queued');
       if(pending) {
-        await atomic(pause,{id:pending.id});
-        // Relay admission is paused; drain the requesting turn and any already-claimed job.
-        let quiet=0;
-        while(!signal.aborted&&quiet<3){quiet=await idle(agent.controlDir)?quiet+1:0;await sleep(500);}
-        if(signal.aborted)break;
-        let result;
-        try {
-          result=await locked(home,async()=>{const latest=await read(path.join(jobPath(home,pending.id),'job.json'));return perform(home,latest,{stopHost,startHost});});
-        } catch(error) {
-          // A pre-switch rejection is terminal. Applying jobs keep their journal for recovery.
-          const latest=await read(path.join(jobPath(home,pending.id),'job.json'));
-          if(latest.status==='queued'){latest.status='failed';latest.error=error.message;await atomic(path.join(jobPath(home,pending.id),'job.json'),latest);}else throw error;
-        } finally {await fs.rm(pause,{force:true});}
+        const result=await withIdleUpgrade(agent.controlDir,pending,signal,async()=>{
+          try {
+            return await locked(home,async()=>{const latest=await read(path.join(jobPath(home,pending.id),'job.json'));return perform(home,latest,{stopHost,startHost});});
+          } catch(error) {
+            // A pre-switch rejection is terminal. Applying jobs keep their journal for recovery.
+            const latest=await read(path.join(jobPath(home,pending.id),'job.json'));
+            if(latest.status==='queued'){latest.status='failed';latest.error=error.message;await atomic(path.join(jobPath(home,pending.id),'job.json'),latest);}else throw error;
+          }
+        });
         if(result?.status==='completed') {
           if(pending.target==='main')return;
           nextCheck=0;