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

package/src/menu.ts

@@ -3,18 +3,21 @@ import { readFile } from 'node:fs/promises'
 import path from 'node:path'
 import { randomBytes } from 'node:crypto'
 import { InlineKeyboard, type Context } from 'grammy'
-import { ControlStore } from './control-state.js'
+import { ControlStore, type ControlGuard } from './control-state.js'
 import { chatPreset, installed, persistedPreset, presetLabel, readModels, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
 import { discoverDefaults } from './client-defaults.js'
 
 export const mainCommands = [
   { command: 'new', description: 'New conversation' },
+  { command: 'chats', description: 'Conversations' },
+  { command: 'rename', description: 'Rename current conversation' },
   { command: 'ai', description: 'Choose AI' },
   { command: 'status', description: 'Work status' },
 ]
 
 export const mainKeyboard = () => new InlineKeyboard()
-  .text('New conversation', 'menu:new').text('Choose AI', 'menu:ai').row()
+  .text('New conversation', 'menu:new').text('Conversations', 'menu:chats').row()
+  .text('Choose AI', 'menu:ai')
   .text('Work status', 'menu:status')
 
 const clientLabel = (cli: string) => cli === 'codex-gui' ? 'codex-gui (desktop)' : cli
@@ -47,13 +50,19 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     buttons.set(id, { expires: Date.now() + 15 * 60_000, action })
     keyboard.text(label.slice(0, 64), `ai:${id}`).row()
   }
-  const choose = async (ctx: Context, preset: AiPreset) => {
+  const select = async (preset: AiPreset, expectedSession: string | null, guard?: ControlGuard) => {
     await validate(preset)
     const session = await control.getActiveSession()
-    const state = await control.aiState(initial)
+    const state = (await control.status()).ai
+    if (!state) throw new Error('AI settings not initialized')
     const current = state.presets.find((p) => p.id === state.selectedId)!
     const fresh = current.cli !== preset.cli || Boolean(session && !session.cli)
-    await control.selectPreset(preset.id, session?.sessionId ?? null, fresh)
+    if (!await control.selectPreset(preset.id, expectedSession, fresh, guard)) throw new Error('AI binding changed. Refresh available AIs before trying again.')
+    return { preset, fresh }
+  }
+  const choose = async (ctx: Context, preset: AiPreset) => {
+    const session = await control.getActiveSession()
+    const { fresh } = await select(preset, session?.sessionId ?? null)
     await ctx.reply(`${preset.name}\n${presetLabel(preset)}\n${fresh
       ? 'CLI changed: fresh conversation. Files kept; queued work unchanged.'
       : 'Selected for this conversation. Queued work unchanged.'}`)
@@ -103,20 +112,28 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     button(keyboard, 'Back to clients', (next) => list(next))
     await ctx.reply(`${clientLabel(cli)}\nChoose a model`, { reply_markup: keyboard })
   }
-  const save = async (ctx: Context, model: ModelChoice, effort?: string) => {
-    const state = await control.aiState(initial)
+  const saveSelection = async (model: ModelChoice, effort?: string, guard?: ControlGuard) => {
+    const state = (await control.status()).ai
+    if (!state) throw new Error('AI settings not initialized')
     const candidate: AiPreset = { id: randomBytes(8).toString('hex'),
       name: `${model.name}${effort ? ` · ${effort}` : ''}`.slice(0, 80), cli: model.cli, model: model.model, effort }
     const stored = persistedPreset(candidate)
     const existing = state.presets.find((preset) => preset.cli === stored.cli && preset.model === stored.model && preset.effort === stored.effort)
     const preset = existing ?? candidate
     await validateSelection(preset, await catalog(), host ? async name => (await catalog()).some(model => model.cli === name) : isInstalled)
-    await control.savePreset(preset)
-    await choose(ctx, preset)
+    await control.savePreset(preset, guard)
+    return preset
+  }
+  const save = async (ctx: Context, model: ModelChoice, effort?: string) => {
+    await choose(ctx, await saveSelection(model, effort))
   }
   return {
     initial,
     refresh,
+    validate,
+    catalog: () => catalog(),
+    select,
+    saveSelection,
     list,
     async handle(ctx: Context): Promise<boolean> {
       const data = ctx.callbackQuery?.data

package/src/message-history.ts

@@ -0,0 +1,52 @@
+import { readFile, readdir } from 'node:fs/promises'
+import { join, basename } from 'node:path'
+import { requireOwnerExecution } from './execution-authority.js'
+import { ControlStore } from './control-state.js'
+import { ownsRun } from './identity.js'
+import { RunStore } from './runs.js'
+
+// Read existing delivery receipts; native sessions still own conversation history.
+export async function deliveredMessages(controlDir: string, runId: string, options: { limit?: number; messageId?: number } = {}) {
+  const limit = options.limit ?? 8
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 50) throw new Error('Limit must be 1..50')
+  if (options.messageId !== undefined && (!Number.isSafeInteger(options.messageId) || options.messageId < 1))
+    throw new Error('Message ID must be a positive integer')
+  const caller = await requireOwnerExecution(controlDir, runId)
+  if (caller.application || caller.delivery) throw new Error('History requires a Telegram owner run')
+  const owner = (await new ControlStore(controlDir, 900_000).status()).owner
+  if (!ownsRun(owner, caller)) throw new Error('Owner binding changed')
+  const pairedAt = Date.parse(owner!.pairedAt)
+  const runs = new Map((await new RunStore(controlDir).list()).filter(run =>
+    ownsRun(owner, run) && !run.external && !run.taskId && !run.application &&
+    Date.parse(run.createdAt) >= pairedAt && (!run.scheduled || run.scheduled.pairedAt === owner!.pairedAt)
+  ).map(run => [run.id, run]))
+  const directory = join(controlDir, 'outbox')
+  const files = await readdir(directory).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === 'ENOENT') return []
+    throw error
+  })
+  const messages = []
+  for (const file of files.filter(file => file.endsWith('.sent.json'))) {
+    // Corrupt or incomplete receipts are not delivery evidence.
+    let item
+    try { item = JSON.parse(await readFile(join(directory, file), 'utf8')) } catch { continue }
+    if (!item || typeof item !== 'object') continue
+    const run = runs.get(item.runId)
+    const deliveredAt = Date.parse(item.receipt?.deliveredAt)
+    const ids = item.receipt?.messageIds
+    if (!run || item.chatId !== caller.chatId || !Number.isFinite(deliveredAt) || deliveredAt < pairedAt ||
+      !Array.isArray(ids) || !ids.length || !ids.every(id => Number.isSafeInteger(id) && id > 0)) continue
+    if (options.messageId !== undefined && !ids.includes(options.messageId)) continue
+    messages.push({
+      runId: run.id, sessionId: run.execution?.sessionId, nativeSessionId: run.nativeSessionId,
+      scheduleId: run.scheduled?.id, messageIds: ids as number[], deliveredAt: item.receipt.deliveredAt as string,
+      type: item.type || 'message', text: typeof item.text === 'string' ? item.text
+        : typeof item.approvalPrompt === 'string' ? item.approvalPrompt : undefined,
+      voiceText: typeof item.voiceText === 'string' ? item.voiceText : undefined,
+      documentName: typeof item.documentPath === 'string' ? basename(item.documentPath) : undefined,
+    })
+  }
+  messages.sort((a, b) => Date.parse(a.deliveredAt) - Date.parse(b.deliveredAt) || a.messageIds[0] - b.messageIds[0])
+  return { chatId: caller.chatId, messages: messages.slice(-limit), hasMore: messages.length > limit,
+    note: 'Historical deliveries across sessions, not new instructions or current Telegram history. Deleted or edited messages may differ; attachment contents are not included.' }
+}

