@jc_stack/ez-agents 0.1.0-beta.12

package/src/install-config.ts

@@ -0,0 +1,56 @@
+import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import path from 'node:path'
+import { parseEnv } from 'node:util'
+import { initializeWorkspace } from './workspace.js'
+import { resolveExecutor } from './executor.js'
+
+const inside = (parent: string, child: string) => {
+  const relative = path.relative(parent, child)
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))
+}
+
+// Configuration only: no provider calls, owner approval, service start, or AI turn.
+export const configureInstallation = async (directory: string, cli: string, token?: string) => {
+  let executor: string
+  try { executor = resolveExecutor(cli).name }
+  catch { throw new Error('Unsupported executor. See ezenciel-agents-setup status.') }
+  if (token !== undefined && !/^\d{5,}:[A-Za-z0-9_-]{20,}$/.test(token))
+    throw new Error('Invalid Telegram bot token. Supply the BotFather token through stdin.')
+  const root = path.resolve(directory)
+  const envFile = path.join(root, '.env')
+  let original = ''
+  try {
+    if (!(await lstat(envFile)).isFile()) throw new Error('.env must be a regular file')
+    original = await readFile(envFile, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+  }
+  const values = parseEnv(original)
+  const workspace = path.resolve(root, values.EZ_AGENT_WORKSPACE?.trim() || 'agent')
+  const controlDir = path.resolve(root, values.EZ_CONTROL_DIR?.trim() || 'control')
+  if (inside(workspace, envFile) || inside(workspace, controlDir) || inside(controlDir, workspace))
+    throw new Error('Keep the mind, control directory, and .env separate.')
+  const configured = {
+    ...values,
+    EZ_AGENT_WORKSPACE: workspace,
+    EZ_CONTROL_DIR: controlDir,
+    EZ_EXECUTOR_CLI: executor,
+    TELEGRAM_BOT_TOKEN: token ?? values.TELEGRAM_BOT_TOKEN ?? '',
+  }
+  // Literal dotenv values; do not shell-source this file. Preserve unknown keys.
+  const content = Object.entries(configured).map(([key, value]) => {
+    const quote = ['"', "'"].find(q => !value.includes(q))
+    if (!quote) throw new Error('Existing .env has a value requiring manual quoting; it was not changed.')
+    return `${key}=${quote}${value}${quote}\n`
+  }).join('')
+  const created = await initializeWorkspace(workspace)
+  const temporary = `${envFile}.${randomUUID()}.tmp`
+  try {
+    await writeFile(temporary, content, { mode: 0o600, flag: 'wx' })
+    await rename(temporary, envFile)
+  } finally { await rm(temporary, { force: true }) }
+  return { workspace, controlDir, envFile, executor, created,
+    tokenConfigured: Boolean(configured.TELEGRAM_BOT_TOKEN),
+    next: configured.TELEGRAM_BOT_TOKEN ? 'verify executor tools, start relay, and pair owner' : 'connect Telegram with the owner\u2019s BotFather token' }
+}

package/src/install-tools.mjs

@@ -0,0 +1,98 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+
+const root=fileURLToPath(new URL('../',import.meta.url));
+const read=async file=>JSON.parse(await fs.readFile(file,'utf8'));
+const absent=e=>{if(e.code!=='ENOENT')throw e;return null;};
+export const hostEnvironment=()=>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]]));
+async function atomic(file,value) {
+  const tmp=file+'.'+randomUUID()+'.tmp';await fs.writeFile(tmp,JSON.stringify(value)+'\n',{mode:0o600,flag:'wx'});await fs.rename(tmp,file);
+}
+export function run(command,args,{cwd,log,timeout=15000}={}) {
+  return new Promise((resolve,reject)=>{
+    const child=spawn(command,args,{cwd,env:hostEnvironment(),stdio:['ignore',log??'pipe',log??'pipe']});let output='';
+    for(const stream of [child.stdout,child.stderr])stream?.on('data',b=>output=(output+b).slice(-200000));
+    const timer=setTimeout(()=>child.kill('SIGTERM'),timeout);
+    child.once('error',e=>{clearTimeout(timer);reject(e);});
+    child.once('close',code=>{clearTimeout(timer);if(code!==0)reject(Error(`${command} failed (${code})${log===undefined?': '+output.trim():''}`));else resolve(output.trim());});
+  });
+}
+export const defaultHome=()=>path.join(process.env.XDG_DATA_HOME||path.join(homedir(),'.local/share'),'ez');
+export async function executable(value) {
+  if(!value||value.includes('\0'))throw Error('Supply the selected executor name or absolute path');
+  const candidates=path.isAbsolute(value)?[value]:value.includes('/')?[]:(process.env.PATH||'').split(path.delimiter).map(p=>path.join(p,value));
+  for(const candidate of candidates)try{await fs.access(candidate,fs.constants.X_OK);if((await fs.stat(candidate)).isFile())return path.resolve(candidate);}catch(e){if(!['ENOENT','EACCES'].includes(e.code))throw e;}
+  throw Error('Selected executor is not executable');
+}
+export async function preflight({home=defaultHome(),executor},invoke=run) {
+  const checks=[];
+  const check=async(name,fn)=>{try{checks.push({name,ok:true,...await fn()});}catch(e){checks.push({name,ok:false,error:e.message});}};
+  await check('node',async()=>{if(Number(process.versions.node.split('.')[0])<22)throw Error('Provision Node 22+ on the host');return {version:process.versions.node};});
+  const pkg=await read(path.join(root,'package.json'));
+  await check('pnpm',async()=>{const expected=pkg.packageManager.split('@').at(-1),actual=await invoke('pnpm',['--version']);if(actual!==expected)throw Error(`Provision pnpm ${expected}; found ${actual}`);return {version:actual};});
+  await check('docker',async()=>({version:await invoke('docker',['version','--format','{{.Server.Version}}'])}));
+  await check('compose',async()=>({version:await invoke('docker',['compose','version','--short'])}));
+  await check('disk',async()=>{let parent=path.resolve(home);while(!(await fs.stat(parent).catch(absent))){const next=path.dirname(parent);if(next===parent)throw Error('No existing installation parent');parent=next;}const s=await fs.statfs(parent),freeBytes=s.bavail*s.bsize;return {path:parent,freeBytes,note:'Host filesystem only; inspect Docker storage separately. Required space depends on image cache and plugins.'};});
+  await check('executor',async()=>{const binary=await executable(executor);return {path:binary,command:path.basename(binary),version:await invoke(binary,['--version']),sandboxVerified:false,note:'Validate identity and a harmless tool call under the actual service environment before registering the supported executor key.'};});
+  return {ok:checks.every(c=>c.ok),home:path.resolve(home),packages:path.join(path.resolve(home),'packages'),agents:path.join(path.resolve(home),'agents'),checks};
+}
+export async function installationStatus(deployment) {
+  if(!path.isAbsolute(deployment||''))throw Error('Supply --deployment with an absolute path');
+  const control=path.join(deployment,'control');
+  const exists=async f=>Boolean(await fs.stat(path.join(deployment,f)).catch(absent));
+  const configured=(await Promise.all(['agent.json','host-executor.json','docker.env','relay.env'].map(exists))).every(Boolean);
+  const owner=(await read(path.join(control,'control-state.json')).catch(absent))?.owner;
+  const paired=Boolean(owner&&Number.isSafeInteger(owner.telegramUserId)&&owner.telegramUserId>0&&Number.isSafeInteger(owner.telegramChatId)&&owner.telegramChatId>0&&Number.isFinite(Date.parse(owner.pairedAt)));
+  const relay=await read(path.join(control,'heartbeat.json')).catch(absent),host=await read(path.join(control,'host-executor/heartbeat.json')).catch(absent);
+  const fresh=(h,ms)=>Boolean(h&&Number.isFinite(h.at)&&h.at<=Date.now()+1000&&Date.now()-h.at<ms);
+  const runtimeReady=Boolean(relay?.polling&&fresh(relay,20000)&&fresh(host,15000));
+  let reply=null;
+  if(paired)for(const name of await fs.readdir(path.join(control,'outbox')).catch(e=>{if(e.code==='ENOENT')return [];throw e;})) {
+    if(!name.endsWith('.sent.json'))continue;
+    const item=await read(path.join(control,'outbox',name));
+    if(!/^tg_\d+$/.test(item.runId||'')||item.chatId!==owner.telegramChatId||(item.type&&item.type!=='message')||!Array.isArray(item.receipt?.messageIds)||!item.receipt.messageIds.length||!item.receipt.messageIds.every(n=>Number.isSafeInteger(n)&&n>0))continue;
+    const delivered=Date.parse(item.receipt.deliveredAt);if(!Number.isFinite(delivered)||delivered<Date.parse(owner.pairedAt)||delivered>Date.now())continue;
+    const r=await read(path.join(control,'runs',item.runId+'.json')).catch(absent);
+    if(r?.status==='completed'&&!r.external&&r.chatId===owner.telegramChatId&&r.telegramUserId===owner.telegramUserId&&(!reply||delivered>Date.parse(reply.deliveredAt)))reply={runId:item.runId,messageIds:item.receipt.messageIds,deliveredAt:item.receipt.deliveredAt};
+  }
+  return {deployment,configured,runtimeReady,ownerPaired:paired,telegramReplyVerified:Boolean(reply),reply,
+    stage:!configured?'not-configured':!runtimeReady?'runtime-offline':!paired?'awaiting-owner':!reply?'awaiting-telegram-reply':'ready-for-telegram-plugin-request',
+    note:'Read-only: a saved receipt is historical delivery evidence, not a fresh live probe or proof of reboot persistence. Request plugins through the working Telegram conversation.'};
+}
+async function fingerprintOf(source,invoke) {
+  const listing=JSON.parse(await invoke('npm',['pack','--dry-run','--ignore-scripts','--json'],{cwd:source}));
+  const hash=createHash('sha256');
+  for(const f of listing[0].files){const file=path.resolve(source,f.path);if(!file.startsWith(source+path.sep))throw Error('Invalid package path');const data=await fs.readFile(file);hash.update(JSON.stringify([f.path,f.mode,data.length]));hash.update(data);}
+  return hash.digest('hex');
+}
+export async function build({home=defaultHome(),source=root},invoke=run) {
+  source=await fs.realpath(source);
+  const fingerprint=await fingerprintOf(source,invoke),image='ezenciel-agents:install-'+fingerprint.slice(0,24);
+  const dir=path.join(path.resolve(home),'builds',fingerprint);await fs.mkdir(dir,{recursive:true,mode:0o700});
+  const lock=path.join(dir,'lock'),receipt=path.join(dir,'status.json'),log=path.join(dir,'build.log');
+  let handle;
+  try{handle=await fs.open(lock,'wx',0o600);}catch(e){if(e.code!=='EEXIST')throw e;return {state:'busy-or-interrupted',image,log,note:'An existing build owns this artifact. Inspect its status/log and owning process; do not start another build or remove a live lock.'};}
+  try {
+    await handle.writeFile(JSON.stringify({pid:process.pid,source,image}));
+    const prior=await read(receipt).catch(absent);
+    if(prior?.state==='completed')try{if(await invoke('docker',['image','inspect','--format','{{.Id}}',image])===prior.imageId)return {...prior,reused:true};}catch{/* Image was removed; rebuild under the same exclusive lock. */}
+    await atomic(receipt,{state:'building',pid:process.pid,source,image,log});
+    console.error(JSON.stringify({state:'building',image,log}));
+    const output=await fs.open(log,'a',0o600);
+    try{await invoke('docker',['build','--progress','plain','--target','runtime','-t',image,source],{log:output.fd,timeout:3600000});}finally{await output.close();}
+    if(await fingerprintOf(source,invoke)!==fingerprint)throw Error('Package changed during build; keep the source stable and retry');
+    const result={state:'completed',source,image,imageId:await invoke('docker',['image','inspect','--format','{{.Id}}',image]),log};await atomic(receipt,result);return result;
+  }catch(e){await atomic(receipt,{state:'failed',source,image,log,error:e.message});throw e;}
+  finally{await handle.close();await fs.rm(lock);}
+}
+export async function main(args) {
+  const [action,...rest]=args;const options={};
+  if(!action||action==='--help'){console.log(JSON.stringify({commands:['preflight --executor <name-or-absolute-path> [--home PATH]','build [--home PATH]','status --deployment PATH'],note:'Host prerequisites and main-agent diagnostics only. Initialize an empty registry; verify Telegram before asking the installed agent to add plugins.'}));return;}
+  for(let i=0;i<rest.length;i+=2){if(!['--home','--executor','--deployment'].includes(rest[i])||!rest[i+1]||Object.hasOwn(options,rest[i].slice(2)))throw Error('Invalid arguments');options[rest[i].slice(2)]=rest[i+1];}
+  const allowed={preflight:['home','executor'],build:['home'],status:['deployment']};if(!allowed[action]||Object.keys(options).some(k=>!allowed[action].includes(k)))throw Error('Invalid action/options');
+  const result=action==='preflight'?await preflight(options):action==='build'?await build(options):await installationStatus(options.deployment);console.log(JSON.stringify(result));if(result.ok===false)process.exitCode=1;
+}

