@jc_stack/ez-agents 0.1.0-beta.19 → 0.1.0-beta.21

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.0-beta.21
+
+- Initialize fresh Telegram bots before reading their identity. Beta.19 could
+  retry forever before polling, causing main upgrades to fail their health gate.
+- Restore the unchanged deployment layout required for upgrades from beta.18
+  and beta.19; extending health grace does not fix the initialization failure.
+- Include beta.20 health diagnostics. Preserve the earlier immutable unpublished
+  candidate; existing beta acceptance limits remain.
+
+## 0.1.0-beta.20
+
+- Retain a bounded, content-free health predicate in a failed main-upgrade
+  receipt before rollback replaces the candidate relay. This distinguishes relay
+  polling and host-executor heartbeat failures without persisting control-state,
+  provider, environment, or Docker diagnostic content.
+
 ## 0.1.0-beta.19
 
 - Preserve host-backed run completion and delivery evidence while the relay

package/docker/healthcheck.mjs

@@ -1,8 +1,15 @@
 import { readFileSync } from 'node:fs';
-const value = JSON.parse(readFileSync('/state/control/heartbeat.json', 'utf8'));
-if (!value.polling || Date.now() - value.at > 20000) process.exit(1);
+const relayControl = process.env.EZ_HEALTH_RELAY_CONTROL_DIR || '/state/control';
+const fail = code => { process.stderr.write(`EZ_HEALTH_${code}\n`); process.exit(1); };
+let value;
+try { value = JSON.parse(readFileSync(relayControl + '/heartbeat.json', 'utf8')); }
+catch { fail('RELAY_UNREADABLE'); }
+if (!value.polling) fail('RELAY_NOT_POLLING');
+if (!Number.isFinite(value.at) || Date.now() - value.at > 20000) fail('RELAY_STALE');
 
 if (process.env.EZ_EXECUTOR_TRANSPORT === 'host') {
-  const host = JSON.parse(readFileSync(process.env.EZ_CONTROL_DIR + '/host-executor/heartbeat.json', 'utf8'));
-  if (Date.now() - host.at > 15000) process.exit(1);
+  let host;
+  try { host = JSON.parse(readFileSync(process.env.EZ_CONTROL_DIR + '/host-executor/heartbeat.json', 'utf8')); }
+  catch { fail('HOST_UNREADABLE'); }
+  if (!Number.isFinite(host.at) || Date.now() - host.at > 15000) fail('HOST_STALE');
 }

package/docs/architecture/ai-selection.md

@@ -28,8 +28,10 @@ offer their own default only in this slice. Refresh by opening the native client
 the relay does not install models, manage subscriptions or guess aliases.
 
 Setup initialization and relay startup seed one default choice per installed client.
-Settings → Refresh available AIs repeats discovery. Active/default presets and
-queued snapshots are preserved; discovery only refreshes unused detected entries.
+Choose AI opens the available installed-model catalog directly; Settings keeps
+saved choices and Refresh available AIs repeats default discovery. Active/default
+presets and queued snapshots are preserved; discovery only refreshes unused
+detected entries.
 Codex uses its native `config/read` interface; Grok reads its documented user
 model/effort settings (or `models` for the default model). Claude reads user and
 workspace JSON settings; OpenCode reports resolved config. Unknown defaults and

package/docs/docker-runtime.md

@@ -61,11 +61,13 @@ Live smoke uses the same host CLI and requires an actual Telegram receipt.
 Restart preserves pairing and files. One kernel lock excludes relay/smoke
 writers; exit 73 means a writer is active. Do not delete its lock to bypass it.
 Health requires recent polling and host-transport heartbeats, not just a process.
-Fatal Telegram polling errors, including `409 Conflict`, stop intake and await
-worker cleanup plus in-flight task/outbox writes before exit. A conflict still
-requires the operator to stop the competing bot poller; the relay does not retry
-around that ownership error. Pending and uncertain deliveries keep their existing
-outbox/receipt semantics; executor stdout is not replayed as a reply.
+Relay replacement retains the existing 30-second startup grace and deployment
+layout, so compatible releases remain eligible for agent-owned upgrades.
+An interrupted Telegram poller keeps authorized work and in-flight outbox writes
+alive while it retries intake. A `409 Conflict` still requires the operator to
+stop the competing poller; it remains unhealthy after the startup grace. Pending
+and uncertain deliveries keep their existing outbox/receipt semantics; executor
+stdout is not replayed as a reply.
 Signal and fatal-error paths share one shutdown; a secondary cleanup error is
 reported without replacing the original startup/polling failure.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.19",