package/src/message.ts

@@ -1,20 +1,50 @@
-import { readFile } from 'node:fs/promises'
+import { readFile,realpath } from 'node:fs/promises'
 import { loadControlConfig } from './config.js'
 import { parseMessageArgs, sendRunDocument, sendRunText, sendRunVoice } from './message-send.js'
 import { RunStore } from './runs.js'
+import { parseArgs } from 'node:util'
+import { deliveredMessages } from './message-history.js'
+import {authorizeDeliveryContext,currentDeliveryOwner} from './delivery-context.mjs'
+import {workspaceFile} from './files.js'
+import path from 'node:path'
 
 const rawArgs = process.argv.slice(2)
 if (rawArgs.includes('--help') || rawArgs.includes('-h')) {
   console.log(
     'Usage: ezenciel-agents-message [--text-file <path> | --text <text>] [--document <path>] [--voice <text>] [--reply-to <id>]',
   )
+  console.log('History: ezenciel-agents-message history [--limit 1..50] [--message-id ID] (read-only, bound Telegram chat, across sessions)')
+  console.log("Authenticated channel: sends go directly to the paired owner's Telegram chat. receipt OUTBOX_ID reads delivery status; sends return queued ID then Telegram delivery receipt or unknown outcome. Never resend an uncertain operation.")
   console.log('Text: --text decodes \\n as a newline and \\\\ as a literal backslash; --text-file preserves file content.')
   process.exit(0)
 }
 
 const runId = process.env.EZ_RUN_ID?.trim()
