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

package/src/task-executor.ts

@@ -6,12 +6,14 @@ 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 { provisionedHome } from './auth-profile.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 +25,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 +36,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 +44,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 })
@@ -55,14 +59,14 @@ export async function startTaskExecutor(options: ExecutorOptions) {
     const catalogInvocation = executorInvocation('codex', ['debug', 'models', '--bundled'])
     const catalog = await promisify(execFile)(catalogInvocation.command, catalogInvocation.args, { env: environment, maxBuffer: 4 * 1024 * 1024 })
     await writeFile(join(temporary, 'models.json'), JSON.stringify(taskModelCatalog(JSON.parse(catalog.stdout))), { mode: 0o600 })
-    const auth = process.env.EZ_ISOLATION === 'isolated'
-      ? join(options.controlDir, 'cli', 'codex', 'auth.json')
+    const auth = process.env.EZ_ISOLATION === 'isolated' || options.authProfile !== undefined
+      ? join(await provisionedHome(options.controlDir, 'codex', options.authProfile), 'auth.json')
       : 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

@@ -6,7 +6,8 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { spawn } from 'node:child_process';
 import { parseEnv } from 'node:util';
-import { atomic, compose, snapshot, checkFolders } from '../plugins/manager.mjs';
+import { tmpdir } from 'node:os';
+import { atomic, compose, snapshot, checkFolders, locked, publishBrokerPlugins } from '../plugins/manager.mjs';
 import { read, state, eligibility, jobPath, cleanupStaleBackups } from './control.mjs';
 import { bindUpdates } from './binding.mjs';
 import { extract, digest } from './artifact.mjs';
@@ -62,10 +63,63 @@ 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');
+    return verifyBroker(config,run);
+  }finally {await fs.rm(temporary,{recursive:true,force:true});}
+}
+// A plugin update normally leaves this single-file binding unchanged. If an
+// operator replaced it (for example to approve new network pins), recreation
+// remains necessary and must retain the existing full-turn drain.
+export async function brokerNeedsRefresh(config,run=execute) {
+  if (!(await relayServices(config)).includes('plugin-broker')) return false;
+  const hostConfig=config.hostConfig||path.join(config.deploymentDir,'host-executor.json');
+  const expected=digest(await fs.readFile(hostConfig));
+  const script="const fs=require('fs'),crypto=require('crypto');console.log(crypto.createHash('sha256').update(fs.readFileSync(process.env.EZ_PLUGIN_BROKER_HOST_CONFIG)).digest('hex'));";
+  const mounted=(await run('docker',[...relayArgs(config),'exec','-T','plugin-broker','node','-e',script],{stdoutOnly:true,timeout:15000})).trim();
+  if(!/^[a-f0-9]{64}$/.test(mounted))throw Error('Invalid broker host binding fingerprint');
+  return mounted!==expected;
 }