+  "version": "0.1.0-beta.21",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

package/src/index.ts

@@ -1029,7 +1029,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           await bot.api.deleteWebhook({ drop_pending_updates: false })
           await bot.api.setMyCommands(commands)
           await bot.api.setMyCommands(commands, { scope: { type: 'all_private_chats' } })
-          if (!bot.botInfo) await bot.init()
+          await bot.init()
           await bot.start({
             drop_pending_updates: false,
             onStart: (botInfo) => console.log(`✓ Bot @${botInfo.username} polling for messages...`),

package/src/menu.ts

@@ -53,9 +53,14 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
       : '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 state = await control.aiState(initial)
     const keyboard = new InlineKeyboard()
-    for (const preset of state.presets) button(keyboard,
+    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) {
@@ -64,16 +69,17 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
           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) => {
+    button(keyboard, 'Browse available models', (next) => available(next))
+    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 })
+    await ctx.reply(settings
+      ? 'Default for new conversations\nChoose a saved AI. Current work will not change.'
+      : 'Choose AI\nNo client catalog available. Showing the current client setup only.', { reply_markup: keyboard })
   }
-  const available = async (ctx: Context, page = 0) => {
-    const models = await catalog()
+  const available = async (ctx: Context, page = 0, listed?: ModelChoice[]) => {
+    const models = listed ?? 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) => {
@@ -86,7 +92,7 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     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.'
+      ? '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 })
   }
   const save = async (ctx: Context, model: ModelChoice, effort?: string) => {

package/src/updates/runtime.mjs

@@ -43,6 +43,14 @@ export async function packageManager(root,run=execute) {
   throw Error(`Upgrade prerequisite unavailable: ${required}. ${failures.join('; ')}. Check the host supervisor service PATH (shell aliases do not count). Reuse its installed pnpm or Corepack; expose the launcher directory to that service and restart it after the current turn. If neither exists, provision the pinned manager first. Do not substitute npm install or reinstall the agent. After repair, prepare/apply a new job when status is failed; recover is only for recovery-required.`);
 }
 export const relayArgs = config => ['compose','--env-file',path.join(config.deploymentDir,'docker.env')];
+const healthCodes = new Set(['RELAY_UNREADABLE','RELAY_NOT_POLLING','RELAY_STALE','HOST_UNREADABLE','HOST_STALE']);
+async function healthEvidence(config,run) {
+  const id=(await run('docker',[...relayArgs(config),'ps','-q','relay'])).trim();
+  if(!/^[a-f0-9]{12,64}$/i.test(id))return '';
+  const raw=await run('docker',['inspect','--format','{{json .State.Health}}',id]);
+  const health=JSON.parse(raw),entry=health?.Log?.at(-1),match=typeof entry?.Output==='string'&&entry.Output.match(/^EZ_HEALTH_([A-Z_]+)\s*$/);
+  return match&&healthCodes.has(match[1])?` (health=${match[1].toLowerCase().replaceAll('_','-')})`:'';
+}
 function envValue(text,key,value) {
   if(/[\r\n\0']/.test(value))throw Error('Unsafe deployment value');
   const line=`${key}='${value}'`;
@@ -118,7 +126,11 @@ export async function perform(home,job,hooks) {
       job.runtimeVerified=running;
     }
     job.status='completed';job.endedAt=new Date().toISOString();await save();return job;
-  }catch(error){job.error=error.message;await save();return recover(home,job,hooks);}
+  }catch(error){
+    let message=error.message;
+    if(job.target==='main'&&job.rollback&&/is unhealthy/.test(message))message+=await healthEvidence(config,run).catch(()=> '');
+    job.error=message;await save();return recover(home,job,hooks);
+  }
 }
 export async function recover(home,job,hooks) {
   const run=hooks.execute||execute,{config}=await state(home);

package/templates/agent-guidance.md

@@ -12,6 +12,19 @@ delegation, model, and effort from the task—not a fixed routing rule. Keep one
 writer per workspace; the primary agent owns integration, verification, and
 external actions.
 
+## AI selection
+
+An explicit owner request to change this conversation's AI or reasoning effort
+is a supported Ez control, not a request to edit the host Codex configuration,
+inspect a native session record, or restart the runtime. Run
+`ezenciel-agents-ai list`, then select only a returned choice with
+`ezenciel-agents-ai select --cli <cli> --model <model> --effort <effort>`.
+This changes subsequent owner messages only; a running or queued job retains
+its captured choice, and the installation default is unchanged. Switching CLI
+starts a fresh native conversation while preserving the workspace. Report the
+confirmed selected choice from the command output; do not infer it from a
+host-level setting or the current native session.
+
 ## Telegram replies
 
 Use the messaging CLI for the current run's source chat, normally the paired

package/test/agent-guidance.test.ts

@@ -45,6 +45,19 @@ test('shared guidance teaches source-chat delivery and real Telegram line breaks
   assert.ok(shared.includes('ezenciel-agents-message --text-file ./work/reply.md'))
 })
 
+test('shared guidance makes owner AI selection a relay control, not host configuration', async () => {
+  const shared = await readFile(sharedGuidancePath, 'utf8')
+  for (const prompt of [
+    executorJobPrompt('tg_owner', ['change to Terra medium']),
+    desktopJobPrompt('tg_owner_gui', ['change to Terra medium'], undefined, '/tmp/bin', '/tmp/control'),
+  ]) {
+    assert.ok(prompt.includes('`ezenciel-agents-ai list`'))
+    assert.ok(prompt.includes('`ezenciel-agents-ai select --cli <cli> --model <model> --effort <effort>`'))
+    assert.ok(prompt.includes('not a request to edit the host Codex configuration'))
+    assert.match(prompt, /a running or queued job retains\s+its captured choice/)
+  }
+})
+
 test('package guidance resolution ignores a workspace shadow file', async () => {
   const root = path.join(tmpdir(), `ez-guidance-${randomUUID()}`)
   await mkdir(root, { recursive: true })

package/test/ai.test.ts

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { ControlStore } from '../src/control-state.js'
 import { initialPreset, chatPreset, readModels, isPreset } from '../src/ai.js'
+import { createAiMenu } from '../src/menu.js'
 import { EXECUTOR_REGISTRY, nativeSessionId } from '../src/executor.js'
 import { InboxStore } from '../src/inbox.js'
 import type { Update } from 'grammy/types'
@@ -92,6 +93,45 @@ test('model catalog projects native metadata only, excluding hidden entries and
   } finally { await rm(home, { recursive: true, force: true }) }
 })
 
+test('Choose AI opens the available installed-model catalog without an Add AI step', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-ai-menu-'))
+  try {
+    const menu = createAiMenu(new ControlStore(dir, 1000), 'grok', async () => [{
+      cli: 'codex', model: 'fixture-model', name: 'Fixture', efforts: ['medium'],
+    }])
+    let reply = ''
+    let keyboard: { inline_keyboard?: Array<Array<{ text: string }>> } | undefined
+    await menu.list({ reply: async (text: string, options?: { reply_markup?: unknown }) => {
+      reply = text
+      keyboard = options?.reply_markup as typeof keyboard
+      return {} as never
+    } } as never)
+    assert.match(reply, /Available models are populated automatically/)
+    assert.deepEqual(keyboard?.inline_keyboard?.flat().map((button) => button.text), ['codex · Fixture'])
+  } finally { await rm(dir, { recursive: true, force: true }) }
+})
+
+test('Choose AI does not expose saved model choices without a catalog to validate them', async () => {
+  const dir = await mkdtemp(join(tmpdir(), 'ez-ai-menu-empty-'))
+  try {
+    const store = new ControlStore(dir, 1000)
+    await store.aiState(initialPreset('grok'))
+    await store.savePreset({ id: 'saved', name: 'Saved model', cli: 'codex', model: 'fixture-model', effort: 'medium' })
+    await store.savePreset({ id: 'saved-default', name: 'Saved client default', cli: 'claude' })
+    const menu = createAiMenu(store, 'grok', async () => [])
+    let reply = ''
+    let keyboard: { inline_keyboard?: Array<Array<{ text: string }>> } | undefined
+    await menu.list({ reply: async (text: string, options?: { reply_markup?: unknown }) => {
+      reply = text
+      keyboard = options?.reply_markup as typeof keyboard
+      return {} as never
+    } } as never)
+    assert.match(reply, /current client setup only/)
+    assert.ok(!keyboard?.inline_keyboard?.flat().some((button) => button.text.includes('Saved model')))
+    assert.ok(!keyboard?.inline_keyboard?.flat().some((button) => button.text.includes('Saved client default')))
+  } finally { await rm(dir, { recursive: true, force: true }) }
+})
+
 test('model catalog can read an agent-bound Codex home', async () => {
   const home = await mkdtemp(join(tmpdir(), 'ez-catalog-home-'))
   const codexHome = await mkdtemp(join(tmpdir(), 'ez-catalog-codex-'))

package/test/failure.test.ts

@@ -17,7 +17,10 @@ import { TelegramSource } from '../src/telegram-source.js'
 import { packageVersion } from '../src/version.js'
 import type { Update } from 'grammy/types'
 const exec=promisify(execFile),bin=fileURLToPath(new URL('../bin/ezenciel-agents-schedule.mjs',import.meta.url))
-const until=async(check:()=>Promise<boolean>)=>{for(let n=0;n<200;n++){if(await check())return;await new Promise(r=>setTimeout(r,20))}throw new Error('Timed out')}
+// This integration test starts subprocesses, persists their receipts, and invokes
+// the schedule CLI. Give a busy CI worker time to settle without changing the
+// production recovery deadline.
+const until=async(check:()=>Promise<boolean>,timeoutMs=15_000)=>{const deadline=Date.now()+timeoutMs;while(!(await check())){if(Date.now()>=deadline)throw new Error(`Timed out after ${timeoutMs}ms`);await new Promise(r=>setTimeout(r,20))}}
 
 test('failure evidence is bounded and redacts configured credentials, headers, tokens, URLs and keys',()=>{
  const token='123456789:abcdefghijklmnopqrstuvwxyz123456789'
@@ -137,6 +140,29 @@ test('relay shutdown waits for executor cleanup and final run state', async () =
  } finally {release();await relay.stop();await rm(dir,{recursive:true,force:true})}
 })
 
+test('a fresh relay initializes its bot identity before polling', async () => {
+ const dir=await mkdtemp(join(tmpdir(),'ez-cold-start-'))
+ const relay=createRelay({workspace:dir,controlDir:dir,pairingTtlMs:1000,executorTimeoutMs:0,executorCli:'grok',telegramBotToken:'fixture'},async()=>{throw new Error('No executor expected')})
+ const methods:string[]=[]
+ relay.bot.api.config.use(async(_prev,method,_payload,signal)=>{
+  methods.push(method)
+  if(method==='getMe') return {ok:true,result:{id:999,is_bot:true,first_name:'Fixture',username:'fixture_bot'}} as any
+  if(method==='getUpdates') {
+   if(signal && !signal.aborted) await new Promise<void>(resolve=>signal.addEventListener('abort',()=>resolve(),{once:true}))
+   return {ok:true,result:[]} as any
+  }
+  return {ok:true,result:true} as any
+ })
+ const started=relay.start()
+ try {
+  await until(async()=>methods.includes('getUpdates'))
+  assert.equal(relay.bot.isRunning(),true)
+  assert.equal(methods.filter(method=>method==='getMe').length,1)
+  assert.ok(methods.indexOf('getMe')<methods.indexOf('getUpdates'))
+ } finally {await relay.stop();await started;await rm(dir,{recursive:true,force:true})}
+ assert.equal(relay.bot.isRunning(),false)
+})
+
 for (const cleanupFails of [false,true]) test(`polling conflict preserves work until an explicit shutdown (cleanup fails: ${cleanupFails})`, async t => {
  const dir=await mkdtemp(join(tmpdir(),'ez-polling-conflict-')),control=new ControlStore(dir,1000),runs=new RunStore(dir)
  let release!:()=>void,entered!:()=>void,releaseDelivery!:()=>void,sending!:()=>void,child:ReturnType<typeof spawn>|undefined,polls=0

package/test/intake-relay.test.ts

@@ -201,7 +201,7 @@ test('owner group discovery routes only to the private chat and rechecks identit
   } finally { await f.close() }
 })
 
-test('four-item menu is owner-only; saved AI buttons work and forged/stale buttons cannot change settings', async () => {
+test('four-item menu is owner-only; available AI choices work and forged/stale buttons cannot change settings', async () => {
   const f = await fixture()
   const callback = (id: number, data: string, user = 101): Update => ({
     update_id: id,
@@ -220,10 +220,18 @@ test('four-item menu is owner-only; saved AI buttons work and forged/stale butto
     await f.relay.bot.handleUpdate(callback(4, 'ai:forged'))
     assert.equal(await store.getActiveSession(), null)
     await f.relay.bot.handleUpdate(callback(5, pick))
+    if (!(await store.getActiveSession())) {
+      let useNow = f.keyboards.at(-1)!.flat().find((button) => button.text === 'Use now')?.callback_data
+      if (!useNow) {
+        await f.relay.bot.handleUpdate(callback(6, f.keyboards.at(-1)!.flat()[0].callback_data))
+        useNow = f.keyboards.at(-1)!.flat().find((button) => button.text === 'Use now')!.callback_data
+      }
+      await f.relay.bot.handleUpdate(callback(7, useNow))
+    }
     assert.ok(await store.getActiveSession())
-    await f.relay.bot.handleUpdate(callback(6, pick))
+    await f.relay.bot.handleUpdate(callback(8, pick))
     assert.match(f.replies.at(-1)!, /Menu expired/)
-    await f.relay.bot.handleUpdate(message(7, '/settings'))
+    await f.relay.bot.handleUpdate(message(9, '/settings'))
     assert.match(f.replies.at(-1)!, /Default for new conversations/)
     await f.relay.bot.handleUpdate(message(8, '/status'))
     assert.ok(f.keyboards.at(-1)!.flat().some((button) => button.text === 'Scheduled tasks'))

package/test/updates.test.mjs

@@ -86,6 +86,16 @@ test('status distinguishes installed, running, legacy and stale main versions wi
  const result=await exec(process.execPath,[new URL('../bin/ezenciel-agents-tools.mjs',import.meta.url).pathname,'--home',f.home,'status']);
  assert.equal(JSON.parse(result.stdout).main.installedVersion,'0.1.0');
 });
+test('relay healthcheck emits bounded predicate evidence without state contents',async t=>{
+ const root=await fs.realpath(await fs.mkdtemp(path.join(tmpdir(),'ez-healthcheck-')));t.after(()=>fs.rm(root,{recursive:true,force:true}));
+ const relay=path.join(root,'relay'),host=path.join(root,'host');await fs.mkdir(relay,{recursive:true});await fs.mkdir(path.join(host,'host-executor'),{recursive:true});
+ const check=async()=>exec(process.execPath,[new URL('../docker/healthcheck.mjs',import.meta.url).pathname],{env:{...process.env,EZ_HEALTH_RELAY_CONTROL_DIR:relay,EZ_EXECUTOR_TRANSPORT:'host',EZ_CONTROL_DIR:host}});
+ await fs.writeFile(path.join(relay,'heartbeat.json'),JSON.stringify({polling:true,at:Date.now()}));await fs.writeFile(path.join(host,'host-executor/heartbeat.json'),JSON.stringify({at:Date.now()}));await check();
+ await fs.writeFile(path.join(relay,'heartbeat.json'),JSON.stringify({polling:false,at:Date.now(),private:'must-not-appear'}));
+ await assert.rejects(check(),error=>{assert.match(error.stderr,/EZ_HEALTH_RELAY_NOT_POLLING/);assert.doesNotMatch(error.stderr,/must-not-appear/);return true;});
+ await fs.writeFile(path.join(relay,'heartbeat.json'),JSON.stringify({polling:true,at:Date.now()}));await fs.writeFile(path.join(host,'host-executor/heartbeat.json'),JSON.stringify({at:Date.now()-20000}));
+ await assert.rejects(check(),error=>{assert.match(error.stderr,/EZ_HEALTH_HOST_STALE/);return true;});
+});
 test('plugin status verifies images and reports stopped, mismatched and unreachable runtimes honestly',async t=>{
  const f=await fixture(t,'plugin'),id='a'.repeat(64),image='sha256:'+'b'.repeat(64);
  for(const mode of ['running','ndjson','stopped','missing','mismatched','offline']) {
@@ -157,6 +167,11 @@ test('failed preparation never stops runtime; failed activation rolls back code
   else assert((await fs.readFile(path.join(f.config.deploymentDir,'docker.env'),'utf8')).includes('sha256:'+'a'.repeat(64)));
  }
 });
+test('main health-gate rollback retains only the recognized sanitized predicate',async t=>{
+ const f=await fixture(t),job=await queued(f),base=runtime(f);let failed=false;
+ const r={...base,execute:async(c,a,o)=>{if(a.includes('up')&&!failed){failed=true;throw Error('container relay is unhealthy');}return a.includes('ps')?'a'.repeat(64):a[0]==='inspect'&&a[2]==='{{json .State.Health}}'?JSON.stringify({Log:[{Output:'EZ_HEALTH_HOST_STALE\n'}]}):base.execute(c,a,o);}};
+ const result=await perform(f.home,job,r);assert.equal(result.status,'rolled-back');assert.match(result.error,/health=host-stale/);assert.doesNotMatch(result.error,/private-test-token/);
+});
 test('plugin transaction preserves named volumes, backs up stopped data and rolls back failed health',async t=>{
  for(const failed of [false,true]) {
   const f=await fixture(t,'plugin'),job=await queued(f),r=runtime(f,{fail:(_c,a)=>failed&&a.includes('up')});