@jc_stack/ez-agents 0.1.0-beta.12 → 0.1.0-beta.18

package/scripts/trusted-beta.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { mkdir, readFile, writeFile, mkdtemp, rm, rename } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+
+const REGISTRY = 'https://registry.npmjs.org/';
+const CORE = 'jdorado/ez-agents';
+const MAX_ARTIFACT = 100 * 1024 * 1024;
+const assert = (condition, message) => { if (!condition) throw new Error(message); };
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+
+export function publishEnvironment(env) {
+  const allowed = ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'LANG', 'LC_ALL', 'CI',
+    'GITHUB_ACTIONS', 'GITHUB_WORKFLOW', 'GITHUB_WORKFLOW_REF', 'GITHUB_WORKFLOW_SHA',
+    'GITHUB_REPOSITORY', 'GITHUB_REPOSITORY_ID', 'GITHUB_REPOSITORY_OWNER', 'GITHUB_REPOSITORY_OWNER_ID',
+    'GITHUB_SERVER_URL', 'GITHUB_REF', 'GITHUB_REF_NAME', 'GITHUB_REF_TYPE', 'GITHUB_SHA',
+    'GITHUB_RUN_ID', 'GITHUB_RUN_NUMBER', 'GITHUB_RUN_ATTEMPT', 'GITHUB_EVENT_NAME', 'GITHUB_JOB',
+    'GITHUB_ACTOR', 'GITHUB_ACTOR_ID', 'RUNNER_ENVIRONMENT', 'RUNNER_OS', 'RUNNER_ARCH',
+    'ACTIONS_ID_TOKEN_REQUEST_URL', 'ACTIONS_ID_TOKEN_REQUEST_TOKEN'];
+  return Object.fromEntries(allowed.filter(key => env[key] !== undefined).map(key => [key, env[key]]));
+}
+
+export function publishArguments(path, npmrc, globalNpmrc) {
+  return ['publish', path, '--fetch-retries=0', '--ignore-scripts', '--provenance', '--access', 'public', '--tag', 'latest', '--registry', REGISTRY, '--userconfig', npmrc, '--globalconfig', globalNpmrc];
+}
+
+export function identity(env) {
+  const value = { repository: env.RELEASE_REPOSITORY, package: env.RELEASE_PACKAGE,
+    version: env.RELEASE_VERSION, sourceSha: env.RELEASE_SOURCE_SHA,
+    sha256: env.RELEASE_SHA256, releaseId: Number(env.RELEASE_ID), requiredChecks: JSON.parse(env.RELEASE_REQUIRED_CHECKS || 'null') };
+  assert(/^[1-9]\d*$/.test(env.RELEASE_ID || '') && Number.isSafeInteger(value.releaseId), 'Invalid draft release ID');
+  assert(/^jdorado\/[A-Za-z0-9_.-]+$/.test(value.repository || ''), 'Invalid repository');
+  assert(/^@jc_stack\/[a-z0-9-]+$/.test(value.package || ''), 'Invalid package');
+  assert(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-beta\.(0|[1-9]\d*)$/.test(value.version || ''), 'Only immutable beta.N versions are allowed');
+  assert(/^[a-f0-9]{40}$/.test(value.sourceSha || ''), 'Invalid source SHA');
+  assert(/^[a-f0-9]{64}$/.test(value.sha256 || ''), 'Invalid artifact SHA256');
+  assert(Array.isArray(value.requiredChecks) && value.requiredChecks.length > 0 && value.requiredChecks.every(x => typeof x === 'string' && x.length > 0) && new Set(value.requiredChecks).size === value.requiredChecks.length, 'Required checks must be a nonempty unique list');
+  assert(env.GITHUB_REPOSITORY === value.repository, 'Caller repository mismatch');
+  assert(env.GITHUB_EVENT_NAME === 'workflow_dispatch' && env.GITHUB_REF === 'refs/heads/main', 'Must manually dispatch from main');
+  assert(env.GITHUB_SHA === value.sourceSha, 'Source must equal dispatched source');
+  return value;
+}
+
+export function validateManifest(manifest, expected) {
+  assert(manifest.name === expected.package && manifest.version === expected.version, 'Package identity mismatch');
+  assert(manifest.private !== true, 'Private packages cannot be published');
+  const repo = typeof manifest.repository === 'string' ? manifest.repository : manifest.repository?.url;
+  assert(repo === `git+https://github.com/${expected.repository}.git` || repo === `https://github.com/${expected.repository}.git` || repo === `https://github.com/${expected.repository}`, 'Package repository mismatch');
+  const config = manifest.publishConfig || {};
+  assert(Object.keys(config).every(key => ['access', 'tag', 'registry', 'provenance'].includes(key)), 'Unsupported publish configuration');
+  assert(config.access === undefined || config.access === 'public', 'Invalid publish access');
+  assert(config.tag === undefined || config.tag === 'latest', 'Invalid publish tag');
+  assert(config.registry === undefined || config.registry === REGISTRY || config.registry === REGISTRY.slice(0, -1), 'Invalid publish registry');
+  assert(config.provenance !== false, 'Provenance must not be disabled');
+}
+
+export function validateReceipt(receipt, expected) {
+  for (const key of ['repository', 'package', 'version', 'sourceSha', 'sha256']) {
+    assert(receipt[key] === expected[key], `Receipt ${key} mismatch`);
+  }
+  const base = `https://github.com/${expected.repository}/`;
+  assert(typeof receipt.independentReviewUrl === 'string' && receipt.independentReviewUrl.startsWith(base) && /^pull\/[1-9]\d*(?:#[A-Za-z0-9_-]+)?$/.test(receipt.independentReviewUrl.slice(base.length)), 'Missing independent review PR URL');
+  assert(Array.isArray(receipt.testEvidenceUrls) && receipt.testEvidenceUrls.length > 0 && receipt.testEvidenceUrls.every(url => typeof url === 'string' && url.startsWith(base) && /^(?:actions\/runs|pull|issues)\/[1-9]\d*(?:#[A-Za-z0-9_-]+)?$/.test(url.slice(base.length))), 'Missing test evidence URLs');
+}
+
+export function validateChecks(checks, expected) {
+  const selected = [];
+  for (const name of expected.requiredChecks) {
+    const runs = checks.filter(check => check.name === name && check.head_sha === expected.sourceSha && check.app?.id === 15368).sort((a, b) => b.id - a.id);
+    assert(runs.length > 0 && runs[0].status === 'completed' && runs[0].conclusion === 'success', `Required GitHub Actions check not successful: ${name}`);
+    selected.push(runs[0]);
+  }
+  return selected;
+}
+
+export function tarManifest(path) {
+  const options = { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, timeout: 30_000 };
+  const entries = execFileSync('tar', ['-tzf', path], options).trim().split('\n');
+  assert(entries.filter(name => name === 'package/package.json').length === 1, 'Tarball must have exactly one package/package.json');
+  assert(entries.every(name => name.startsWith('package/') && !name.split('/').includes('..') && !name.includes('\\')), 'Unsafe tarball path');
+  const details = execFileSync('tar', ['-tvzf', path], options).trim().split('\n');
+  assert(details.every(line => line.startsWith('-') || line.startsWith('d')), 'Tarball links or special files are forbidden');
+  return JSON.parse(execFileSync('tar', ['-xOf', path, 'package/package.json'], { ...options, maxBuffer: 1024 * 1024 }));
+}
+
+async function responseBytes(response, max = MAX_ARTIFACT) {
+  assert(response.ok, `HTTP ${response.status} while reading release evidence`);
+  assert(Number(response.headers.get('content-length') || 0) <= max, 'Response too large');
+  let size = 0; const chunks = [];
+  for await (const chunk of response.body) { size += chunk.length; assert(size <= max, 'Response too large'); chunks.push(chunk); }
+  return Buffer.concat(chunks);
+}
+
+export function githubClient(token, fetcher = fetch) {
+  return async (path, binary = false) => {
+    assert(path.startsWith('/repos/'), 'Invalid GitHub API path');
+    const response = await fetcher(`https://api.github.com${path}`, {
+      headers: { Accept: binary ? 'application/octet-stream' : 'application/vnd.github+json', ...(token ? { Authorization: `Bearer ${token}` } : {}), 'X-GitHub-Api-Version': '2022-11-28' },
+      redirect: 'manual', signal: AbortSignal.timeout(30_000),
+    });
+    if (binary && [301, 302, 303, 307, 308].includes(response.status)) {
+      const location = new URL(response.headers.get('location'));
+      assert(location.protocol === 'https:' && (location.hostname === 'release-assets.githubusercontent.com' || location.hostname === 'objects.githubusercontent.com'), 'Unexpected asset redirect');
+      return responseBytes(await fetcher(location, { signal: AbortSignal.timeout(60_000), redirect: 'error' }));
+    }
+    const bytes = await responseBytes(response, binary ? MAX_ARTIFACT : 8 * 1024 * 1024);
+    return binary ? bytes : JSON.parse(bytes.toString());
+  };
+}
+
+export async function validateSource(expected, api) {
+  const repo = await api(`/repos/${expected.repository}`);
+  assert(repo.full_name === expected.repository && repo.private === false && repo.visibility === 'public' && repo.default_branch === 'main' && !repo.archived, 'Repository must be public and active on main');
+  const catalog = await api(`/repos/${CORE}/contents/docs/plugin-catalog.md?ref=main`);
+  const catalogText = Buffer.from(catalog.content, 'base64').toString('utf8');
+  const enrolled = catalogText.split('\n').some(line => line.startsWith('|') && line.includes(`](https://github.com/${expected.repository})`) && line.includes('`' + expected.package + '`'));
+  assert(expected.repository === CORE ? expected.package === '@jc_stack/ez-agents' : enrolled, 'Repository/package is not enrolled in public catalog');
+  const main = await api(`/repos/${expected.repository}/git/ref/heads/main`);
+  assert(main.object?.sha === expected.sourceSha, 'Source is no longer current main');
+  const manifest = await api(`/repos/${expected.repository}/contents/package.json?ref=${expected.sourceSha}`);
+  const sourceManifest = JSON.parse(Buffer.from(manifest.content, 'base64').toString('utf8'));
+  validateManifest(sourceManifest, expected);
+  let tag = (await api(`/repos/${expected.repository}/git/ref/tags/v${expected.version}`)).object;
+  for (let depth = 0; tag?.type === 'tag' && depth < 5; depth++) tag = (await api(`/repos/${expected.repository}/git/tags/${tag.sha}`)).object;
+  assert(tag?.type === 'commit' && tag.sha === expected.sourceSha, 'Release tag does not identify approved source');
+  // Select CI identity before considering outcomes: tag/PR runs at the same SHA
+  // must neither shadow main CI nor let a failed latest main run fall back.
+  const runs = [];
+  for (let page = 1; ; page++) {
+    assert(page <= 100, 'Too many workflow run pages');
+    const result = await api(`/repos/${expected.repository}/actions/workflows/ci.yml/runs?branch=main&event=push&head_sha=${expected.sourceSha}&per_page=100&page=${page}`);
+    assert(Array.isArray(result.workflow_runs), 'Invalid workflow run response');
+    runs.push(...result.workflow_runs.filter(run => run.head_sha === expected.sourceSha && run.event === 'push' && run.head_branch === 'main' && run.path === '.github/workflows/ci.yml'));
+    if (result.workflow_runs.length < 100) break;
+  }
+  const run = runs.sort((a, b) => b.id - a.id)[0];
+  assert(run && Number.isSafeInteger(run.id) && run.id > 0 && Number.isSafeInteger(run.run_attempt) && run.run_attempt > 0 && run.status === 'completed' && run.conclusion === 'success', 'Required check is not successful main push CI');
+  const jobs = [];
+  for (let page = 1; ; page++) {
+    assert(page <= 100, 'Too many job pages');
+    const result = await api(`/repos/${expected.repository}/actions/runs/${run.id}/attempts/${run.run_attempt}/jobs?per_page=100&page=${page}`);
+    assert(Array.isArray(result.jobs), 'Invalid job response');
+    jobs.push(...result.jobs);
+    if (result.jobs.length < 100) break;
+  }
+  const checks = [];
+  for (const name of expected.requiredChecks) {
+    const matches = jobs.filter(job => job.name === name);
+    assert(matches.length === 1, `Missing or ambiguous required CI job: ${name}`);
+    const job = matches[0];
+    assert(job.run_id === run.id && job.run_attempt === run.run_attempt && job.head_sha === expected.sourceSha && job.status === 'completed' && job.conclusion === 'success', `Required CI job not successful: ${name}`);
+    const prefix = `https://api.github.com/repos/${expected.repository}/check-runs/`;
+    assert(typeof job.check_run_url === 'string' && job.check_run_url.startsWith(prefix) && /^[1-9]\d*$/.test(job.check_run_url.slice(prefix.length)), 'Invalid job check evidence URL');
+    const check = await api(job.check_run_url.slice('https://api.github.com'.length));
+    assert(check.name === name && check.details_url === `https://github.com/${expected.repository}/actions/runs/${run.id}/job/${job.id}`, 'Check does not identify the required CI job');
+    checks.push(check);
+  }
+  validateChecks(checks, expected);
+  return sourceManifest;
+}
+
+export async function registryState(expected, fetcher = fetch) {
+  const response = await fetcher(`${REGISTRY}${encodeURIComponent(expected.package)}`, { signal: AbortSignal.timeout(30_000), redirect: 'error', headers: { Accept: 'application/json' } });
+  assert(response.status !== 404, 'Package does not exist: first reviewed beta needs interactive registry-owner publication before trust enrollment');
+  const data = JSON.parse((await responseBytes(response, 32 * 1024 * 1024)).toString());
+  assert(data.name === expected.package && data.versions && data['dist-tags'], 'Invalid registry package metadata');
+  const published = data.versions[expected.version];
+  if (!published) return { exists: false, latest: data['dist-tags'].latest ?? null, beta: data['dist-tags'].beta ?? null };
+  assert(published.name === expected.package && published.version === expected.version, 'Registry version identity mismatch');
+  const url = new URL(published.dist?.tarball);
+  assert(url.origin === REGISTRY.slice(0, -1), 'Unexpected registry tarball host');
+  const bytes = await responseBytes(await fetcher(url, { signal: AbortSignal.timeout(60_000), redirect: 'error' }));
+  assert(sha256(bytes) === expected.sha256, 'Existing registry artifact differs; never overwrite');
+  return { exists: true, latest: data['dist-tags'].latest ?? null, beta: data['dist-tags'].beta ?? null };
+}
+
+export async function validate(output, env = process.env, api = githubClient(env.GH_TOKEN)) {
+  const expected = identity(env);
+  const sourceManifest = await validateSource(expected, api);
+  const release = await api(`/repos/${expected.repository}/releases/${expected.releaseId}`);
+  assert(release.id === expected.releaseId && release.draft === true && release.prerelease === true && release.tag_name === `v${expected.version}`, 'Candidate must be a draft prerelease');
+  const asset = name => {
+    const matches = (release.assets || []).filter(item => item.name === name && item.state === 'uploaded');
+    assert(matches.length === 1 && Number.isSafeInteger(matches[0].id), `Missing or ambiguous asset: ${name}`);
+    return matches[0];
+  };
+  const candidateAsset = asset('candidate.tgz');
+  const receiptAsset = asset('release-receipt.json');
+  const bytes = await api(`/repos/${expected.repository}/releases/assets/${candidateAsset.id}`, true);
+  assert(sha256(bytes) === expected.sha256, 'Candidate artifact SHA256 mismatch');
+  const receipt = JSON.parse((await api(`/repos/${expected.repository}/releases/assets/${receiptAsset.id}`, true)).toString());
+  validateReceipt(receipt, expected);
+  // Dispatch is the authorized maintainer's attestation to these review/test URLs.
+  // Their existence alone is not an independent review verdict.
+  const reviewPr = Number(new URL(receipt.independentReviewUrl).pathname.split('/')[4]);
+  const pr = await api(`/repos/${expected.repository}/pulls/${reviewPr}`);
+  assert(pr.merged === true && pr.base?.repo?.full_name === expected.repository && pr.base?.ref === 'main' && pr.merge_commit_sha === expected.sourceSha, 'Review PR must be merged as the exact release source');
+  await mkdir(output, { recursive: true });
+  const tarball = resolve(output, 'candidate.tgz');
+  await writeFile(tarball, bytes, { flag: 'wx' });
+  const packedManifest = tarManifest(tarball);
+  validateManifest(packedManifest, expected);
+  assert(isDeepStrictEqual(packedManifest, sourceManifest), 'Packed manifest differs from approved source manifest');
+  await writeFile(resolve(output, 'validated.json'), JSON.stringify({ schema: 1, expected, receipt, releaseId: release.id, candidateAssetId: candidateAsset.id }, null, 2) + '\n', { flag: 'wx' });
+  return { sourceSha: expected.sourceSha, sha256: expected.sha256, version: expected.version };
+}
+
+export async function publishOnce(expected, { readState, publishTarball, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), report = console.log, record = async () => {}, allowWrite = true }) {
+  const before = await readState();
+  await record({ phase: 'preflight', before });
+  if (before.exists) {
+    assert(before.latest === expected.version, 'Artifact exists but latest tag differs; reconcile without republishing');
+    return { status: 'already-published', version: expected.version, sha256: expected.sha256 };
+  }
+  assert(allowWrite, 'Rerun cannot repeat publication: reconcile registry state and create a fresh authorized dispatch if a new attempt is needed');
+  await record({ phase: 'write-started', before });
+  let writeError;
+  try { await publishTarball(); } catch (error) { writeError = error; }
+  let lastError;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    if (attempt) await sleep(5000);
+    try {
+      const after = await readState();
+      await record({ phase: 'readback', before, after, publishCommandFailed: Boolean(writeError), attempt });
+      if (after.exists && after.latest === expected.version) {
+        if (writeError) report('Publish command was uncertain; registry readback verified exact artifact and latest tag.');
+        return { status: 'published', version: expected.version, sha256: expected.sha256 };
+      }
+      lastError = new Error('Exact artifact and latest tag not yet verified');
+    } catch (error) { lastError = error; await record({ phase: 'readback-error', before, error: error.message, attempt }); }
+  }
+  throw new Error(`Publication unresolved; do not repeat the write before registry reconciliation: ${lastError?.message || writeError?.message}`);
+}
+
+export async function publish(output, env = process.env) {
+  const expected = identity(env);
+  const bundle = JSON.parse(await readFile(resolve(output, 'validated.json'), 'utf8'));
+  assert(bundle.schema === 1 && JSON.stringify(bundle.expected) === JSON.stringify(expected), 'Validated bundle does not match dispatched identity');
+  validateReceipt(bundle.receipt, expected);
+  const path = resolve(output, 'candidate.tgz');
+  assert(sha256(await readFile(path)) === expected.sha256, 'Validated artifact changed');
+  const packedManifest = tarManifest(path);
+  validateManifest(packedManifest, expected);
+  const sourceManifest = await validateSource(expected, githubClient(env.GH_TOKEN));
+  assert(isDeepStrictEqual(packedManifest, sourceManifest), 'Packed manifest differs from approved source manifest');
+  assert(!env.NODE_AUTH_TOKEN && !env.NPM_TOKEN, 'Token-based npm publishing is forbidden');
+  const temporary = await mkdtemp(join(tmpdir(), 'trusted-beta-'));
+  try {
+    const npmrc = join(temporary, 'npmrc');
+    const globalNpmrc = join(temporary, 'global-npmrc');
+    await writeFile(npmrc, 'registry=https://registry.npmjs.org/\n');
+    await writeFile(globalNpmrc, '');
+    const events = [];
+    const record = async event => {
+      events.push({ at: new Date().toISOString(), ...event });
+      const receiptPath = resolve(output, 'publication-receipt.json');
+      await writeFile(`${receiptPath}.${process.pid}.tmp`, JSON.stringify({ schema: 1, expected, events }, null, 2) + '\n', { mode: 0o600 });
+      await rename(`${receiptPath}.${process.pid}.tmp`, receiptPath);
+    };
+    try {
+      const result = await publishOnce(expected, {
+      record,
+      allowWrite: env.GITHUB_RUN_ATTEMPT === '1',
+      readState: () => registryState(expected),
+      publishTarball: () => execFileSync('npm', publishArguments(path, npmrc, globalNpmrc), {
+        cwd: temporary, stdio: 'inherit', timeout: 180_000,
+        env: publishEnvironment(env),
+      }),
+    });
+      await record({ phase: 'complete', result });
+      return result;
+    } catch (error) {
+      await record({ phase: 'failed', error: error.message });
+      throw error;
+    }
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const [mode, output] = process.argv.slice(2);
+    assert(['validate', 'publish'].includes(mode) && output && process.argv.length === 4, 'Usage: trusted-beta.mjs validate|publish OUTPUT_DIR');
+    console.log(JSON.stringify(await (mode === 'validate' ? validate(output) : publish(output))));
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/src/agent-guidance.ts

@@ -0,0 +1,5 @@
+import { readFileSync } from 'node:fs'
+
+// Resolve against the installed package, never the agent's editable workspace.
+export const agentGuidance = (): string =>
+  readFileSync(new URL('../templates/agent-guidance.md', import.meta.url), 'utf8').trim()

package/src/ai-cli.ts

@@ -1,11 +1,12 @@
 import { parseArgs } from 'node:util'
 import { randomBytes } from 'node:crypto'
+import { join } from 'node:path'
 import { readModels, validateSelection, type AiPreset } from './ai.js'
 import { ControlStore } from './control-state.js'
 
 const {values,positionals}=parseArgs({allowPositionals:true,options:{cli:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
 if (!process.env.EZ_CONTROL_DIR) throw new Error('Use this agent’s bound control directory')
-const catalog=await readModels()
+const catalog=await readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR,'cli','codex'))
 if(positionals[0]==='list')console.log(JSON.stringify(catalog))
 else if(positionals[0]==='select'){
   const preset:AiPreset={id:randomBytes(8).toString('hex'),name:[values.model||values.cli,values.effort].filter(Boolean).join(' · '),cli:values.cli||'',model:values.model,effort:values.effort}

package/src/ai.ts

@@ -1,3 +1,4 @@
+import { CODEX_DEFAULT_MODEL, DEFAULT_EFFORT, assertEffort, allowedEffort } from './model-policy.js'
 import { access, readFile } from 'node:fs/promises'
 import { constants } from 'node:fs'
 import { homedir } from 'node:os'
@@ -21,10 +22,18 @@ export const isExecutionChoice = (v: unknown): v is ExecutionChoice => {
   return Boolean(c && /^[0-9a-f-]{36}$/i.test(c.sessionId) && isPreset(c.preset))
 }
 export const presetLabel = (p: AiPreset) => `${p.cli} · ${p.model || 'client default'} · ${p.effort || 'default effort'}`
+// The seed delegates model selection to the native client. Project its resolved
+// settings for status without pinning future conversations to that snapshot.
+export const statusPreset = (preset: AiPreset, discovered: AiPreset[]): AiPreset =>
+  preset.cli === 'codex' && !preset.model && !preset.effort
+    ? discovered.find((candidate) => candidate.cli === preset.cli) ?? preset
+    : preset
 export const initialPreset = (cli: string): AiPreset => {
   const key = executorKey(cli)
   return {
     id: 'initial', name: `${resolveExecutor(key).name} · current setup`, cli: key,
+    ...(key === 'codex' || key === 'codex-gui'
+      ? { model: CODEX_DEFAULT_MODEL, effort: DEFAULT_EFFORT } : {}),
     ...(key === 'opencode'
       ? { model: process.env.OPENCODE_MODEL || 'opencode/nemotron-3.5-lightning-free' } : {}),
   }
@@ -40,17 +49,17 @@ export const installed = async (cli: string): Promise<boolean> => {
 
 // Read only metadata from native client catalogs. Never import prompts, credentials,
 // provider configuration, or model instructions into relay context.
-export const readModels = async (home = homedir(), available = installed): Promise<ModelChoice[]> => {
+export const readModels = async (home = homedir(), available = installed, codexHome = join(home, '.codex')): Promise<ModelChoice[]> => {
   const models: ModelChoice[] = []
   const record = (value: unknown): Record<string, unknown> =>
     value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {}
   const efforts = (value: unknown, key: string): string[] =>
-    (Array.isArray(value) ? value : []).map((e: unknown) => record(e)[key]).filter(safe)
+    (Array.isArray(value) ? value : []).map((e: unknown) => record(e)[key]).filter(safe).filter(allowedEffort)
   const json = async (file: string) => {
-    try { return record(JSON.parse(await readFile(join(home, file), 'utf8'))) } catch { return {} }
+    try { return record(JSON.parse(await readFile(file, 'utf8'))) } catch { return {} }
   }
   if (await available('grok')) {
-    const cache = await json('.grok/models_cache.json')
+    const cache = await json(join(home, '.grok', 'models_cache.json'))
     for (const entry of Object.values(record(cache.models))) {
       const info = record(record(entry).info)
       if (info.hidden || !safe(info.id)) continue
@@ -59,7 +68,7 @@ export const readModels = async (home = homedir(), available = installed): Promi
     }
   }
   if (await available('codex')) {
-    const cache = await json('.codex/models_cache.json')
+    const cache = await json(join(codexHome, 'models_cache.json'))
     for (const entry of Array.isArray(cache.models) ? cache.models : []) {
       const info = record(entry)
       if (info.visibility !== 'list' || !safe(info.slug)) continue
@@ -80,6 +89,7 @@ export const readModels = async (home = homedir(), available = installed): Promi
 }
 
 export const validateSelection = async (p: AiPreset, catalog: ModelChoice[], available = installed): Promise<void> => {
+  assertEffort(p.effort)
   if (!isPreset(p) || !(await available(p.cli))) throw new Error('This CLI is not installed.')
   if (!p.model && !p.effort && p.cli !== 'agy') return
   const model = catalog.find((m) => m.cli === p.cli && m.model === p.model)

package/src/channel-backend.ts

@@ -0,0 +1,46 @@
+import { readFile } from 'node:fs/promises'
+import type { Config } from './config.js'
+import type { RunRecord } from './runs.js'
+import { workspaceFile } from './files.js'
+
+// Application-owned jobs; no CLI state, provider credentials or business routing here.
+export async function dispatchChannel(config: Config, run: RunRecord): Promise<string | null> {
+  const url = new URL(config.channelBackendUrl!)
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1'].includes(url.hostname)))
+    throw new Error('Channel backend requires HTTPS (or loopback HTTP)')
+  if (!config.channelBackendToken || url.username || url.password || url.search || url.hash)
+    throw new Error('Channel backend requires a private token and plain endpoint URL')
+  const items = []
+  for (const item of run.items ?? []) {
+    let attachment
+    if (item.attachment) {
+      const bytes = await readFile(await workspaceFile(config.workspace, item.attachment.path))
+      if (bytes.length > 12 * 1024 * 1024) throw new Error('Channel attachment exceeds 12 MB')
+      attachment = { type: item.attachment.type, data: bytes.toString('base64') }
+    }
+    items.push({ text: item.attachment ? (item.caption ?? '') : item.text,
+      message_id: item.messageId, sent_at: item.sentAt, album_id: item.albumId, attachment })
+  }
+  if (!items.length) throw new Error('Channel run is missing normalized items')
+  const response = await fetch(url, {
+    method: 'POST', redirect: 'error', signal: AbortSignal.timeout(60_000),
+    headers: { Authorization: `Bearer ${config.channelBackendToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ version: 1, event_id: run.id, channel: 'telegram',
+      sender_id: String(run.telegramUserId), chat_id: String(run.chatId), items }),
+  })
+  if (!response.ok) {
+    const error = new Error(`Channel backend HTTP ${response.status}`)
+    if (response.status >= 400 && response.status < 500 && ![408, 429].includes(response.status))
+      Object.assign(error, { permanent: true })
+    throw error
+  }
+  const result = await response.json() as { status?: string; reply?: string }
+  if (result.status === 'queued' || result.status === 'running') {
+    // Yield to the durable relay queue; backend requests with the same ID only resume/poll.
+    await new Promise(resolve => setTimeout(resolve, 4000))
+    return null
+  }
+  if (!['complete', 'failed'].includes(result.status ?? '') || typeof result.reply !== 'string')
+    throw new Error('Invalid channel backend response')
+  return result.reply
+}

package/src/client-defaults.ts

@@ -15,11 +15,28 @@ const value = (v: unknown): string | undefined =>
 const command = async (cli: string, args: string[], cwd: string): Promise<string> =>
   (await promisify(execFile)(cli, args, { cwd, env: executorEnvironment(), timeout: 8000, maxBuffer: 2 * 1024 * 1024 })).stdout
 
+export const resolvedCodexDefaults = (configValue: unknown, catalogValue: unknown): Record<string, unknown> => {
+  const config = record(configValue)
+  const managed = record(record(config.models).new_thread)
+  const model = value(managed.model) ?? value(config.model)
+  const effort = value(managed.model_reasoning_effort) ?? value(config.model_reasoning_effort)
+  const catalog = (Array.isArray(catalogValue) ? catalogValue : []).map(record)
+  const selected = model
+    ? catalog.find((entry) => value(entry.model) === model || value(entry.id) === model)
+    : catalog.find((entry) => entry.isDefault === true)
+  return {
+    ...(model ?? value(selected?.model) ?? value(selected?.id) ? { model: model ?? value(selected?.model) ?? value(selected?.id) } : {}),
+    ...(effort ?? value(selected?.defaultReasoningEffort) ? { effort: effort ?? value(selected?.defaultReasoningEffort) } : {}),
+  }
+}
+
 // Native config/read resolves Codex's layers; do not reimplement TOML or start a turn.
-export const codexDefaults = (cwd: string): Promise<Record<string, unknown>> => new Promise((resolve) => {
-  const child = spawn('codex', ['app-server'], { cwd, env: executorEnvironment(), stdio: ['pipe', 'pipe', 'ignore'] })
+export const codexDefaults = (cwd: string, codexHome?: string, nativeFallback = false): Promise<Record<string, unknown>> => new Promise((resolve) => {
+  const child = spawn('codex', ['app-server'], { cwd,
+    env: { ...executorEnvironment(), ...(codexHome ? { CODEX_HOME: codexHome } : {}) }, stdio: ['pipe', 'pipe', 'ignore'] })
   const lines = createInterface({ input: child.stdout })
   let done = false
+  let config: unknown = {}
   const finish = (config: Record<string, unknown> = {}) => {
     if (done) return
     done = true
@@ -37,10 +54,12 @@ export const codexDefaults = (cwd: string): Promise<Record<string, unknown>> =>
         send({ method: 'initialized', params: {} })
         send({ id: 1, method: 'config/read', params: { includeLayers: false, cwd } })
       } else if (message.id === 1) {
-        const config = record(message.result?.config)
-        const managed = record(record(config.models).new_thread)
-        finish({ model: managed.model ?? config.model,
-          effort: managed.model_reasoning_effort ?? config.model_reasoning_effort })
+        config = message.result?.config
+        const resolved = resolvedCodexDefaults(config, [])
+        if (!nativeFallback || (resolved.model && resolved.effort)) finish(resolved)
+        else send({ id: 2, method: 'model/list', params: { limit: 100, includeHidden: false } })
+      } else if (message.id === 2) {
+        finish(resolvedCodexDefaults(config, message.result?.data))
       }
     } catch { finish() }
   })
@@ -56,7 +75,7 @@ export const grokSettings = (text: string): { model?: string; effort?: string }
 }
 
 export const discoverDefaults = async (cwd: string, options: {
-  home?: string; available?: typeof installed; run?: typeof command; codex?: typeof codexDefaults
+  home?: string; codexHome?: string; nativeCodexFallback?: boolean; available?: typeof installed; run?: typeof command; codex?: typeof codexDefaults
 } = {}): Promise<AiPreset[]> => {
   const home = options.home ?? homedir()
   const available = options.available ?? installed
@@ -73,7 +92,7 @@ export const discoverDefaults = async (cwd: string, options: {
         model = settings.model ?? value((await run(cli, ['models'], cwd)).match(/^Default model:\s*(\S+)/m)?.[1])
         effort = settings.effort
       } else if (cli === 'codex') {
-        const config = await (options.codex ?? codexDefaults)(cwd)
+        const config = await (options.codex ?? codexDefaults)(cwd, options.codexHome, options.nativeCodexFallback)
         model = value(config.model); effort = value(config.effort)
       } else if (cli === 'claude') {
         // Match Claude's documented user -> project -> local settings precedence.
@@ -91,11 +110,8 @@ export const discoverDefaults = async (cwd: string, options: {
   }))
   const discovered = results.filter((p): p is AiPreset => Boolean(p))
   if (await available('codex-gui')) {
-    const source = discovered.find((preset) => preset.cli === 'codex')
-    const model = source?.model, effort = source?.effort
-    const id = 'detected_' + createHash('sha256').update(JSON.stringify(['codex-gui', model, effort])).digest('hex').slice(0, 12)
-    discovered.push({ id, cli: 'codex-gui', model, effort,
-      name: `codex-gui · ${model || 'desktop'}${effort ? ` · ${effort}` : ''}`.slice(0, 80) })
+    const id = 'detected_' + createHash('sha256').update('codex-gui').digest('hex').slice(0, 12)
+    discovered.push({ id, cli: 'codex-gui', name: 'codex-gui · desktop' })
   }
   return discovered
 }

package/src/codex-session.ts

@@ -0,0 +1,98 @@
+import { executionDefaults } from './model-policy.js'
+import { spawn, type ChildProcess } from 'node:child_process'
+import { createInterface } from 'node:readline'
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import { terminateJob } from './executor.js'
+
+type Options = {workspace:string;controlDir:string;toolsHome?:string;sharedWorkspace?:string;model?:string;effort?:string;prompt:string;goal:boolean}
+type Message = {id?:number;method?:string;params?:any;result?:any;error?:{message:string;code?:number}}
+
+// Keep Codex's native session alive. Codex itself starts goal continuation turns;
+// this transport never generates a continuation prompt or an Ez goal record.
+export async function runCodexSession(options:Options, io:{launch?:()=>ChildProcess;emit?:(line:string)=>void}={}):Promise<number> {
+  options = executionDefaults('codex', options)
+  const child=io.launch?.() ?? spawn('codex',['app-server','--stdio','--disable','memories','--enable','skip_host_skill_discovery'],{cwd:options.workspace,env:process.env,stdio:['pipe','pipe','pipe']})
+  const emit=io.emit ?? (line=>process.stdout.write(line+'\n'))
+  let id=0,threadId:string|undefined,activeTurn:string|undefined,finished=false,sawTurn=false,hadGoal=options.goal
+  let resolveDone!:(code:number)=>void
+  const done=new Promise<number>(resolve=>{resolveDone=resolve})
+  const pending=new Map<number,{resolve:(value:any)=>void;reject:(error:Error)=>void;timer:ReturnType<typeof setTimeout>}>()
+  const finish=(code:number)=>{if(!finished){finished=true;resolveDone(code)}}
+  const fail=(error:unknown)=>{console.error('Codex native session failed:',error instanceof Error?error.message:String(error));finish(1)}
+  const send=(message:Message)=>child.stdin!.write(JSON.stringify(message)+'\n')
+  const request=(method:string,params:unknown):Promise<any>=>new Promise((resolve,reject)=>{
+    const next=++id
+    const timer=setTimeout(()=>{pending.delete(next);reject(new Error(`Codex request timed out: ${method}`))},30000)
+    pending.set(next,{resolve,reject,timer});send({id:next,method,params})
+  })
+  const settled=(goal:any)=>{
+    if(goal)hadGoal=true
+    if(activeTurn || goal?.status==='active')return
+    if(goal && goal.status!=='complete'){console.error(`Native goal stopped: ${goal.status}`);finish(1);return}
+    if(!goal && hadGoal){fail(new Error('Native goal disappeared without verified completion'));return}
+    if(!sawTurn)return
+    finish(0)
+  }
+  child.stderr?.pipe(process.stderr)
+  child.on('error',fail)
+  child.stdin?.on('error',fail)
+  child.once('close',()=>{
+    for(const p of pending.values()){clearTimeout(p.timer);p.reject(new Error('Codex app-server closed'))}
+    pending.clear();if(!finished)fail(new Error('Codex app-server closed before work completed'))
+  })
+  const lines=createInterface({input:child.stdout!})
+  lines.on('line',line=>{
+    let message:Message
+    try{message=JSON.parse(line)}catch{fail(new Error('Invalid Codex app-server response'));return}
+    if(message.id!==undefined && pending.has(message.id) && !message.method){
+      const p=pending.get(message.id)!;pending.delete(message.id);clearTimeout(p.timer)
+      if(message.error)p.reject(new Error(message.error.message));else p.resolve(message.result)
+      return
+    }
+    if(message.id!==undefined && message.method){
+      // Never turn an unexpected approval/elicitation request into permission.
+      send({id:message.id,error:{code:-32601,message:`Unsupported unattended request: ${message.method}`}});fail(new Error(`Codex requires attention: ${message.method}`));return
+    }
+    if(message.params?.threadId!==threadId)return
+    if(message.method==='turn/started'){activeTurn=message.params.turn.id;sawTurn=true}
+    if(message.method==='thread/goal/updated')settled(message.params.goal)
+    if(message.method==='thread/goal/cleared')settled(null)
+    if(message.method==='turn/completed'){
+      if(activeTurn===message.params.turn.id)activeTurn=undefined
+      if(message.params.turn.status!=='completed'){finish(message.params.turn.status==='interrupted'?130:1);return}
+      // Completion of a turn is not completion of a native goal. The native
+      // app-server remains running and owns any automatic next turn.
+      void request('thread/goal/get',{threadId}).then(result=>settled(result.goal)).catch(fail)
+    }
+  })
+  try{
+    await request('initialize',{clientInfo:{name:'ezenciel-agents',version:'1'},capabilities:{experimentalApi:true}})
+    send({method:'initialized',params:{}})
+    const result=await request('thread/start',{
+      cwd:options.workspace,approvalPolicy:'never',sandbox:'workspace-write',model:options.model,
+      config:{'sandbox_workspace_write.writable_roots':[options.controlDir,...(options.toolsHome?[options.toolsHome]:[]),...(options.sharedWorkspace?[options.sharedWorkspace]:[])],
+        'sandbox_workspace_write.network_access':Boolean(options.toolsHome),...(options.effort?{model_reasoning_effort:options.effort}:{})},
+    })
+    threadId=result.thread?.id
+    if(!threadId)throw new Error('Codex did not return a native thread ID')
+    emit(JSON.stringify({type:'thread.started',thread_id:threadId}))
+    if(options.goal){
+      // This is the native request used by the interactive /goal command.
+      // Setting it active starts work in Codex; do not also send turn/start.
+      const result=await request('thread/goal/set',{threadId,objective:options.prompt,status:'active'})
+      if(result.goal)settled(result.goal)
+    }else await request('turn/start',{threadId,input:[{type:'text',text:options.prompt}],model:options.model,effort:options.effort})
+    return await done
+  }catch(error){fail(error);return 1}
+  finally{
+    finished=true
+    for(const p of pending.values()){clearTimeout(p.timer);p.reject(new Error('Codex session closed'))}
+    pending.clear();lines.close();child.stdin?.end();terminateJob(child)
+  }
+}
+
+if(process.argv[1] && path.resolve(process.argv[1])===fileURLToPath(import.meta.url)){
+  let input='';for await(const chunk of process.stdin)input+=chunk
+  process.exitCode=await runCodexSession(JSON.parse(input))
+}