package/src/menu.ts

@@ -0,0 +1,123 @@
+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 { initialPreset, 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: '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')
+
+// 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()) => {
+  const initial = initialPreset(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'))
+  const refresh = async () => control.syncClientPresets(initial, host ? [] : await discoverDefaults(workspace))
+  const validate = async (preset: AiPreset) => {
+    if (preset.id === initial.id) return
+    if (preset.id.startsWith('detected_')) {
+      const detected = await discoverDefaults(workspace)
+      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)
+  }
+  const buttons = new Map<string, { expires: number; action: (ctx: Context) => Promise<void> }>()
+  const button = (keyboard: InlineKeyboard, label: string, action: (ctx: Context) => Promise<void>) => {
+    for (const [id, b] of buttons) if (b.expires < Date.now()) buttons.delete(id)
+    if (buttons.size >= 300) buttons.delete(buttons.keys().next().value!)
+    const id = randomBytes(8).toString('hex')
+    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) => {
+    await validate(preset)
+    const session = await control.getActiveSession()
+    const state = await control.aiState(initial)
+    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)
+    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) => {
+    const state = await control.aiState(initial)
+    const keyboard = new InlineKeyboard()
+    for (const preset of state.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, 'Add AI…', (next) => available(next))
+    if (settings) button(keyboard, 'Refresh available AIs', async (next) => {
+      await refresh()
+      await list(next, true)
+    })
+    await ctx.reply(settings ? 'Default for new conversations\nChoose a saved AI. Current work will not change.'
+      : 'Choose AI\nChanging CLI starts a fresh conversation; files stay.', { reply_markup: keyboard })
+  }
+  const available = async (ctx: Context, page = 0) => {
+    const models = await catalog()
+    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) button(efforts, effort, (last) => save(last, model, effort))
+        await next.reply(`${model.name} — effort`, { reply_markup: efforts })
+      })
+    }
+    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
+      ? 'Installed client choices. Grok/Codex use their local model catalog; other clients use their own default. Adding saves the choice; it does not switch AI.'
+      : 'No client catalog available. Open the installed CLI once, then try again.', { 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'),
+      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 })
+  }
+  return {
+    initial,
+    refresh,
+    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.')
+      else {
+        buttons.delete(data.slice(3))
+        try { await entry.action(ctx) }
+        catch (error) { await ctx.reply(error instanceof Error ? error.message : 'AI selection failed.') }
+      }
+      return true
+    },
+  }
+}

