@jc_stack/ez-agents 0.1.0-beta.12

package/docs/upgrades.md

@@ -0,0 +1,193 @@
+# Agent-owned software upgrades
+
+Available in this beta. Earlier main upgrade/rollback VM QA passed; final-release
+fresh-host/reboot and live plugin upgrade acceptance remain pending. npm
+publication is not required to test this feature. Stable releases are the default
+automatic channel. The existing owner may select beta or manual policy per target.
+The main target and installed plugins version independently.
+
+The agent owns release review, policy decisions and communication. The host
+supervisor owns interruption-safe replacement. There is one host service per
+agent, not a second agent or an additional updater daemon. Its replaceable child
+runs the normal CLI transport. It checks npm every six hours while running and
+queues an owner-bound maintenance turn only when an automatic channel changes.
+No owner means no maintenance executor. Normal user work and maintenance share
+one serial queue. Checks use the installed scoped npm identity; failures are
+visible in `updates check` and private `tools/updates/available.json`.
+
+## Installation and scope
+
+Use normal setup and initialize the registry with this deployment's
+`host-executor.json`. This binds `ez updates`, the active package root and the
+Software updates guidance in TOOLS.md. Start `ezenciel-agents-host` using the
+normal OS service template. The host service must use the existing user's Node,
+pnpm (or Corepack) and Docker access. Never put tokens in its environment. Keep the original
+package directory: its small bootstrap remains the service entry point and loads
+the active supervisor on each restart. It must not be moved or garbage-collected.
+
+Older beta installations have no supervisor or release contract. Their initial
+migration to this candidate is installer-owned: stop the old host/relay, install
+and build this candidate, retain the deployment, and use its tools entry point:
+
+```sh
+node /absolute/candidate/package/bin/ezenciel-agents-tools.mjs enable-updates \
+  --home /absolute/deployment/tools \
+  --host-config /absolute/deployment/host-executor.json
+```
+
+Point the host service and relay Compose source/image at the candidate, then
+restart and verify. Do not recreate the agent or its registry. Subsequent
+compatible upgrades are agent-owned. Noncanonical/multi-agent host configuration
+files require migration to one canonical deployment per service first.
+
+## Package-manager preflight and repair
+
+Before installing candidate dependencies or stopping services, the supervisor
+checks `pnpm --version` in its own service environment. It requires the exact
+`packageManager` version declared by the candidate. If that launcher is missing,
+broken or reports another version, it tries `corepack pnpm@<exact-version>`
+directly and verifies the result. Corepack may download/cache that pinned version;
+it does not need a global pnpm shim. The selected command/version is in the job
+receipt. Both routes retain `--frozen-lockfile --ignore-scripts`.
+
+If neither route works, the job fails before dependency installation or service
+replacement, with both errors and repair guidance. The agent should inspect the
+host service's PATH and existing launchers first, including the Node installation
+and any known pnpm installation directory. Reuse them; do not install a second
+manager just because the interactive shell sees a different PATH. If provisioning
+is actually necessary, install the pinned pnpm version using an available package
+manager (npm can provision pnpm). Do not run `npm install` on the Ez candidate:
+that would replace the pnpm lockfile contract. Do not source arbitrary shell
+profiles or copy secrets into the service environment.
+
+For an existing beta.3 supervisor reporting `spawn pnpm ENOENT`, a newer candidate
+cannot repair the updater that must install it. The VM agent must first expose a
+real pnpm launcher in that supervisor's PATH. With working Corepack it can use
+`corepack enable pnpm --install-directory /absolute/user-owned/bin` and include
+that directory in the service PATH. Verify the pinned version under the same user,
+PATH and working directory as the service. Schedule any needed service restart
+after the requesting turn ends, then verify its fresh heartbeat and Telegram reply.
+Keep the deployment, accounts, images and job receipts intact.
+
+Read `ez updates status` after repair. For `failed` or `rolled-back`, prepare the
+same candidate again and apply the new job; do not edit the old receipt. Only
+`recovery-required` uses `ez updates recover <job-id>` to restore the prior runtime.
+Finish the requesting turn after queuing either operation. Verify the main relay
+before requesting a separate plugin upgrade.
+
+## Agent interface
+
+Telegram `/status` shows the relay's loaded version, fresh host version and
+installed plugin versions alongside work/queue health. The host heartbeat carries
+only plugin IDs/versions; the relay gets no plugin registry or Docker access.
+Plugin versions in Telegram are explicitly installed versions, not live-provider
+verification. Stale or legacy host metadata is shown as unavailable/unknown.
+
+Use `ez status` (also `ez updates status`) for `{main, plugins, jobs}`. Status now
+returns an object; the previous bare job array is under `jobs`. It is read-only
+and does not contact npm, start services or require an upgrade job to exist.
+
+`main.installedVersion` comes from the active package binding. `runningVersion`
+comes from a fresh polling heartbeat written by the running relay; `main.host`
+reports the host transport separately. Versions are captured when each process
+loads, so an older running process is not relabeled by a newer installation.
+Old releases without heartbeat versions, stale/offline services and unreadable
+evidence report `runningVersion: null`; never infer a running version from the
+installed version alone.
+
+Each plugin includes `installedVersion`, runtime state and service health.
+`runningVersion` is the registered plugin version only when all declared services
+are running with image IDs matching the registered deployment's expected images.
+This is deployment-image evidence, not a provider account/delivery check. Stopped,
+partial or mismatched deployments report a null running version; Docker failures
+report unknown while keeping installed versions visible. Plugins need not be Node
+packages inside their containers: status does not execute commands inside them.
+`ez plugins status <id>` also includes its registered `installedVersion`.
+
+Check both installed and running versions after an upgrade before reporting it as
+live. A healthy container alone does not prove a Telegram or plugin reply.
+
+```sh
+ez updates check
+ez updates policy main                 # defaults: automatic, stable
+ez updates policy whatsapp beta        # only under owner authorization
+ez updates policy main manual          # disable unattended upgrades
+ez updates prepare main --version 0.1.0-beta.4
+# Or a local candidate, independently of npm:
+ez updates prepare whatsapp --file /absolute/candidates/whatsapp.tgz
+ez updates apply <returned-job-id>       # explicit owner-requested candidate
+# Automatic registry release within saved policy:
+ez updates apply <returned-job-id> --automatic
+ez updates status
+```
+
+Examples are candidate version placeholders, not a claim of published versions.
+`prepare` downloads from npm or reads a local tarball, checks integrity, rejects
+unsafe archive entries, and records identity/version/hash. It does not stop a
+service. Local candidates never qualify for `--automatic`; an explicit request
+is required. Stable automation excludes prereleases, major changes and 0.x minor
+changes. Beta policy permits compatible prereleases. Downgrades are rejected;
+rollback is a recovery operation for the previous installation only.
+
+`apply` records one durable queued job. **The agent must finish its turn after
+queuing it.** It must not wait for completion in that same turn. The supervisor
+pauses new run admission, drains already-started work, then consumes the job.
+One job at a time; an unresolved recovery blocks new upgrades. The agent processes
+multiple requested packages over successive maintenance turns.
+
+The exact archive is reverified and re-extracted before execution; editing a
+prepared tree cannot substitute code. Main dependencies install with the frozen
+lock and lifecycle scripts disabled. Images build before services stop. The host
+pins the previous relay image, saves a private backup and replaces the runtime
+and host child. Plugin replacements use the registry lock and canonical project
+and volumes. Running plugins restart with a health check; stopped plugins stay
+stopped and report `runtimeVerified:false`. Upgrading never links an account.
+
+## Recovery and limits
+
+Job receipts live privately under `tools/updates/<job-id>/`. `status` omits private
+rollback configuration. States are prepared, queued, applying, completed, failed,
+rolled-back and recovery-required. A service restart recovers an interrupted
+applying job before resuming normal work. A failed build leaves the old runtime
+running. Failed activation restores the previous code/configuration and checks it.
+If recovery itself fails, inspect and fix the reported infrastructure problem,
+then use `ez updates recover <job-id>` and finish the turn. This retries only the
+saved code/configuration recovery, not provider operations.
+Completion or failure wakes the agent to inspect the receipt and report naturally.
+
+Backups contain credentials and must stay private. Main backups cover the
+canonical mind/control and deployment files. Plugins back up existing named
+volumes while their services are stopped, using the previous image's `tar` and
+read-only volume mounts; archive output is written by the host with mode 0600.
+No backup deletes live data or revokes credentials. Retain old package roots and
+images until QA and any recovery window are complete; there is no automatic GC.
+
+The updater accepts only matching state-schema and protocol contracts and an
+unchanged deployment layout. Changes to privileges, services, volumes or Compose
+configuration fail before replacement, even for an explicit candidate. These
+need a separately reviewed migration, not an override flag. Release authors must
+truthfully declare schema compatibility. Code rollback **does not rewind private
+state**, provider cursors or operation receipts; uncertain actions are never
+replayed. Docker health is not proof of live provider identity or delivery.
+
+## Contributor acceptance
+
+Every main/plugin release must declare `package.json.ezRelease`:
+
+```json
+{"protocol":1,"kind":"plugin","stateSchema":1,"mainProtocol":1}
+```
+
+Use `kind: "main"` for the main package. `stateSchema` is the compatibility epoch
+for persisted state: keep it only when the previous release can safely read state
+written by the new one. Increment it for incompatible writes; this updater will
+refuse that migration. `mainProtocol` identifies the supported updater/registry
+contract, currently 1. Plugin package and manifest versions must match.
+
+Verify upgrade from the previous supported artifact, retained identity/state,
+failed-health rollback, and rejection of incompatible candidates. Main runtime
+changes also need supervisor restart and requesting-process-exit tests. Run
+`pnpm verify`, `npm run release:check`, packed Docker builds and
+`node docker/upgrade-smoke.mjs` with a local `EZ_WHATSAPP_SOURCE` containing the
+WhatsApp fixture. The smoke uses synthetic transport only. VM installation,
+agent-led upgrades, restart and real account acceptance remain separate QA gates.

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@jc_stack/ez-agents",
+  "version": "0.1.0-beta.12",
+  "private": false,
+  "type": "module",
+  "description": "A minimal Telegram-to-CLI executor relay.",
+  "packageManager": "pnpm@10.30.3",
+  "bin": {
+    "ezenciel-agents-install": "bin/ezenciel-agents-install",
+    "ezenciel-agents": "bin/ezenciel-agents.mjs",
+    "ezenciel-agents-owner": "bin/ezenciel-agents-owner.mjs",
+    "ezenciel-agents-message": "bin/ezenciel-agents-message.mjs",
+    "ezenciel-agents-react": "bin/ezenciel-agents-react.mjs",
+    "ezenciel-agents-approval": "bin/ezenciel-agents-approval.mjs",
+    "ezenciel-agents-setup": "bin/ezenciel-agents-setup.mjs",
+    "ezenciel-agents-source": "bin/ezenciel-agents-source.mjs",
+    "ezenciel-agents-docker": "bin/ezenciel-agents-docker",
+    "ezenciel-agents-create": "bin/ezenciel-agents-create",
+    "ezenciel-agents-host": "bin/ezenciel-agents-host",
+    "ezenciel-agents-tools": "bin/ezenciel-agents-tools.mjs",
+    "ezenciel-agents-ai": "bin/ezenciel-agents-ai.mjs"
+  },
+  "files": [
+    "default-plugins.json",
+    "bin",
+    "src",
+    "docs",
+    "templates",
+    ".env.example",
+    "AGENTS.md",
+    "README.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "Dockerfile",
+    "compose.yaml",
+    "docker",
+    "compose.whatsapp.yaml",
+    "scripts/smoke.ts",
+    "LICENSE",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
+    "scripts/release-check.mjs",
+    "test",
+    "tsconfig.json",
+    "scripts/assert-local-registry.mjs",
+    ".dockerignore"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "scripts": {
+    "setup": "tsx --env-file-if-exists=.env src/setup.ts",
+    "dev": "EZ_DEVELOPMENT=1 tsx watch --clear-screen=false --exclude 'agent/**' --exclude 'test/**' --env-file=.env src/index.ts",
+    "start": "./bin/ezenciel-agents-docker up -d --wait relay",
+    "owner": "tsx --env-file=.env src/owner.ts",
+    "message": "tsx src/message.ts",
+    "react": "tsx src/react.ts",
+    "build": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts test/*.test.mjs",
+    "verify": "pnpm test && pnpm build",
+    "smoke": "./bin/ezenciel-agents-docker run --rm --no-deps relay smoke",
+    "prepublishOnly": "npm run verify",
+    "registry:up": "docker compose -f registry/docker-compose.yml up -d",
+    "registry:down": "docker compose -f registry/docker-compose.yml down",
+    "publish:local": "node scripts/publish-local.mjs",
+    "publish:watch": "node scripts/publish-local.mjs --watch",
+    "smoke:docker": "node docker/smoke.mjs",
+    "host:executor": "tsx src/host-executor.ts",
+    "smoke:plugins": "node docker/plugin-smoke.mjs",
+    "release:check": "node scripts/release-check.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "grammy": "^1.39.3",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "keywords": [
+    "ai-agent",
+    "cli",
+    "docker",
+    "telegram",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jdorado/ez-agents.git"
+  },
+  "homepage": "https://github.com/jdorado/ez-agents#readme",
+  "bugs": {
+    "url": "https://github.com/jdorado/ez-agents/issues"
+  },
+  "ezRelease": {
+    "protocol": 1,
+    "kind": "main",
+    "stateSchema": 1,
+    "mainProtocol": 1
+  }
+}

package/scripts/assert-local-registry.mjs

@@ -0,0 +1,22 @@
+const registry = process.env.npm_config_registry || process.env.NPM_CONFIG_REGISTRY || ''
+const allowed = process.env.EZ_LOCAL_REGISTRY || 'http://127.0.0.1:4873/'
+
+const allowedHosts = new Set(['127.0.0.1:4873', 'localhost:4873'])
+try {
+  allowedHosts.add(new URL(allowed).host)
+} catch {
+  throw new Error(`EZ_LOCAL_REGISTRY is not a URL: ${allowed}`)
+}
+
+let host = ''
+try {
+  host = new URL(registry).host
+} catch {
+  host = ''
+}
+
+if (!host || !allowedHosts.has(host)) {
+  throw new Error(
+    `Refusing to publish outside the local ez registry. Received ${registry || '(no registry)'}. Use pnpm publish:local.`,
+  )
+}

package/scripts/release-check.mjs

@@ -0,0 +1,14 @@
+// Read-only package boundary check; no credentials or provider access.
+import {execFileSync} from 'node:child_process';
+import {readFileSync} from 'node:fs';
+import assert from 'node:assert/strict';
+assert.equal(readFileSync('docker/pnpm-lock.yaml','utf8'),readFileSync('pnpm-lock.yaml','utf8'),'Refresh docker/pnpm-lock.yaml after dependency changes');
+const p=JSON.parse(readFileSync('package.json','utf8'));
+const [pack]=JSON.parse(execFileSync('npm',['pack','--dry-run','--ignore-scripts','--json'],{encoding:'utf8'}));
+const names=pack.files.map(f=>f.path);
+for(const required of ['LICENSE','README.md','SECURITY.md','CONTRIBUTING.md','CHANGELOG.md','THIRD_PARTY_NOTICES.md','Dockerfile','.dockerignore','docker/pnpm-lock.yaml']) assert(names.includes(required),`Missing ${required}`);
+for(const name of names) assert(!/^agent\//.test(name) && !/(^|\/)(node_modules|\.git|\.private|todo\.md|principles\.md|backlog\.md|sprints\.md)(\/|$)|(^|\/)\.env$|\.(tgz|log)$|(^|\/)(qa|plugin-manager-qa|spec-benchmark)\.md$/.test(name),`Private/internal package entry: ${name}`);
+for(const entry of p.files) assert(names.some(name=>name===entry || name.startsWith(entry+'/')),`Declared package entry missing: ${entry}`);
+for(const bin of Object.values(p.bin||{})) assert(names.includes(bin),`Missing binary ${bin}`);
+if(names.includes('ez-plugin.json')) assert.equal(JSON.parse(readFileSync('ez-plugin.json')).version,p.version);
+console.log(JSON.stringify({name:p.name,version:p.version,files:names,unpackedSize:pack.unpackedSize},null,2));

package/scripts/smoke.ts

@@ -0,0 +1,102 @@
+import { dirname, join } from 'node:path'
+import { readdir, readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { randomUUID } from 'node:crypto'
+import { loadConfig } from '../src/config.js'
+import { ControlStore } from '../src/control-state.js'
+import { startExecutorJob, terminateJob } from '../src/executor.js'
+import { RunStore } from '../src/runs.js'
+import { createRelay } from '../src/index.js'
+
+// Outbound integration test, not proof of Telegram intake or UI interactions.
+// Run while the polling relay is stopped; the owner must already be paired.
+async function main() {
+  const config = loadConfig()
+  let prompt = 'Smoke test: use the messaging tool to send exactly "Smoke test passed ✅".'
+  let resume = false
+  const args = process.argv.slice(2).filter((arg) => arg !== '--')
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--resume') resume = true
+    else if (args[i] === '--cli' && args[i + 1]) config.executorCli = args[++i]
+    else if (args[i] === '--prompt' && args[i + 1]) prompt = args[++i]
+    else throw new Error('Usage: pnpm smoke [--cli grok] [--resume] [--prompt "..."]')
+  }
+  const relay = createRelay(config)
+  await relay.bot.api.getMe()
+  const state = await new ControlStore(config.controlDir, config.pairingTtlMs).status()
+  const owner = state.owner
+  const choice = state.ai?.presets.find(p => p.id === state.ai!.selectedId && p.cli === config.executorCli)
+  const session = resume ? state.activeSession : undefined
+  if (resume && (!session?.hasStarted || session.cli !== config.executorCli))
+    throw new Error('Resume smoke requires an existing started session for the selected CLI')
+  if (!owner) throw new Error('Pair an owner before running smoke')
+  const runs = new RunStore(config.controlDir)
+  if ((await runs.running()) || (await runs.nextQueued()))
+    throw new Error('Stop the relay and finish queued work before smoke')
+  const run = await runs.create({
+    chatId: owner.telegramChatId,
+    telegramUserId: owner.telegramUserId,
+    texts: [prompt],
+  })
+  await runs.patch(run.id, { status: 'running', startedAt: new Date().toISOString() })
+  const job = await startExecutorJob(run.texts, {
+    workspace: config.workspace,
+    timeoutMs: config.executorTimeoutMs,
+    runId: run.id,
+    controlDir: config.controlDir,
+    binDir: join(dirname(fileURLToPath(import.meta.url)), '..', 'bin'),
+    cli: config.executorCli,
+    model: choice?.model,
+    effort: choice?.effort,
+    sessionId: session?.nativeSessionId ?? session?.sessionId ?? randomUUID(),
+    isResume: resume,
+  }).catch(async (error) => {
+    await runs.patch(run.id, { status: 'failed', endedAt: new Date().toISOString() })
+    throw error
+  })
+  const stop = () => terminateJob(job.child)
+  process.once('SIGINT', stop)
+  process.once('SIGTERM', stop)
+  const finished = new Promise<number>((resolve) => job.child.once('close', (code) => resolve(code ?? 1)))
+  let drain: Promise<void> = Promise.resolve()
+  const timer = setInterval(() => {
+    drain = drain.then(() => relay.drainOutbox(run.id))
+  }, 500)
+  try {
+    await runs.patch(run.id, { pid: job.child.pid })
+    const code = await finished
+    clearInterval(timer)
+    await drain
+    await relay.drainOutbox(run.id)
+    await runs.patch(run.id, {
+      status: code === 0 ? 'completed' : 'failed',
+      endedAt: new Date().toISOString(),
+    })
+    const names = (await readdir(join(config.controlDir, 'outbox'))).filter((name) =>
+      name.startsWith(run.id + '_'),
+    )
+    const receipts = []
+    for (const name of names.filter((name) => name.endsWith('.sent.json'))) {
+      const item = JSON.parse(await readFile(join(config.controlDir, 'outbox', name), 'utf8'))
+      if (item.receipt) receipts.push(item.receipt)
+    }
+    console.log(
+      JSON.stringify({ runId: run.id, executor: config.executorCli, model: choice?.model, effort: choice?.effort, exitCode: code, receipts }, null, 2),
+    )
+    if (code !== 0 || !receipts.length || names.some((name) => !name.endsWith('.sent.json'))) {
+      throw new Error('Smoke failed: executor failure, missing receipt, or undelivered outbox item')
+    }
+    console.log('Outbound smoke passed. Telegram intake and button/media UI still require a live chat test.')
+  } finally {
+    clearInterval(timer)
+    process.removeListener('SIGINT', stop)
+    process.removeListener('SIGTERM', stop)
+    await job.cleanup()
+    await relay.stop()
+  }
+}
+
+main().catch((error) => {
+  console.error(error.message)
+  process.exitCode = 1
+})

package/src/agent-install.ts

@@ -0,0 +1,96 @@
+import { mkdir, readFile, writeFile, rm, readdir } from 'node:fs/promises'
+import { isAbsolute, join, resolve, dirname } from 'node:path'
+import { parseArgs } from 'node:util'
+import { executorKey } from './executor.js'
+import { fileURLToPath } from 'node:url'
+
+// Recorded by the installing CLI once; agent creation inherits this binding.
+export const installationCli = async (root: string, installerCli?: string): Promise<string> => {
+  const file = join(root, 'installation.json')
+  let saved: string | undefined
+  try {
+    const value = JSON.parse(await readFile(file, 'utf8')).cli
+    if (typeof value !== 'string' || !value.trim()) throw new Error('Installation CLI record is invalid')
+    saved = executorKey(value)
+  }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+  const requested = installerCli?.trim() ? executorKey(installerCli) : undefined
+  if (saved) {
+    if (requested && requested !== saved) throw new Error('Use the CLI already selected for this host installation')
+    return saved
+  }
+  if (!requested) throw new Error('The installing agent must record its CLI during package installation; no default is guessed.')
+  await mkdir(root, {recursive:true, mode:0o700})
+  try { await writeFile(file, JSON.stringify({cli:requested})+'\n', {mode:0o600,flag:'wx'}) }
+  catch(error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+    return installationCli(root, requested)
+  }
+  return requested
+}
+
+export const createAgent = async (options: {
+  root: string; hostRoot: string; composeFile: string; name: string; purpose: string; token: string; cli?: string; image?: string
+}) => {
+  const { root, hostRoot, composeFile, name, purpose, token } = options
+  if (!/^[a-z][a-z0-9-]{0,39}$/.test(name)) throw new Error('Use an agent name of 1–40 lowercase letters, digits or hyphens, starting with a letter.')
+  if (![root, hostRoot, composeFile].every(p => isAbsolute(p) && !/[\r\n\0']/.test(p)))
+    throw new Error('Installation paths must be absolute and contain no newline or single quote.')
+  if (!purpose.trim() || purpose.length > 12000) throw new Error('Supply a purpose of 1–12000 characters.')
+  if (!/^\d{5,}:[A-Za-z0-9_-]{20,}$/.test(token)) throw new Error('Supply the BotFather token through stdin.')
+  const image=options.image||'ezenciel-agents:local'
+  if(!/^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,255}$/.test(image))throw new Error('Invalid relay image reference')
+  await mkdir(root, {recursive:true, mode:0o700})
+  const cli = await installationCli(root, options.cli)
+  const directory = join(root, name), deploymentDir = join(hostRoot, name)
+  // Exclusive directory creation: a repeated name never overwrites another agent.
+  await mkdir(directory, {mode:0o700})
+  try {
+    const project = `ez-agent-${name}`
+    const values = {
+      COMPOSE_PROJECT_NAME: project,
+      COMPOSE_FILE: composeFile,
+      EZ_RELAY_IMAGE: image,
+      EZ_RELAY_ENV_FILE: join(deploymentDir, 'relay.env'),
+      EZ_AGENT_PURPOSE_FILE: join(deploymentDir, 'purpose.md'),
+      EZ_EXECUTOR_CLI: cli,
+      EZ_AGENT_WORKSPACE: join(deploymentDir, 'mind'),
+      EZ_CONTROL_DIR: join(deploymentDir, 'control'),
+      EZ_WHATSAPP_IPC_VOLUME: `${project}-whatsapp-ipc`,
+      EZ_WHATSAPP_CLIENT_VOLUME: `${project}-whatsapp-client`,
+    }
+    await writeFile(join(directory, 'docker.env'), Object.entries(values).map(([k,v]) => `${k}='${v}'\n`).join(''), {mode:0o600, flag:'wx'})
+    await writeFile(join(directory, 'relay.env'), `TELEGRAM_BOT_TOKEN=${token}\n`, {mode:0o600, flag:'wx'})
+    await writeFile(join(directory, 'purpose.md'), purpose.trim()+'\n', {mode:0o644, flag:'wx'})
+    await mkdir(join(directory,'mind'),{mode:0o700})
+    await mkdir(join(directory,'control'),{mode:0o700})
+    const agent = {name, project, deploymentDir, purpose:purpose.trim(), executor:cli}
+    const host = {cli,agents:[{name,workspace:join(deploymentDir,'mind'),controlDir:join(deploymentDir,'control'),binDir:join(dirname(composeFile),'bin')}]}
+    await writeFile(join(directory,'host-executor.json'),JSON.stringify(host,null,2)+'\n',{mode:0o600,flag:'wx'})
+    await writeFile(join(directory, 'agent.json'), JSON.stringify(agent,null,2)+'\n', {mode:0o600, flag:'wx'})
+    return agent
+  } catch (error) { await rm(directory, {recursive:true, force:true}); throw error }
+}
+
+export const listAgents = async (root: string) => {
+  const agents = []
+  for (const entry of await readdir(root, {withFileTypes:true})) {
+    if (!entry.isDirectory()) continue
+    try { agents.push(JSON.parse(await readFile(join(root,entry.name,'agent.json'),'utf8'))) }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+  }
+  return agents
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const {values:v} = parseArgs({options:{name:{type:'string'},purpose:{type:'string'},'host-root':{type:'string'},'compose-file':{type:'string'},'relay-image':{type:'string'},list:{type:'boolean'},cli:{type:'string'},'register-cli':{type:'string'}}})
+    if (v['register-cli']) console.log(JSON.stringify({cli:await installationCli('/installations',v['register-cli'])}))
+    else if (v.list) console.log(JSON.stringify(await listAgents('/installations')))
+    else {
+      let token=''
+      for await (const chunk of process.stdin) { token+=chunk; if(token.length>512) throw new Error('Token input is too long.') }
+      console.log(JSON.stringify(await createAgent({root:'/installations',hostRoot:v['host-root']||'',composeFile:v['compose-file']||'',name:v.name||'',purpose:v.purpose||'',token:token.trim(),cli:v.cli||'',image:v['relay-image']})))
+    }
+  } catch (error) { console.error((error as Error).message); process.exitCode=1 }
+}

package/src/ai-cli.ts

@@ -0,0 +1,22 @@
+import { parseArgs } from 'node:util'
+import { randomBytes } from 'node:crypto'
+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()
+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}
+  await validateSelection(preset,catalog)
+  const control=new ControlStore(process.env.EZ_CONTROL_DIR,900000)
+  const state=await control.status()
+  if(!state.ai)throw new Error('Agent AI settings are not initialized')
+  const existing=state.ai.presets.find(p=>p.cli===preset.cli&&p.model===preset.model&&p.effort===preset.effort)
+  const selected=existing||preset
+  if(!existing)await control.savePreset(selected)
+  const current=state.ai.presets.find(p=>p.id===state.ai!.selectedId)!
+  await control.selectPreset(selected.id,state.activeSession?.sessionId??null,current.cli!==selected.cli||Boolean(state.activeSession&&!state.activeSession.cli))
+  console.log(JSON.stringify({selected,defaultUnchanged:true,applies:'subsequent messages; queued work keeps its captured choice'}))
+}else throw new Error('Use list or select --cli <installed-cli> [--model <model>] [--effort <effort>]')

package/src/ai.ts

@@ -0,0 +1,88 @@
+import { access, readFile } from 'node:fs/promises'
+import { constants } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, delimiter } from 'node:path'
+import { executorKey, resolveExecutor } from './executor.js'
+import { desktopCodexPath } from './desktop-bridge.js'
+
+export type AiPreset = { id: string; name: string; cli: string; model?: string; effort?: string }
+export type ExecutionChoice = { sessionId: string; preset: AiPreset }
+export type ModelChoice = { cli: string; model?: string; name: string; efforts: string[] }
+const safe = (s: unknown): s is string => typeof s === 'string' && /^[a-zA-Z0-9_./:-]{1,160}$/.test(s)
+export const isPreset = (p: unknown): p is AiPreset => {
+  if (!p || typeof p !== 'object') return false
+  const v = p as AiPreset
+  return safe(v.id) && typeof v.name === 'string' && v.name.length > 0 && v.name.length <= 80 &&
+    ['grok', 'codex', 'codex-gui', 'claude', 'opencode', 'agy'].includes(v.cli) &&
+    (v.model === undefined || safe(v.model)) && (v.effort === undefined || safe(v.effort))
+}
+export const isExecutionChoice = (v: unknown): v is ExecutionChoice => {
+  const c = v as ExecutionChoice | undefined
+  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'}`
+export const initialPreset = (cli: string): AiPreset => {
+  const key = executorKey(cli)
+  return {
+    id: 'initial', name: `${resolveExecutor(key).name} · current setup`, cli: key,
+    ...(key === 'opencode'
+      ? { model: process.env.OPENCODE_MODEL || 'opencode/nemotron-3.5-lightning-free' } : {}),
+  }
+}
+
+export const installed = async (cli: string): Promise<boolean> => {
+  if (cli === 'codex-gui') return Boolean(await desktopCodexPath())
+  for (const directory of (process.env.PATH || '').split(delimiter)) {
+    try { await access(join(directory, cli), constants.X_OK); return true } catch {}
+  }
+  return false
+}
+
+// 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[]> => {
+  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)
+  const json = async (file: string) => {
+    try { return record(JSON.parse(await readFile(join(home, file), 'utf8'))) } catch { return {} }
+  }
+  if (await available('grok')) {
+    const cache = await json('.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
+      models.push({ cli: 'grok', model: info.id, name: String(info.name || info.id).slice(0, 80),
+        efforts: efforts(info.reasoning_efforts, 'value') })
+    }
+  }
+  if (await available('codex')) {
+    const cache = await json('.codex/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
+      models.push({ cli: 'codex', model: info.slug, name: String(info.display_name || info.slug).slice(0, 80),
+        efforts: efforts(info.supported_reasoning_levels, 'effort') })
+    }
+  }
+  if (await available('codex-gui')) {
+    const desktop = models.filter((model) => model.cli === 'codex').map((model) => ({
+      ...model, cli: 'codex-gui', name: `codex-gui · ${model.name}`.slice(0, 80),
+    }))
+    models.push(...(desktop.length ? desktop : [{ cli: 'codex-gui', name: 'codex-gui · desktop', efforts: [] }]))
+  }
+  // Other adapters expose the authenticated client's default, not a guessed catalog.
+  for (const cli of ['claude', 'opencode', 'agy'])
+    if (await available(cli)) models.push({ cli, name: `${cli} · client default`, efforts: [] })
+  return models
+}
+
+export const validateSelection = async (p: AiPreset, catalog: ModelChoice[], available = installed): Promise<void> => {
+  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)
+  if (!model || (p.effort && !model.efforts.includes(p.effort)))
+    throw new Error('This model/effort is not in the installed client catalog. Refresh the client and try again; no fallback was selected.')
+}