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

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)

package/src/index.ts

@@ -13,6 +13,7 @@ import { scheduledTasksText } from './scheduled-tasks.js'
 import { taskWorkspace } from './task-workspace.js'
 import { queueUpdateAttention } from './update-attention.js'
 import { EventSources, eventRunId, batchReady, type SourceEvent } from './event-sources.js'
+import {removeTaskAttachments} from './task-attachments.js'
 import { dirname, join, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import path from 'node:path'
@@ -28,7 +29,7 @@ import { startExecutorJob, terminateJob } from './executor.js'
 import { RunStore, type RunRecord } from './runs.js'
 import { splitTelegramText } from './reply.js'
 import { markdownToTelegramHtml, escapeHtml } from './format.js'
-import { sanitizeFileName, stageIncomingFile, workspaceFile } from './files.js'
+import { sanitizeFileName, stageChatAttachment, workspaceFile } from './files.js'
 import { transcribeAudio, synthesizeSpeech } from './audio.js'
 import { normalizeReactionEmoji } from './reaction.js'
 import { downloadTelegramFile } from './read-request.js'
@@ -108,7 +109,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   }
 
   const applicationChannel = new ApplicationChannel({
-    controlDir: config.controlDir, initial: aiMenu.initial,
+    controlDir: config.controlDir, workspace: config.workspace, initial: aiMenu.initial,
     aiControls: aiMenu,
     wake: () => { void drainSources().catch(error => console.error('Application queue unavailable', safeError(error))) },
     cancel: id => withStartLock(async () => {
@@ -153,7 +154,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     return ids
   }
 
-  const telegramSource = telegramEnabled ? new TelegramSource(config.controlDir, config.telegramBotToken.split(':')[0], sendChat) : null
+  const telegramSource = telegramEnabled ? new TelegramSource(config.controlDir, config.telegramBotToken.split(':')[0], sendChat,
+    async(chatId,text,bytes,filename)=>[(await bot!.api.sendDocument(chatId,new InputFile(bytes,filename),{caption:text})).message_id]) : null
 
   const startJob = async (run: RunRecord): Promise<void> => {
     await withStartLock(async () => {
@@ -161,19 +163,20 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       // stat uses the effective UID; access uses the relay's isolated real UID.
       if (await stat(join(config.controlDir,'upgrade-pause.json')).then(()=>true,e=>{if(e.code==='ENOENT')return false;throw e})) return
       if ((await runs.get(run.id))?.status !== 'queued') return
-      if (!telegramEnabled && !run.application && !run.delivery && !run.scheduled) return
+      if (!telegramEnabled && !run.application && !run.delivery && !run.scheduled && !run.external) return
       if (!run.scheduled && await runs.running(false)) return
       const owner = (await control.status()).owner
       if (!owner || !ownsRun(owner, run)) {
         await runs.patch(run.id, { status: 'failed', endedAt: new Date().toISOString() })
+        await releaseExternal(run)
         return
       }
       if (run.application || run.delivery) {
         try { await applicationChannel.bindings.authorize(run) }
-        catch { await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() }); return }
+        catch { await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() }); await releaseExternal(run); return }
       }
       if (config.channelBackendUrl) {
-        if (run.external || run.taskId || run.scheduled || run.id.startsWith('r_update_')) { await runs.patch(run.id, { status: 'failed' }); return }
+        if (run.external || run.taskId || run.scheduled || run.id.startsWith('r_update_')) { await runs.patch(run.id, { status: 'failed' }); await releaseExternal(run); return }
         activeBackend = true
         await runs.patch(run.id, { status: 'running', backendSubmitted: true })
         void dispatchChannel(config, run).then(async reply => {
@@ -201,18 +204,20 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         try { events = await sources.check(run.external, owner); unavailableSources.delete(run.external.sourceId) } catch { unavailableSources.add(run.external.sourceId); return }
         if (!events.length) {
           await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() })
+          await releaseExternal(run)
           return
         }
         texts = events.map(event => JSON.stringify(event))
       }
       if (run.taskId) {
         try { await tasks.authorize(run) } catch {
-          await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() }); return
+          await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() }); await releaseExternal(run); return
         }
       }
       const blockReason = run.taskId ? undefined : executionBlockReason(run, owner)
       if (blockReason) {
         await runs.patch(run.id, { status: 'cancelled', blockReason, endedAt: new Date().toISOString() })
+        await releaseExternal(run)
         return
       }
       try {
@@ -288,6 +293,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
                 if (code === 0 && !run.external && !run.taskId && !run.scheduled) await control.markSessionStarted(session.sessionId)
                 const cancelled = ownerStopped.has(child) || Boolean(run.scheduled && await scheduler.cancelled(run.id))
                 await runs.patch(started.id, { status: cancelled ? 'cancelled' : code === 0 ? 'completed' : 'failed', endedAt: new Date().toISOString(), exitCode: code, ...(code !== 0 && !cancelled ? { failureReason, interrupted, failure: await failureEvidence(config.controlDir, safeError(errorTail || `Executor exited with ${code === null ? 'a signal' : `code ${code}`}`)) } : {}) })
+                await releaseExternal(run)
               } catch (error) {
                 await runs.patch(started.id, { status: ownerStopped.has(child) ? 'cancelled' : 'failed', failureReason: 'session-finalization', failure: await failureEvidence(config.controlDir, safeError(error)), endedAt: new Date().toISOString() })
                 console.error('Session completion failed', safeError(error))
@@ -313,6 +319,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           activeTypingTimer = null
         }
         await runs.patch(run.id, { status: 'failed', failureReason: 'executor-start', failure: await failureEvidence(config.controlDir, safeError(error)), endedAt: new Date().toISOString() })
