@jc_stack/ez-agents 0.1.0-beta.29 → 0.1.0-beta.32

package/src/application-channel.ts

@@ -7,7 +7,10 @@ import { RunStore, type RunRecord, type OutboxItem } from './runs.js'
 import { ownsRun } from './identity.js'
 import { applicationId, validApplicationOrigin } from './application-origin.js'
 import { isPreset, type AiPreset, type ModelChoice } from './ai.js'
+import { MAX_INCOMING_ATTACHMENT_BYTES, stageChatAttachment } from './files.js'
 import { assertEffort } from './model-policy.js'
+import { ApprovalStore } from './approval.js'
+import { Tasks } from './tasks.js'
 
 const hash = (value: string) => createHash('sha256').update(value).digest('hex')
 export const applicationScope = (bindingId: string, scope: string) => hash(JSON.stringify([bindingId, scope]))
@@ -68,7 +71,7 @@ export class ApplicationChannel {
   private admissions = Promise.resolve()
   readonly bindings: ApplicationBindings
   constructor(private options: {
-    controlDir: string; initial: AiPreset
+    controlDir: string; workspace?: string; initial: AiPreset
     wake: () => void
     cancel: (id: string) => Promise<void>
     aiControls?: {
@@ -192,8 +195,8 @@ export class ApplicationChannel {
         if ('followTelegram' in rest) throw new Error('Invalid application request: choose one conversation option')
         input = {...rest, followTelegram: followOwner}
       }
-      const value = input as { requestId?: unknown; scope?: unknown; text?: unknown; context?: Record<string, unknown>; expectedNativeSessionId?: unknown; activateTelegram?: unknown; followTelegram?: unknown; ai?: { cli?: unknown; model?: unknown; effort?: unknown } }
-      if (!value || !applicationId(value.requestId) || !applicationId(value.scope) || typeof value.text !== 'string' || !value.text.trim() || value.text.length > 16000 || Object.keys(value).some(key => !['requestId','scope','text','context','expectedNativeSessionId','activateTelegram','followTelegram','ai'].includes(key))) throw new Error('Invalid application request')
+      const value = input as { requestId?: unknown; scope?: unknown; text?: unknown; attachment?: { name?: unknown; data?: unknown }; context?: Record<string, unknown>; expectedNativeSessionId?: unknown; activateTelegram?: unknown; followTelegram?: unknown; ai?: { cli?: unknown; model?: unknown; effort?: unknown } }
+      if (!value || !applicationId(value.requestId) || !applicationId(value.scope) || typeof value.text !== 'string' || (!value.text.trim() && value.attachment === undefined) || value.text.length > 16000 || Object.keys(value).some(key => !['requestId','scope','text','attachment','context','expectedNativeSessionId','activateTelegram','followTelegram','ai'].includes(key))) throw new Error('Invalid application request')
       if (value.expectedNativeSessionId !== undefined && (typeof value.expectedNativeSessionId !== 'string' || !/^[a-zA-Z0-9_-]{1,160}$/.test(value.expectedNativeSessionId))) throw new Error('Invalid application native session assertion')
       if (value.activateTelegram !== undefined && typeof value.activateTelegram !== 'boolean') throw new Error('Invalid application Telegram activation')
       if (value.followTelegram !== undefined && typeof value.followTelegram !== 'boolean') throw new Error('Invalid application Telegram following')
@@ -205,7 +208,17 @@ export class ApplicationChannel {
         assertEffort(candidate.effort, candidate.model, candidate.cli)
         requestedPreset = candidate
       }
-      const application = { bindingId, requestId: value.requestId, scope: value.scope, ...(value.followTelegram ? { followTelegram: true } : {}), ...(value.context === undefined ? {} : { context: value.context }) }
+      let bytes: Buffer | undefined
+      if (value.attachment !== undefined) {
+        const attachment = value.attachment
+        if (!attachment || typeof attachment.name !== 'string' || !attachment.name.length || attachment.name.length > 255 ||
+          typeof attachment.data !== 'string' || attachment.data.length > Math.ceil(MAX_INCOMING_ATTACHMENT_BYTES / 3) * 4 ||
+          Object.keys(attachment).some(key => !['name', 'data'].includes(key))) throw new Error('Invalid application attachment')
+        bytes = Buffer.from(attachment.data, 'base64')
+        if (!bytes.length || bytes.length > MAX_INCOMING_ATTACHMENT_BYTES || bytes.toString('base64') !== attachment.data) throw new Error('Invalid application attachment encoding or size')
+      }
+      const attachmentHash = bytes ? hash(JSON.stringify([value.attachment!.name, bytes.toString('base64')])) : undefined
+      const application = { bindingId, requestId: value.requestId, scope: value.scope, ...(attachmentHash ? {inputText: value.text, attachmentHash} : {}), ...(value.followTelegram ? { followTelegram: true } : {}), ...(value.context === undefined ? {} : { context: value.context }) }
       if (!validApplicationOrigin(application)) throw new Error('Invalid application context')
       const binding = (await this.bindings.list()).find(item => item.bindingId === bindingId)
       if (!binding) throw new Error('Application authority revoked')
@@ -215,13 +228,18 @@ export class ApplicationChannel {
       if (existing) {
         await this.bindings.authorize(existing)
         if (requestedPreset && (existing.execution?.preset.cli !== requestedPreset.cli || existing.execution?.preset.model !== requestedPreset.model || existing.execution?.preset.effort !== requestedPreset.effort)) throw new Error('Application request ID conflicts with prior AI selection')
-        if (Boolean(existing.application?.followTelegram) !== Boolean(value.followTelegram) || existing.application?.scope !== value.scope || existing.texts[0] !== value.text) throw new Error('Application request ID conflicts with prior scope or text')
+        if (Boolean(existing.application?.followTelegram) !== Boolean(value.followTelegram) || existing.application?.scope !== value.scope || (existing.application?.inputText ?? existing.texts[0]) !== value.text || existing.application?.attachmentHash !== attachmentHash) throw new Error('Application request ID conflicts with prior scope or text')
         return existing // Retried context never replaces already admitted capabilities.
       }
       const control = new ControlStore(this.options.controlDir, 900000)
       if (!sameOwner(binding.owner, (await control.status()).owner)) throw new Error('Application authority revoked')
+      if (bytes && !this.options.workspace) throw new Error('Invalid application attachment: workspace unavailable')
+      const staged = bytes ? await stageChatAttachment(this.options.workspace!, value.attachment!.name as string, bytes, value.text) : undefined
+      let run: RunRecord
+      try {
       const execution = value.followTelegram ? await control.captureChoice(this.options.initial) : await control.captureApplicationChoice(this.options.initial, applicationScope(bindingId, value.scope), binding.shareTelegram === true && value.activateTelegram === true, requestedPreset, value.expectedNativeSessionId as string | undefined)
-      const run = await this.runs.create({ id, ownerId: ownerId(binding.owner), ownerEpoch: ownerEpoch(binding.owner), texts: [value.text], execution, application })
+        run = await this.runs.create({ id, ownerId: ownerId(binding.owner), ownerEpoch: ownerEpoch(binding.owner), texts: [staged?.text ?? value.text], execution, application }) }
+      catch (error) { if (staged) await unlink(staged.fullPath).catch(() => {}); throw error }
       this.options.wake()
       return run
     })
@@ -234,11 +252,11 @@ export class ApplicationChannel {
     await this.bindings.authorize(run)
     const state = await new ControlStore(this.options.controlDir, 900000).status()
     const session = state.activeSession?.sessionId === run.execution?.sessionId ? state.activeSession : state.sessions?.find(item => item.sessionId === run.execution?.sessionId)
-    return { ...(session ? { sessionId: session.sessionId, nativeSessionId: session.nativeSessionId, cli: session.cli } : {}), ...(run.scheduled?.originRunId ? {originRunId:run.scheduled.originRunId} : {}), id: run.id, scope: (run.application ?? run.delivery)!.scope, status: run.status, messages: await this.runs.applicationMessages(run.id), ...(run.status === 'failed' ? { error: 'Agent execution failed; inspect the core run' } : {}) }
+    return { ...(session ? { sessionId: session.sessionId, nativeSessionId: session.nativeSessionId, cli: session.cli } : {}), ...(run.scheduled?.originRunId ? {originRunId:run.scheduled.originRunId} : {}), id: run.id, scope: (run.application ?? run.delivery)!.scope, status: run.status, messages: await this.runs.applicationMessages(run.id), approvals:await this.runs.applicationApprovals(run.id), ...(run.status === 'failed' ? { error: 'Agent execution failed; inspect the core run' } : {}) }
   }
   async deliver(run: RunRecord, item: OutboxItem): Promise<void> {
     await this.bindings.authorize(run)
-    if (item.type && item.type !== 'message') throw new Error('Application channel supports text messages only')
+    if (item.type && !['message','approval'].includes(item.type)) throw new Error('Application channel supports text messages and approvals only')
     await this.runs.markOutboxSent(item.id)
   }
   private async route(request: IncomingMessage, response: ServerResponse) {
@@ -277,12 +295,25 @@ export class ApplicationChannel {
       }
       if (request.method === 'POST' && path === '/v1/runs') {
         const chunks: Buffer[] = []; let size = 0
-        for await (const chunk of request) { size += chunk.length; if (size > 65536) throw new Error('Application request too large'); chunks.push(chunk) }
+        for await (const chunk of request) { size += chunk.length; if (size > Math.ceil(MAX_INCOMING_ATTACHMENT_BYTES / 3) * 4 + 256 * 1024) throw new Error('Application request too large'); chunks.push(chunk) }
         const input = JSON.parse(Buffer.concat(chunks).toString('utf8'))
         if (applicationId(input?.requestId)) admissionId = `r_app_${hash(JSON.stringify([binding.bindingId, input.requestId]))}`
         const run = await this.submit(binding.bindingId, input)
         send(202, await this.snapshot(binding.bindingId, run.id)); return
       }
+      const approvalMatch=path.match(/^\/v1\/approvals\/(task_[a-f0-9]{32})$/)
+      if(approvalMatch && request.method==='POST') {
+        const approval=await new ApprovalStore(this.options.controlDir).getDecision(approvalMatch[1])
+        const run=approval?.runId ? await this.runs.get(approval.runId) : null
+        if(!run || run.application?.bindingId!==binding.bindingId)throw new Error('Unknown application approval')
+        await this.bindings.authorize(run)
+        const chunks:Buffer[]=[];let size=0;for await(const chunk of request){size+=chunk.length;if(size>1024)throw new Error('Invalid application approval');chunks.push(chunk)}
+        const input=JSON.parse(Buffer.concat(chunks).toString('utf8'))
+        if(!input || !['approved','denied'].includes(input.decision) || Object.keys(input).some(key=>key!=='decision'))throw new Error('Invalid application approval')
+        await new ApprovalStore(this.options.controlDir).recordOwnerDecision(approvalMatch[1],input.decision,binding.owner)
+        if(!await new Tasks(this.options.controlDir).decide(approvalMatch[1]))throw new Error('Unknown application approval')
+        send(200,{id:approvalMatch[1],decision:input.decision});return
+      }
       const match = path.match(/^\/v1\/runs\/(r_(?:app|schedule)_[a-f0-9]{64})(\/cancel)?$/)
       if (match && ((!match[2] && request.method === 'GET') || (match[2] && request.method === 'POST'))) {
         await this.snapshot(binding.bindingId, match[1])

package/src/application-origin.ts

@@ -3,6 +3,8 @@ export type ApplicationOrigin = {
   scope: string
   requestId: string
   followTelegram?: boolean
+  inputText?: string
+  attachmentHash?: string
   context?: Record<string, unknown>
 }
 export const applicationId = (value: unknown): value is string =>
@@ -11,5 +13,7 @@ export const validApplicationOrigin = (value: unknown): value is ApplicationOrig
   const origin = value as ApplicationOrigin | undefined
   return !!origin && /^[a-f0-9-]{36}$/.test(origin.bindingId) && applicationId(origin.scope) && applicationId(origin.requestId) &&
     (origin.followTelegram === undefined || typeof origin.followTelegram === 'boolean') &&
+    (origin.inputText === undefined || (typeof origin.inputText === 'string' && origin.inputText.length <= 16000)) &&
+    (origin.attachmentHash === undefined || /^[a-f0-9]{64}$/.test(origin.attachmentHash)) &&
     (origin.context === undefined || (!!origin.context && typeof origin.context === 'object' && !Array.isArray(origin.context) && JSON.stringify(origin.context).length <= 48000))
 }

package/src/approval.ts

@@ -1,11 +1,12 @@
 import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 import { assertId } from './identity.js'
+import { ownerEpoch, ownerId, type Owner } from './control-state.js'
 
 export type ApprovalDecision = 'pending' | 'approved' | 'denied'
 
 export type ApprovalRecord = {
-  version: 1
+  version: 1 | 2
   actionId: string
   runId?: string
   prompt: string
@@ -14,19 +15,22 @@ export type ApprovalRecord = {
   decidedAt?: string
   decidedBy?: number
   decisionUpdateId?: number
+  decidedOwnerId?: string
+  decidedOwnerEpoch?: string
 }
 
 const isApprovalRecord = (value: unknown): value is ApprovalRecord => {
   if (!value || typeof value !== 'object') return false
   const candidate = value as Partial<ApprovalRecord>
   return (
-    candidate.version === 1 &&
+    [1,2].includes(candidate.version ?? 0) &&
     typeof candidate.actionId === 'string' &&
     /^[a-zA-Z0-9_-]{1,40}$/.test(candidate.actionId) &&
     typeof candidate.prompt === 'string' &&
     ['pending', 'approved', 'denied'].includes(candidate.decision ?? '') &&
     typeof candidate.createdAt === 'string' &&
-    Number.isFinite(Date.parse(candidate.createdAt))
+    Number.isFinite(Date.parse(candidate.createdAt)) &&
+    (candidate.version === 1 || typeof candidate.decidedOwnerId === 'string' && typeof candidate.decidedOwnerEpoch === 'string')
   )
 }
 
@@ -105,6 +109,18 @@ export class ApprovalStore {
     return record
   }
 
+  async recordOwnerDecision(actionId: string, decision: 'approved' | 'denied', owner: Owner): Promise<ApprovalRecord> {
+    await this.ensure()
+    const existing = await this.getDecision(actionId)
+    if (!existing) throw new Error('Unknown approval request')
+    if (existing.decision !== 'pending') throw new Error('Approval already decided')
+    if (Date.now() - Date.parse(existing.createdAt) > 900_000) throw new Error('Approval expired')
+    const record: ApprovalRecord = {...existing,version:2,decision,decidedAt:new Date().toISOString(),decidedOwnerId:ownerId(owner),decidedOwnerEpoch:ownerEpoch(owner)}
+    const file=this.filePath(actionId),temporary=`${file}.${process.pid}.tmp`
+    await writeFile(temporary,`${JSON.stringify(record,null,2)}\n`,{mode:0o600});await rename(temporary,file)
+    return record
+  }
+
   async getDecision(actionId: string): Promise<ApprovalRecord | null> {
     try {
       const parsed: unknown = JSON.parse(await readFile(this.filePath(actionId), 'utf8'))

package/src/codex-session.ts

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url'
 import path from 'node:path'
 import { terminateJob } from './executor.js'
 
-type Options = {workspace:string;controlDir:string;toolsHome?:string;sharedWorkspace?:string;model?:string;effort?:string;prompt:string;codexSandbox?:'external'}
+type Options = {workspace:string;controlDir:string;toolsHome?:string;sharedWorkspace?:string;additionalWorkspaces?:string[];model?:string;effort?:string;prompt:string;codexSandbox?:'external'}
 type Message = {id?:number;method?:string;params?:any;result?:any;error?:{message:string;code?:number}}
 
 // Keep Codex's native session alive. Codex itself starts goal continuation turns;
@@ -72,7 +72,7 @@ export async function runCodexSession(options:Options, io:{launch?:()=>ChildProc
     send({method:'initialized',params:{}})
     const result=await request('thread/start',{
       cwd:options.workspace,approvalPolicy:'never',sandbox:options.codexSandbox === 'external' ? 'danger-full-access' : 'workspace-write',model:options.model,
-      config:{project_root_markers:['AGENTS.md','.git'],'sandbox_workspace_write.writable_roots':[options.controlDir,...(options.toolsHome?[options.toolsHome]:[]),...(options.sharedWorkspace?[options.sharedWorkspace]:[])],
+      config:{project_root_markers:['AGENTS.md','.git'],'sandbox_workspace_write.writable_roots':[options.controlDir,...(options.toolsHome?[options.toolsHome]:[]),...(options.sharedWorkspace?[options.sharedWorkspace]:[]),...(options.additionalWorkspaces ?? [])],
         'sandbox_workspace_write.network_access':Boolean(options.toolsHome),...(options.effort?{model_reasoning_effort:options.effort}:{})},
     })
     threadId=result.thread?.id

package/src/desktop-bridge.ts

@@ -3,6 +3,7 @@ import { executionDefaults } from './model-policy.js'
 import { access, constants } from 'node:fs/promises'
 import { createHash, randomBytes } from 'node:crypto'
 import { createConnection, type Socket } from 'node:net'
+import { execFile } from 'node:child_process'
 import { homedir } from 'node:os'
 import { delimiter, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -29,6 +30,7 @@ export type DesktopClient = {
   request: (method: string, params?: unknown) => Promise<Record<string, unknown>>
   notify: (method: string, params?: unknown) => void
   wait: (match: (message: Record<string, unknown>) => boolean, timeoutMs: number) => Promise<Record<string, unknown>>
+  setServerRequestContext: (threadId?: string, turnId?: string) => void
   close: () => void
 }
 
@@ -57,6 +59,8 @@ export const desktopCodexPath = async (home = homedir(), envPath = process.env.P
 const writableRoots = (options: DesktopTurnOptions): string[] =>
   [options.controlDir, options.toolsHome].filter((value): value is string => Boolean(value))
 
+const approvalPolicy = (scheduledDesktop: boolean): 'on-request' | 'never' => scheduledDesktop ? 'on-request' : 'never'
+
 const sendFrame = (socket: Socket, text: string) => {
   const payload = Buffer.from(text)
   const mask = randomBytes(4)
@@ -71,6 +75,29 @@ const sendFrame = (socket: Socket, text: string) => {
   socket.write(Buffer.concat([header, mask, masked]))
 }
 
+export const desktopServerRequestResult = (
+  message: Record<string, unknown>,
+  context?: { threadId: string; turnId?: string },
+): Record<string, unknown> => {
+  if (message.method === 'mcpServer/elicitation/request') {
+    const params = message.params as { threadId?: unknown; turnId?: unknown; _meta?: Record<string, unknown> } | undefined
+    const meta = params?._meta
+    const toolParams = meta?.tool_params as Record<string, unknown> | undefined
+    const origin = toolParams?.origin
+    const browserOrigin = meta?.connector_id === 'browser-use' && meta.codex_approval_kind === 'mcp_tool_call' &&
+      meta.codex_request_type === 'approval_request' && meta.tool_name === 'access_browser_origin' &&
+      typeof origin === 'string' && /^https?:\/\//.test(origin) && meta.origin === origin
+    const chromeApp = meta?.connector_id === 'computer-use' && meta.codex_approval_kind === 'mcp_tool_call' &&
+      meta.codex_request_type !== 'approval_request' && meta.tool_name !== 'start_audio_recording' &&
+      toolParams?.app === 'com.google.Chrome'
+    if (context && params?.threadId === context.threadId && typeof params.turnId === 'string' &&
+      (!context.turnId || params.turnId === context.turnId) && (browserOrigin || chromeApp))
+      return { action: 'accept', content: null, _meta: { persist: 'session' } }
+    return { action: 'decline', content: null, _meta: null }
+  }
+  return { decision: 'decline' }
+}
+
 export const attachClient = (socket: Socket, pending: Buffer[] = []): DesktopClient => {
   let buffer = Buffer.concat(pending)
   let nextId = 1
@@ -79,6 +106,7 @@ export const attachClient = (socket: Socket, pending: Buffer[] = []): DesktopCli
   const failedWaits = new Set<() => void>()
   const notifications: Record<string, unknown>[] = []
   const watchers: Array<(message: Record<string, unknown>) => void> = []
+  let serverRequestContext: { threadId: string; turnId?: string } | undefined
   const deliver = (message: Record<string, unknown>) => {
     const id = message.id
     if (typeof id === 'number' && replies.has(id) && (message.result !== undefined || message.error)) {
@@ -89,8 +117,13 @@ export const attachClient = (socket: Socket, pending: Buffer[] = []): DesktopCli
       else reply.resolve(message.result as Record<string, unknown>)
       return
     }
-    if (typeof id === 'number' && typeof message.method === 'string') {
-      sendFrame(socket, JSON.stringify({ id, result: { decision: 'approved' } }))
+    if ((typeof id === 'number' || typeof id === 'string') && typeof message.method === 'string') {
+      const result = desktopServerRequestResult(message, serverRequestContext)
+      if (result.action === 'accept' && serverRequestContext && !serverRequestContext.turnId) {
+        const turnId = (message.params as { turnId?: unknown } | undefined)?.turnId
+        if (typeof turnId === 'string') serverRequestContext.turnId = turnId
+      }
+      sendFrame(socket, JSON.stringify({ id, result }))
       return
     }
     notifications.push(message)
@@ -168,6 +201,9 @@ export const attachClient = (socket: Socket, pending: Buffer[] = []): DesktopCli
       failedWaits.add(fail)
       watchers.push(watcher)
     }),
+    setServerRequestContext: (threadId, turnId) => {
+      serverRequestContext = threadId ? { threadId, turnId } : undefined
+    },
     close: () => socket.destroy(),
   }
 }
@@ -200,6 +236,32 @@ export const connectDesktop = (socketPath = desktopControlSocket()): Promise<Des
     socket.on('data', onData)
   })
 
+const startDesktopDaemon = async (
+  home = homedir(),
+  envPath = process.env.PATH || '',
+  run: typeof execFile = execFile,
+): Promise<void> => {
+  const codex = await desktopCodexPath(home, envPath)
+  if (!codex) throw new Error(DESKTOP_UNAVAILABLE)
+  await new Promise<void>((resolve, reject) => run(codex, ['app-server', 'daemon', 'start'], {
+    env: { HOME: home, PATH: envPath }, timeout: 15_000, maxBuffer: 64 * 1024,
+  }, (error) => error ? reject(new Error(DESKTOP_UNAVAILABLE)) : resolve()))
+}
+
+export const connectManagedDesktop = async (
+  connect: typeof connectDesktop = connectDesktop,
+  start: typeof startDesktopDaemon = startDesktopDaemon,
+): Promise<DesktopClient> => {
+  try { return await connect() }
+  catch {
+    // The native Codex daemon owns its lifecycle and is idempotent. New desktop
+    // builds do not necessarily create the control socket merely by opening the
+    // app, so ask Codex to restore its own bridge before failing closed.
+    await start()
+    return connect()
+  }
+}
+
 export const runDesktopTurn = async (
   options: DesktopTurnOptions,
   io: { connect?: typeof connectDesktop; emit?: (line: string) => void; signal?: AbortSignal } = {},
@@ -208,7 +270,8 @@ export const runDesktopTurn = async (
   const emit = io.emit ?? ((line: string) => process.stdout.write(`${line}\n`))
   let client: DesktopClient | undefined
   try {
-    client = await (io.connect ?? connectDesktop)()
+    const scheduledDesktop = options.runId.startsWith('r_schedule_')
+    client = await (io.connect ?? connectManagedDesktop)()
     await client.request('initialize', { clientInfo: { name: 'ezenciel-agents', title: 'ez', version: '1' } })
     client.notify('initialized', {})
     const roots = writableRoots(options)
@@ -227,7 +290,7 @@ export const runDesktopTurn = async (
       const started = await client.request('thread/start', {
         cwd: options.workspace,
         config,
-        approvalPolicy: 'never',
+        approvalPolicy: approvalPolicy(scheduledDesktop),
         sandbox: 'workspace-write',
         model: options.model,
         serviceName: 'ezenciel-agents',
@@ -238,17 +301,19 @@ export const runDesktopTurn = async (
     }
     if (!nativeThread(threadId)) throw new Error(DESKTOP_UNAVAILABLE)
     emit(JSON.stringify({ type: 'thread.started', thread_id: threadId }))
+    client.setServerRequestContext(scheduledDesktop ? threadId! : undefined)
     const turn = await client.request('turn/start', {
       threadId,
       input: [{ type: 'text', text: options.prompt }],
       model: options.model,
       effort: options.effort,
       cwd: options.workspace,
-      approvalPolicy: 'never',
+      approvalPolicy: approvalPolicy(scheduledDesktop),
       sandboxPolicy: { type: 'workspaceWrite', writableRoots: roots, networkAccess: Boolean(options.toolsHome) },
     })
     const turnId = (turn.turn as { id?: string } | undefined)?.id
     if (!turnId) throw new Error(DESKTOP_UNAVAILABLE)
+    if (scheduledDesktop) client.setServerRequestContext(threadId!, turnId)
     const interrupt = () => { void client?.request('turn/interrupt', { threadId, turnId }).catch(() => {}) }
     io.signal?.addEventListener('abort', interrupt, { once: true })
     if (io.signal?.aborted) interrupt()

package/src/event-sources.ts

@@ -2,21 +2,22 @@ import { mkdir, open, readFile, rename, unlink, lstat } from 'node:fs/promises'
 import { join, isAbsolute } from 'node:path'
 import { randomUUID, createHash } from 'node:crypto'
 import { request } from 'node:http'
-import type { Owner } from './control-state.js'
+import { sameOwner, validOwner, type Owner } from './control-state.js'
 
-export type ExternalOrigin = { sourceId: string; bindingId: string; eventIds: string[] }
+export type ExternalOrigin = { sourceId: string; bindingId: string; conversationId?: string; eventIds: string[] }
 export type SourceEvent = { id: string; conversationId: string; receivedAt: number; text: string }
 export type EventSource = { id: string; bindingId: string; socketPath: string; initialCursor: number; owner: Owner }
 const identifier = (s: unknown): s is string => typeof s === 'string' && /^[a-zA-Z0-9_-]{1,100}$/.test(s)
 export const validOrigin = (o: unknown): o is ExternalOrigin => {
   const v = o as ExternalOrigin | undefined
-  return !!v && identifier(v.sourceId) && identifier(v.bindingId) && Array.isArray(v.eventIds) && v.eventIds.length > 0 && v.eventIds.length <= 10 && v.eventIds.every(identifier)
+  return !!v && identifier(v.sourceId) && identifier(v.bindingId) &&
+    (v.conversationId === undefined || typeof v.conversationId === 'string' && v.conversationId.length > 0 && v.conversationId.length <= 200) &&
+    Array.isArray(v.eventIds) && v.eventIds.length > 0 && v.eventIds.length <= 10 && v.eventIds.every(identifier)
 }
 const cursorOK = (v: unknown): v is number => Number.isSafeInteger(v) && Number(v) >= 0
 export const validEvents = (v: unknown): v is SourceEvent[] => Array.isArray(v) && v.length <= 10 && v.every(e =>
   identifier(e?.id) && typeof e.conversationId === 'string' && e.conversationId.length > 0 && e.conversationId.length <= 200 &&
   Number.isFinite(e.receivedAt) && typeof e.text === 'string' && e.text.length <= 16000) && new Set(v.map(e => e.id)).size === v.length
-const sameOwner = (a: Owner, b: Owner) => a.telegramUserId === b.telegramUserId && a.telegramChatId === b.telegramChatId
 async function read<T>(path: string, fallback: T): Promise<T> {
   try { return JSON.parse(await readFile(path, 'utf8')) as T } catch (e) { if ((e as NodeJS.ErrnoException).code === 'ENOENT') return fallback; throw new Error('Unreadable event-source state') }
 }
@@ -49,8 +50,7 @@ export class EventSources {
     const value = await read<{ version: number; sources: EventSource[] }>(this.registry, { version: 1, sources: [] })
     if (value.version !== 1 || !Array.isArray(value.sources) || value.sources.some(s => !identifier(s.id) || !identifier(s.bindingId) ||
       typeof s.socketPath !== 'string' || !isAbsolute(s.socketPath) || !cursorOK(s.initialCursor) ||
-      !Number.isSafeInteger(s.owner?.telegramUserId) || s.owner.telegramUserId! <= 0 || !Number.isSafeInteger(s.owner.telegramChatId) ||
-      (s.owner.kind === 'group' ? s.owner.telegramChatId! >= 0 : s.owner.kind !== undefined || s.owner.telegramChatId! <= 0)) ||
+      !validOwner(s.owner)) ||
       new Set(value.sources.map(s => s.id)).size !== value.sources.length) throw new Error('Invalid event-source registry')
     return value.sources
   }
@@ -106,6 +106,13 @@ export class EventSources {
     if (!validEvents(result?.events) || result.events.some((e: SourceEvent) => !origin.eventIds.includes(e.id))) throw new Error('Invalid event recheck')
     return result.events
   }
+  async release(origin: ExternalOrigin, owner: Owner): Promise<void> {
+    if (!validOrigin(origin)) return
+    const source = (await this.available(owner)).find(s => s.id === origin.sourceId && s.bindingId === origin.bindingId)
+    if (!source) return
+    const head = await sourceCall(source.socketPath, 'events-head')
+    if (head.releaseEvents === true) await sourceCall(source.socketPath, 'events-release', {ids:origin.eventIds})
+  }
 }
 export const eventRunId = (source: EventSource, events: SourceEvent[]) => 'event_' + createHash('sha256')
   .update(JSON.stringify([source.bindingId, events.map(e => e.id)])).digest('hex')

package/src/executor.ts

@@ -21,6 +21,7 @@ export type ExecutorOptions = {
   binDir: string
   toolsHome?: string
   sharedWorkspace?: string
+  additionalWorkspaces?: string[]
   cli?: string
   sessionId?: string
   isResume?: boolean
@@ -75,7 +76,7 @@ export type CliAdapter = {
   command: string
   description: string
   buildArgs: (
-    options: Pick<ExecutorOptions, 'workspace' | 'sessionId' | 'isResume' | 'model' | 'effort' | 'toolsHome' | 'sharedWorkspace' | 'codexAutoCompactTokens' | 'codexSandbox'> & { controlDir?: string },
+    options: Pick<ExecutorOptions, 'workspace' | 'sessionId' | 'isResume' | 'model' | 'effort' | 'toolsHome' | 'sharedWorkspace' | 'additionalWorkspaces' | 'codexAutoCompactTokens' | 'codexSandbox'> & { controlDir?: string },
     promptFile: string,
     promptText: string,
   ) => string[]
@@ -94,6 +95,7 @@ export const EXECUTOR_REGISTRY: Record<string, CliAdapter> = {
       }
       if (opts.controlDir) args.push('--add-dir', opts.controlDir)
       if (opts.sharedWorkspace) args.push('--add-dir', opts.sharedWorkspace)
+      for (const workspace of opts.additionalWorkspaces ?? []) args.push('--add-dir', workspace)
       if (opts.toolsHome) args.push('--add-dir', opts.toolsHome, '-c', 'sandbox_workspace_write.network_access=true')
       if (opts.model) args.push('--model', opts.model)
       if (opts.effort) args.push('-c', `model_reasoning_effort=${JSON.stringify(opts.effort)}`)
@@ -248,7 +250,7 @@ export const startExecutorJob = async (
   const nativeSession = !host && key === 'codex' && options.runId.startsWith('r_schedule_')
   // Chat-mode experiment: only direct chat input at the engine boundary.
   const applicationReminder = !host && (run?.application || run?.delivery)
-    ? '\n\n[Application channel] This is an owner-authorized application conversation. Send text replies using ezenciel-agents-message; stdout alone is not delivered. Attachments/reactions/approval controls are unsupported here. Domain tools can retrieve private context from ezenciel-agents-schedule context under run.application.context; do not expose credentials from that data. The application scope is ' + JSON.stringify((run.application ?? run.delivery)!.scope) + '.'
+    ? '\n\n[Application channel] This is an owner-authorized application conversation. Send text replies using ezenciel-agents-message; stdout alone is not delivered. Outgoing file delivery, reactions and approval controls are unsupported here. Domain tools can retrieve private context from ezenciel-agents-schedule context under run.application.context; do not expose credentials from that data. The application scope is ' + JSON.stringify((run.application ?? run.delivery)!.scope) + '.'
     : ''
   const chatReminder = !host && !run?.taskId && run?.messageId !== undefined
     ? '\n\n[Chat context] You are replying in chat. Send replies with ezenciel-agents-message --text "..."; your final answer alone is not delivered. Before lengthy tool or repository work, briefly acknowledge through that CLI. Keep chat responsive: use ezenciel-agents-schedule for long-running work and native subagents for useful independent parts. Decide when to delegate and what to send.'

package/src/files.ts

@@ -73,3 +73,15 @@ export const workspaceFile = async (workspace: string, file: string, regular = t
   if (regular && !(await stat(target)).isFile()) throw new Error('Expected a regular file')
   return target
 }
+
+// Canonical native-engine attachment metadata for every inbound channel.
+export const MAX_INCOMING_ATTACHMENT_BYTES = 10 * 1024 * 1024
+export const stageChatAttachment = async (workspace: string, name: string, bytes: Buffer, comment: string) => {
+  const type = detectFileType(bytes)
+  if (!bytes.length || bytes.length > MAX_INCOMING_ATTACHMENT_BYTES || type === 'unknown' ||
+    (type === 'text' && !/\.(txt|md|markdown)$/i.test(name))) throw new Error('Invalid application attachment: unsupported type or size')
+  const staged = await stageIncomingFile(workspace, name, bytes)
+  const kind = ['jpeg', 'png', 'webp'].includes(staged.fileType) ? 'image' : 'document'
+  return { text: `[Attached ${kind} staged at ${staged.relativePath} (type: ${staged.fileType}, size: ${bytes.length} bytes)]${comment ? `\n\nCaption: ${comment}` : ''}`,
+    attachment: {path: staged.relativePath, type: staged.fileType}, fullPath: staged.fullPath }
+}

package/src/host-executor-protocol.ts

@@ -1,2 +1,2 @@
-// Telegram batches, registered plugin events and locally created runs cross this transport.
-export const isHostRunId = (id: string): boolean => /^(?:r_[a-zA-Z0-9_]+|tg_\d+|event_[a-f0-9]{64})$/.test(id)
+// Telegram batches (including scheduler recovery), registered plugin events and locally created runs cross this transport.
+export const isHostRunId = (id: string): boolean => /^(?:r_[a-zA-Z0-9_]+|tg_(?:\d+|replay_\d+_\d{8})|event_[a-f0-9]{64})$/.test(id)

package/src/host-executor.ts

@@ -13,11 +13,14 @@ import type { ChildProcess } from 'node:child_process'
 import { taskWorkspace } from './task-workspace.js'
 import { packageVersion } from './version.js'
 import { installedPluginVersions } from './software-status.js'
+import { processSnapshot } from './process-tree.js'
 
 export type PluginNetworkRoute = { revisions:string[]; bindings:{service:string;network:string}[] }
-export type HostBinding = { name: string; workspace: string; controlDir: string; binDir: string; toolsHome?: string; sharedWorkspace?: string; pluginNetworkBindings?: Record<string, PluginNetworkRoute> }
+export type HostBinding = { name: string; workspace: string; controlDir: string; binDir: string; toolsHome?: string; sharedWorkspace?: string; additionalWorkspaces?: string[]; pluginNetworkBindings?: Record<string, PluginNetworkRoute> }
 export type HostInstallation = { cli: string; agents: HostBinding[] }
 
+const processStart = async (pid:number) => (await processSnapshot()).get(pid)?.birth
+
 export const serveHostExecutor = async (installation: HostInstallation, signal: AbortSignal, launch = startExecutorJob) => {
   resolveExecutor(installation.cli)
   if (new Set(installation.agents.map(a=>a.workspace)).size !== installation.agents.length ||
@@ -27,12 +30,17 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
   const tasks = new Set<Promise<void>>()
   const locks: string[] = []
   const sharedWorkspaces = new Map<HostBinding, string>()
+  const additionalWorkspaces = new Map<HostBinding, string[]>()
   const catalog = (agent: HostBinding) => readModels(undefined, undefined, path.join(agent.controlDir, 'cli', 'codex'))
   try {
     for (const agent of installation.agents) {
       if (![agent.workspace,agent.controlDir,agent.binDir].every(path.isAbsolute)) throw new Error('Host bindings require absolute paths')
       if (agent.sharedWorkspace && !path.isAbsolute(agent.sharedWorkspace)) throw new Error('Shared workspace requires an absolute path')
       if (agent.sharedWorkspace) sharedWorkspaces.set(agent, await realpath(agent.sharedWorkspace))
+      if (agent.additionalWorkspaces) {
+        if (!Array.isArray(agent.additionalWorkspaces) || agent.additionalWorkspaces.some(workspace=>typeof workspace!=='string' || !path.isAbsolute(workspace))) throw new Error('Additional workspaces require absolute paths')
+        additionalWorkspaces.set(agent,await Promise.all(agent.additionalWorkspaces.map(workspace=>realpath(workspace))))
+      }
       if (agent.toolsHome) {
         if (!path.isAbsolute(agent.toolsHome)) throw new Error('Plugin registry binding requires an absolute path')
         const config=JSON.parse(await readFile(path.join(agent.toolsHome,'config.json'),'utf8'))
@@ -41,9 +49,17 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
       const directory = path.join(agent.controlDir,'host-executor')
       await mkdir(directory,{recursive:true,mode:0o700})
       const lock=path.join(directory,'worker.lock')
-      try { const prior=JSON.parse(await readFile(lock,'utf8')); try { process.kill(prior.pid,0); throw new Error('Host executor already running') } catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error }; await rm(lock) }
+      try {
+        const prior=JSON.parse(await readFile(lock,'utf8'))
+        const currentStart=await processStart(prior.pid)
+        if (!prior.started || !currentStart || prior.started===currentStart) {
+          try { process.kill(prior.pid,0); throw new Error('Host executor already running') }
+          catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error }
+        }
+        await rm(lock)
+      }
       catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
-      await writeFile(lock,JSON.stringify({pid:process.pid}),{mode:0o600,flag:'wx'})
+      await writeFile(lock,JSON.stringify({pid:process.pid,started:await processStart(process.pid)}),{mode:0o600,flag:'wx'})
       locks.push(lock)
       await installAgentGuidance(agent.workspace)
       await writeFile(path.join(directory,'models.json'),JSON.stringify(await catalog(agent)),{mode:0o600})
@@ -114,7 +130,7 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
               const cli = opts.cli || installation.cli
               resolveExecutor(cli)
               if (cli !== installation.cli) await validateSelection({id:'selected',name:'Selected model',cli,model:opts.model,effort:opts.effort},await catalog(agent))
-              const options:ExecutorOptions={workspace:run?.scheduled ? await taskWorkspace(agent.workspace,id) : agent.workspace,controlDir:agent.controlDir,binDir:agent.binDir,toolsHome:agent.toolsHome,sharedWorkspace,cli,
+              const options:ExecutorOptions={workspace:run?.scheduled ? await taskWorkspace(agent.workspace,id) : agent.workspace,controlDir:agent.controlDir,binDir:agent.binDir,toolsHome:agent.toolsHome,sharedWorkspace,additionalWorkspaces:additionalWorkspaces.get(agent),cli,
                 runId:path.basename(base),timeoutMs:0,repairEnabled:opts.repairEnabled,
                 sessionId:opts.sessionId,isResume:opts.isResume,eventSource:opts.eventSource,model:opts.model,effort:opts.effort,codexAutoCompactTokens:opts.codexAutoCompactTokens}
               job=await launch(request.texts,options)