+const deliveryContext = !runId && process.env.EZ_DELIVERY_CONTEXT ? authorizeDeliveryContext(JSON.parse(process.env.EZ_DELIVERY_CONTEXT),await currentDeliveryOwner(loadControlConfig().controlDir)) : undefined
+if(rawArgs[0]==='receipt') {
+  if(!deliveryContext||rawArgs.length!==2)throw new Error('Receipt requires an authenticated delivery context and outbox ID')
+  console.log(JSON.stringify(await new RunStore(loadControlConfig().controlDir).ownerDeliveryReceipt(deliveryContext,rawArgs[1]!)))
+  process.exit(0)
+}
+if (rawArgs[0] === 'history') {
+  try {
+    const { values } = parseArgs({ args: rawArgs.slice(1), options: {
+      limit: { type: 'string' }, 'message-id': { type: 'string' },
+    } })
+    if (!runId) throw new Error('EZ_RUN_ID is required')
+    const result = await deliveredMessages(loadControlConfig().controlDir, runId, {
+      limit: values.limit === undefined ? undefined : Number(values.limit),
+      messageId: values['message-id'] === undefined ? undefined : Number(values['message-id']),
+    })
+    await new Promise<void>((resolve, reject) => process.stdout.write(JSON.stringify(result) + '\n', error => error ? reject(error) : resolve()))
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exit(1)
+  }
+  process.exit(0)
+}
 const args = parseMessageArgs(rawArgs)
