@jc_stack/ez-agents 0.1.0-beta.47 → 0.1.0-beta.49

package/src/menu.ts

@@ -4,8 +4,9 @@ import path from 'node:path'
 import { randomBytes } from 'node:crypto'
 import { InlineKeyboard, type Context } from 'grammy'
 import { ControlStore, type ControlGuard } from './control-state.js'
-import { chatPreset, installed, persistedPreset, presetLabel, presetProvider, readModels, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
+import { chatPreset, installed, persistedPreset, presetLabel, presetProvider, readModels, sameChoice, sameEngine, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
 import { discoverDefaults } from './client-defaults.js'
+import { claudeConfigHome } from './executor.js'
 
 export const mainCommands = [
   { command: 'new', description: 'New conversation' },
@@ -24,7 +25,7 @@ export const mainKeyboard = () => new InlineKeyboard()
 const clientLabel = (cli: string) => cli === 'codex-gui' ? 'codex-gui (desktop)' : cli
 
 const matchesModel = (preset: AiPreset, model: ModelChoice) =>
-  model.cli === preset.cli && model.provider === preset.provider && (preset.model === undefined || model.model === preset.model) &&
+  sameEngine(model, preset) && model.provider === preset.provider && (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.
@@ -38,14 +39,15 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
   // directory, but the default catalog probed the process home instead. Bind it
   // to the same agent-bound home so /ai lists the models Codex can actually run.
   else if (codexHome && catalog === readModels) catalog = () => readModels(undefined, isInstalled, codexHome, undefined, opencodeDataHome, undefined, process.env.EZ_CONTROL_DIR)
-  const refresh = async () => control.syncClientPresets(initial, host ? [] : await discoverDefaults(workspace, { codexHome }))
+  const claudeHome = process.env.EZ_CONTROL_DIR ? claudeConfigHome(process.env.EZ_CONTROL_DIR) : undefined
+  const refresh = async () => control.syncClientPresets(initial, host ? [] : await discoverDefaults(workspace, { codexHome, claudeHome }))
   const validate = async (preset: AiPreset) => {
     assertEffort(preset.effort, preset.model, preset.cli)
     if (preset.id === initial.id) return
     if (preset.id.startsWith('detected_')) {
       if (host) await validateSelection(preset, await catalog(), async name => (await catalog()).some(model => model.cli === name))
       else {
-        const detected = await discoverDefaults(workspace, { codexHome })
+        const detected = await discoverDefaults(workspace, { codexHome, claudeHome })
         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) : isInstalled)
@@ -64,7 +66,7 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     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 || presetProvider(current) !== presetProvider(preset) || Boolean(session && !session.cli)
+    const fresh = !sameEngine(current, preset) || presetProvider(current) !== presetProvider(preset) || Boolean(session && !session.cli)
     if (!await control.selectPreset(preset.id, expectedSession, fresh, guard)) throw new Error('AI binding changed. Refresh available AIs before trying again.')
     return { preset, fresh }
   }
@@ -125,9 +127,9 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     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, provider:model.provider, model: model.model, effort }
+      name: `${model.name}${effort ? ` · ${effort}` : ''}`.slice(0, 80), cli: model.cli, provider:model.provider, ...(model.authProfile ? {authProfile:model.authProfile} : {}), model: model.model, effort }
     const stored = persistedPreset(candidate)
-    const existing = state.presets.find((preset) => preset.cli === stored.cli && preset.provider === stored.provider && preset.model === stored.model && preset.effort === stored.effort)
+    const existing = state.presets.find((preset) => sameChoice(preset, stored))
     const preset = existing ?? candidate
     await validateSelection(preset, await catalog(), host ? async name => (await catalog()).some(model => model.cli === name) : isInstalled)
     // Private scopes persist their selection on the session, not the owner menu.

package/src/plugin-broker.mjs

@@ -1,10 +1,12 @@
+import { combinePreflight } from './schedule-preflight.js';
 import * as fs from 'node:fs/promises';
+import {callDeliverySocket} from './delivery-socket-client.mjs';
 import path from 'node:path';
 import { createServer } from 'node:net';
 import { randomBytes, randomUUID, createHash } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { prepareCommand, registry, run as dockerRun, stewardOwned } from './plugins/manager.mjs';
+import { prepareCommand, registry, run as dockerRun, stewardOwned, publishBrokerPlugins } from './plugins/manager.mjs';
 
 const MAX_FRAME = 4 * 1024 * 1024;
 const MAX_ARGS = 100;
@@ -163,15 +165,7 @@ const writeReceipt = async (binding, receipt) => {
 // Installed plugin versions for relay status. Rewritten on broker start and
 // after every management call; the relay reads it without Docker access.
 // Failures stay local so a status snapshot never breaks plugin operations.
-const refreshBrokerPlugins = async binding => {
-  const r = await registry(binding.home);
-  const plugins = Object.values(r.plugins).map(record => ({ id: record.manifest.id, version: record.manifest.version }));
-  const file = path.join(binding.controlDir, 'plugin-broker-plugins.json');
-  const temporary = `${file}.${randomUUID()}.tmp`;
-  await fs.writeFile(temporary, JSON.stringify({ version: 1, at: new Date().toISOString(), plugins }) + '\n', { mode: 0o600, flag: 'wx' });
-  await fs.rename(temporary, file);
-  await stewardOwned(file);
-};
+const refreshBrokerPlugins = binding => publishBrokerPlugins(binding.home,binding.controlDir);
 
 const response = (socket, value) => {
   if (socket.destroyed || !socket.writable) return;
@@ -223,23 +217,38 @@ const managerCommand = async (binding, args, signal, runId) => new Promise((reso
   });
 });
 
-const invokePlugin = async (binding, request, signal) => {
+const authorizeTaskLaunch=async(binding,request)=>{
+  const input=JSON.parse(request.stdin)
+  if(Object.keys(input).some(k=>!['taskId','taskToken','expiresAt'].includes(k)) || typeof input.taskToken!=='string' || !/^[a-f0-9]{64}$/.test(input.taskToken))throw Error('Invalid task launch input')
+  const ticketHash=createHash('sha256').update(input.taskToken).digest('hex')
+  const grant=await callDeliverySocket(deliverySocketPath(binding.controlDir),{op:'taskApplication',payload:{runId:request.runId,ticketHash}})
+  if(input.taskId!==grant.taskId || input.expiresAt!==grant.expiresAt)throw Error('Task launch authority mismatch')
+  return grant.launch
+}
+const invokePlugin = async (binding, request, signal, scheduledPreflight = false) => {
   const startedAt = new Date().toISOString();
   let plugin = request.alias;
   let revision = request.revision;
   let result;
   let failure;
   try {
-    await authorize(binding, request.runId);
+    if (!scheduledPreflight) {
+      if(request.operation==='task-launch') {
+        const launch=await authorizeTaskLaunch(binding,request)
+        if(launch.command!==request.alias || JSON.stringify(launch.args)!==JSON.stringify(request.args))throw Error('Task launch command changed')
+      }else await authorize(binding, request.runId);
+    }
     const current = await registry(binding.home);
     const selected = recordForAlias(current, request.alias);
+    if (scheduledPreflight && (!selected.command.exposure || selected.command.exposure.changesRecords !== false || selected.command.exposure.sendsExternally !== false)) throw Error('Scheduled preflight requires an explicitly read-only plugin command');
     plugin = selected.plugin;
     revision = selected.record.revision;
     if (selected.record.revision !== request.revision) throw Error('Plugin changed; discover again');
     const command = await prepareCommand(binding.home, request.alias, request.args, {
       revision: request.revision,
       invocation: true,
-      environment: { EZ_CONTROL_DIR: binding.controlDir, EZ_RUN_ID: request.runId, EZ_DELIVERY_SOCKET: process.env.EZ_DELIVERY_SOCKET ?? deliverySocketPath(binding.controlDir) },
+      signal,
+      environment: { EZ_CONTROL_DIR: binding.controlDir, ...(scheduledPreflight ? {} : {EZ_RUN_ID: request.runId}), EZ_DELIVERY_SOCKET: process.env.EZ_DELIVERY_SOCKET ?? deliverySocketPath(binding.controlDir) },
     });
     try {
       result = await dockerRun(command.argv, {
@@ -282,8 +291,17 @@ const invokePlugin = async (binding, request, signal) => {
 
 export async function validateBrokerRequest(request, workspace) {
   if (!request || typeof request !== 'object' || request.version !== 1 || !REQUEST_ID.test(request.id)) throw Error('Invalid plugin broker request');
-  if (!['resolve', 'invoke', 'manager'].includes(request.operation)) throw Error('Unknown plugin broker operation');
+  if(request.operation === 'preflight') {
+    validId(request.scheduleId,RUN_ID,'schedule ID'); validId(request.revision,/^[a-f0-9-]{36}$/,'schedule revision');
+    if(Object.keys(request).some(k=>!['version','id','operation','scheduleId','revision'].includes(k))) throw Error('Unexpected schedule preflight field');
+    return request;
+  }
+  if (!['resolve', 'invoke', 'manager','task-launch'].includes(request.operation)) throw Error('Unknown plugin broker operation');
   validId(request.runId, RUN_ID, 'plugin run ID');
+  if(request.operation==='task-launch') {
+    if(Object.keys(request).some(k=>!['version','id','operation','runId','stdin'].includes(k)))throw Error('Unexpected task launch field')
+    boundedString(request.stdin,1024,'task launch stdin');return request
+  }
   if (request.operation === 'manager') {
     await validateManagerArgs(request.args, workspace);
     if (Object.keys(request).some(key => !['version', 'id', 'operation', 'runId', 'args'].includes(key))) throw Error('Unexpected broker management field');
@@ -328,6 +346,18 @@ export async function servePluginBroker(binding, signal = new AbortController().
       (async () => {
         try {
           await validateBrokerRequest(request, binding.workspace);
+          if (request.operation === 'preflight') {
+            const condition=await (await import('./delivery-socket-client.mjs')).callDeliverySocket(deliverySocketPath(binding.controlDir),{op:'schedulePreflight',payload:{scheduleId:request.scheduleId,revision:request.revision}});
+            const values=[];
+            for(const check of condition.checks) {
+              const selected=recordForAlias(await registry(binding.home),check.alias);
+              const result=await invokePlugin(binding,{alias:check.alias,args:check.args,revision:selected.record.revision,runId:`preflight_${request.scheduleId}`,id:randomUUID()},abort.signal,true);
+              if(!result.ok || result.code!==0) throw Error('Scheduled plugin preflight unavailable');
+              try { values.push(JSON.parse(result.stdout)); } catch { throw Error('Scheduled plugin preflight returned invalid output'); }
+            }
+            response(socket,{version:1,id:request.id,ok:true,result:combinePreflight(values)});
+            return;
+          }
           if (request.operation === 'resolve') {
             await authorize(binding, request.runId);
             const selected = recordForAlias(await registry(binding.home), request.alias);
@@ -338,6 +368,12 @@ export async function servePluginBroker(binding, signal = new AbortController().
             response(socket, { version: 1, id: request.id, ok: true, plugin: selected.plugin, alias: request.alias, revision: selected.record.revision, capability });
             return;
           }
+          if(request.operation==='task-launch') {
+            const launch=await authorizeTaskLaunch(binding,request)
+            const selected=recordForAlias(await registry(binding.home),launch.command)
+            const result=await invokePlugin(binding,{...request,alias:launch.command,args:launch.args,revision:selected.record.revision},abort.signal)
+            response(socket,{version:1,id:request.id,...result});return
+          }
           if (request.operation === 'manager') {
             await authorize(binding, request.runId);
             const result = await managerCommand(binding, request.args, abort.signal, request.runId);

package/src/plugins/manager.mjs

@@ -78,7 +78,8 @@ async function activeInvocations(home) {
   const directory=invocationDirectory(home),files=await fs.readdir(directory).catch(error=>{if(error.code==='ENOENT')return [];throw error;});
   for(const file of files) {
     if(!/^[0-9a-f-]{36}\.json$/.test(file))throw Error('Invalid command invocation lease; inspect before recovery');
-    const lease=await json(path.join(directory,file));
+    const lease=await json(path.join(directory,file)).catch(error=>{if(error.code==='ENOENT')return null;throw error;});
+    if(!lease)continue;
     if(!Number.isSafeInteger(lease.pid)||lease.pid<1||typeof lease.container!=='string'||!lease.container)throw Error('Invalid command invocation lease; inspect before recovery');
     try {process.kill(lease.pid,0);return true;} catch(error) {if(error.code!=='ESRCH'&&error.code!=='EPERM')throw error;}
     const state=await run(['container','inspect',lease.container],{capture:true});
@@ -94,14 +95,31 @@ async function invocationLease(home,container) {
   await stewardOwned(file);
   return async()=>{await fs.rm(file,{force:true});};
 }
-export async function locked(home, fn, {allowInvocations=false}={}) {
+export async function locked(home, fn, {allowInvocations=false, waitMs=0, upgradeWaitMs=0, drainInvocations=false, signal}={}) {
   const lock = path.join(home,'registry.lock');
   let handle;
-  try { handle=await fs.open(lock,'wx',0o600); }
-  catch(error) { if(error.code==='EEXIST') throw Error('Registry busy; inspect registry.lock before recovering an interrupted manager'); throw error; }
+  const started=Date.now();
+  while(!handle) {
+    signal?.throwIfAborted();
+    try { handle=await fs.open(lock,'wx',0o600); }
+    catch(error) {
+      if(error.code!=='EEXIST')throw error;
+      const owner=await json(lock).catch(()=>null);
+      const limit=owner?.kind==='plugin-upgrade'&&upgradeWaitMs?upgradeWaitMs:waitMs;
+      if(Date.now()-started>=limit)throw Error('Registry busy; inspect registry.lock before recovering an interrupted manager');
+      await new Promise(resolve=>setTimeout(resolve,25));
+    }
+  }
   try {
-    await handle.writeFile(JSON.stringify({pid:process.pid}));
-    if(!allowInvocations&&await activeInvocations(home))throw Error('Plugin commands are active; retry the registry or lifecycle change after they finish');
+    await handle.writeFile(JSON.stringify({pid:process.pid,...(drainInvocations?{kind:'plugin-upgrade'}:{})}));
+    // Keep admission closed while already-started calls release their leases.
+    // This is a lifecycle barrier, not an agent-turn drain or a command retry.
+    while(!allowInvocations&&await activeInvocations(home)) {
+      if(!drainInvocations)throw Error('Plugin commands are active; retry the registry or lifecycle change after they finish');
+      signal?.throwIfAborted();
+      await new Promise(resolve=>setTimeout(resolve,25));
+    }
+    signal?.throwIfAborted();
     return await fn();
   }
   finally { await handle.close(); await fs.rm(lock); }
@@ -467,8 +485,16 @@ export 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;
 }
+// Relay status reads this generated inventory without Docker/registry access.
+export async function publishBrokerPlugins(home,controlDir) {
+  const r=await registry(home);
+  const plugins=Object.values(r.plugins).map(record=>({id:record.manifest.id,version:record.manifest.version}));
+  const file=path.join(controlDir,'plugin-broker-plugins.json');
+  await atomic(file,{version:1,at:new Date().toISOString(),plugins});
+  await stewardOwned(file);
+}
 // The lock protects admission and compose refresh, never a persistent connection.
-export async function prepareCommand(home,alias,args,{revision,exclude,publish,invocation=false,environment=process.env}={}) {
+export async function prepareCommand(home,alias,args,{revision,exclude,publish,invocation=false,environment=process.env,signal}={}) {
   strings(args);
   return locked(home,async()=>{
     const config=await json(path.join(home,'config.json')),r=await registry(home);
@@ -498,7 +524,7 @@ export async function prepareCommand(home,alias,args,{revision,exclude,publish,i
     const invocationRelease=invocation?await invocationLease(home,container):undefined;
     const release=(invocationRelease||contextFile)?(async()=>{try{if(contextFile)await fs.rm(contextFile,{force:true});}finally{await invocationRelease?.();}}):undefined;
     return {container,plugin:record.manifest.id,revision:record.revision,contextFile,argv:[...composeArgs(record),...(contextFile?['--file',contextFile]:[]),'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||[])],release};
-  },{allowInvocations:true});
+  },{allowInvocations:true,waitMs:5000,upgradeWaitMs:invocation?300000:0,signal});
 }
 export async function init(home,workspace,catalogFile,hostConfig,standalone=false) {
   if(standalone && hostConfig) throw Error('Standalone setup cannot bind a relay host config');

package/src/run-evidence.ts

@@ -0,0 +1,78 @@
+import { createHash } from 'node:crypto'
+import { readOnlyOwner, requireOwnerExecution } from './execution-authority.js'
+import { ownsRun, assertId } from './identity.js'
+import { RunStore, retainedOutbox, type RunRecord, type StoredOutboxItem } from './runs.js'
+import type { Owner } from './control-state.js'
+
+const sha256 = (value: string) => createHash('sha256').update(value).digest('hex')
+const version = (value?: string) => value && /^[0-9A-Za-z.+-]{1,80}$/.test(value) ? value : undefined
+
+function delivery(item: StoredOutboxItem) {
+  const receipt = item.receipt as { messageIds?: unknown; deliveredAt?: unknown } | undefined
+  const valid = item.state === 'sent' && !item.deliveryUnknown &&
+    Array.isArray(receipt?.messageIds) && receipt.messageIds.length > 0 &&
+    receipt.messageIds.every(id => Number.isSafeInteger(id) && id > 0) &&
+    typeof receipt.deliveredAt === 'string' && Number.isFinite(Date.parse(receipt.deliveredAt))
+  const field = typeof item.text === 'string' ? 'text' : typeof item.voiceText === 'string' ? 'voiceText' : undefined
+  const content = field === 'text' ? item.text : field === 'voiceText' ? item.voiceText : undefined
+  return { id: item.id, createdAt: item.createdAt, type: item.type ?? 'message',
+    state: item.deliveryUnknown ? 'unknown' : item.state ?? 'queued', receiptVerified: Boolean(valid),
+    ...(valid ? { deliveredAt: receipt!.deliveredAt, messageCount: (receipt!.messageIds as number[]).length } : {}),
+    ...(content === undefined ? {} : { content: { field, sha256: sha256(content), bytes: Buffer.byteLength(content), representation: 'submitted UTF-8' } }),
+    recipientContentReadback: 'unavailable', attachmentContent: 'not exported' }
+}
+
+// Projection only: never read native sessions, tool arguments/results or model text.
+export function projectRunEvidence(runs: RunRecord[], outbox: StoredOutboxItem[], owner: Owner) {
+  return runs.filter(run => ownsRun(owner, run) && Date.parse(run.createdAt) >= Date.parse(owner.pairedAt) &&
+    !run.external && !run.taskId && !run.application && !run.delivery &&
+    (!run.scheduled || run.scheduled.pairedAt === owner.pairedAt))
+    .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id))
+    .map(run => ({ id: run.id, status: run.status, createdAt: run.createdAt,
+      startedAt: run.startedAt, endedAt: run.endedAt, exitCode: run.exitCode, interrupted: run.interrupted,
+      scheduled: run.scheduled ? { id: run.scheduled.id, revision: run.scheduled.revision, dueAt: run.scheduled.dueAt } : undefined,
+      executionType: run.script ? 'script' : 'agent',
+      script: run.script ? { id: run.script.id, revision: run.script.revision, sha256: run.script.sha256, timedOut: Boolean(run.timedOut),
+        outputSha256: run.output ? sha256(run.output) : undefined } : undefined,
+      preset: run.execution ? { cli: run.execution.preset.cli, model: run.execution.preset.model, effort: run.execution.preset.effort } : undefined,
+      failure: run.failure ? { recorded: true, errorSha256: sha256(run.failure.error), relayVersion: version(run.failure.relayVersion), hostVersion: version(run.failure.hostVersion) } : undefined,
+      failureReasonRecorded: Boolean(run.failureReason), blockReasonRecorded: Boolean(run.blockReason),
+      failureReview: run.failureReview ? { failedAt: run.failureReview.failedAt, reviewedAt: run.failureReview.reviewedAt, status: run.failureReview.status } : undefined,
+      nativeSessionRecorded: Boolean(run.nativeSessionId),
+      toolDelegationMetadata: { state: 'unavailable', reason: 'The relay does not retain native tool or delegation events.' },
+      deliveries: outbox.filter(item => item.runId === run.id && item.chatId === owner.telegramChatId &&
+        Date.parse(item.createdAt) >= Date.parse(owner.telegramLinkedAt ?? owner.pairedAt))
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id)).map(delivery),
+    }))
+}
+
+export type EvidenceOptions = { callerRunId?: string; runId?: string; offset?: number; limit?: number; expected?: string }
+
+export async function runEvidence(controlDir: string, options: EvidenceOptions = {}) {
+  const readStartedAt = new Date().toISOString()
+  const offset = options.offset ?? 0, limit = options.limit ?? 100
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+    throw new Error('Offset must be nonnegative; limit must be 1..100')
+  if (offset > 0 && !options.expected) throw new Error('Continuation requires --expected snapshot SHA-256')
+  if (options.expected !== undefined && !/^[a-f0-9]{64}$/.test(options.expected)) throw new Error('Invalid expected snapshot SHA-256')
+  if (options.callerRunId !== undefined) {
+    const caller = await requireOwnerExecution(controlDir, options.callerRunId)
+    if (caller.application || caller.delivery || caller.replyOnly) throw new Error('Evidence requires Telegram owner execution or the bound operator')
+  }
+  const owner = await readOnlyOwner(controlDir)
+  if (!owner) throw new Error('No authorized owner')
+  const records = projectRunEvidence(await new RunStore(controlDir).list(), retainedOutbox(controlDir), owner)
+    .filter(run => options.runId === undefined || run.id === assertId(options.runId))
+  if (options.runId !== undefined && !records.length) throw new Error('Unknown owner run')
+  const snapshotSha256 = sha256(JSON.stringify(records))
+  if (options.expected !== undefined && options.expected !== snapshotSha256) throw new Error('Evidence changed; restart at offset zero')
+  if (offset > records.length) throw new Error('Offset exceeds retained coverage')
+  const page = records.slice(offset, offset + limit)
+  return { schemaVersion: 1, readStartedAt, observedAt: new Date().toISOString(), snapshotSha256,
+    coverage: { scope: 'current-owner Telegram foreground and scheduled runs', total: records.length, offset, limit, returned: page.length,
+      nextOffset: offset + page.length < records.length ? offset + page.length : null,
+      history: 'relay memory; resets on restart; at most 2000 terminal runs and 2000 terminal outbox items retained',
+      completeness: 'retained records only; older history and unassociated deliveries unknown',
+      excluded: ['external tasks', 'isolated tasks', 'application/channel runs', 'native sessions', 'tool/delegation events', 'failure/review prose', 'message content', 'recipient-side content readback'] },
+    runs: page }
+}

package/src/runs.ts

@@ -6,7 +6,9 @@ import { normalizeReactionEmoji } from './reaction.js'
 import { validScheduledOrigin, type ScheduledOrigin } from './scheduler.js'
 import type { IncomingItem } from './inbox.js'
 import { assertId } from './identity.js'
-import { isExecutionChoice, type ExecutionChoice } from './ai.js'
+import { isExecutionChoice, type AiPreset, type ExecutionChoice } from './ai.js'
+import type { SetupAttempt } from './setup-fallback.js'
+import type { ScriptRunRef } from './scripts.js'
 import {authorizeDeliveryContext,currentDeliveryOwner,type DeliveryContext} from './delivery-context.mjs'
 
 export type RunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled'
@@ -31,6 +33,8 @@ export type RunRecord = {
   pid?: number
   blockReason?: string
   execution?: ExecutionChoice
+  // Ordered task setups tried for this occurrence; the last one is active.
+  attempts?: SetupAttempt[]
   replyOnly?: boolean
   exitCode?: number | null
   failureReason?: string
@@ -44,6 +48,11 @@ export type RunRecord = {
   application?: ApplicationOrigin
   telegramApplication?: ApplicationOrigin
   delivery?: { bindingId: string; scope: string }
+  // Registered script occurrence (no execution preset or native session).
+  script?: ScriptRunRef
+  // Bounded, redacted script stdout/stderr tail; diagnostic, never delivered.
+  output?: string
+  timedOut?: boolean
 }
 
 export type OutboxItemType = 'message' | 'reaction' | 'document' | 'voice' | 'approval'
@@ -71,6 +80,9 @@ export type StoredOutboxItem = OutboxItem & { state?: 'queued' | 'sending' | 'se
 export const sentOutbox = (controlDir: string): StoredOutboxItem[] =>
   [...outboxFor(controlDir).values()].filter(item => item.state === 'sent')
 
+// Explicit operational evidence reads; the projection verifies owner/run scope.
+export const retainedOutbox = (controlDir: string): StoredOutboxItem[] => [...outboxFor(controlDir).values()]
+
 // Stateless pipe: the relay owns the ledger in process memory. Cross-process
 // producers (engine children, plugin children, host executor) reach it through
 // the delivery socket (see delivery-socket.ts), never through control/ files.
@@ -120,6 +132,14 @@ const pruneTerminals = (controlDir: string): void => {
   }
 }
 
+// The setup the current attempt runs with: the latest recorded attempt, else the
+// saved choice. Only a setup saved on the task itself is ever admitted.
+export const activeSetup = (run: Pick<RunRecord, 'attempts' | 'execution'>): AiPreset | undefined => {
+  if (!run.execution) return undefined
+  const preset = [...run.attempts ?? []].reverse().find(attempt => attempt.outcome !== 'skipped')?.preset ?? run.execution.preset
+  return [run.execution.preset, ...run.execution.fallbacks ?? []].find(candidate => JSON.stringify(candidate) === JSON.stringify(preset))
+}
+
 export const newRunId = (): string => `r_${Date.now().toString(36)}_${randomBytes(3).toString('hex')}`
 
 export class RunStore {
@@ -141,6 +161,7 @@ export class RunStore {
     taskId?: string
     application?: ApplicationOrigin
     delivery?: { bindingId: string; scope: string }
+    script?: ScriptRunRef
   }, exclusiveSchedule = false): Promise<RunRecord> {
     const store = runsFor(this.controlDir)
     if (input.id) {
@@ -172,6 +193,7 @@ export class RunStore {
       application: input.application,
       delivery: input.delivery,
       scheduled: input.scheduled,
+      ...(input.script ? { script: input.script } : {}),
       status: 'queued',
       createdAt: new Date().toISOString(),
     }
@@ -187,7 +209,7 @@ export class RunStore {
 
   async patch(
     id: string,
-    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview' | 'externalReleased'>>,
+    change: Partial<Pick<RunRecord, 'status' | 'startedAt' | 'endedAt' | 'pid' | 'nativeSessionId' | 'interrupted' | 'blockReason' | 'backendSubmitted' | 'replyOnly' | 'exitCode' | 'failureReason' | 'failure' | 'failureReview' | 'externalReleased' | 'output' | 'timedOut' | 'attempts'>>,
   ): Promise<RunRecord> {
     const store = runsFor(this.controlDir)
     const run = store.get(id)

package/src/schedule-cli.ts

@@ -1,38 +1,80 @@
 import { needsFailureReview, failureStamp, redactFailure } from './failure.js'
 import { parseArgs } from 'node:util'
 import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { loadControlConfig } from './config.js'
 import { ControlStore, sameOwner } from './control-state.js'
 import { ApplicationBindings } from './application-channel.js'
 import type { RunRecord } from './runs.js'
 import { callDeliverySocket, socketPathFor } from './delivery-socket.js'
-import { initialPreset, isPreset } from './ai.js'
+import { initialPreset, isPreset, presetLabel, MAX_FALLBACKS, type AiPreset } from './ai.js'
 import { executionOverrides } from './model-policy.js'
-import { holdsSchedule, Scheduler } from './scheduler.js'
+import { holdsSchedule, Scheduler, executionType } from './scheduler.js'
+import { Scripts, fileSha256, workspaceEntry, DEFAULT_SCRIPT_TIMEOUT_SECONDS } from './scripts.js'
+import { executorEnvironment } from './executor.js'
+import { provisionedHome } from './auth-profile.js'
 import { ownsRun } from './identity.js'
 import { type Trigger } from './schedule-time.js'
 
+// `cli=claude,model=sonnet,effort=medium` names one fallback setup.
+const fallbackSetup = (spec: string, index: number): AiPreset => {
+  const fields = Object.fromEntries(spec.split(',').map(part => {
+    const at = part.indexOf('=')
+    if (at < 1) throw new Error('Fallback uses cli=EXECUTOR,model=MODEL[,effort=EFFORT][,provider=ID]')
+    return [part.slice(0, at), part.slice(at + 1)]
+  }))
+  if (Object.keys(fields).some(key => !['cli','model','effort','provider'].includes(key)) || !fields.cli || !fields.model)
+    throw new Error('Fallback uses cli=EXECUTOR,model=MODEL[,effort=EFFORT][,provider=ID]')
+  const base = initialPreset(fields.cli)
+  const preset = executionOverrides(base.cli, {...base, ...(fields.provider ? {provider: fields.provider} : {})}, fields.model, fields.effort)
+  const named = {...preset, id: `fallback-${index + 1}`, name: presetLabel(preset).slice(0, 80)}
+  if (!isPreset(named)) throw new Error('Invalid fallback setup')
+  return named
+}
+
 async function main() {
-  const { values:v, positionals:[action='list',id] } = parseArgs({allowPositionals:true,options:{
-    cli:{type:'string'}, model:{type:'string'}, effort:{type:'string'},
-    all:{type:'boolean'}, limit:{type:'string'}, key:{type:'string'}, when:{type:'string'}, status:{type:'string'}, diagnosis:{type:'string'}, recovery:{type:'string'}, outcome:{type:'string'}, 'failed-at':{type:'string'},
-    name:{type:'string'}, text:{type:'string'}, 'text-file':{type:'string'}, at:{type:'string'}, now:{type:'boolean'},
+  const { values:v, positionals:[action='list',id,scriptId] } = parseArgs({allowPositionals:true,options:{
+    script:{type:'string'}, arg:{type:'string',multiple:true}, file:{type:'string'}, interpreter:{type:'string'}, 'timeout-seconds':{type:'string'},
+    cli:{type:'string'}, 'auth-profile':{type:'string'}, model:{type:'string'}, effort:{type:'string'}, fallback:{type:'string',multiple:true}, 'clear-fallbacks':{type:'boolean'},
+    all:{type:'boolean'}, limit:{type:'string'}, offset:{type:'string'}, expected:{type:'string'}, key:{type:'string'}, when:{type:'string'}, status:{type:'string'}, diagnosis:{type:'string'}, recovery:{type:'string'}, outcome:{type:'string'}, 'failed-at':{type:'string'},
+    'preflight-file':{type:'string'},'clear-preflight':{type:'boolean'},name:{type:'string'}, text:{type:'string'}, 'text-file':{type:'string'}, at:{type:'string'}, now:{type:'boolean'},
     cron:{type:'string'}, timezone:{type:'string'}, 'every-seconds':{type:'string'}, start:{type:'string'}, until:{type:'string'}, help:{type:'boolean'},
   }})
   if(v.help){console.log(`ezenciel-agents-schedule list | runs | show ID | pause ID | resume ID | remove ID | cancel RUN_ID
   failures [--all] [--limit N] | run RUN_ID | context
+  evidence [RUN_ID] [--offset N --limit N --expected SNAPSHOT_SHA256]
   trigger SCHEDULE_ID --key REQUEST_KEY
   review RUN_ID --failed-at ISO --status resolved|attention --diagnosis TEXT --recovery TEXT --outcome TEXT
-  create [ID] | edit ID --name NAME (--text TEXT | --text-file FILE)
+  create [ID] | edit ID --name NAME (--text TEXT | --text-file FILE | --script SCRIPT_ID [--arg=VALUE ...])
     --now | --at ISO_WITH_OFFSET | --every-seconds N | --cron 'MIN HOUR DAY MONTH WEEKDAY' --timezone IANA
-    [--cli EXECUTOR] [--model MODEL] [--effort <native-effort>]
+    [--cli EXECUTOR] [--auth-profile NAME] [--model MODEL] [--effort <native-effort>]
+    [--fallback cli=EXECUTOR,model=MODEL[,effort=EFFORT][,provider=ID] ... | --clear-fallbacks]
+    [--preflight-file FILE | --clear-preflight]
     [--start ISO_WITH_OFFSET] [--until ISO_WITH_OFFSET] [--when unreviewed-failures]
+  script list | show SCRIPT_ID | remove SCRIPT_ID
+  script register|update SCRIPT_ID --file WORKSPACE_PATH --interpreter COMMAND [--arg=VALUE ...] [--timeout-seconds N]
+Execution types: agent (prompt, engine, auth profile, model, effort) or script (registered script ID and saved arguments).
+--auth-profile runs a Codex/Claude task under that provisioned login (ezenciel-agents-ai profiles); --cli alone uses the default login.
+A script registration references an entry point inside the agent workspace and records its SHA-256. Core invokes
+the installed interpreter with the entry point and arguments directly, without a shell or a model. Changed entry-point
+bytes refuse to run until an explicit script update. The hash covers that file only, not imported dependencies.
+Script runs receive EZ_RUN_ID, EZ_SCHEDULE_ID, EZ_SCHEDULE_REVISION, EZ_DUE_AT, EZ_SCRIPT_ID, EZ_SCRIPT_REVISION and
+EZ_SCRIPT_SHA256 plus the normal executor allowlist. Stdout/stderr are bounded diagnostics in run, never owner messages.
+Script runs have a timeout (default ${DEFAULT_SCRIPT_TIMEOUT_SECONDS}s) and are never retried automatically.
 Context reads the current run only.
+Evidence exports sanitized current-owner Telegram operational metadata only.
+Follow nextOffset with --expected; a changed snapshot requires restarting.
+Relay retention is incomplete. Content hashes identify submitted text, not recipient content.
+Native sessions, tool/delegation events and failure/review prose are not exported.
 Failures default to unreviewed owner runs. Review records a diagnosis; it never changes execution status or retries work.
 A conditional review schedule consumes no model run when there are no unreviewed failures.
 New tasks capture the selected engine settings; edit preserves existing settings unless overridden.
 Every task requires a concrete saved model. Supply --model if the selected settings have none; existing tasks never fall back to chat or client defaults.
+Fallbacks (at most ${MAX_FALLBACKS}, in order) run only when the previous setup's CLI is unavailable or its provider
+rejected the turn before any work began. Access denial, unknown errors, cancellation and failure after work began stop
+the chain; nothing is replayed. A quota rejection skips later setups of the same client or provider (quota scope),
+even with different credentials. The run records each attempt, setup, failure category and any reported reset time.
 Trigger runs an existing task once with its saved instructions, AI and delivery binding in a fresh session. Reuse the request key after an uncertain result; the regular schedule is unchanged.
 Creates a scheduled task. Instructions are text, never shell commands.
 Use --now to run once. Run completion is not delivery proof.
@@ -66,6 +108,10 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
   if(process.env.EZ_RUN_ID && (!caller || caller.status!=='running' || caller.external || caller.taskId || caller.replyOnly ||
     !ownsRun(owner, caller) ||
     (caller.scheduled && caller.scheduled.pairedAt!==owner.pairedAt)))throw new Error('Scheduling requires an active owner-authorized run')
+  // A script occurrence may read state and deliver through bound plugins; it
+  // cannot change registrations or schedules, including its own.
+  const readOnly=['list','runs','show','run','context','failures','evidence'].includes(action) || (action==='script' && ['list','show'].includes(id ?? ''))
+  if(caller?.script && !readOnly)throw new Error('Script runs cannot change scripts or schedules')
   const owned=(s:{owner:typeof owner})=>sameOwner(s.owner,owner)
   const ownsFailureRun=(r:RunRecord | null)=>r && ownsRun(owner,r) && (!r.scheduled || r.scheduled.pairedAt===owner.pairedAt)
   const show=async(s:Awaited<ReturnType<Scheduler['get']>>)=>{
@@ -73,11 +119,38 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     const interruptedRunIds=held.filter(r=>r.interrupted).map(r=>r.id)
     const failedReviewRunIds=held.filter(r=>!r.interrupted).map(r=>r.id)
     const next=s.enabled && !held.length ? await scheduler.pendingOccurrence(s) : null
-    return {...s,interruptedRunIds,failedReviewRunIds,nextEligibleAt:next===null ? null : new Date(next).toISOString(),
+    return {...s,executionType:executionType(s),preflightReceipt:await scheduler.preflightReceipt(s),interruptedRunIds,failedReviewRunIds,nextEligibleAt:next===null ? null : new Date(next).toISOString(),
       ...(held.length ? {recovery:'Inspect the failed run and explicitly edit this schedule to resume; pause/resume does not clear the stop.'} : {})}
   }
+  const scripts=new Scripts(config.controlDir)
   let result:unknown
-  if(action==='context'){
+  if(action==='script'){
+    const workspace=process.env.EZ_AGENT_WORKSPACE?.trim() || process.cwd()
+    if(id==='list')result=await scripts.list(owner)
+    else if(!scriptId)throw new Error('Script ID required')
+    else if(id==='show'){
+      const registration=await scripts.owned(scriptId,owner)
+      let current:string|null=null
+      try{current=await fileSha256((await workspaceEntry(workspace,registration.entry)).file)}catch{}
+      result={...registration,currentSha256:current,matchesRegistration:current===registration.sha256,
+        schedules:(await scheduler.list()).filter(s=>owned(s) && s.script?.id===scriptId).map(s=>s.id)}
+    }else if(id==='remove'){
+      const users=(await scheduler.list()).filter(s=>owned(s) && s.script?.id===scriptId).map(s=>s.id)
+      if(users.length)throw new Error(`Script is used by schedules ${users.join(', ')}; edit or remove them first`)
+      await scripts.remove(scriptId,owner);result={removed:scriptId}
+    }else if(id==='register' || id==='update'){
+      const previous=id==='update' ? await scripts.owned(scriptId,owner) : undefined
+      if(id==='register' && (!v.file || !v.interpreter))throw new Error('Register requires --file and --interpreter')
+      const timeout=v['timeout-seconds']===undefined ? previous?.timeoutSeconds ?? DEFAULT_SCRIPT_TIMEOUT_SECONDS : Number(v['timeout-seconds'])
+      result=await scripts.save({id:scriptId,owner,workspace,entry:v.file ? resolve(v.file) : previous!.entry,interpreter:v.interpreter ?? previous!.interpreter,
+        args:v.arg ?? previous?.args ?? [],timeoutSeconds:timeout,pathValue:executorEnvironment().PATH},id==='register')
+    }else throw new Error('Unknown script action; use --help')
+  }else if(action==='evidence'){
+    result=await callDeliverySocket(socketPath,{op:'evidence',payload:{
+      ...(caller ? {callerRunId:caller.id} : {}), ...(id ? {runId:id} : {}),
+      offset:Number(v.offset ?? 0),limit:Number(v.limit ?? 100),expected:v.expected,
+    }})
+  }else if(action==='context'){
     if(!caller)throw new Error('Context requires an active owner run')
     const origin=caller.scheduled?.originRunId ? await runs.get(caller.scheduled.originRunId) : null
     if(origin && !ownsFailureRun(origin))throw new Error('Source context is outside this owner binding')
@@ -108,23 +181,37 @@ Cron uses numeric five-field syntax, lists/ranges/steps, and traditional day/wee
     if(action==='edit' && (!id || !owned(await scheduler.get(id))))throw new Error('Unknown schedule')
     if(action==='create' && id && (await scheduler.list()).some(s=>s.id===id))throw new Error('Schedule exists; use edit')
     if([v.now,v.at,v.cron,v['every-seconds']].filter(Boolean).length!==1)throw new Error('Choose exactly one trigger')
-    if(Boolean(v.text)===Boolean(v['text-file']))throw new Error('Choose --text or --text-file')
+    if([v.text,v['text-file'],v.script].filter(Boolean).length!==1)throw new Error('Choose --text, --text-file or --script')
+    if(v.script && (v.cli || v['auth-profile'] || v.model || v.effort || v.fallback || v['clear-fallbacks']))throw new Error('Script schedules run no model; --cli, --auth-profile, --model, --effort and --fallback do not apply')
+    if(v.fallback && v['clear-fallbacks'])throw new Error('Choose --fallback or --clear-fallbacks')
+    if(v.arg && !v.script)throw new Error('--arg applies to script schedules only')
     const start=v.start || new Date(Date.now()+1000).toISOString()
     const trigger:Trigger=v.now ? {at:new Date(Date.now()+1000).toISOString()} : v.at ? {at:v.at} :
       v.cron ? {cron:v.cron,timezone:v.timezone!,start,until:v.until} : {everySeconds:Number(v['every-seconds']),start,until:v.until}
+    if(v['clear-preflight'] && v['preflight-file']) throw Error('Choose one preflight operation')
     const previousSchedule = action === 'edit' ? await scheduler.get(id!) : undefined
+    const preflight = v['clear-preflight'] ? undefined : v['preflight-file'] ? JSON.parse(await readFile(v['preflight-file'],'utf8')) : previousSchedule?.preflight
     const origin = caller?.application ?? caller?.delivery
     const delivery = previousSchedule ? previousSchedule.delivery : (origin ? {bindingId:origin.bindingId,scope:origin.scope} : undefined)
     if (!delivery && !owner.telegramChatId) throw new Error('Create the schedule from an authenticated channel turn to bind its reply destination')
+    if (v.script) {
+      result=await show(await scheduler.save({id:id || 's_'+randomUUID(),name:v.name || v.script,preflight,
+        originRunId:previousSchedule?.originRunId ?? caller?.scheduled?.originRunId ?? caller?.id,delivery,text:'',when:v.when as 'unreviewed-failures' | undefined,trigger,enabled:true,owner,
+        script:{id:v.script,args:v.arg ?? []}},action==='create'))
+      console.log(JSON.stringify(result,null,2));return
+    }
     const previous = previousSchedule?.execution
     const state = await control.status()
     const selected = state.ai?.presets.find(p => p.id === state.ai!.selectedId)
     const base = v.cli ? initialPreset(v.cli) : previous?.preset || selected || initialPreset(process.env.EZ_EXECUTOR_CLI || 'codex')
-    const preset = executionOverrides(base.cli, base, v.model, v.effort)
+    const preset = executionOverrides(base.cli, v['auth-profile'] === undefined ? base : {...base, authProfile:v['auth-profile']}, v.model, v.effort)
     if (!isPreset(preset)) throw new Error('Invalid task AI selection')
+    const fallbacks = v['clear-fallbacks'] ? undefined : v.fallback ? v.fallback.map(fallbackSetup) : previous?.fallbacks
+    if (preset.authProfile !== undefined) await provisionedHome(config.controlDir, preset.cli, preset.authProfile)
     result=await show(await scheduler.save({id:id || 's_'+randomUUID(),name:v.name || 'Task',
+      preflight,
       originRunId:previousSchedule?.originRunId ?? caller?.scheduled?.originRunId ?? caller?.id,delivery,text:v.text || await readFile(v['text-file']!,'utf8'),when:v.when as 'unreviewed-failures' | undefined,trigger,enabled:true,owner,
-      execution:{sessionId:previous?.sessionId || randomUUID(),preset}},action==='create'))
+      execution:{sessionId:previous?.sessionId || randomUUID(),preset,...(fallbacks ? {fallbacks} : {})}},action==='create'))
   }else{
     if(!id)throw new Error('ID required')
     if(action==='cancel'){