@jc_stack/ez-agents 0.1.0-beta.26 → 0.1.0-beta.28

package/src/menu.ts

@@ -3,24 +3,33 @@ 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 { chatPreset, presetLabel, readModels, validateSelection, type AiPreset, type ModelChoice } from './ai.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' },
-  { command: 'settings', description: 'Settings' },
 ]
 
 export const mainKeyboard = () => new InlineKeyboard()
-  .text('New conversation', 'menu:new').text('Choose AI', 'menu:ai').row()
-  .text('Work status', 'menu:status').text('Settings', 'menu:settings')
+  .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
+
+const matchesModel = (preset: AiPreset, model: ModelChoice) =>
+  model.cli === preset.cli && (preset.model === undefined || model.model === preset.model) &&
+  (preset.effort === undefined || model.efforts.includes(preset.effort))
 
 // Short-lived opaque button IDs: no model names or executable arguments from callbacks.
 // These are operational settings, not a second conversational/agent loop.
-export const createAiMenu = (control: ControlStore, cli: string, catalog = readModels, workspace = process.cwd(), codexHome?: string) => {
+export const createAiMenu = (control: ControlStore, cli: string, catalog = readModels, workspace = process.cwd(), codexHome?: string,
+  isInstalled = installed) => {
   const initial = chatPreset(cli)
   const host = process.env.EZ_EXECUTOR_TRANSPORT === 'host'
   if (host) catalog = async () => JSON.parse(await readFile(path.join(process.env.EZ_CONTROL_DIR!, 'host-executor/models.json'),'utf8'))
@@ -31,7 +40,7 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     if (preset.id.startsWith('detected_')) {
       const detected = await discoverDefaults(workspace, { codexHome })
       if (!detected.some((p) => p.id === preset.id)) throw new Error('Client settings changed. Refresh available AIs and select the updated choice.')
-    } else await validateSelection(preset, await catalog(), host ? async name => (await catalog()).some(model => model.cli === name) : undefined)
+    } else await validateSelection(preset, await catalog(), host ? async name => (await catalog()).some(model => model.cli === name) : isInstalled)
   }
   const buttons = new Map<string, { expires: number; action: (ctx: Context) => Promise<void> }>()
   const button = (keyboard: InlineKeyboard, label: string, action: (ctx: Context) => Promise<void>) => {
@@ -41,85 +50,97 @@ 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.'}`)
   }