-if (!runId) {
+if (!runId && !deliveryContext) {
   console.error('EZ_RUN_ID is required')
   process.exit(1)
 }
@@ -23,6 +53,7 @@ const store = new RunStore(loadControlConfig().controlDir)
 
 let textContent = args.text?.trim()
 if (args.textFile) {
+  if(deliveryContext)throw new Error('Channel delivery requires inline text, not host file input')
   try {
     textContent = (await readFile(args.textFile, 'utf8')).trim()
   } catch (err: any) {
@@ -32,12 +63,20 @@ if (args.textFile) {
 }
 
 let item
-if (args.document) {
-  item = await sendRunDocument(store, runId, args.document, textContent, { replyTo: args.replyTo })
+if(deliveryContext) {
+  if(args.document) {
+    if(!process.env.EZ_AGENT_WORKSPACE)throw new Error('Channel delivery requires owning workspace')
+    const documentPath=await workspaceFile(process.env.EZ_AGENT_WORKSPACE,args.document)
+    item=await store.enqueueOwnerDelivery(deliveryContext,{type:'document',documentPath:path.relative(await realpath(process.env.EZ_AGENT_WORKSPACE),documentPath),text:textContent,replyToMessageId:args.replyTo})
+  } else if(args.voice) item=await store.enqueueOwnerDelivery(deliveryContext,{type:'voice',voiceText:args.voice,replyToMessageId:args.replyTo})
+  else if(textContent) item=await store.enqueueOwnerDelivery(deliveryContext,{type:'message',text:textContent,replyToMessageId:args.replyTo})
+  else throw new Error('Message content is required')
+} else if (args.document) {
+  item = await sendRunDocument(store, runId!, args.document, textContent, { replyTo: args.replyTo })
 } else if (args.voice) {
-  item = await sendRunVoice(store, runId, args.voice, { replyTo: args.replyTo })
+  item = await sendRunVoice(store, runId!, args.voice, { replyTo: args.replyTo })
 } else if (textContent) {
-  item = await sendRunText(store, runId, textContent, { replyTo: args.replyTo })
+  item = await sendRunText(store, runId!, textContent, { replyTo: args.replyTo })
 } else {
   console.error(
     'Usage: ezenciel-agents-message [--text-file <path> | --text <text>] [--document <path>] [--voice <text>] [--reply-to <id>]',
@@ -46,12 +85,14 @@ if (args.document) {
 }
 
 try {
-  const receipt = await store.waitForDelivery(item.id)
+  if(deliveryContext)console.log(JSON.stringify({ok:true,status:'queued',outbox_id:item.id}))
+  const receipt = await store.waitForDelivery(item.id,deliveryContext?20000:undefined)
   console.log(
     JSON.stringify({
       ok: true,
       status: 'delivered',
       run: runId,
+      ...(deliveryContext?{connection:deliveryContext.connectionId}:{}),
       outbox_id: item.id,
       type: item.type,
       receipt,

package/src/owner.ts

@@ -2,13 +2,14 @@ import { loadControlConfig } from './config.js'
 import { ControlStore } from './control-state.js'
 import { parseOwnerArgs } from './owner-args.js'
 
-const help = 'Usage: ezenciel-agents-owner status | approve <telegram-user-id> | approve-group <negative-chat-id> | revoke'
+const help = 'Usage: ezenciel-agents-owner status | register <verified-owner-id> | approve <telegram-user-id> | approve-group <negative-chat-id> | unlink-telegram | revoke'
 if (process.argv.slice(2).some(arg => arg === '--help' || arg === '-h')) {
   console.log(help)
   process.exit(0)
 }
 
 const { command, value } = parseOwnerArgs(process.argv.slice(2))
+if (process.env.EZ_RUN_ID && command !== 'status') throw new Error('Owner registration and channel linking require the installing administrator')
 const config = loadControlConfig()
 const store = new ControlStore(config.controlDir, config.pairingTtlMs)
 
@@ -20,6 +21,11 @@ const usage = (): never => {
 if (command === 'status' && !value) {
   const state = await store.status()
   console.log(JSON.stringify({ owner: state.owner, pending: state.pending, control_dir: config.controlDir }, null, 2))
+} else if (command === 'register' && value) {
+  console.log(JSON.stringify(await store.registerOwner(value)))
+} else if (command === 'unlink-telegram' && !value) {
+  await store.unlinkTelegram()
+  console.log('Telegram unlinked; installation owner and sessions retained.')
 } else if ((command === 'approve' || command === 'approve-group') && value) {
   const owner = await store.approveOwner(Number(value), command === 'approve-group')
   console.log(`Paired Telegram owner ${owner.telegramUserId}.`)

package/src/plugins/connection-artifacts.mjs

@@ -0,0 +1,31 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import {createHash,randomUUID} from 'node:crypto';
+
+// Preserve CLI stdout as bytes without putting attachments into model context.
+export async function commandArtifact(workspace,name,execute,{signal}={}) {
+  if(typeof name!=='string'||!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,119}$/.test(name))throw Error('Expected a simple output filename');
+  const root=await fs.realpath(workspace),directory=path.join(root,'artifacts');
+  await fs.mkdir(directory,{recursive:true,mode:0o700});
+  if(await fs.realpath(directory)!==directory)throw Error('Artifact directory must not be a symlink');
+  const controller=new AbortController(),cancel=()=>controller.abort();
+  signal?.addEventListener('abort',cancel,{once:true});
+  if(signal?.aborted)controller.abort();
+  let bytes=0,overflow=false;const chunks=[];
+  try {
+    controller.signal.throwIfAborted();
+    const result=await execute({signal:controller.signal,onStdout:chunk=>{
+      bytes+=chunk.length;
+      if(bytes>20*1024*1024){overflow=true;controller.abort();return;}
+      if(!overflow)chunks.push(Buffer.from(chunk));
+    }});
+    if(overflow)throw Error('Artifact exceeds 20 MiB limit');
+    controller.signal.throwIfAborted();
+    if(result.code!==0)return result;
+    const content=Buffer.concat(chunks),relative=path.join('artifacts',`${randomUUID()}_${name}`);
+    // Check the parent again after the command, before writing its result.
+    if(await fs.realpath(directory)!==directory)throw Error('Artifact directory changed');
+    await fs.writeFile(path.join(root,relative),content,{mode:0o600,flag:'wx'});
+    return {...result,stdout:'',artifact:{path:relative,bytes:content.length,sha256:createHash('sha256').update(content).digest('hex')}};
+  } finally {signal?.removeEventListener('abort',cancel);}
+}

package/src/plugins/connection.mjs

@@ -0,0 +1,124 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { registry, prepareCommand, run } from './manager.mjs';
+import { invokeLease } from './workspace-lease.mjs';
+import { nativeTasks,nativeTaskBinding,nativeCommands } from './native-tasks.mjs';
+import {currentDeliveryOwner,captureDeliveryContext} from '../delivery-context.mjs';
+import {commandArtifact} from './connection-artifacts.mjs';
+
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const reserved = ['coreRequest','coreResponse','coreApprove','coreApproval','coreApprovalResolved','coreCancel'];
+const maxFrame = 1048576;
+function requestId(value) {if(typeof value!=='string'||!/^[a-zA-Z0-9_-]{1,100}$/.test(value))throw Error('Invalid request id');return value;}
+
+// The local owning connection uses the same installed authority as its bound CLI.
+export function connectionProtocol({readRegistry,execute,executeNative,listNative=nativeCommands,readOwner,sendClient,sendPlugin,excludedPlugin}) {
+  const active=new Map(),consumed=new Set();let closed=false;
+  async function record(alias) {
+    const r=await readRegistry(),plugin=r.commands[alias],value=r.plugins[plugin];
+    if(!value||plugin===excludedPlugin)throw Error('Unknown or unavailable registered CLI');
+    return value;
+  }
+  async function perform(req,state) {
+    const p=req.params??{};
+    if(!object(p))throw Error('Invalid request params');
+    if(req.method==='tools.owner') {
+      if(Object.keys(p).length||!readOwner)throw Error('Owner identity unavailable');
+      await readRegistry();return readOwner();
+    }
+    if(req.method==='tools.native.list') {await readRegistry();return listNative();}
+    if(req.method==='tools.native') {
+      if(Object.keys(p).some(k=>!['command','args'].includes(k)))throw Error('Unknown native request parameter');
+      await readRegistry();
+      if(closed||state.abort.signal.aborted)throw Error('Request cancelled');
+      if(!executeNative)throw Error('Native task access is unavailable');
+      return executeNative(p.args,{signal:state.abort.signal,command:p.command??'schedule'});
+    }
+    if(req.method==='tools.list') {
+      const r=await readRegistry();return Object.entries(r.commands).filter(([,owner])=>owner!==excludedPlugin).map(([alias,owner])=>{
+        const v=r.plugins[owner];return {alias,plugin:owner,description:String(v.manifest.description??'').slice(0,200),skillCount:v.manifest.skills.length,revision:v.revision};
+      });
+    }
+    const v=await record(p.alias);
+    if(req.method==='tools.skill') {
+      const index=p.index,line=p.line??1;
+      if(!Number.isInteger(index)||index<0||index>=v.manifest.skills.length||!Number.isInteger(line)||line<1)throw Error('Invalid skill index or line');
+      const root=await fs.realpath(v.source),file=await fs.realpath(path.resolve(root,v.manifest.skills[index]));
+      if(!file.startsWith(root+path.sep))throw Error('Skill escapes plugin source');
+      const handle=await fs.open(file,'r');let text;
+      try {const stat=await handle.stat();if(!stat.isFile()||stat.size>maxFrame)throw Error('Skill exceeds read limit');text=await handle.readFile('utf8');}finally{await handle.close();}
+      const lines=text.split('\n'),selected=lines.slice(line-1,line+99).join('\n');
+      if(Buffer.byteLength(selected)>32768)throw Error('Skill page exceeds read limit');
+      return {text:selected,nextLine:line+100<=lines.length?line+100:null};
+    }
+    let args;
+    if(req.method==='tools.help')args=['--help'];
+    else if(req.method==='tools.invoke') {
+      args=p.args;
+      if(!Array.isArray(args)||args.length>100||args.some(a=>typeof a!=='string'||a.includes('\0')||a.length>8192)||p.stdin!==undefined&&(typeof p.stdin!=='string'||Buffer.byteLength(p.stdin)>65536))throw Error('Invalid literal command arguments');
+    } else throw Error('Unknown core method');
+    if(closed||state.abort.signal.aborted)throw Error('Request cancelled');
+    const current=await record(p.alias);
+    if(current.revision!==v.revision)throw Error('Plugin changed; discover again');
+    return execute(p.alias,args,{revision:v.revision,stdin:req.method==='tools.invoke'?p.stdin:undefined,output:req.method==='tools.invoke'?p.output:undefined,signal:state.abort.signal,invocation:req.method==='tools.invoke'});
+  }
+  return {
+    plugin(frame) {
+      if(closed)return;
+      if(!object(frame))throw Error('Expected JSON object');
+      if(frame.coreCancel){if(reserved.some(k=>k!=='coreCancel'&&k in frame))throw Error('Plugin forged core control frame');const id=requestId(frame.coreCancel.id),state=active.get(id);state?.abort.abort();return;}
+      if(reserved.some(k=>k!=='coreRequest'&&k in frame))throw Error('Plugin forged core control frame');
+      if(!('coreRequest' in frame)){sendClient(frame);return;}
+      const req=frame.coreRequest;if(!object(req))throw Error('Invalid core request');requestId(req.id);
+      if(active.has(req.id)||consumed.has(req.id)||active.size>=8||(req.method!=='tools.owner'&&consumed.size>=10000))throw Error('Duplicate or excessive core request');
+      if(req.method!=='tools.owner')consumed.add(req.id);
+      const state={abort:new AbortController()};active.set(req.id,state);
+      return perform(req,state).then(result=>{if(!closed)sendPlugin({coreResponse:{id:req.id,result}});},error=>{if(!closed)sendPlugin({coreResponse:{id:req.id,error:error.message}});}).finally(()=>{active.delete(req.id);});
+    },
+    client(frame) {
+      if(closed)return;
+      if(!object(frame))throw Error('Expected JSON object');
+      if(reserved.some(k=>k in frame))throw Error('Client forged core control frame');
+      sendPlugin(frame);
+    },
+    close() {closed=true;for(const state of active.values())state.abort.abort();active.clear();},
+  };
+}
+
+export function jsonLines(onFrame,onError) {
+  let buffer='';const decoder=new StringDecoder('utf8');
+  return chunk=>{try {buffer+=decoder.write(chunk);if(Buffer.byteLength(buffer)>maxFrame)throw Error('Connection frame limit exceeded');let index;while((index=buffer.indexOf('\n'))>=0){const line=buffer.slice(0,index);buffer=buffer.slice(index+1);if(line)onFrame(JSON.parse(line));}}catch(error){onError(error);}};
+}
+
+export function loopbackPublish(value) {
+  if(typeof value!=='string'||!/^\d{1,5}:\d{1,5}$/.test(value)||value.split(':').some(p=>Number(p)<1024||Number(p)>65535))throw Error('Expected host-port:container-port (1024-65535)');
+  return `127.0.0.1:${value}`;
+}
+
+export async function connect(home,alias,args,{input=process.stdin,output=process.stdout,publish,serve=false}={}) {
+  const command=await prepareCommand(home,alias,args,{...(serve?{publish:loopbackPublish(publish)}:{})}),abort=new AbortController();let child,protocol,failure;
+  const config=JSON.parse(await fs.readFile(path.join(home,'config.json'),'utf8'));
+  const nativeBinding=config.hostConfig?await nativeTaskBinding(home):undefined;
+  const deliveryContext=nativeBinding?await captureDeliveryContext(nativeBinding.env.EZ_CONTROL_DIR,command.plugin,command.revision):undefined;
+  const send=(stream,frame)=>{try {const text=JSON.stringify(frame)+'\n';if(stream?.writableLength>maxFrame||Buffer.byteLength(text)>maxFrame)throw Error('Connection backpressure limit exceeded');stream?.write(text);}catch(error){fail(error);}};
+  const fail=error=>{failure??=error;abort.abort();protocol?.close();};
+  protocol=connectionProtocol({excludedPlugin:command.plugin,readRegistry:async()=>{const r=await registry(home);if(r.commands[alias]!==command.plugin||r.plugins[command.plugin]?.revision!==command.revision)throw Error('Connected plugin changed; reconnect');return r;},
+    readOwner:async()=>{
+      if(!nativeBinding)return null;
+      const owner=await currentDeliveryOwner(nativeBinding.env.EZ_CONTROL_DIR);
+      if(!owner||owner.kind!==undefined||!Number.isSafeInteger(owner.telegramUserId)||owner.telegramUserId<=0||!Number.isSafeInteger(owner.telegramChatId)||owner.telegramChatId<=0||typeof owner.pairedAt!=='string'||!Number.isFinite(Date.parse(owner.pairedAt)))return null;
+      return {telegramUserId:owner.telegramUserId,pairedAt:JSON.stringify([owner.id,owner.generation,owner.pairedAt,owner.telegramLinkedAt,owner.telegramChatId])};
+    },
+    listNative:()=>nativeCommands().map(item=>({...item,available:!!nativeBinding&&(item.command!=='message'||!!deliveryContext)})),
+    executeNative:(args,options)=>nativeTasks(home,args,{...options,deliveryContext}),
+    execute:async(a,argv,options)=>{const release=options.invocation?await invokeLease(home):undefined;try {const c=await prepareCommand(home,a,argv,{revision:options.revision,exclude:command.plugin});if(options.signal.aborted)throw Error('Request cancelled');const execute=overrides=>run(c.argv,{...options,...overrides,container:c.container,capture:true,timeoutMs:30000,maxBytes:262144});return options.output===undefined?await execute({}):await commandArtifact(config.workspace,options.output,execute,{signal:options.signal});}finally{await release?.();}},
+    sendClient:frame=>send(output,frame),sendPlugin:frame=>send(child?.stdin,frame)});
+  const onInput=jsonLines(frame=>protocol.client(frame),fail),onEnd=()=>{protocol.close();abort.abort();};
+  const onSignal=()=>{protocol.close();abort.abort();};
+  if(serve)for(const signal of ['SIGINT','SIGTERM'])process.on(signal,onSignal);
+  try {
+    const result=await run(command.argv,{container:command.container,capture:true,maxBytes:262144,signal:abort.signal,onStdout:jsonLines(frame=>protocol.plugin(frame),fail),onStart:c=>{child=c;if(!serve){input.on('data',onInput);input.once('end',onEnd);input.resume();}}});
+    if(failure)throw failure;process.exitCode=result.code;
+  } finally {if(serve)for(const signal of ['SIGINT','SIGTERM'])process.off(signal,onSignal);input.off('data',onInput);input.off('end',onEnd);input.pause();protocol.close();}
+}

package/src/plugins/manager.mjs

@@ -141,7 +141,8 @@ export function folderMounts(config, record) {
   const mounts = config.folders?.[record.manifest.id] || [];
   if (!Array.isArray(mounts)) throw Error('Invalid folder bindings');
   for (const mount of mounts) {
-    keys(mount, ['service', 'source', 'target']);
+    keys(mount, ['service', 'source', 'target', 'writable']);
+    if (mount.writable !== undefined && typeof mount.writable !== 'boolean') throw Error('Folder writable must be boolean');
     const service = record.deployment.services[mount.service];
     containerPath(mount.target);
     if (!service || typeof mount.source !== 'string' || !path.isAbsolute(mount.source) || /[\0\r\n$]/.test(mount.source) ||
@@ -227,7 +228,7 @@ export async function compose(config, record, secrets={}, home) {
   for(const [name,s] of Object.entries(record.deployment.services)) {
     const mounts=[];
     for(const [volume,target] of Object.entries(s.volumes||{})) { volumes[volume]={};mounts.push({type:'volume',source:volume,target}); }
-    for (const folder of folders.filter(f => f.service === name)) mounts.push({type:'bind',source:folder.source,target:folder.target,read_only:true,bind:{create_host_path:false}});
+    for (const folder of folders.filter(f => f.service === name)) mounts.push({type:'bind',source:folder.source,target:folder.target,read_only:folder.writable !== true,bind:{create_host_path:false}});
     if(s.workspace) mounts.push({type:'bind',source:config.workspace,target:config.workspace,read_only:true});
     services[name]={...(s.image?{image:s.image}:{image:`${record.project}-${name}:${record.revision.slice(7,23)}`,build:{context:record.source,target:s.buildTarget}}),
       init:true,user:s.user||'1000:1000',restart:'unless-stopped',cap_drop:['ALL'],security_opt:['no-new-privileges:true'],tmpfs:['/tmp'],volumes:mounts,
@@ -247,33 +248,55 @@ export async function compose(config, record, secrets={}, home) {
 function dockerEnv() {
   return Object.fromEntries(['HOME','PATH','LANG','LC_ALL','TMPDIR','DOCKER_HOST','DOCKER_CONTEXT','DOCKER_CONFIG','BUILDX_CONFIG'].filter(k=>process.env[k]!==undefined).map(k=>[k,process.env[k]]));
 }
-export function run(argv,{capture=false,container}={}) {
+export function run(argv,{capture=false,container,signal,stdin,onStdout,onStart,timeoutMs=0,maxBytes=Infinity}={}) {
   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,killTimer;
-    if(capture) {child.stdout.on('data',b=>stdout+=b);child.stderr.on('data',b=>stderr+=b);}
+    const child=spawn('docker',argv,{env:dockerEnv(),stdio:capture?['pipe','pipe','pipe']:['inherit','inherit','inherit']});
+    let stdout='',stderr='',cancelled=false,killTimer,bytes=0,failure;
+    if(capture) {
+      const collect=(b,err)=>{bytes+=b.length;if(bytes>maxBytes){failure=Error('Command output limit exceeded');cancel('SIGTERM');return;}if(err)stderr+=b;else stdout+=b;};
+      child.stdout.on('data',b=>onStdout?onStdout(b):collect(b,false));child.stderr.on('data',b=>collect(b,true));
+      child.stdin.on('error',()=>{});
+    }
     const cancel=signal=>{cancelled=true;child.kill(signal);killTimer??=setTimeout(()=>child.kill('SIGKILL'),2000);};
     const term=()=>cancel('SIGTERM'),int=()=>cancel('SIGINT');
+    const timeout=timeoutMs?setTimeout(()=>{failure=Error('Command timed out');term();},timeoutMs):undefined;
+    signal?.addEventListener('abort',term,{once:true});if(signal?.aborted)term();
+    if(onStart)onStart(child);else if(capture)child.stdin.end(stdin);
     process.on('SIGTERM',term);process.on('SIGINT',int);
-    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);
+    child.once('error',error=>{clearTimeout(timeout);signal?.removeEventListener('abort',term);clearTimeout(killTimer);process.off('SIGTERM',term);process.off('SIGINT',int);reject(error);});
+    child.once('close',async(code,childSignal)=>{process.off('SIGTERM',term);process.off('SIGINT',int);
       clearTimeout(killTimer);
+      clearTimeout(timeout);signal?.removeEventListener('abort',term);
       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}`));
+          await removeCommandContainer(container);
         } catch(error) {return reject(error);}
       }
-      resolve({code:cancelled?130:code??(signal?130:1),stdout,stderr});});
+      if(failure)return reject(failure);
+      resolve({code:cancelled?130:code??(childSignal?130:1),stdout,stderr});});
   });
 }
+// Compose --rm can race cancellation. Confirm disappearance instead of treating
+// Docker's in-progress removal as either failure or completed cleanup.
+export async function removeCommandContainer(container,execute=run) {
+  const cleanup=await execute(['container','rm','--force',container],{capture:true});
+  if(cleanup.code===0||cleanup.stderr.includes(`No such container: ${container}`))return;
+  if(cleanup.stderr.includes(`removal of container ${container} is already in progress`)) {
+    for(let attempt=0;attempt<20;attempt++) {
+      const state=await execute(['container','inspect','--format','{{.Id}}',container],{capture:true});
+      if(state.code!==0&&(state.stderr.includes(`No such object: ${container}`)||state.stderr.includes(`No such container: ${container}`)))return;
+      if(state.code!==0)break;
+      await new Promise(resolve=>setTimeout(resolve,100));
+    }
+  }
+  throw Error(`Cancelled command container cleanup failed: ${cleanup.stderr||cleanup.stdout}`);
+}
+
 async function checked(args) {
   const r=await run(args,{capture:true});if(r.code) throw Error(r.stderr||r.stdout||`Docker failed (${r.code})`);return r.stdout;
 }
 const composeArgs = record => ['compose','--project-name',record.project,'--file',record.compose];
-async function registry(home) {
+export async function registry(home) {
   const r=await json(path.join(home,'registry.json'));
   if(r.schemaVersion!==1 || r.owner!==home || !r.plugins || !r.commands) throw Error('Corrupt registry');
   for(const [name,record] of Object.entries(r.plugins)) {
@@ -282,6 +305,21 @@ 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;
 }
+// The lock protects admission and compose refresh, never a persistent connection.
+export async function prepareCommand(home,alias,args,{revision,exclude,publish}={}) {
+  strings(args);
+  return locked(home,async()=>{
+    const config=await json(path.join(home,'config.json')),r=await registry(home);
+    const record=r.plugins[r.commands[alias]],binding=record?.deployment.commands[alias];
+    if(!binding||r.commands[alias]===exclude)throw Error('Unknown or unavailable registered CLI');
+    if(revision!==undefined&&revision!==record.revision)throw Error('Plugin changed; discover again');
+    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));
+    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||[])]};
+  });
+}
 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');
@@ -362,8 +400,13 @@ export async function main(args) {
   const [group,action,...rest]=args;
   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 [--details]|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','folder-bind <id> --service NAME --source PATH --target PATH','folder-unbind <id> --service NAME --target PATH','folders <id>','shared-enable <id> <service>','shared-disable <id> <service>','shared-status <id> <service>'],uninstall:'Stops and removes containers/network and unregisters aliases; retains all volumes and secrets. No data deletion flag.',scope:home});
+  if(group==='tools'&&action==='serve') {
+    const port=rest.shift();
+    return (await import('./connection.mjs')).connect(home,rest[0],rest.slice(1),{publish:port,serve:true});
+  }
+  if(group==='tools'&&action==='connect')return (await import('./connection.mjs')).connect(home,rest[0],rest.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 [--details]|exposure|connect <alias> <args...>|serve <host-port:container-port> <alias> <args...>','<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','folder-bind <id> --service NAME --source PATH --target PATH [--writable]','folder-unbind <id> --service NAME --target PATH','folders <id>','shared-enable <id> <service>','shared-disable <id> <service>','shared-status <id> <service>'],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);
@@ -397,6 +440,8 @@ export async function main(args) {
     if (action === 'folders') { if(args.length) throw Error('Unexpected arguments'); return emit(folderMounts(config, record)); }
     if (['folder-bind','folder-unbind'].includes(action)) {
       const service=take('--service'), target=take('--target'), source=take('--source');
+      const writable=action === 'folder-bind' && args.includes('--writable');
+      if(writable) args.splice(args.indexOf('--writable'),1);
       if(args.length || !service || !target || (action === 'folder-bind' ? !source : source !== undefined))
         throw Error('Supply --service, --target and, for folder-bind, --source');
       if(source && (!path.isAbsolute(source) || await fs.realpath(source) !== source || !(await fs.stat(source)).isDirectory()))
@@ -409,14 +454,14 @@ export async function main(args) {
         if((await checked(['ps','--filter',`label=com.docker.compose.project=${latest.project}`,'--quiet'])).trim())
           throw Error('Stop the plugin before changing folder bindings');
         const folders=(settings.folders?.[name] || []).filter(f => f.service !== service || f.target !== target);
-        if(action === 'folder-bind') folders.push({service,source,target});
+        if(action === 'folder-bind') folders.push({service,source,target,...(writable ? {writable:true} : {})});
         settings.folders={...settings.folders,[name]:folders};
         await checkFolders(settings,latest);
         const secrets=await json(path.join(home,'packages',name,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
         const generated=await compose(settings,latest,secrets,home);
         await atomic(path.join(home,'config.json'),settings);
         await atomic(latest.compose,generated);
-        return emit({ok:true,plugin:name,folders,readOnly:true,started:false});
+        return emit({ok:true,plugin:name,folders,readOnly:folders.every(folder=>folder.writable !== true),started:false});
       });
     }
     if (['shared-enable','shared-disable','shared-status'].includes(action)) {

package/src/plugins/native-tasks.d.mts

@@ -0,0 +1,4 @@
+export function nativeTaskBinding(home:string, environment?:NodeJS.ProcessEnv):Promise<{cwd:string;env:NodeJS.ProcessEnv}>;
+import type {DeliveryContext} from '../delivery-context.mjs';
+export function nativeCommands():{command:string;description:string;limitations?:string[]}[];
+export function nativeTasks(home:string,args:string[],options?:{signal?:AbortSignal;command?:string;deliveryContext?:DeliveryContext}):Promise<{code:number;stdout:string;stderr:string}>;