@jc_stack/ez-agents 0.1.0-beta.31 → 0.1.0-beta.33

package/docs/plugins.md

@@ -168,6 +168,29 @@ attention during setup/use; it does not enable an automated reviewer. Declaring
 false never grants permissions, disables core checks or certifies a plugin safe.
 The core owns authority; plugins own provider transport/authentication/receipts.
 
+A command may additionally set `"channelQuery": true` only when all four
+exposure fields are explicit and describe external input with no external send,
+record change, or interactive review. This is narrow eligibility for inclusion
+in an owner-approved restricted channel grant, not an activated permission or a
+safety label for the rest of the plugin. Mixed read/write aliases are ineligible;
+publish a dedicated query-only alias.
+
+For original file bytes, declare `"channelFile": true` instead, with the same
+read-only exposure fields. The approved task capability must specify
+`"output": "file"`. Its command accepts one literal input and writes only the
+file bytes to stdout (maximum 20 MiB across a run). Core returns an attachment ID and filename
+to the agent; binary content stays in private task staging. The input basename
+supplies the download filename.
+
+The task's existing `send` tool accepts `attachmentId` plus text and an
+idempotency key. Only a completed file capability from that run can supply it.
+The destination remains the authorized conversation. Providers opt in through
+`events-head.taskAttachments: true`, optionally declaring `attachmentCaptionLimit`,
+and accept the attachment metadata in `task-send`. Telegram delivers a document
+with a caption of at most 1024 characters; channels without this contract fail
+explicitly before dispatch. Staged bytes are removed when the external run is
+released. File capability access must be included in the owner's grant.
+
 Owner adapters retain owner access. External correspondence can run only in an
 approved core messaging task through the restricted task runner. Declarations
 and monitoring subscriptions alone never grant task execution. See

package/docs/responsive-channels.md

@@ -12,4 +12,7 @@ the message CLI. Native final text is not automatically delivered to Telegram.
 
 Restricted correspondence receives a typed activation event and scoped tools.
 Authorization, sandboxing and tool handlers enforce contact and lifecycle limits.
+An owner-approved channel capability adds only a fixed installed alias declared
+as a read-only channel query; it does not expose the workspace, shell, owner
+session or other installed tools.
 Maintenance and group notifications carry event data; CLI help owns operations.

package/docs/selective-monitoring.md

@@ -12,8 +12,9 @@ is a reminder, never an activated source, watch or reply permission.
 Keep mode names internal. Linking/syncing an account defaults to quiet capture;
 finish connection verification, then at most one short optional prompt such as
 “WhatsApp is connected. Want me to follow up with anyone?” Do not present a
-technical three-mode menu or suggest blanket autonomous replies that v1 cannot
-safely authorize. If the owner already gave a job, continue it without this prompt.
+technical three-mode menu. Suggest an any-conversation reply grant only when the
+owner has actually asked to serve everyone on that source. If the owner already
+gave a job, continue it without this prompt.
 
 Infer the complete job from ordinary language:
 
@@ -42,7 +43,8 @@ when it matters to that proposed job; never silently expand or renew permission.
 - Selected: wake for named contacts only. Never turn on all-inbox mode to satisfy
   a one-contact request.
 - All: attention for all eligible incoming contacts; requires that broader
-  owner request. Attention alone never grants autonomous reply permission.
+  owner request. Attention alone never grants autonomous reply permission; a
+  separate approved any-conversation task does.
 
 For an approved core reply task, the provider's task-watch supplies expiring
 selected attention even if its general policy remains manual. That is expected:
@@ -95,6 +97,56 @@ members of that approved group may converse; this does not grant owner tools.
 The group runs with the existing restricted messaging runner, and its notes are
 separate from private PA memory. Group text is supported; media is not yet.
 
+## Everyone on an enabled channel
+
+When the owner explicitly asks to answer anyone on one channel, propose one
+incoming-only `--any-conversation` grant for that registered source. The flag
+also selects `--until-revoked` and contact `*`. Do not widen “this group,” “this
+person,” or “customers in this list” into everyone. The source must support a
+wildcard watch; otherwise report that adapter gap without inventing a parallel
+poller. Telegram's built-in source supports private chats and groups. Other
+channels use the same core grant when their adapter advertises the same event-
+source contract. Authenticated owner application channels remain owner routes;
+an untrusted web, voice or phone audience needs an event-source adapter and this
+grant.
+
+Capabilities are optional and provider-neutral. Put an array in a private
+capability file; each entry has `id`, `description`, registered `command`, and a
+fixed `args` array ending in `"--", "{input}"`. Example for an already installed
+Library source:
+
+```json
+[
+  {
+    "id": "knowledge",
+    "description": "Search the approved public Library source",
+    "command": "library-query",
+    "args": ["--library", "public", "--limit", "5", "--", "{input}"]
+  }
+]
+```
+
+The registered alias must declare `channelQuery: true` with explicit exposure
+metadata showing that it accepts external input but cannot send, change records,
+or require interactive review. Core verifies that installed declaration on every
+invocation. Verify the selected source and query alias first, then propose:
+
+```sh
+ezenciel-agents-task propose --source telegram --any-conversation \
+  --purpose "Answer questions using approved public knowledge" \
+  --context-file work/public-answer-policy.txt \
+  --capability-file work/public-answer-capabilities.json
+```
+
+The approval names the audience, disclosure context and exact command vectors.
+Command output may be shown to anyone in that audience. External writes need
+their own bounded tool contract and receipts. Revocation stops new capture,
+cancels queued replies and rechecks every tool/send. Public Telegram groups must
+mention or reply to the bot; one conversation can have only one outstanding run
+and the source-wide public backlog is bounded. Core admits at most 60 public
+conversations and 60 replies per hour. A grant revokes after 1,000 conversations
+or replies so the owner must review continued broad access.
+
 The core presents the exact proposal for owner confirmation. Ordinary messages
 inside that grant need no repeated confirmations. Incoming-only grants create
 no initial run or opening message. They remain active across replies until expiry

package/docs/setup.md

@@ -19,7 +19,8 @@ Make the bot a group admin so Telegram delivers ordinary member messages and
 allows membership verification for approval and control buttons. Group ownership only authorizes
 the exact approved chat, not other groups or members' private DMs. Telegram group
 migration to a new chat ID requires a new explicit binding. Verify a real group
-reply before considering setup complete. All other groups retain their existing
+reply before considering setup complete. Unless an explicit any-conversation
+grant is active, all other groups retain their existing
 restricted conversation-grant behavior.
 
 Ez supports two independent, composable uses: an autonomous Telegram agent and

package/docs/upgrades.md

@@ -174,10 +174,12 @@ No backup deletes live data or revokes credentials. Retain old package roots and
 images until QA and any recovery window are complete; there is no automatic GC.
 
 The updater accepts only matching state-schema and protocol contracts and an
-unchanged deployment layout. Changes to privileges, services, volumes or Compose
-configuration fail before replacement, even for an explicit candidate. These
-need a separately reviewed migration, not an override flag. Release authors must
-truthfully declare schema compatibility. Code rollback **does not rewind private
+unchanged deployment layout. Plugins may add command routes to existing services;
+existing routes and all services, privileges, volumes and other deployment
+configuration must remain unchanged. Incompatible changes fail before replacement,
+even for an explicit candidate, and need a separately reviewed migration rather
+than an override flag. Release authors must truthfully declare schema compatibility.
+Code rollback **does not rewind private
 state**, provider cursors or operation receipts; uncertain actions are never
 replayed. Docker health is not proof of live provider identity or delivery.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.31",
+  "version": "0.1.0-beta.33",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

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 }
+}