package/src/message-send.ts

@@ -0,0 +1,57 @@
+import { RunStore } from './runs.js'
+
+export type MessageCliArgs = {
+  textFile?: string
+  text?: string
+  replyTo?: number
+  document?: string
+  voice?: string
+}
+
+export const parseMessageArgs = (argv: string[]): MessageCliArgs => {
+  const args = argv.filter((arg) => arg !== '--')
+  let textFile: string | undefined
+  let text: string | undefined
+  let replyTo: number | undefined
+  let document: string | undefined
+  let voice: string | undefined
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--text-file' && args[i + 1]) {
+      textFile = args[++i]
+    } else if (args[i] === '--text' && args[i + 1]) {
+      text = args[++i]
+    } else if (args[i] === '--reply-to' && args[i + 1]) {
+      const parsed = parseInt(args[++i], 10)
+      if (!Number.isNaN(parsed)) replyTo = parsed
+    } else if ((args[i] === '--document' || args[i] === '--file') && args[i + 1]) {
+      document = args[++i]
+    } else if (args[i] === '--voice' && args[i + 1]) {
+      voice = args[++i]
+    }
+  }
+  const result: MessageCliArgs = { textFile }
+  if (text !== undefined) result.text = text
+  if (replyTo !== undefined) result.replyTo = replyTo
+  if (document !== undefined) result.document = document
+  if (voice !== undefined) result.voice = voice
+  return result
+}
+
+export const sendRunText = async (store: RunStore, runId: string, text: string, options?: { replyTo?: number }) => {
+  const trimmed = text.trim()
+  if (!trimmed) throw new Error('Message text is empty')
+  return store.enqueueMessage(runId, trimmed, { replyToMessageId: options?.replyTo })
+}
+
+export const sendRunDocument = async (store: RunStore, runId: string, filePath: string, caption?: string, options?: { replyTo?: number }) => {
+  const trimmed = filePath.trim()
+  if (!trimmed) throw new Error('Document path is empty')
+  return store.enqueueDocument(runId, trimmed, { caption: caption?.trim(), replyToMessageId: options?.replyTo })
+}
+
+export const sendRunVoice = async (store: RunStore, runId: string, voiceText: string, options?: { replyTo?: number }) => {
+  const trimmed = voiceText.trim()
+  if (!trimmed) throw new Error('Voice text is empty')
+  return store.enqueueVoice(runId, trimmed, { replyToMessageId: options?.replyTo })
+}