+        await releaseExternal(run)
         console.error('run start failed', run.id, safeError(error))
         if (bot && !run.application && !run.delivery && run.chatId !== undefined) await sendChat(run.chatId, `Run ${run.id} failed to start. Check the local relay log.`)
         setImmediate(() => {
@@ -326,6 +333,22 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   }
 
   const unavailableSources = new Set<string>()
+  const releaseExternal = async (run: RunRecord):Promise<boolean> => {
+    if (!run.external) return true
+    try {await removeTaskAttachments(config.controlDir,run.id)} catch {return false}
+    const current=await runs.get(run.id)
+    if (current?.externalReleased) {if(run.taskId)await runs.pruneTaskHistory(run.taskId);return true}
+    const task = run.taskId ? await tasks.get(run.taskId).catch(() => null) : null
+    const registered=(await sources.list()).find(source=>source.id===run.external!.sourceId&&source.bindingId===run.external!.bindingId)
+    const owner=task?.owner ?? (registered&&ownsRun(registered.owner,run)?registered.owner:(await control.status()).owner)
+    if(!owner)return false
+    try {
+      await sources.release(run.external,owner)
+      await runs.patch(run.id,{externalReleased:true})
+      if(run.taskId)await runs.pruneTaskHistory(run.taskId)
+      return true
+    } catch {unavailableSources.add(run.external.sourceId);return false}
+  }
   let sourceWork: Promise<void> | undefined
   const drainSources = (): Promise<void> => {
     if (sourceWork) return sourceWork
@@ -337,6 +360,11 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         try {
           if (!ownsRun(owner, foreground)) throw new Error('Owner channel revoked')
           if (foreground.application) await applicationChannel.bindings.authorize(foreground)
+          if (foreground.taskId) {
+            const task = await tasks.authorize(foreground,false)
+            const ownerWaiting=(await inbox.status()).pending>0 || (await runs.list()).some(run=>run.status==='queued'&&!run.taskId&&!run.scheduled)
+            if (task.anyConversation && ownerWaiting) throw new Error('Owner input preempts public work')
+          }
         }
         catch { ownerStopped.add(activeChild); terminateJob(activeChild) }
       }
@@ -348,6 +376,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         } catch { ownerStopped.add(child); terminateJob(child); continue }
         if (await scheduler.cancelled(id)) terminateJob(child)
       }
+      const pendingRelease=(await runs.list()).find(run=>run.external&&!run.externalReleased&&['completed','failed','cancelled'].includes(run.status))
+      if(pendingRelease)await releaseExternal(pendingRelease)
       if (!owner) return
       if (!config.channelBackendUrl) {
       await drainTaskRequests()
@@ -356,7 +386,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       }
       if (telegramOwner(owner)) await queueUpdateAttention(config.controlDir,owner,runs,await durableWorkerChoice())
       }