-  const list = async (ctx: Context, settings = false) => {
-    if (!settings) {
-      const models = await catalog()
-      if (models.length) return available(ctx, 0, models)
-    }
+  const list = async (ctx: Context) => {
+    const models = await catalog()
     const state = await control.aiState(initial)
     const keyboard = new InlineKeyboard()
-    const presets = settings ? state.presets : state.presets.filter((preset) => preset.id === initial.id)
-    for (const preset of presets) button(keyboard,
-      `${preset.id === (settings ? state.defaultId : state.selectedId) ? '✓ ' : ''}${preset.name}`,
-      async (next) => {
-        if (settings) {
-          await validate(preset)
-          await control.defaultPreset(preset.id)
-          await next.reply(`Default: ${preset.name}. Applies to new conversations only.`)
-        } else await choose(next, preset)
-      })
-    button(keyboard, 'Browse available models', (next) => available(next))
+    if (models.length) {
+      const recent = (state.recentIds ?? [])
+        .map((id) => state.presets.find((preset) => preset.id === id))
+        .filter((preset): preset is AiPreset => Boolean(preset))
+        .filter((preset) => models.some((model) => matchesModel(preset, model)))
+        .slice(0, 3)
+      for (const preset of recent) button(keyboard,
+        `${preset.id === state.selectedId ? '✓ ' : ''}Recent · ${clientLabel(preset.cli)} · ${preset.name}`,
+        (next) => choose(next, preset))
+      for (const cli of [...new Set(models.map((model) => model.cli))].sort((a, b) => clientLabel(a).localeCompare(clientLabel(b))))
+        button(keyboard, clientLabel(cli), (next) => available(next, cli, 0, models))
+    } else {
+      const current = state.presets.find((preset) => preset.id === initial.id)
+      if (current) button(keyboard, `✓ ${current.name}`, (next) => choose(next, current))
+    }
     button(keyboard, 'Refresh available AIs', async (next) => {
       await refresh()
-      await list(next, true)
+      await list(next)
     })
-    await ctx.reply(settings
-      ? 'Default for new conversations\nChoose a saved AI. Current work will not change.'
+    await ctx.reply(models.length
+      ? 'Choose AI\nUse a recent choice or select an installed client, then choose its model and reasoning level.'
       : 'Choose AI\nNo client catalog available. Showing the current client setup only.', { reply_markup: keyboard })
   }
-  const available = async (ctx: Context, page = 0, listed?: ModelChoice[]) => {
-    const models = listed ?? await catalog()
+  const available = async (ctx: Context, cli: string, page = 0, listed?: ModelChoice[]) => {
+    const models = (listed ?? await catalog()).filter((model) => model.cli === cli)
     const keyboard = new InlineKeyboard()
     for (const model of models.slice(page * 8, page * 8 + 8)) {
-      button(keyboard, `${model.cli} · ${model.name}`, async (next) => {
-        if (!model.efforts.length) return save(next, model)
-        const efforts = new InlineKeyboard()
-        for (const effort of model.efforts.filter(effort => allowedEffort(effort, model.model, model.cli))) button(efforts, effort, (last) => save(last, model, effort))
-        await next.reply(`${model.name} — effort`, { reply_markup: efforts })
+      button(keyboard, model.name, async (next) => {
+        const supportedEfforts = model.efforts.filter(effort => allowedEffort(effort, model.model, model.cli))
+        if (!supportedEfforts.length) return save(next, model)
+        const effortKeyboard = new InlineKeyboard()
+        for (const effort of supportedEfforts) button(effortKeyboard, effort, (last) => save(last, model, effort))
+        button(effortKeyboard, 'Back to models', (last) => available(last, cli, page, listed))
+        await next.reply(`${clientLabel(cli)} · ${model.name}\nChoose reasoning level`, { reply_markup: effortKeyboard })
       })
     }
-    if (page > 0) button(keyboard, 'Previous', (next) => available(next, page - 1))
-    if (models.length > (page + 1) * 8) button(keyboard, 'Next', (next) => available(next, page + 1))
-    await ctx.reply(models.length
-      ? 'Choose AI\nAvailable models are populated automatically from the installed clients. Grok/Codex use their local catalog; other clients use their own default. Choosing one saves it; it does not switch AI.'
-      : 'No client catalog available. Open the installed CLI once, then try again.', { reply_markup: keyboard })
+    if (page > 0) button(keyboard, 'Previous', (next) => available(next, cli, page - 1, listed))
+    if (models.length > (page + 1) * 8) button(keyboard, 'Next', (next) => available(next, cli, page + 1, listed))
+    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 existing = state.presets.find((p) => p.cli === model.cli && p.model === model.model && p.effort === effort)
-    const preset: AiPreset = existing ?? { id: randomBytes(8).toString('hex'),
+  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 }
-    await validateSelection(preset, await catalog(), host ? async name => (await catalog()).some(model => model.cli === name) : undefined)
-    await control.savePreset(preset)
-    const keyboard = new InlineKeyboard()
-    button(keyboard, 'Use now', (next) => choose(next, preset))
-    button(keyboard, 'Make default', async (next) => {
-      await control.defaultPreset(preset.id)
-      await next.reply(`Default: ${preset.name}. Applies to new conversations only.`)
-    })
-    await ctx.reply(`Saved: ${preset.name}\n${presetLabel(preset)}`, { reply_markup: keyboard })
+    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, 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
       if (!data?.startsWith('ai:')) return false
       const entry = buttons.get(data.slice(3))
       await ctx.answerCallbackQuery().catch(() => {})
-      if (!entry || entry.expires < Date.now()) await ctx.reply('Menu expired. Open /ai or /settings again.')
+      if (!entry || entry.expires < Date.now()) await ctx.reply('Menu expired. Open /ai again.')
       else {
         buttons.delete(data.slice(3))
         try { await entry.action(ctx) }

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-send.ts

@@ -20,7 +20,7 @@ export const parseMessageArgs = (argv: string[]): MessageCliArgs => {
     if (args[i] === '--text-file' && args[i + 1]) {
       textFile = args[++i]
     } else if (args[i] === '--text' && args[i + 1]) {
-      text = args[++i]
+      text = args[++i].replace(/\\(\\|n)/g, (_, escape: string) => escape === 'n' ? '\n' : '\\')
     } else if (args[i] === '--reply-to' && args[i + 1]) {
       const parsed = parseInt(args[++i], 10)
       if (!Number.isNaN(parsed)) replyTo = parsed

package/src/message.ts

@@ -1,19 +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)
 }
@@ -22,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) {
@@ -31,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>]',
@@ -45,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/model-policy.ts

@@ -1,21 +1,11 @@
-export const CODEX_CHAT_MODEL = 'gpt-5.6-sol'
-export const CHAT_EFFORT = 'medium'
-export const CODEX_DEFAULT_MODEL = 'gpt-5.6-luna'
-export const DEFAULT_EFFORT = 'max'
-export const allowedEffort = (effort?: string, model?: string, cli?: string) => effort === undefined ||
-  ['none', 'minimal', 'low', 'medium', 'high'].includes(effort) ||
-  (['xhigh', 'max'].includes(effort) && model === 'gpt-5.6-luna' && ['codex', 'codex-gui'].includes(cli || ''))
+// Validate option syntax; the installed engine owns supported models and effort levels.
+export const allowedEffort = (effort?: string, _model?: string, _cli?: string) => effort === undefined || /^[a-z][a-z0-9_-]{0,31}$/.test(effort)
 export function assertEffort(effort?: string, model?: string, cli?: string) {
-  if (!allowedEffort(effort, model, cli)) throw new Error('Reasoning effort is capped at high, except Codex Luna/xhigh/max; choose none, minimal, low, medium, high, xhigh, or max with gpt-5.6-luna.')
+  if (!allowedEffort(effort,model,cli)) throw new Error('Invalid reasoning effort')
 }
 export function executionDefaults<T extends { model?: string; effort?: string }>(cli: string, options: T): T {
-  assertEffort(options.effort, options.model, cli)
-  const model = options.model || CODEX_DEFAULT_MODEL
-  return { ...options,
-    ...(['codex', 'codex-gui'].includes(cli) ? { model } : {}),
-    ...(['codex', 'codex-gui'].includes(cli)
-      ? { effort: options.effort || (model === 'gpt-5.6-luna' ? DEFAULT_EFFORT : 'high') } : {}),
-  }
+  assertEffort(options.effort,options.model,cli)
+  return options
 }
 
 export function executionOverrides<T extends { model?: string; effort?: string }>(

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();}
+}