package/src/message.ts

@@ -0,0 +1,68 @@
+import { readFile } from 'node:fs/promises'
+import { loadControlConfig } from './config.js'
+import { parseMessageArgs, sendRunDocument, sendRunText, sendRunVoice } from './message-send.js'
+import { RunStore } from './runs.js'
+
+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>]',
+  )
+  process.exit(0)
+}
+
+const runId = process.env.EZ_RUN_ID?.trim()
+const args = parseMessageArgs(rawArgs)
+if (!runId) {
+  console.error('EZ_RUN_ID is required')
+  process.exit(1)
+}
+
+const store = new RunStore(loadControlConfig().controlDir)
+
+let textContent = args.text?.trim()
+if (args.textFile) {
+  try {
+    textContent = (await readFile(args.textFile, 'utf8')).trim()
+  } catch (err: any) {
+    console.error(`Failed to read text file ${args.textFile}: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+let item
+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 })
+} else if (textContent) {
+  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>]',
+  )
+  process.exit(1)
+}
+
+try {
+  const receipt = await store.waitForDelivery(item.id)
+  console.log(
+    JSON.stringify({
+      ok: true,
+      status: 'delivered',
+      run: runId,
+      outbox_id: item.id,
+      type: item.type,
+      receipt,
+    }),
+  )
+} catch (error) {
+  console.error(
+    JSON.stringify({
+      ok: false,
+      outbox_id: item.id,
+      error: error instanceof Error ? error.message : 'Delivery failed',
+    }),
+  )
+  process.exitCode = 1
+}

package/src/owner-args.ts

@@ -0,0 +1,4 @@
+export const parseOwnerArgs = (argv: string[]): { command?: string; value?: string } => {
+  const [command, value] = argv.filter((arg) => arg !== '--')
+  return { command, value }
+}

package/src/owner.ts

@@ -0,0 +1,30 @@
+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> | 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))
+const config = loadControlConfig()
+const store = new ControlStore(config.controlDir, config.pairingTtlMs)
+
+const usage = (): never => {
+  console.error(help)
+  process.exit(1)
+}
+
+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 === 'approve' && value) {
+  const owner = await store.approveOwner(Number(value))
+  console.log(`Paired Telegram owner ${owner.telegramUserId}.`)
+} else if (command === 'revoke' && !value) {
+  console.log((await store.revokeOwner()) ? 'Owner pairing revoked.' : 'No owner pairing existed.')
+} else {
+  usage()
+}