@jc_stack/ez-agents 0.1.0-beta.12 → 0.1.0-beta.13

package/src/index.ts

@@ -1,5 +1,11 @@
+import { Tasks } from './tasks.js'
+import { taskRequests } from './task-rpc.js'
+import { executionBlockReason } from './execution-authority.js'
+import { dispatchChannel } from './channel-backend.js'
 import { randomUUID } from 'node:crypto'
 import { stat } from 'node:fs/promises'
+import { Scheduler } from './scheduler.js'
+import { taskWorkspace } from './task-workspace.js'
 import { queueUpdateAttention } from './update-attention.js'
 import { EventSources, eventRunId, batchReady, type SourceEvent } from './event-sources.js'
 import { dirname, join, basename } from 'node:path'
@@ -29,7 +35,7 @@ import { softwareStatus } from './software-status.js'
 export const createRelay = (config: Config, launch = startExecutorJob) => {
   const safeError = (error: unknown): string => {
     let message = error instanceof Error ? error.message : 'Unknown error'
-    for (const secret of [config.telegramBotToken, config.geminiApiKey, config.openaiApiKey]) {
+    for (const secret of [config.channelBackendToken, config.telegramBotToken, config.geminiApiKey, config.openaiApiKey]) {
       if (secret) message = message.replaceAll(secret, '[redacted]')
     }
     return message
@@ -40,10 +46,15 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const runs = new RunStore(config.controlDir)
   const inbox = new InboxStore(config.controlDir)
   const sources = new EventSources(config.controlDir)
+  const scheduler = new Scheduler(config.controlDir)
+  const background = new Map<string, ChildProcess>()
+  const tasks = new Tasks(config.controlDir)
+  const drainTaskRequests = taskRequests(tasks)
   const aiMenu = createAiMenu(control, config.executorCli, undefined, config.workspace)
   const binDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin')
 
   let activeTypingTimer: ReturnType<typeof setInterval> | null = null
+  let activeBackend = false
   let activeChild: ChildProcess | null = null
   let shuttingDown = false
   let nextSendAt = 0
@@ -91,16 +102,38 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
 
   const startJob = async (run: RunRecord): Promise<void> => {
     await withStartLock(async () => {
-      if (shuttingDown || activeChild) return
+      if (shuttingDown || activeBackend) return
       // 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 (await runs.running()) return
+      if (!run.scheduled && await runs.running(false)) return
       const owner = (await control.status()).owner
       if (!owner || owner.telegramUserId !== run.telegramUserId || owner.telegramChatId !== run.chatId) {
         await runs.patch(run.id, { status: 'failed', endedAt: new Date().toISOString() })
         return
       }
+      if (config.channelBackendUrl) {
+        if (run.external || run.taskId || run.scheduled || run.id.startsWith('r_update_')) { await runs.patch(run.id, { status: 'failed' }); return }
+        activeBackend = true
+        await runs.patch(run.id, { status: 'running', backendSubmitted: true })
+        void dispatchChannel(config, run).then(async reply => {
+          if (reply === null) { await runs.patch(run.id, { status: 'queued' }); return }
+          if (reply) await runs.enqueueMessage(run.id, reply, { id: `${run.id}_backend`, replyToMessageId: run.messageId })
+          await runs.patch(run.id, { status: 'completed', endedAt: new Date().toISOString() })
+        }).catch(async error => {
+          console.error('Channel backend unavailable', safeError(error))
+          // The backend deduplicates the stable run ID. Retry transport, never create another operation.
+          await new Promise(resolve => setTimeout(resolve, 5000))
+          await runs.patch(run.id, { status: error?.permanent ? 'failed' : 'queued' })
+        }).finally(() => { activeBackend = false })
+        return
+      }
+      if (run.scheduled && (!await scheduler.current(run, owner) || await scheduler.cancelled(run.id))) {
+        await runs.patch(run.id, {status:'cancelled',endedAt:new Date().toISOString()})
+        return
+      }
+      if (run.scheduled && !(await scheduler.get(run.scheduled.id)).enabled) return
+      if (run.scheduled ? background.size >= 4 : activeChild) return
       let texts = run.texts
       if (run.external) {
         // Availability failures leave durable queued work for a later check.
@@ -112,15 +145,25 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         }
         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
+        }
+      }
+      const blockReason = run.taskId ? undefined : executionBlockReason(run, owner)
+      if (blockReason) {
+        await runs.patch(run.id, { status: 'cancelled', blockReason, endedAt: new Date().toISOString() })
+        return
+      }
       try {
         const started = await runs.patch(run.id, { status: 'running', startedAt: new Date().toISOString() })
-        if (!started.execution) throw new Error('Legacy queued work has no pinned AI. Resend the request after /new.')
-        const session = run.external
+        if (!started.execution && !run.taskId) throw new Error('Legacy queued work has no pinned AI. Resend the request after /new.')
+        const session = run.external || run.taskId || run.scheduled
           ? { sessionId: randomUUID(), hasStarted: false, nativeSessionId: undefined }
-          : await control.executionSession(started.execution)
-        const selected = started.execution.preset
+          : await control.executionSession(started.execution!)
+        const selected = run.taskId ? { cli: 'codex', model: undefined, effort: undefined } : started.execution!.preset
         const { child, cleanup } = await launch(texts, {
-          workspace: config.workspace,
+          workspace: run.scheduled ? await taskWorkspace(config.workspace,run.id) : config.workspace,
           timeoutMs: config.executorTimeoutMs,
           runId: started.id,
           controlDir: config.controlDir,
@@ -131,9 +174,10 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           sessionId: session.nativeSessionId || session.sessionId,
           isResume: session.hasStarted,
           eventSource: run.external?.sourceId,
-          onSession: run.external ? undefined : (id) => control.saveNativeSession(session.sessionId, id),
+          onSession: run.scheduled ? async (id) => { await runs.patch(run.id,{nativeSessionId:id}) } : run.external || run.taskId ? undefined : (id) => control.saveNativeSession(session.sessionId, id),
         })
-        activeChild = child
+        if (run.scheduled) background.set(run.id,child)
+        else activeChild = child
         const finished = new Promise<number | null>((resolve) => {
           if (child.exitCode !== null || child.signalCode !== null) resolve(child.exitCode)
           else child.once('close', resolve)
@@ -147,8 +191,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           isResume: session.hasStarted,
         })
 
-        if (activeTypingTimer) clearInterval(activeTypingTimer)
-        if (!run.external) activeTypingTimer = setInterval(() => {
+        if (!run.scheduled && activeTypingTimer) clearInterval(activeTypingTimer)
+        if (!run.external && !run.taskId && !run.scheduled) activeTypingTimer = setInterval(() => {
           void bot.api.sendChatAction(run.chatId, 'typing').catch(() => {})
         }, 4000)
 
@@ -160,24 +204,27 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
             await withStartLock(async () => {
               try {
                 await cleanup()
-                if (code === 0 && !run.external) await control.markSessionStarted(session.sessionId)
-                await runs.patch(started.id, { status: code === 0 ? 'completed' : 'failed', endedAt: new Date().toISOString() })
+                if (code === 0 && !run.external && !run.taskId && !run.scheduled) await control.markSessionStarted(session.sessionId)
+                await runs.patch(started.id, { status: run.scheduled && await scheduler.cancelled(run.id) ? 'cancelled' : code === 0 ? 'completed' : 'failed', endedAt: new Date().toISOString() })
               } catch (error) {
                 await runs.patch(started.id, { status: 'failed', endedAt: new Date().toISOString() })
                 console.error('Session completion failed', safeError(error))
               } finally {
-                activeChild = null
-                if (activeTypingTimer) clearInterval(activeTypingTimer)
-                activeTypingTimer = null
+                if (run.scheduled) background.delete(run.id)
+                else {
+                  activeChild = null
+                  if (activeTypingTimer) clearInterval(activeTypingTimer)
+                  activeTypingTimer = null
+                }
               }
             })
             console.info('run ended', { run_id: started.id, code })
-            const next = await runs.nextQueued()
+            const next = await runs.nextQueued(false)
             if (next && !shuttingDown) await startJob(next)
           })().catch((error) => console.error('Run completion failed', error.message))
         })
       } catch (error) {
-        if (activeTypingTimer) {
+        if (!run.scheduled && activeTypingTimer) {
           clearInterval(activeTypingTimer)
           activeTypingTimer = null
         }
@@ -186,7 +233,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         await sendChat(run.chatId, `Run ${run.id} failed to start. Check the local relay log.`)
         setImmediate(() => {
           void runs
-            .nextQueued()
+            .nextQueued(false)
             .then((next) => next && startJob(next))
             .catch(console.error)
         })
@@ -202,8 +249,14 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       if (shuttingDown) return
       const owner = (await control.status()).owner
       if (!owner) return
+      if (!config.channelBackendUrl) {
+      await drainTaskRequests()
+      for (const task of await tasks.list()) if (task.state === 'pending' || task.state === 'active') {
+        try { await tasks.decide(task.id) } catch { /* Failed or stale grants cannot launch. */ }
+      }
       await queueUpdateAttention(config.controlDir,owner,runs,await control.captureChoice(aiMenu.initial))
-      for (const source of 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)
@@ -213,18 +266,27 @@ 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])
-            for (const events of groups.values()) await runs.create({
+            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 control.captureChoice(aiMenu.initial),
               external: { sourceId: source.id, bindingId: source.bindingId, eventIds: events.map(e => e.id) },
             })
+            }
             // Acknowledgement follows durable run creation; replay uses the saved batch.
             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 [id,child] of background) {
+        if (await scheduler.cancelled(id)) terminateJob(child)
+      }
       for (const run of (await runs.list()).filter(r => r.status === 'queued')) {
-        if (activeChild || shuttingDown) break
+        if (shuttingDown) break
         await startJob(run)
       }
     })().finally(() => { sourceWork = undefined })