-      for (const source of !telegramOwner(owner) || config.channelBackendUrl ? [] : await sources.available(owner)) {
+      for (const source of config.channelBackendUrl ? [] : await sources.available(owner)) {
         try {
           const batch = await sources.batch(source)
           unavailableSources.delete(source.id)
@@ -366,23 +396,37 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
             await sources.remember(source, batch)
             const groups = new Map<string, SourceEvent[]>()
             for (const event of batch.events) groups.set(event.conversationId, [...(groups.get(event.conversationId) || []), event])
+            const known = await runs.list()
+            const publicTaskIds = new Set((await tasks.list()).filter(task=>task.anyConversation).map(task=>task.id))
+            let publicOutstanding = known.filter(run => run.taskId && publicTaskIds.has(run.taskId) && ['queued','running'].includes(run.status)).length
+            let admitted = true
             for (const events of groups.values()) {
-              const task = await tasks.match(source.id, source.bindingId, events)
-              await runs.create({
-              taskId: task?.id,
-              id: eventRunId(source, events), chatId: owner.telegramChatId, telegramUserId: owner.telegramUserId,
-              texts: [], execution: await durableWorkerChoice(),
-              external: { sourceId: source.id, bindingId: source.bindingId, eventIds: events.map(e => e.id) },
-            })
+              let task = await tasks.match(source.id, source.bindingId, events)
+              const id = eventRunId(source,events)
+              if (known.some(run => run.id === id)) continue
+              if (task?.anyConversation) {
+                const publicTaskId=task.id
+                if (publicOutstanding >= 8 || known.some(run => run.taskId === publicTaskId &&
+                  run.external?.conversationId === events[0].conversationId && ['queued','running'].includes(run.status))) { admitted=false; continue }
+                const admission = await tasks.admitPublic(task.id)
+                if (admission === 'defer') { admitted=false; continue }
+                if (admission === 'revoked') task=undefined
+              }
+              const identity = owner.telegramUserId !== undefined && owner.telegramChatId !== undefined
+                ? {chatId:owner.telegramChatId,telegramUserId:owner.telegramUserId}
+                : {ownerId:ownerId(owner),ownerEpoch:ownerEpoch(owner)}
+              const created = await runs.create({taskId:task?.id,id,...identity,texts:[],execution:await durableWorkerChoice(),
+                external:{sourceId:source.id,bindingId:source.bindingId,conversationId:events[0].conversationId,eventIds:events.map(e=>e.id)}})
+              known.push(created); if(task?.anyConversation)publicOutstanding++
             }
             // Acknowledgement follows durable run creation; replay uses the saved batch.
-            await sources.advance(source, batch.cursor)
+            if(admitted)await sources.advance(source, batch.cursor)
           })
         } catch { unavailableSources.add(source.id) }
       }
       await runs.running(true)
       if (!config.channelBackendUrl) await scheduler.tick(owner,runs)
-      for (const run of (await runs.list()).filter(r => r.status === 'queued')) {
+      for (const run of (await runs.list()).filter(r => r.status === 'queued').sort((a,b)=>Number(Boolean(a.taskId))-Number(Boolean(b.taskId)))) {
         if (shuttingDown) break
         await startJob(run)
       }
@@ -673,6 +717,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       for (const run of await runs.list()) {
         if (run.status !== 'queued' || run.backendSubmitted) continue
         await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() })
+        await releaseExternal(run)
         count++
       }
     })