+// Plugin upgrades change the directory-mounted registry, not the broker's
+// single-file host binding. Verify the live broker without replacing its socket.
+export async function verifyBroker(config,run=execute) {
+  if (!(await relayServices(config)).includes('plugin-broker')) return null;
+  const args=relayArgs(config);
+  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;
+}
+
 const healthCodes = new Set(['RELAY_UNREADABLE','RELAY_NOT_POLLING','RELAY_STALE','HOST_UNREADABLE','HOST_STALE','PLUGIN_BROKER_UNREADABLE']);
 async function healthEvidence(config,run) {
   const id=(await run('docker',[...relayArgs(config),'ps','-q','relay'])).trim();
@@ -106,6 +160,17 @@ export async function perform(home,job,hooks) {
   const next=await eligibility(home,job.target,root,job.automatic);
   if(next.old.root!==job.previousRoot||next.old.pkg.version!==job.previousVersion)throw Error('Stale upgrade job');
   job.status='applying';job.root=root;job.startedAt=new Date().toISOString();await save();
+  const complete=async()=>{
+    job.status='completed';job.endedAt=new Date().toISOString();await save();
+    try { job.cleanup=await cleanupStaleBackups(home);await save(); }
+    catch(error) { job.cleanupError=error.message;await save().catch(()=>{}); }
+    return job;
+  };
+  const fail=async(error,recoveryHooks)=>{
+    let message=error.message;
+    if(job.target==='main'&&job.rollback&&/is unhealthy/.test(message))message+=await healthEvidence(config,run).catch(()=> '');
+    job.error=message;await save();return recover(home,job,recoveryHooks);
+  };
   try {
     if(job.target==='main') {
       job.packageManager=await packageManager(root,run);await save();
@@ -143,40 +208,50 @@ 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 old=next.old.record;
       const secrets=await read(path.join(home,'packages',job.target,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
       const s=await snapshot(root),candidate={...old,source:root,revision:s.revision,manifest:s.manifest,deployment:s.deployment,sharedRevisions:s.sharedRevisions};
       for (const key of old.sharedEnabled || []) if (sharedIdentity(old, key).fingerprint !== sharedIdentity(candidate, key).fingerprint) throw Error('Shared worker changed; disable this client and coordinate an explicit shared worker upgrade before updating');
       await checkFolders(config,candidate,home);
       const stage={...candidate,compose:path.join(dir,'compose.json')};await atomic(stage.compose,await compose(config,stage,secrets,home));
       for(const [service,spec] of Object.entries(stage.deployment.services))await run('docker',[...pluginArgs(stage),spec.image?'pull':'build',service]);
-      const running=Boolean((await run('docker',[...pluginArgs(old),'ps','--status','running','-q'])).trim());
-      job.rollback={record:old,registry:structuredClone(r),compose:await read(old.compose),running};await save();
-      await run('docker',[...pluginArgs(old),'stop']);
-      const backup=path.join(dir,'backup');await fs.mkdir(backup,{mode:0o700});
-      const volumes=new Set(Object.values(old.deployment.services).flatMap(s=>Object.keys(s.volumes||{})));
-      for(const name of volumes)await backupVolume(run,old,name,backup);
-      await atomic(old.compose,await compose(config,candidate,secrets,home));
-      if(running)await run('docker',[...pluginArgs(candidate),'up','-d','--wait','--wait-timeout','90','--no-build']);
-      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.runtimeVerified=running;
+      return await locked(home,async()=>{
+        try {
+          const current=await eligibility(home,job.target,root,job.automatic);
+          if(current.old.root!==job.previousRoot||current.old.pkg.version!==job.previousVersion||JSON.stringify(current.old.record)!==JSON.stringify(old)||JSON.stringify((await state(home)).config)!==JSON.stringify(config))throw Error('Stale upgrade job');
+          if(await brokerNeedsRefresh(config,run)&&!hooks.refreshPluginBroker)throw Error('Broker host binding changed; retry the plugin update after native work drains');
+          const r=await read(path.join(home,'registry.json'));
+          const running=Boolean((await run('docker',[...pluginArgs(old),'ps','--status','running','-q'])).trim());
+          job.rollback={record:old,registry:structuredClone(r),compose:await read(old.compose),running};await save();
+          await run('docker',[...pluginArgs(old),'stop']);
+          const backup=path.join(dir,'backup');await fs.mkdir(backup,{mode:0o700});
+          const volumes=new Set(Object.values(old.deployment.services).flatMap(s=>Object.keys(s.volumes||{})));
+          for(const name of volumes)await backupVolume(run,old,name,backup);
+          await atomic(old.compose,await compose(config,candidate,secrets,home));
+          if(running)await run('docker',[...pluginArgs(candidate),'up','-d','--wait','--wait-timeout','90','--no-build']);
+          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);
+          job.brokerReadiness=hooks.refreshPluginBroker?await refreshBroker(config,run):await verifyBroker(config,run);
+          await publishBrokerPlugins(home,agent.controlDir);
+          job.runtimeVerified=running;
+          return await complete();
+        } catch(error) { return fail(error,{...hooks,registryLocked:true}); }
+      },{drainInvocations:true,signal:hooks.signal});
     }
-    job.status='completed';job.endedAt=new Date().toISOString();await save();
-    try { job.cleanup=await cleanupStaleBackups(home);await save(); }
-    catch(error) { job.cleanupError=error.message;await save().catch(()=>{}); }
-    return job;
-  }catch(error){
-    let message=error.message;
-    if(job.target==='main'&&job.rollback&&/is unhealthy/.test(message))message+=await healthEvidence(config,run).catch(()=> '');
-    job.error=message;await save();return recover(home,job,hooks);
-  }
+    return await complete();
+  }catch(error){return fail(error,hooks);}
+
 }
 export async function recover(home,job,hooks) {
+  if(job.target!=='main'&&job.rollback&&!hooks.registryLocked)
+    return locked(home,()=>recover(home,job,{...hooks,registryLocked:true}),{drainInvocations:true,signal:hooks.signal});
   const run=hooks.execute||execute,{config}=await state(home);
   try {
     if(job.rollback) {
@@ -195,12 +270,14 @@ 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=hooks.refreshPluginBroker?await refreshBroker(config,run):await verifyBroker(config,run);
+        await publishBrokerPlugins(home,(await state(home)).agent.controlDir);
         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

@@ -5,7 +5,7 @@ import { spawn } from 'node:child_process';
 import { atomic, locked } from '../plugins/manager.mjs';
 import { callDeliverySocket } from '../delivery-socket-client.mjs';
 import { state, read, jobs, jobPath, check, prepare, submit, missing, cleanupStaleBackups } from './control.mjs';
-import { perform, environment } from './runtime.mjs';
+import { perform, environment, brokerNeedsRefresh } from './runtime.mjs';
 
 const reservedProviderKeys=new Set(['HOME','LANG','LC_ALL','LOGNAME','PATH','SHELL','TERM','TMPDIR','USER','CODEX_HOME','NODE_OPTIONS']);
 const providerEnvironmentKey=value=>{
@@ -52,6 +52,11 @@ export async function withIdleUpgrade(control,job,signal,apply,{isIdle=idle,wait
     if(!signal.aborted)return await apply();
   } finally {await fs.rm(pause,{force:true});}
 }
+// Plugin replacement drains command leases at activation, not native turns.
+export async function withUpgrade(control,job,signal,apply,options) {
+  if(job.target==='main'||options?.requiresIdle)return withIdleUpgrade(control,job,signal,apply,options);
+  if(!signal.aborted)return apply();
+}
 export async function queueAutomatic(home,available) {
   const existing=await jobs(home);
   if(existing.some(job=>['queued','applying','recovery-required'].includes(job.status)))return null;
@@ -94,6 +99,15 @@ export async function supervise(deployment,signal,{discover=check}={}) {
     await waitForHostHeartbeat(agent.controlDir,child,()=>error);
   };
   const pause=path.join(agent.controlDir,'upgrade-pause.json');
+  const refreshRequirement=async job=>{
+    if(job.target==='main')return false;
+    try {return await brokerNeedsRefresh((await state(home)).config);}
+    catch(error) {
+      job.status=job.status==='applying'?'recovery-required':'failed';job.error=error.message;
+      await atomic(path.join(jobPath(home,job.id),'job.json'),job);
+      return null;
+    }
+  };
   const beat=setInterval(()=>{void atomic(path.join(directory,'supervisor.json'),{pid:process.pid,at:Date.now()}).catch(()=>{});},1000);
   try {
     await atomic(path.join(directory,'supervisor.json'),{pid:process.pid,at:Date.now()});
@@ -107,8 +121,11 @@ export async function supervise(deployment,signal,{discover=check}={}) {
     await sleep(1200);
     const interrupted=(await jobs(home)).find(j=>j.status==='applying');
     if(interrupted){
-      await atomic(pause,{id:interrupted.id});const result=await locked(home,()=>perform(home,interrupted,{stopHost,startHost}));await fs.rm(pause,{force:true});
-      if(result.status==='completed'&&interrupted.target==='main')return;
+      const refreshPluginBroker=await refreshRequirement(interrupted);
+      const result=refreshPluginBroker===null?undefined:interrupted.target==='main'
+        ? await (async()=>{await atomic(pause,{id:interrupted.id});try{return await locked(home,()=>perform(home,interrupted,{stopHost,startHost}));}finally{await fs.rm(pause,{force:true});}})()
+        : await withUpgrade(agent.controlDir,interrupted,signal,()=>perform(home,interrupted,{stopHost,startHost,signal,refreshPluginBroker}),{requiresIdle:refreshPluginBroker});
+      if(result?.status==='completed'&&interrupted.target==='main')return;
     }
     const isolated=host.isolation==='isolated'
     if(!isolated && !child)await startHost((await state(home)).config.packageRoot);
@@ -117,15 +134,19 @@ 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) {
-        const result=await withIdleUpgrade(agent.controlDir,pending,signal,async()=>{
+        const refreshPluginBroker=await refreshRequirement(pending);
+        if(refreshPluginBroker===null)continue;
+        const apply=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});});
+            const activate=async()=>{const latest=await read(path.join(jobPath(home,pending.id),'job.json'));return perform(home,latest,{stopHost,startHost,signal,refreshPluginBroker});};
+            return pending.target==='main'?await locked(home,activate):await activate();
           } 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;
           }
-        });
+        };
+        const result=await withUpgrade(agent.controlDir,pending,signal,apply,{requiresIdle:refreshPluginBroker});
         if(result?.status==='completed') {
           if(pending.target==='main')return;
           nextCheck=0;