@@ -239,6 +301,9 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   let intakeWork: Promise<void> | undefined
   const collectItem = (item: IncomingItem) => {
     const message = normalizing?.message
+    item.sentAt = message?.date
+    item.caption = message?.caption
+    item.albumId = message?.media_group_id
     if (message?.media_group_id) item.text = `[Telegram album: ${message.media_group_id}]\n${item.text}`
     if (message && !message.text && message.reply_to_message) {
       const quoted = message.reply_to_message
@@ -284,6 +349,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
                 telegramUserId: first.fromId,
                 messageId: first.messageId,
                 texts: collected.map((item) => item.text),
+                items: collected,
                 execution: batch.entries[0].execution,
               })
             await inbox.finish(batch.id)
@@ -328,6 +394,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
             !owner ||
             origin.telegramUserId !== owner.telegramUserId ||
             origin.chatId !== owner.telegramChatId ||
+            (origin.scheduled && origin.scheduled.pairedAt !== owner.pairedAt) ||
             item.chatId !== origin.chatId
           )
             throw new Error('Outbox ownership mismatch')
@@ -342,7 +409,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
             ])
             console.info('run reaction sent', { run_id: item.runId, emoji })
           } else if (item.type === 'document' && item.documentPath) {
-            const docPath = await workspaceFile(config.workspace, item.documentPath)
+            const docPath = await workspaceFile(origin.scheduled ? await taskWorkspace(config.workspace,origin.id) : config.workspace, item.documentPath)
             await paceSend()
             attemptedDelivery = true
             const sent = await bot.api.sendDocument(item.chatId, new InputFile(docPath), {
@@ -424,7 +491,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const commands = mainCommands
   const controlCommand = (text?: string) => text?.trim().replace(/@[a-zA-Z0-9_]+$/, '')
   const statusText = async () => {
-    const running = await runs.running()
+    const running = await runs.running(false)
     const all = await runs.list()
     const incoming = await inbox.status()
     const delivery = await runs.deliveryStatus()
@@ -437,8 +504,10 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       `Default: ${ai.presets.find((p) => p.id === ai.defaultId)!.name}`,
       `Session: ${session?.sessionId.slice(0, 8) || 'none'}`,
       `Work: ${running ? `running ${running.id}` : 'idle'}`,
+      `Background: ${all.filter(r => r.scheduled && r.status === 'running').map(r=>r.id).join(', ') || 'idle'}`,
       `Queue: ${all.filter((r) => r.status === 'queued').length} runs; ${incoming.pending} incoming messages`,
       `Failed: ${all.filter((r) => r.status === 'failed').length} runs; ${incoming.failed} incoming batches`,
+      `Blocked: ${all.filter((r) => r.blockReason === 'external-execution-unavailable').length} external runs (isolated execution unavailable)`,
       `Delivery: ${delivery.failed} failed; ${delivery.unknown} unknown/in-flight (inspect before retrying)`,
       ...(unavailableSources.size ? [`Unavailable event sources: ${[...unavailableSources].join(', ')}`] : []),
       '/stop stops active work only. /cancel clears pending work only.',
@@ -454,7 +523,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     await withStartLock(async () => {
       count += await inbox.cancel()
       for (const run of await runs.list()) {
-        if (run.status !== 'queued') continue
+        if (run.status !== 'queued' || run.backendSubmitted) continue
         await runs.patch(run.id, { status: 'cancelled', endedAt: new Date().toISOString() })
         count++
       }
@@ -505,12 +574,22 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       return
     }
 
+    if (config.channelBackendUrl && ['/new', '/ai', '/settings'].includes(text ?? '')) {
+      await ctx.reply('Conversation and model settings are managed in the connected application.')
+      return
+    }
+
     // Steering & session commands
+    if (text === '/stop' && config.channelBackendUrl) {
+      await ctx.reply('This channel uses an application backend. Stopping its active job is not supported here; check the application. /cancel removes only pending relay work.')
+      return
+    }
     if (text === '/stop') {
-      const running = await runs.running()
-      if (running && running.pid) {
+      const running = await runs.running(false)
+      if ((running && running.pid) || background.size) {
         try {
           if (activeChild) terminateJob(activeChild)
+          for (const [id,child] of background) { await scheduler.cancel(id); terminateJob(child) }
         } catch {}
         if (activeTypingTimer) {
           clearInterval(activeTypingTimer)
@@ -586,6 +665,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       const prompt = `[Attached image staged at ${staged.relativePath} (type: ${staged.fileType}, size: ${buffer.length} bytes)]${caption ? `\n\nCaption: ${caption}` : ''}`
       collectItem({
         text: prompt,
+        attachment: { path: staged.relativePath, type: staged.fileType },
         messageId: ctx.message.message_id,
         updateId: ctx.update.update_id,
         chatId: ctx.chat.id,
@@ -614,6 +694,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       const prompt = `[Attached document staged at ${staged.relativePath} (type: ${staged.fileType}, size: ${buffer.length} bytes)]${caption ? `\n\nCaption: ${caption}` : ''}`
       collectItem({
         text: prompt,
+        attachment: { path: staged.relativePath, type: staged.fileType },
         messageId: ctx.message.message_id,
         updateId: ctx.update.update_id,
         chatId: ctx.chat.id,
@@ -693,6 +774,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         const original = ctx.callbackQuery.message?.text || ''
         const updated = `${escapeHtml(original)}\n\n<b>Decision:</b> ${isApproved ? 'Approved ✅' : 'Denied ❌'}`
         await ctx.editMessageText(updated, { parse_mode: 'HTML' }).catch(() => {})
+        if (await tasks.decide(actionId)) { void drainSources(); return }
         collectItem({
           text: JSON.stringify({ event: 'approval_decision', actionId, decision, prompt: request?.prompt }),
           messageId: ctx.callbackQuery.message?.message_id,
@@ -702,6 +784,9 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         })
         console.info('Approval decision recorded', { actionId, decision: isApproved ? 'approved' : 'denied' })
       }
+    } else if (config.channelBackendUrl && ['menu:new', 'menu:ai', 'menu:settings'].includes(data)) {
+      await ctx.answerCallbackQuery()
+      await ctx.reply('Conversation and model settings are managed in the connected application.')
     } else if (await aiMenu.handle(ctx)) {
       return
     } else if (data.startsWith('menu:')) {
@@ -728,10 +813,14 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       } else if (action === 'cancel') {
         await ctx.answerCallbackQuery()
         await ctx.reply(await cancelPending())
+      } else if (action === 'stop' && config.channelBackendUrl) {
+        await ctx.answerCallbackQuery()
+        await ctx.reply('This channel uses an application backend. Stopping its active job is not supported here; check the application.')
       } else if (action === 'stop') {
-        const running = await runs.running()
-        if (running && running.pid) {
+        const running = await runs.running(false)
+        if ((running && running.pid) || background.size) {
           if (activeChild) terminateJob(activeChild)
+          for (const [id,child] of background) { await scheduler.cancel(id); terminateJob(child) }
           await ctx.answerCallbackQuery({ text: 'Run stopped' })
           await ctx.reply(
             '🛑 Stop requested for active work. Queued work remains and will run next. /cancel clears it.',
@@ -755,6 +844,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     if (intakeTimer) clearTimeout(intakeTimer)
     if (sourceTimer) clearInterval(sourceTimer)
     if (activeChild) terminateJob(activeChild)
+    for (const child of background.values()) terminateJob(child)
     if (activeTypingTimer) clearInterval(activeTypingTimer)
     if (sourceWork) await sourceWork.catch(() => {})
     if (bot.isRunning()) await bot.stop()
@@ -762,9 +852,11 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
 
   const start = async () => {
     await initializeWorkspace(config.workspace)
+    await scheduler.recover(runs)
     sourceTimer = setInterval(() => {
       void drainSources().catch(error => console.error('Event-source drain failed', safeError(error)))
     }, 1000)
+    const taskTimer = setInterval(() => { void drainTaskRequests().catch(console.error) }, 250)
     const drainTimer = setInterval(() => {
       void drainOutbox().catch((error) => console.error('Outbox drain failed', error.message))
     }, 250)
@@ -773,12 +865,15 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       console.log(`ezenciel-agents listening with workspace ${config.workspace}`)
       console.log(`Authority control state: ${config.controlDir}`)
       console.log(`CLI executor: ${config.executorCli}`)
-      await aiMenu.refresh()
+      if (!config.channelBackendUrl) await aiMenu.refresh()
 
       // Reconcile stale runs and start any queued run on boot
-      const currentRunning = await runs.running()
+      if (config.channelBackendUrl) {
+        for (const run of await runs.list()) if (run.status === 'running' && !run.pid) await runs.patch(run.id, { status: 'queued' })
+      }
+      const currentRunning = await runs.running(false)
       if (!currentRunning) {
-        const pendingRun = await runs.nextQueued()
+        const pendingRun = await runs.nextQueued(false)
         if (pendingRun) {
           console.info('Processing queued run on startup:', pendingRun.id)
           void startJob(pendingRun)
@@ -796,10 +891,11 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       })
     } finally {
       clearInterval(drainTimer)
+      clearInterval(taskTimer)
       if (sourceTimer) clearInterval(sourceTimer)
     }
   }
-  return { bot, start, stop, drainOutbox, drainInbox, drainSources }
+  return { bot, start, stop, drainOutbox, drainInbox, drainSources, drainTaskRequests }
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {

package/src/plugins/exposure.mjs

@@ -0,0 +1,13 @@
+// Self-reported exposure is discovery metadata, never an authority grant.
+const fields = ['receivesExternalContent', 'sendsExternally', 'changesRecords', 'requiresReview'];
+export function exposure(value) {
+  if (value !== undefined && (!value || typeof value !== 'object' || Array.isArray(value) ||
+      Object.keys(value).some(key => !fields.includes(key)) ||
+      Object.values(value).some(item => typeof item !== 'boolean')))
+    throw new Error('Invalid plugin exposure declaration');
+  return Object.fromEntries(fields.map(key => [key, value?.[key] ?? true]));
+}
+export function commandExposure(manifest) {
+  return Object.fromEntries(Object.entries(manifest.commands).map(([name, command]) =>
+    [name, { declared: command.exposure !== undefined, ...exposure(command.exposure) }]));
+}

package/src/plugins/manager.mjs

@@ -1,3 +1,4 @@
+import { exposure, commandExposure } from './exposure.mjs';
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -83,7 +84,7 @@ 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']); strings(c.args);
+    keys(c,['executable','args','exposure']); strings(c.args); exposure(c.exposure);
     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||[]);
@@ -118,14 +119,22 @@ function dockerEnv() {
 export function run(argv,{capture=false,container}={}) {
   return new Promise((resolve,reject)=>{
     const child=spawn('docker',argv,{env:dockerEnv(),stdio:capture?['ignore','pipe','pipe']:['inherit','inherit','inherit']});
-    let stdout='',stderr='',cancelled=false;
+    let stdout='',stderr='',cancelled=false,killTimer;
     if(capture) {child.stdout.on('data',b=>stdout+=b);child.stderr.on('data',b=>stderr+=b);}
-    const cancel=signal=>{cancelled=true;child.kill(signal);};
+    const cancel=signal=>{cancelled=true;child.kill(signal);killTimer??=setTimeout(()=>child.kill('SIGKILL'),2000);};
     const term=()=>cancel('SIGTERM'),int=()=>cancel('SIGINT');
     process.on('SIGTERM',term);process.on('SIGINT',int);
-    child.once('error',reject);
+    child.once('error',error=>{clearTimeout(killTimer);process.off('SIGTERM',term);process.off('SIGINT',int);reject(error);});
     child.once('close',async(code,signal)=>{process.off('SIGTERM',term);process.off('SIGINT',int);
-      if(cancelled&&container) await run(['rm','-f',container],{capture:true});
+      clearTimeout(killTimer);
+      if(cancelled&&container) {
+        try {
+          const cleanup=await run(['container','rm','--force',container],{capture:true});
+          // Compose --rm may already have removed this exact command container.
+          if(cleanup.code!==0&&!cleanup.stderr.includes(`No such container: ${container}`))
+            return reject(Error(`Cancelled command container cleanup failed: ${cleanup.stderr||cleanup.stdout}`));
+        } catch(error) {return reject(error);}
+      }
       resolve({code:cancelled?130:code??(signal?130:1),stdout,stderr});});
   });
 }
@@ -142,7 +151,8 @@ async function registry(home) {
   for(const [alias,plugin] of Object.entries(r.commands)) if(!r.plugins[plugin]?.deployment?.commands?.[alias]) throw Error('Corrupt command registry');
   return r;
 }
-export async function init(home,workspace,catalogFile,hostConfig) {
+export async function init(home,workspace,catalogFile,hostConfig,standalone=false) {
+  if(standalone && hostConfig) throw Error('Standalone setup cannot bind a relay host config');
   if(typeof home!=='string'||typeof workspace!=='string'||!path.isAbsolute(home)||!path.isAbsolute(workspace)||/[\r\n\0$:,]/.test(home+workspace)) throw Error('Explicit absolute home/workspace required');
   workspace=await fs.realpath(workspace);await privateDir(home);home=await fs.realpath(home);
   if(await fs.lstat(path.join(home,'registry.json')).catch(()=>null)) throw Error('Registry already exists; refusing replacement');
@@ -171,7 +181,7 @@ export async function init(home,workspace,catalogFile,hostConfig) {
     }
   });
   const index=path.join(workspace,'TOOLS.md');
-  const prior=await fs.readFile(index,'utf8').catch(e=>{if(e.code==='ENOENT')return fs.readFile(new URL('../../templates/agent/TOOLS.md',import.meta.url),'utf8');throw e;});
+  const prior=await fs.readFile(index,'utf8').catch(e=>{if(e.code==='ENOENT')return fs.readFile(new URL(standalone?'../../templates/standalone-tools.md':'../../templates/agent/TOOLS.md',import.meta.url),'utf8');throw e;});
   await fs.writeFile(index,prior+'\n## Registered plugins\n\nUse `'+path.join(home,'bin','ez')+'` for this agent only.\nDiscover reviewed packages with `ez plugins available`; inspect with `ez plugins inspect <id>`.\nOn an authorized installation request, run `ez plugins install <id>`, then `ez plugins start <id>`.\nRead the installed skill paths from `ez plugins list` before onboarding or provider operations.\nUse `ez tools list` for aliases and `ez <alias> --help` for native commands.\nInstallation does not grant send authority. The registry is the only plugin installation, command and lifecycle authority. Do not create standalone provider launchers or deployments.\n',{mode:0o600});
   if(hostConfig && path.basename(hostConfig)==='host-executor.json') await (await import('../updates/binding.mjs')).bindUpdates(home,hostConfig);
   return {ok:true,launcher:path.join(home,'bin','ez'),workspace};
@@ -214,22 +224,27 @@ export async function main(args) {
   // Only the fixed launcher may supply the leading home binding. Never consume plugin arguments here.
   let home;if(args[0]==='--home') {home=args[1];args=args.slice(2);}
   if(args[0]==='enable-updates') {args.shift();const h=take('--home'),host=take('--host-config');if(args.length||!h||!host)throw Error('Supply --home and --host-config');return emit(await (await import('../updates/binding.mjs')).bindUpdates(h,host));}
-  if(args[0]==='init') {args.shift();const options=[take('--home'),take('--workspace'),take('--catalog'),take('--host-config')];if(args.length)throw Error('Unknown init arguments');return emit(await init(...options));}
+  if(!home && (args.length===0 || (args.length===1 && ['--help','-h'].includes(args[0])))) return emit({usage:'ezenciel-agents-tools init --standalone --home /absolute/tools --workspace /absolute/workspace',relay:'Omit --standalone and supply --host-config for a relay binding',discovery:'Use the returned launcher from any local executor; read workspace/TOOLS.md'});
+  if(args[0]==='init') {args.shift();const standalone=args.includes('--standalone');if(standalone)args.splice(args.indexOf('--standalone'),1);const options=[take('--home'),take('--workspace'),take('--catalog'),take('--host-config')];if(args.length)throw Error('Unknown init arguments');return emit(await init(...options,standalone));}
   if(!home || !path.isAbsolute(home)) throw Error('Use the agent-bound launcher, or init --home /absolute/tools --workspace /absolute/mind --catalog /absolute/catalog.json');
   home=await fs.realpath(home);
   const config=await json(path.join(home,'config.json'));
   if(config.schemaVersion!==1 || !path.isAbsolute(config.workspace)) throw Error('Invalid binding');
   const [group,action,...rest]=args;
-  if(group==='status'){if(args.length!==1)throw Error('Use status without arguments');return emit(await (await import('../updates/status.mjs')).status(home));}
+  if(group==='status'){if(args.length!==1)throw Error('Use status without arguments');await registry(home);return emit(await (await import('../updates/status.mjs')).status(home));}
   if(group==='updates')return emit(await (await import('../updates/control.mjs')).command(home,args.slice(1)));
-  if(group==='--help'||!group) return emit({commands:['status','updates check|policy|prepare|apply|status','plugins available|catalog-add|list|inspect|install|start|stop|status|logs|uninstall|export','tools list','<registered CLI> ...'],scope:home});
+  if(group==='--help'||!group) return emit({commands:['status','updates check|policy|prepare|apply|status','plugins available|catalog-add|list|inspect|install|start|stop|status|logs|uninstall|export','tools list|exposure','<registered CLI> ...'],scope:home});
   if(group==='plugins'&&(!action||args.includes('--help'))) return emit({commands:['available','list','inspect <id>','install <id>','start <id>','stop <id>','status <id>','logs <id>','uninstall <id>','catalog-add <id> --source PATH --revision HASH','export <id> <artifact> --output PATH'],uninstall:'Stops and removes containers/network and unregisters aliases; retains all volumes and secrets. No data deletion flag.',scope:home});
   if(group==='plugins'||group==='tools') {
     args=rest;args=args.filter(a=>a!=='--json');
     if(action==='available'&&group==='plugins') return emit(config.catalog);
     const r=await registry(home);
     if(action==='list') return emit(group==='tools'?r.commands:r.plugins);
-    if(group==='tools') throw Error('Only tools list is supported; installation registers CLI bindings');
+    if(group==='tools' && action==='exposure') {
+      if(args.length) throw Error('Use tools exposure without arguments');
+      return emit(Object.fromEntries(Object.entries(r.plugins).map(([name, record]) => [name, commandExposure(record.manifest)])));
+    }
+    if(group==='tools') throw Error('Use tools list or tools exposure; installation registers CLI bindings');
     const name=args.shift();id(name);
     if(action==='inspect'||action==='install'||action==='catalog-add') {
       const source=take('--source')||config.catalog[name]?.source,revision=take('--revision')||config.catalog[name]?.revision;
@@ -238,7 +253,7 @@ export async function main(args) {
         const p=await snapshot(source);if(p.manifest.id!==name||p.revision!==revision)throw Error('Inspect and pin the exact catalog package first');
         return locked(home,async()=>{const latest=await json(path.join(home,'config.json'));latest.catalog[name]={source:p.source,revision:p.revision};await atomic(path.join(home,'config.json'),latest);emit({ok:true,plugin:name,revision:p.revision,installed:false});});
       }
-      if(action==='inspect') {const p=await snapshot(source);return emit({id:p.manifest.id,source:p.source,revision:p.revision,catalogRevision:config.catalog[name]?.revision??null,catalogMatches:config.catalog[name]?.source===p.source&&config.catalog[name]?.revision===p.revision,inspection:'Read-only; does not update the catalog pin. After review, pass --revision to install or use catalog-add --source --revision.',manifest:p.manifest,deployment:p.deployment});}
+      if(action==='inspect') {const p=await snapshot(source);return emit({id:p.manifest.id,source:p.source,revision:p.revision,catalogRevision:config.catalog[name]?.revision??null,catalogMatches:config.catalog[name]?.source===p.source&&config.catalog[name]?.revision===p.revision,inspection:'Read-only; does not update the catalog pin. After review, pass --revision to install or use catalog-add --source --revision.',manifest:p.manifest,exposure:commandExposure(p.manifest),deployment:p.deployment});}
       return emit(await install(home,config,name,source,revision));
     }
     const record=r.plugins[name];if(!record)throw Error('Plugin not installed');

package/src/process-tree.ts

@@ -0,0 +1,33 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+type ProcessInfo = {parent: number; birth: string}
+type Snapshot = Map<number, ProcessInfo>
+
+export const matchingProcessIds = (original: Snapshot, current: Snapshot): number[] =>
+  [...original].filter(([pid, info]) => info.birth && current.get(pid)?.birth === info.birth).map(([pid]) => pid)
+
+export const processSnapshot = async (): Promise<Snapshot> => {
+  if (process.platform === 'win32') return new Map()
+  if (process.platform !== 'linux') {
+    const {stdout} = await promisify(execFile)('/bin/ps', ['-axo', 'pid=,ppid=,lstart='], {timeout: 2000})
+    return new Map(stdout.trim().split('\n').flatMap(line => {
+      const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/)
+      return match ? [[Number(match[1]), {parent:Number(match[2]),birth:match[3]}] as const] : []
+    }))
+  }
+  const scan = async (): Promise<Snapshot> => new Map(await Promise.all(
+    (await readdir('/proc')).filter(id => /^\d+$/.test(id)).map(async id => {
+      const stat = await readFile(`/proc/${id}/stat`, {encoding:'utf8',signal:AbortSignal.timeout(2000)}).catch(() => '')
+      const fields = stat.slice(stat.lastIndexOf(')')+2).split(' ')
+      return [Number(id), {parent:Number(fields[1]),birth:fields[19] || ''}] as const
+    }),
+  ))
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([scan(), new Promise<never>((_,reject) => {
+      timer = setTimeout(() => reject(new Error('Process inspection timed out')),2000)
+    })])
+  } finally { clearTimeout(timer) }
+}