@@ -683,26 +728,32 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   // return after the authorized update has reached the atomic local journal.
   if (bot) {
   bot.use(async (ctx, next) => {
-    if (ctx.callbackQuery && (await control.status()).owner?.kind === 'group') {
-      if (!isOwner(ctx, (await control.status()).owner)) return
+    const currentOwner = (await control.status()).owner
+    if (ctx.callbackQuery && currentOwner?.kind === 'group') {
+      if (!isOwner(ctx, currentOwner)) return
       try {
         const member = await bot!.api.getChatMember(ctx.chat!.id, ctx.from!.id)
         if (!['creator', 'administrator', 'member'].includes(member.status) &&
           !(member.status === 'restricted' && member.is_member)) return
       } catch { throw new Error('Group membership verification unavailable; retry the update') }
     }
-    if ((ctx.chat?.type === 'group' || ctx.chat?.type === 'supergroup') &&
-      !isOwner(ctx, (await control.status()).owner)) {
+    const externalText = !replay.has(ctx.update) && ctx.message?.text && !ctx.message.sender_chat && ctx.from && !ctx.from.is_bot && telegramOwner(currentOwner) && !isOwner(ctx,currentOwner)
+    if (externalText) {
+      await telegramSource!.start(currentOwner!)
+      const group = ctx.chat?.type === 'group' || ctx.chat?.type === 'supergroup'
+      const addressed = !group || ctx.message.reply_to_message?.from?.id === bot!.botInfo.id || Boolean(bot!.botInfo.username &&
+        new RegExp(`(^|\\s)@${bot!.botInfo.username}(?=\\s|$|[,.!?;:])`,'i').test(ctx.message.text!))
+      if (await telegramSource!.capture(ctx.update.update_id,ctx.message as import('grammy/types').Message.TextMessage,ctx.from!,addressed)) return
+    }
+    if ((ctx.chat?.type === 'group' || ctx.chat?.type === 'supergroup') && !isOwner(ctx, currentOwner)) {
       if (config.channelBackendUrl) return
-      const owner = telegramOwner((await control.status()).owner)
+      const owner = telegramOwner(currentOwner)
       const message = ctx.message
       if (!owner && message && !message.sender_chat && ctx.from && !ctx.from.is_bot) {
         await control.requestPairing(ctx.from.id, ctx.chat.id, ctx.chat.title)
         return
       }
       if (!owner || !message?.text || message.sender_chat || !ctx.from || ctx.from.is_bot) return
-      await telegramSource!.start(owner)
-      if (await telegramSource!.capture(ctx.update.update_id, message as import('grammy/types').Message.TextMessage, ctx.from)) return
       if (owner.kind === 'group') return
       if (ctx.from.id !== owner.telegramUserId) return
       if (replay.has(ctx.update)) {
@@ -859,12 +910,10 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       const fileUrl = `https://api.telegram.org/file/bot${config.telegramBotToken}/${fileInfo.file_path}`
       const buffer = await downloadTelegramFile(fileUrl)
       const fileName = sanitizeFileName(basename(fileInfo.file_path) || 'photo.jpg')
-      const staged = await stageIncomingFile(config.workspace, fileName, buffer)
-      const caption = ctx.message.caption?.trim() || ''
-      const prompt = `[Attached image staged at ${staged.relativePath} (type: ${staged.fileType}, size: ${buffer.length} bytes)]${caption ? `\n\nCaption: ${caption}` : ''}`
+      const staged = await stageChatAttachment(config.workspace, fileName, buffer, ctx.message.caption ?? '')
       collectItem({
-        text: prompt,
-        attachment: { path: staged.relativePath, type: staged.fileType },
+        text: staged.text,
+        attachment: staged.attachment,
         messageId: ctx.message.message_id,
         updateId: ctx.update.update_id,
         chatId: ctx.chat.id,
@@ -888,12 +937,10 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       const fileUrl = `https://api.telegram.org/file/bot${config.telegramBotToken}/${fileInfo.file_path}`
       const buffer = await downloadTelegramFile(fileUrl)
       const fileName = sanitizeFileName(doc.file_name || basename(fileInfo.file_path) || 'document.bin')
-      const staged = await stageIncomingFile(config.workspace, fileName, buffer)
-      const caption = ctx.message.caption?.trim() || ''
-      const prompt = `[Attached document staged at ${staged.relativePath} (type: ${staged.fileType}, size: ${buffer.length} bytes)]${caption ? `\n\nCaption: ${caption}` : ''}`
+      const staged = await stageChatAttachment(config.workspace, fileName, buffer, ctx.message.caption ?? '')
       collectItem({
-        text: prompt,
-        attachment: { path: staged.relativePath, type: staged.fileType },
+        text: staged.text,
+        attachment: staged.attachment,
         messageId: ctx.message.message_id,
         updateId: ctx.update.update_id,
         chatId: ctx.chat.id,

package/src/plugins/manager.mjs

@@ -41,12 +41,36 @@ export async function bindToolDiscovery(home,workspace) {
     try {await fs.writeFile(tmp,next,{mode:0o600,flag:'wx'});await fs.rename(tmp,file);}finally{await fs.rm(tmp,{force:true});}
   }
 }
-export async function locked(home, fn) {
+const invocationDirectory = home => path.join(home,'command-invocations');
+async function activeInvocations(home) {
+  const directory=invocationDirectory(home),files=await fs.readdir(directory).catch(error=>{if(error.code==='ENOENT')return [];throw error;});
+  for(const file of files) {
+    if(!/^[0-9a-f-]{36}\.json$/.test(file))throw Error('Invalid command invocation lease; inspect before recovery');
+    const lease=await json(path.join(directory,file));
+    if(!Number.isSafeInteger(lease.pid)||lease.pid<1||typeof lease.container!=='string'||!lease.container)throw Error('Invalid command invocation lease; inspect before recovery');
+    try {process.kill(lease.pid,0);return true;} catch(error) {if(error.code!=='ESRCH')throw error;}
+    const state=await run(['container','inspect',lease.container],{capture:true});
+    if(state.code===0)throw Error(`Stale command invocation lease; inspect container ${lease.container} before recovery`);
+    if(!/No such (?:object|container)/i.test(state.stderr+state.stdout))throw Error('Unable to verify a stale command invocation lease; inspect Docker before recovery');
+    await fs.rm(path.join(directory,file));
+  }
+  return false;
+}
+async function invocationLease(home,container) {
+  const directory=invocationDirectory(home);await privateDir(directory);
+  const file=path.join(directory,randomUUID()+'.json');await fs.writeFile(file,JSON.stringify({pid:process.pid,container}),{mode:0o600,flag:'wx'});
+  return async()=>{await fs.rm(file,{force:true});};
+}
+export async function locked(home, fn, {allowInvocations=false}={}) {
   const lock = path.join(home,'registry.lock');
   let handle;
   try { handle=await fs.open(lock,'wx',0o600); }
   catch(error) { if(error.code==='EEXIST') throw Error('Registry busy; inspect registry.lock before recovering an interrupted manager'); throw error; }
-  try { await handle.writeFile(JSON.stringify({pid:process.pid})); return await fn(); }
+  try {
+    await handle.writeFile(JSON.stringify({pid:process.pid}));
+    if(!allowInvocations&&await activeInvocations(home))throw Error('Plugin commands are active; retry the registry or lifecycle change after they finish');
+    return await fn();
+  }
   finally { await handle.close(); await fs.rm(lock); }
 }
 // Snapshot only explicitly packaged files. No symlinks, credentials inferred from cwd, or install scripts.
@@ -126,7 +150,13 @@ export function validate(m,d,files) {
   if(JSON.stringify(Object.keys(m.commands).sort())!==JSON.stringify(Object.keys(d.commands).sort())) throw Error('Command bindings must match manifest');
   for(const [alias,c] of Object.entries(m.commands)) {
     id(alias); if(reserved.has(alias)) throw Error('Reserved alias');
-    keys(c,['executable','args','exposure']); strings(c.args); exposure(c.exposure);
+    keys(c,['executable','args','exposure','channelQuery','channelFile']); strings(c.args); exposure(c.exposure);
+    if(c.channelFile!==undefined && c.channelFile!==true) throw Error('channelFile must be true when declared');
+    if(c.channelFile && c.channelQuery)throw Error('Choose one channel output type');
+    if(c.channelQuery!==undefined && c.channelQuery!==true) throw Error('channelQuery must be true when declared');
+    if((c.channelQuery || c.channelFile) && (c.exposure?.receivesExternalContent!==true || c.exposure?.sendsExternally!==false ||
+      c.exposure?.changesRecords!==false || c.exposure?.requiresReview!==false))
+      throw Error('Channel queries must explicitly accept external input without sends, writes, or review');
     if(!files.has(c.executable)) throw Error('Missing package executable');
     const b=d.commands[alias];keys(b,['service','argv','suffix']);
     if(!d.services[b.service] || !strings(b.argv).length) throw Error('Invalid command service'); strings(b.suffix||[]);
@@ -270,7 +300,10 @@ export function run(argv,{capture=false,container,signal,stdin,onStdout,onStart,
       if(cancelled&&container) {
         try {
           await removeCommandContainer(container);
-        } catch(error) {return reject(error);}
+        } catch(error) {
+          const uncertain=error instanceof Error?error:Error('Cancelled command container cleanup failed');
+          uncertain.containerCleanupUncertain=true;return reject(uncertain);
+        }
       }
       if(failure)return reject(failure);
       resolve({code:cancelled?130:code??(childSignal?130:1),stdout,stderr});});
@@ -306,7 +339,7 @@ export async function registry(home) {
   return r;
 }
 // The lock protects admission and compose refresh, never a persistent connection.
-export async function prepareCommand(home,alias,args,{revision,exclude,publish}={}) {
+export async function prepareCommand(home,alias,args,{revision,exclude,publish,invocation=false}={}) {
   strings(args);
   return locked(home,async()=>{
     const config=await json(path.join(home,'config.json')),r=await registry(home);
@@ -317,8 +350,9 @@ export async function prepareCommand(home,alias,args,{revision,exclude,publish}=
     const secrets=await json(path.join(home,'packages',record.manifest.id,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
     await atomic(record.compose,await compose(config,record,secrets,home));
     const container=`${record.project}-call-${randomUUID()}`;
-    return {container,plugin:record.manifest.id,revision:record.revision,argv:[...composeArgs(record),'run','--rm','--no-deps','-T','--name',container,...(publish?['--publish',publish]:[]),'--entrypoint',binding.argv[0],binding.service,...binding.argv.slice(1),...record.manifest.commands[alias].args,...args,...(binding.suffix||[])]};
-  });
+    const release=invocation?await invocationLease(home,container):undefined;
+    return {container,plugin:record.manifest.id,revision:record.revision,argv:[...composeArgs(record),'run','--rm','--no-deps','-T','--name',container,...(publish?['--publish',publish]:[]),'--entrypoint',binding.argv[0],binding.service,...binding.argv.slice(1),...record.manifest.commands[alias].args,...args,...(binding.suffix||[])],release};
+  },{allowInvocations:true});
 }
 export async function init(home,workspace,catalogFile,hostConfig,standalone=false) {
   if(standalone && hostConfig) throw Error('Standalone setup cannot bind a relay host config');
@@ -509,17 +543,15 @@ export async function main(args) {
       emit({ok:true,plugin:name,action,dataPreserved:true});
     });
   }
-  return locked(home,async()=>{
-  const config=await json(path.join(home,'config.json'));
-  const r=await registry(home),record=r.plugins[r.commands[group]],binding=record?.deployment.commands[group];
-  if(!binding)throw Error('Unknown registered CLI');
-  await checkFolders(config,record);
-  const secrets=await json(path.join(home,'packages',record.manifest.id,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
-  await atomic(record.compose,await compose(config,record,secrets,home));
-  // Docker exec does not reliably forward cancellation to the in-container process.
-  // Run each client as a one-shot Compose container; docker compose run forwards signals.
-  const name=`${record.project}-call-${randomUUID()}`;
-  const result=await run([...composeArgs(record),'run','--rm','--no-deps','-T','--name',name,'--entrypoint',binding.argv[0],binding.service,...binding.argv.slice(1),...record.manifest.commands[group].args,...args.slice(1),...(binding.suffix||[])],{container:name});
-  process.exitCode=result.code;
-  });
+  const command=await prepareCommand(home,group,args.slice(1),{invocation:true});
+  try {
+    // Docker exec does not reliably forward cancellation to the in-container process.
+    // Run each client as a one-shot Compose container; docker compose run forwards signals.
+    const result=await run(command.argv,{container:command.container});
+    process.exitCode=result.code;
+    await command.release();
+  } catch(error) {
+    if(error?.containerCleanupUncertain!==true)await command.release();
+    throw error;
+  }
 }

package/src/runs.ts

@@ -42,6 +42,7 @@ export type RunRecord = {
   nativeSessionId?: string
   scheduled?: ScheduledOrigin
   external?: ExternalOrigin
+  externalReleased?: true
   application?: ApplicationOrigin
   delivery?: { bindingId: string; scope: string }
 }
@@ -89,6 +90,7 @@ const isRun = (value: unknown): value is RunRecord => {
     (candidate.scheduled === undefined || validScheduledOrigin(candidate.scheduled)) &&
     (candidate.blockReason === undefined || ['owner-mismatch', 'external-execution-unavailable'].includes(candidate.blockReason)) &&
     (candidate.external === undefined || validOrigin(candidate.external)) &&
+    (candidate.externalReleased === undefined || candidate.external !== undefined && candidate.externalReleased === true) &&
     (candidate.id.startsWith('r_app_') === (candidate.application !== undefined)) &&
     (candidate.application === undefined || (validApplicationOrigin(candidate.application) && candidate.external === undefined && candidate.scheduled === undefined && candidate.taskId === undefined && !candidate.replyOnly)) &&
     (candidate.delivery === undefined || (!!candidate.scheduled && validApplicationOrigin({...candidate.delivery, requestId: candidate.id}) && candidate.application === undefined)) &&
@@ -186,7 +188,7 @@ export class RunStore {
 
   async patch(
     id: string,
-    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview'>>,
+    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview' | 'externalReleased'>>,
   ): Promise<RunRecord> {
     const prior = this.changes.get(id) || Promise.resolve()
     const work = prior.catch(() => {}).then(async () => {
@@ -219,6 +221,11 @@ export class RunStore {
     return runs.sort((left, right) => left.createdAt.localeCompare(right.createdAt))
   }
 
+  async pruneTaskHistory(taskId:string,keep=100):Promise<void>{
+    const terminal=(await this.list()).filter(run=>run.taskId===taskId&&['completed','failed','cancelled'].includes(run.status)&&(run.external===undefined||run.externalReleased===true)).sort((a,b)=>a.createdAt.localeCompare(b.createdAt))
+    for(const run of terminal.slice(0,Math.max(0,terminal.length-keep)))await rm(this.runPath(run.id),{force:true})
+  }
+
   async running(background?: boolean): Promise<RunRecord | undefined> {
     const runs = await this.list()
     let first: RunRecord | undefined
@@ -231,7 +238,8 @@ export class RunStore {
   }
 
   async nextQueued(background?: boolean): Promise<RunRecord | undefined> {
-    return (await this.list()).find((run) => run.status === 'queued' && (background === undefined || Boolean(run.scheduled) === background))
+    const queued = (await this.list()).filter((run) => run.status === 'queued' && (background === undefined || Boolean(run.scheduled) === background))
+    return queued.find(run => !run.taskId) ?? queued[0]
   }
 
   async deliveryStatus(): Promise<{ failed: number; unknown: number }> {
@@ -440,6 +448,15 @@ export class RunStore {
     return [...messages.values()].sort((a, b) => a.createdAt.localeCompare(b.createdAt)).map(item => ({ id: item.id, text: item.text! }))
   }
 
+  async applicationApprovals(runId:string):Promise<{id:string;prompt:string;state:string}[]> {
+    assertId(runId);await this.ensure();const result=[] as {id:string;prompt:string;state:string}[]
+    for(const name of await readdir(this.outboxDir))if(name.startsWith(`${runId}_`)&&name.endsWith('.json')&&!name.includes('.tmp')&&!name.endsWith('.failed.json'))try{
+      const item=JSON.parse(await readFile(path.join(this.outboxDir,name),'utf8')) as OutboxItem
+      if(item.runId===runId&&item.type==='approval'&&item.approvalActionId&&item.approvalPrompt)result.push({id:item.approvalActionId,prompt:item.approvalPrompt,state:name.endsWith('.sent.json')?'delivered':'pending'})
+    }catch(error){if((error as NodeJS.ErrnoException).code!=='ENOENT')throw error}
+    return result
+  }
+
   async claimOutbox(id: string): Promise<boolean> {
     assertId(id)
     const from = path.join(this.outboxDir, `${id}.json`)

package/src/task-attachments.ts

@@ -0,0 +1,56 @@
+import {mkdir,lstat,open,rm,readdir} from 'node:fs/promises'
+import {constants} from 'node:fs'
+import {join,basename} from 'node:path'
+import {createHash} from 'node:crypto'
+
+export const attachmentLimit = 20 * 1024 * 1024
+export type TaskAttachment = {runId:string;id:string;filename:string;bytes:number;sha256:string}
+const hash = (data:Buffer) => createHash('sha256').update(data).digest('hex')
+function directory(control:string,runId:string) {
+  if(!/^[a-zA-Z0-9_-]{1,160}$/.test(runId))throw Error('Invalid attachment run')
+  return join(control,'task-files',runId)
+}
+function validate(file:TaskAttachment) {
+  if(!file || !/^[a-f0-9-]{36}$/.test(file.id) || typeof file.filename!=='string' || !file.filename || file.filename!==basename(file.filename) || /[\\\x00-\x1f\x7f]/.test(file.filename) || file.filename.length>200 ||
+    !Number.isSafeInteger(file.bytes)||file.bytes<1||file.bytes>attachmentLimit||!/^[a-f0-9]{64}$/.test(file.sha256))throw Error('Invalid task attachment')
+}
+async function safeDirectory(control:string,runId:string,create=false) {
+  const dir=directory(control,runId)
+  for(const entry of [join(control,'task-files'),dir]) {
+    if(create)await mkdir(entry,{mode:0o700}).catch(e=>{if(e.code!=='EEXIST')throw e})
+    const stat=await lstat(entry);if(!stat.isDirectory()||stat.isSymbolicLink())throw Error('Unsafe attachment directory')
+  }
+  return dir
+}
+export async function stageTaskAttachment(control:string,runId:string,id:string,input:string,data:Buffer):Promise<TaskAttachment> {
+  const file={runId,id,filename:basename(input),bytes:data.length,sha256:hash(data)};validate(file)
+  const dir=await safeDirectory(control,runId,true)
+  // The task broker serializes its calls; bound the entire run, including unsent files.
+  let total=0
+  for(const entry of await readdir(dir)) {
+    const stat=await lstat(join(dir,entry))
+    if(!stat.isFile()||stat.isSymbolicLink())throw Error('Unsafe staged attachment')
+    if(entry!==id)total+=stat.size
+  }
+  if(total+data.length>attachmentLimit)throw Error('Task attachments exceed the 20 MiB run limit')
+  const fd=await open(join(dir,id),constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,0o600).catch(async error=>{
+    if(error.code!=='EEXIST')throw error
+    await readTaskAttachment(control,file);return null
+  })
+  if(!fd)return file
+  try{await fd.writeFile(data)}finally{await fd.close()}
+  return file
+}
+export async function readTaskAttachment(control:string,file:TaskAttachment) {
+  validate(file)
+  const dir=await safeDirectory(control,file.runId)
+  const fd=await open(join(dir,file.id),constants.O_RDONLY|constants.O_NOFOLLOW)
+  try {
+    const stat=await fd.stat();if(!stat.isFile()||stat.size!==file.bytes)throw Error('Attachment changed')
+    const data=await fd.readFile();if(hash(data)!==file.sha256)throw Error('Attachment changed')
+    return data
+  }finally{await fd.close()}
+}
+export async function removeTaskAttachments(control:string,runId:string) {
+  await rm(directory(control,runId),{recursive:true,force:true})
+}

package/src/task-capability.ts

@@ -0,0 +1,45 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { executorEnvironment } from './executor.js'
+import type { TaskCapability } from './tasks.js'
+import {attachmentLimit,stageTaskAttachment,type TaskAttachment} from './task-attachments.js'
+
+const execute = promisify(execFile)
+
+export async function assertChannelQuery(toolsHome: string | undefined, capability: TaskCapability) {
+  if (!toolsHome || !path.isAbsolute(toolsHome)) throw new Error('Channel capabilities require an installed tool registry')
+  const registry = JSON.parse(await readFile(path.join(toolsHome,'registry.json'),'utf8')) as {
+    commands?: Record<string,string>, plugins?: Record<string,{manifest?:{commands?:Record<string,{channelQuery?:boolean,channelFile?:boolean,exposure?:Record<string,boolean>}>}}>
+  }
+  const command = registry.plugins?.[registry.commands?.[capability.command] ?? '']?.manifest?.commands?.[capability.command]
+  const exposure = command?.exposure
+  if ((capability.output==='file'?command?.channelFile:command?.channelQuery) !== true || exposure?.receivesExternalContent !== true || exposure.sendsExternally !== false ||
+      exposure.changesRecords !== false || exposure.requiresReview !== false)
+    throw new Error(`Capability ${capability.id} is not an installed read-only channel query`)
+}
+
+export async function runTaskCapability(toolsHome: string | undefined, capability: TaskCapability, input: string, staging?:{controlDir:string;runId:string;lease:string}):Promise<{output:string;attachment?:never}|{attachment:TaskAttachment;output?:never}> {
+  await assertChannelQuery(toolsHome,capability)
+  const home = toolsHome!
+  const args = [capability.command, ...capability.args.map(value => value === '{input}' ? input : value)]
+  if(capability.output==='file') {
+    if(!staging)throw Error('File capability requires task staging')
+    const result=await execute(path.join(home,'bin','ez'),args,{encoding:'buffer',env:executorEnvironment(),timeout:30000,maxBuffer:attachmentLimit})
+    const attachment=await stageTaskAttachment(staging.controlDir,staging.runId,staging.lease,input,result.stdout)
+    return {attachment}
+  }
+  let stdout = '', code = 0
+  try {
+    const result = await execute(path.join(home,'bin','ez'),args,{encoding:'utf8',env:executorEnvironment(),timeout:15000,maxBuffer:131072})
+    stdout = result.stdout
+  } catch (error) {
+    const failure = error as Error & {stdout?:string;code?:number|string}
+    stdout = typeof failure.stdout === 'string' ? failure.stdout : ''
+    code = typeof failure.code === 'number' ? failure.code : 1
+  }
+  if (Buffer.byteLength(stdout) > 131072) throw new Error('Channel capability output is too large')
+  if (code !== 0 || !stdout.trim()) throw new Error(`Channel capability failed with exit ${code}`)
+  return {output:stdout}
+}