@jc_stack/ez-agents 0.1.0-beta.33 → 0.1.0-beta.36

package/docs/upgrades.md

@@ -16,9 +16,9 @@ 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
+records automatic-channel changes; discovery never wakes the agent or injects
+wrapper state into a session. Updates stay owner-invoked through `ez updates`.
+Checks use the installed scoped npm identity; failures are
 visible in `updates check` and private `tools/updates/available.json`. Plugins marked
 `private: true` in their package metadata are reported as local-source updates
 only, without querying public npm; this does not mean they are up to date.
@@ -144,7 +144,7 @@ rollback is a recovery operation for the previous installation only.
 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.
+multiple requested packages over successive update requests.
 
 The exact archive is reverified and re-extracted before execution; editing a
 prepared tree cannot substitute code. Main dependencies install with the frozen
@@ -164,24 +164,43 @@ running. Failed activation restores the previous code/configuration and checks i
 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.
+An update never wakes the agent or injects wrapper state into its session; the
+owner or agent inspects receipts with `ez updates` when asked.
 
 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.
+No backup deletes live data or revokes credentials. After a successful update, the
+supervisor retains the newest completed backup per target and removes backup
+directories from older terminal receipts (`completed`, `failed` or
+`rolled-back`). Queued, applying and recovery-required jobs are never pruned. Old
+package roots and images remain available until they are no longer needed for the
+active or immediate rollback path; backup cleanup does not remove them. A cleanup
+failure is recorded on the completed receipt and does not turn a successful
+update into a rollback. The supervisor repeats this reconciliation at startup so
+a release restart also cleans backups left by a crash window or by the release
+that installed the policy.
 
 The updater accepts only matching state-schema and protocol contracts and an
-unchanged deployment layout. Plugins may add command routes to existing services;
-existing routes and all services, privileges, volumes and other deployment
-configuration must remain unchanged. Incompatible changes fail before replacement,
-even for an explicit candidate, and need a separately reviewed migration rather
-than 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.
+unchanged effective deployment layout. The reviewed beta.34 runtime migration
+allows the optional empty `EZ_ISOLATION` passthrough and a changed purpose-file
+fallback when the deployment already binds `EZ_AGENT_PURPOSE_FILE`; the job
+receipt records that migration. Plugins may add command routes to existing
+services; existing routes and all services, privileges, volumes and other
+deployment configuration must remain unchanged. Incompatible changes fail
+before replacement, even for an explicit candidate, and need a separately
+reviewed migration rather than 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.
+
+The updater also records the exact Library beta14 command migration: it removes
+the retired `library-document` route and changes `library-query` from
+`query-context` to `search`, while requiring every other manifest and deployment
+field to remain unchanged. A completed main upgrade exits the active supervisor
+after publishing its receipt; the retained bootstrap is then restarted by the
+host service and loads the new package root.
 
 ## Contributor acceptance
 
@@ -214,12 +233,16 @@ policy selects non-deprecated stable versions, even when latest is a prerelease.
 No eligible version is reported as available:null with newer:false. Older installed
 updaters need an exact-version core update to adopt this discovery behavior.
 
-## Shared agent guidance
+## Operating-agent instructions
 
-Setup and runtime startup install `templates/agent-guidance.md` into a marked
-section of the workspace's native `AGENTS.md` (and existing `AGENTS.override.md`).
-Upgrade refreshes only that section; personal content outside it is preserved
-byte-for-byte. New scheduled task workspaces receive the same shared guidance.
+Setup and the main upgrade step strip any obsolete `<!-- ez shared guidance -->`
+handbook from workspace `AGENTS.md` (and existing `AGENTS.override.md`).
+Personal text outside that block is preserved byte-for-byte. Do not reinsert
+coding, KISS, contribution or repair loops into operating minds.
+
+The package-owned locator is the managed `<!-- ez tools -->` block: the bound
+`ez` launcher, `ez --help`, and `ez tools list --details`. Inventory is
+generated on read. Plugin registry init and update binding refresh that locator.
 Malformed markers and symlinks fail visibly rather than overwriting personal work.
 
 Codex, agy, Grok and OpenCode discover workspace instructions natively. Claude
@@ -236,9 +259,9 @@ preserved. Restricted contact tasks retain their separate
 bounded instruction scopes. For delivered busy replies absent from the native
 conversation, the owner engine can call `ezenciel-agents-schedule context`.
 
-Keep general defaults in the shipped shared file and identity/preferences in
-workspace personal files. Instructions cannot grant permissions; explicit owner
-requests take precedence within existing execution authority.
+Keep identity and purpose in the agent's own `AGENTS.md`. Instructions cannot
+grant permissions; explicit owner requests take precedence within existing
+execution authority.
 
 Update discovery runs independently of active host work. A discovery failure is
 logged locally and retried at the next regular six-hour check; it does not stop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.33",
+  "version": "0.1.0-beta.36",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",
@@ -21,8 +21,9 @@
     "ezenciel-agents-host": "bin/ezenciel-agents-host",
     "ezenciel-agents-tools": "bin/ezenciel-agents-tools.mjs",
     "ezenciel-agents-ai": "bin/ezenciel-agents-ai.mjs",
-    "ezenciel-agents-watch": "bin/ezenciel-agents-watch.mjs",
-    "ezenciel-agents-application": "bin/ezenciel-agents-application.mjs"
+    "ezenciel-agents-application": "bin/ezenciel-agents-application.mjs",
+    "ezenciel-agents-provision-telegram": "bin/ezenciel-agents-provision-telegram.mjs",
+    "ezenciel-agents-plugin-broker": "bin/ezenciel-agents-plugin-broker.mjs"
   },
   "files": [
     "default-plugins.json",
@@ -37,7 +38,6 @@
     "CONTRIBUTING.md",
     "Dockerfile",
     "compose.yaml",
-    "compose.workforce-watch.yaml",
     "docker",
     "compose.whatsapp.yaml",
     "scripts/smoke.ts",
@@ -61,7 +61,7 @@
   "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",
+    "start": "./bin/ezenciel-agents-docker up -d --wait",
     "owner": "tsx --env-file=.env src/owner.ts",
     "message": "tsx src/message.ts",
     "react": "tsx src/react.ts",

package/scripts/smoke-scheduler.ts

@@ -7,6 +7,8 @@ import { createRelay } from '../src/index.js'
 import { ControlStore } from '../src/control-state.js'
 import { Scheduler } from '../src/scheduler.js'
 import { RunStore } from '../src/runs.js'
+import { serveDeliverySocket, createLedgerHandler } from '../src/delivery-socket.js'
+import { packageVersion } from '../src/version.js'
 import { initialPreset } from '../src/ai.js'
 import { initializeWorkspace } from '../src/workspace.js'
 import type { Update } from 'grammy/types'
@@ -15,12 +17,18 @@ const duration=Number(process.argv[2] || 1860),cli=process.argv[3] || 'codex'
 const nativeGoal=process.argv[4]==='goal'
 if(!Number.isSafeInteger(duration) || duration<30)throw new Error('Duration must be at least 30 seconds')
 const root=await mkdtemp(join(tmpdir(),'ez-scheduler-smoke-')),workspace=join(root,'agent'),controlDir=join(root,'control')
-await initializeWorkspace(workspace)
+const purpose=join(root,'purpose.md');await writeFile(purpose,'Verify native scheduled work and responsive owner chat.\n')
+await initializeWorkspace(workspace,purpose)
 const control=new ControlStore(controlDir,1000),scheduler=new Scheduler(controlDir),runs=new RunStore(controlDir)
 await control.requestPairing(101,101);await control.approveOwner(101)
 const owner=(await control.status()).owner!,execution=await control.captureChoice(initialPreset(cli))
 const replies:{at:number;text:string}[]=[]
 const relay=createRelay({workspace,controlDir,pairingTtlMs:1000,executorTimeoutMs:0,executorCli:cli,telegramBotToken:'fixture'})
+// Engine children reach this process's memory ledger through the socket.
+const ledger=await serveDeliverySocket(controlDir,createLedgerHandler(controlDir,{
+ wake:()=>{void relay.drainOutbox()},
+ status:()=>({polling:false,applicationOnly:!relay.telegramEnabled,telegramConfigured:true,version:packageVersion}),
+}))
 relay.bot.botInfo={id:999,is_bot:true,first_name:'Fixture',username:'fixture_bot'} as typeof relay.bot.botInfo
 relay.bot.api.config.use(async(_previous,method,payload)=>{
  if(method==='sendMessage') {const reply={at:Date.now(),text:(payload as {text:string}).text};replies.push(reply);console.log(JSON.stringify({reply}))}
@@ -58,11 +66,11 @@ try{
  await relay.drainOutbox()
  const status=(await runs.get(background.id))?.status
  if(status!=='completed' || replies.filter(r=>r.text.includes('BACKGROUND_DONE')).length!==1)throw new Error('Missing completed run or exactly one delivered result')
- const finished=await readFile(join(workspace,'work/tasks',background.id,'finished.txt'),'utf8')
+ const finished=await readFile(join(controlDir,'work/tasks',background.id,'finished.txt'),'utf8')
  if(finished.trim()!=='DONE')throw new Error('Missing finished.txt artifact')
  if(nativeGoal){
   for(const [file,expected] of [['phase1.txt','ONE'],['phase2.txt','TWO']])
-   if((await readFile(join(workspace,'work/tasks',background.id,file),'utf8')).trim()!==expected)throw new Error(`Missing native goal artifact: ${file}`)
+   if((await readFile(join(controlDir,'work/tasks',background.id,file),'utf8')).trim()!==expected)throw new Error(`Missing native goal artifact: ${file}`)
  }
  const record=(await runs.get(background.id))!
  if(Date.parse(record.endedAt!)-Date.parse(record.startedAt!) < duration*1000)throw new Error('Worker completed before requested duration')
@@ -87,4 +95,4 @@ try{
  const evidence={duration,cli,nativeGoal,goalEvidence,status,replies,run:await runs.get(background.id)}
  await writeFile(join(root,'evidence.json'),JSON.stringify(evidence,null,2),{mode:0o600})
  console.log(JSON.stringify({passed:true,evidence:join(root,'evidence.json')}))
-}finally{clearInterval(tick);while(draining)await new Promise(r=>setTimeout(r,50));await relay.stop()}
+}finally{clearInterval(tick);while(draining)await new Promise(r=>setTimeout(r,50));await relay.stop();await ledger.stop()}

package/scripts/smoke.ts

@@ -1,12 +1,13 @@
 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 { RunStore, sentOutbox } from '../src/runs.js'
 import { createRelay } from '../src/index.js'
+import { serveDeliverySocket, createLedgerHandler } from '../src/delivery-socket.js'
+import { packageVersion } from '../src/version.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.
@@ -39,6 +40,11 @@ async function main() {
     texts: [prompt],
   })
   await runs.patch(run.id, { status: 'running', startedAt: new Date().toISOString() })
+  // The engine child reaches the smoke-process memory ledger through the socket.
+  const ledger = await serveDeliverySocket(config.controlDir, createLedgerHandler(config.controlDir, {
+    wake: () => { void relay.drainOutbox(run.id) },
+    status: () => ({ polling: false, applicationOnly: !relay.telegramEnabled, telegramConfigured: config.telegramBotToken !== '', version: packageVersion }),
+  }))
   const job = await startExecutorJob(run.texts, {
     workspace: config.workspace,
     timeoutMs: config.executorTimeoutMs,
@@ -72,18 +78,14 @@ async function main() {
       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)
-    }
+    const receipts = sentOutbox(config.controlDir)
+      .filter((item) => item.runId === run.id && item.receipt)
+      .map((item) => item.receipt)
+    const delivery = await runs.deliveryStatus()
     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'))) {
+    if (code !== 0 || !receipts.length || (await runs.pendingOutbox()).length || delivery.failed || delivery.unknown) {
       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.')
@@ -93,6 +95,7 @@ async function main() {
     process.removeListener('SIGTERM', stop)
     await job.cleanup()
     await relay.stop()
+    await ledger.stop()
   }
 }
 

package/src/agent-guidance.ts

@@ -1,17 +1,12 @@
 import { lstat, readFile, rename, rm, writeFile } from 'node:fs/promises'
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
-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()
 
 const start = '<!-- ez shared guidance: begin -->'
 const end = '<!-- ez shared guidance: end -->'
 
-// Native instruction installation, refreshed at setup/runtime upgrade, not per turn.
-// Personal instructions outside this one managed block remain byte-for-byte intact.
+// Drop the obsolete package-owned handbook. Discovery lives in the managed
+// ez tools locator. Personal text outside the markers stays byte-for-byte.
 export async function installAgentGuidance(workspace: string): Promise<void> {
   for (const name of ['AGENTS.md', 'AGENTS.override.md']) {
     const file = path.join(workspace, name)
@@ -23,11 +18,13 @@ export async function installAgentGuidance(workspace: string): Promise<void> {
       if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue
       throw error
     }
-    const block = `${start}\n${agentGuidance()}\n${end}\n\n`
     const from = original.indexOf(start), to = original.indexOf(end)
     if ((from < 0) !== (to < 0) || (from >= 0 && (to < from || original.indexOf(start, from + start.length) >= 0 || original.indexOf(end, to + end.length) >= 0)))
       throw new Error(`Malformed shared guidance block: ${file}`)
-    const updated = from < 0 ? block + original : original.slice(0, from) + block.trimEnd() + original.slice(to + end.length)
+    if (from < 0) continue
+    let rest = original.slice(to + end.length)
+    if (from === 0 && rest.startsWith('\n')) rest = rest.slice(1)
+    const updated = original.slice(0, from) + rest
     if (updated === original) continue
     const temporary = `${file}.${randomUUID()}.tmp`
     try {

package/src/agent-install.ts

@@ -1,8 +1,13 @@
-import { mkdir, readFile, writeFile, rm, readdir } from 'node:fs/promises'
-import { isAbsolute, join, resolve, dirname } from 'node:path'
+import { chmod, mkdir, readFile, writeFile, rm, readdir } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import { isAbsolute, join, resolve, dirname, delimiter } from 'node:path'
 import { parseArgs } from 'node:util'
 import { executorKey } from './executor.js'
+import { isolationTransport, parseIsolationClass, type IsolationClass } from './isolation.js'
+import { ledgerOverlayName, ledgerOverlayYaml } from './ledger-endpoint.mjs'
+import { initializeWorkspace } from './workspace.js'
 import { fileURLToPath } from 'node:url'
+import { validateCodexProvider, type CodexProviderBinding } from './executor.js'
 
 // Recorded by the installing CLI once; agent creation inherits this binding.
 export const installationCli = async (root: string, installerCli?: string): Promise<string> => {
@@ -30,42 +35,70 @@ export const installationCli = async (root: string, installerCli?: string): Prom
 }
 
 export const createAgent = async (options: {
-  root: string; hostRoot: string; composeFile: string; name: string; purpose: string; token: string; cli?: string; image?: string
+  root: string; hostRoot: string; composeFile: string; name: string; purpose: string; token: string; cli?: string; image?: string; isolation?: string; codexProvider?: CodexProviderBinding; ledgerPort?: number
 }) => {
   const { root, hostRoot, composeFile, name, purpose, token } = options
+  const requestedIsolation = options.isolation?.trim()
+  if (requestedIsolation) parseIsolationClass(requestedIsolation)
   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 (!purpose.trim() || purpose.length > 2000) throw new Error('Supply a concise purpose of 1–2000 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 isolation: IsolationClass = requestedIsolation ? parseIsolationClass(requestedIsolation) : cli === 'codex' ? 'isolated' : 'host-capable'
+  if (isolation === 'isolated' && cli !== 'codex') throw new Error(`Isolated execution is unavailable for ${cli}; use host-capable isolation`)
+  const transport = isolationTransport(isolation)
+  const ledgerPort = isolation === 'host-capable'
+    ? options.ledgerPort ?? 20000 + (createHash('sha256').update(name).digest().readUInt16BE(0) % 10000)
+    : undefined
+  if (isolation === 'host-capable' && (!Number.isSafeInteger(ledgerPort) || ledgerPort! < 1024 || ledgerPort! > 65535))
+    throw new Error('Host-capable agents require a free loopback ledger port for host CLI access')
+  const codexProvider = options.codexProvider ? validateCodexProvider(options.codexProvider) : undefined
+  if (codexProvider && cli !== 'codex') throw new Error('A Codex provider requires the Codex installation 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 ledgerOverlay = join(deploymentDir, ledgerOverlayName)
     const values = {
       COMPOSE_PROJECT_NAME: project,
-      COMPOSE_FILE: composeFile,
+      COMPOSE_FILE: [composeFile, ...(ledgerPort ? [ledgerOverlay] : [])].join(delimiter),
       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_ISOLATION: isolation,
+      EZ_EXECUTOR_TRANSPORT: transport,
+      ...(ledgerPort ? { EZ_DELIVERY_TCP_PORT: String(ledgerPort) } : {}),
+      ...(isolation === 'isolated' && cli === 'codex' ? { EZ_CODEX_SANDBOX: 'external' } : {}),
       EZ_AGENT_WORKSPACE: join(deploymentDir, 'mind'),
       EZ_CONTROL_DIR: join(deploymentDir, 'control'),
+      EZ_TOOLS_HOME: join(deploymentDir, 'tools'),
+      EZ_PLUGIN_BROKER_SOCKET: join(deploymentDir, 'control', 'plugin-broker.sock'),
+      EZ_PLUGIN_BROKER_HOST_CONFIG: join(deploymentDir, 'host-executor.json'),
+      ...(isolation === 'isolated' ? { COMPOSE_PROFILES: 'isolated' } : {}),
       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'})
+    if (ledgerPort) await writeFile(join(directory, ledgerOverlayName), ledgerOverlayYaml(), {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})
+    // Install-time seed: the relay never writes the workspace at startup.
+    // Readable beyond the installer UID so a mismatched runtime UID still
+    // loads its own purpose; the 0700 deployment directory keeps it private.
+    const seeded = await initializeWorkspace(join(directory,'mind'), join(directory,'purpose.md'))
+    if (seeded.includes('AGENTS.md')) await chmod(join(directory,'mind','AGENTS.md'), 0o644)
     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 mkdir(join(directory,'tools'),{mode:0o700})
+    const agent = {name, project, deploymentDir, purpose:purpose.trim(), executor:cli, isolation}
+    const host = {cli,isolation,agents:[{name,workspace:join(deploymentDir,'mind'),controlDir:join(deploymentDir,'control'),binDir:join(dirname(composeFile),'bin'),...(isolation === 'isolated' ? {toolsHome:join(deploymentDir,'tools')} : {}),...(codexProvider?{codexProviders:[codexProvider]}:{})}]}
     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
@@ -84,13 +117,15 @@ export const listAgents = async (root: string) => {
 
 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'}}})
+    const {values:v} = parseArgs({options:{name:{type:'string'},purpose:{type:'string'},isolation:{type:'string'},'host-root':{type:'string'},'compose-file':{type:'string'},'relay-image':{type:'string'},'ledger-port':{type:'string'},list:{type:'boolean'},cli:{type:'string'},'register-cli':{type:'string'},'codex-provider':{type:'string'},'codex-provider-name':{type:'string'},'codex-base-url':{type:'string'},'codex-env-key':{type:'string'},'codex-model':{type:'string',multiple:true}}})
     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']})))
+      const providerValues=[v['codex-provider'],v['codex-provider-name'],v['codex-base-url'],v['codex-env-key'],v['codex-model']]
+      const codexProvider=providerValues.some(Boolean)?validateCodexProvider({id:v['codex-provider']||'',name:v['codex-provider-name']||v['codex-provider']||'',baseUrl:v['codex-base-url']||'',envKey:v['codex-env-key']||'',models:v['codex-model']||[]}):undefined
+      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'],isolation:v.isolation,codexProvider,ledgerPort:v['ledger-port']===undefined?undefined:Number(v['ledger-port'])})))
     }
   } catch (error) { console.error((error as Error).message); process.exitCode=1 }
 }

package/src/ai-cli.ts

@@ -1,27 +1,29 @@
 import { parseArgs } from 'node:util'
 import { randomBytes } from 'node:crypto'
 import { join } from 'node:path'
+import { readFile } from 'node:fs/promises'
 import { readModels, validateSelection, type AiPreset } from './ai.js'
 import { ControlStore } from './control-state.js'
 
-const {values,positionals}=parseArgs({allowPositionals:true,options:{help:{type:'boolean'},cli:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
+const {values,positionals}=parseArgs({allowPositionals:true,options:{help:{type:'boolean'},cli:{type:'string'},provider:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
 if(values.help){
-  console.log('Usage: ezenciel-agents-ai list | select --cli <installed-cli> [--model <model>] [--effort <effort>]\nChoose only values returned by list. Selection affects subsequent messages; queued work and the installation default are unchanged.')
+  console.log('Usage: ezenciel-agents-ai list | select --cli <installed-cli> [--provider <provider>] [--model <model>] [--effort <effort>]\nChoose only values returned by list. Selection affects subsequent messages; queued work and the installation default are unchanged.')
   process.exit(0)
 }
 if (!process.env.EZ_CONTROL_DIR) throw new Error('Use this agent’s bound control directory')
-const catalog=await readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR,'cli','codex'))
+const catalog=await readFile(join(process.env.EZ_CONTROL_DIR,'host-executor','models.json'),'utf8')
+  .then(text=>JSON.parse(text)).catch(()=>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}
+  const preset:AiPreset={id:randomBytes(8).toString('hex'),name:[values.provider,values.model||values.cli,values.effort].filter(Boolean).join(' · '),cli:values.cli||'',provider:values.provider,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 existing=state.ai.presets.find(p=>p.cli===preset.cli&&p.provider===preset.provider&&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))
+  await control.selectPreset(selected.id,state.activeSession?.sessionId??null,current.cli!==selected.cli||current.provider!==selected.provider||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>]')
+}else throw new Error('Use list or select --cli <installed-cli> [--provider <provider>] [--model <model>] [--effort <effort>]')

package/src/ai.ts

@@ -6,26 +6,26 @@ 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 AiPreset = { id: string; name: string; cli: string; provider?: string; model?: string; effort?: string }
 export type ExecutionChoice = { sessionId: string; preset: AiPreset }
-export type ModelChoice = { cli: string; model?: string; name: string; efforts: string[] }
+export type ModelChoice = { cli: string; provider?: 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))
+    (v.provider === undefined || safe(v.provider)) && (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 presetLabel = (p: AiPreset) => `${p.cli}${p.provider ? ` (${p.provider})` : ''} · ${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 =>
-  ['codex','codex-gui'].includes(preset.cli) && !preset.model && !preset.effort
+  ['codex','codex-gui'].includes(preset.cli) && !preset.provider && !preset.model && !preset.effort
     ? discovered.find((candidate) => candidate.cli === preset.cli) ?? preset
     : preset
 export const initialPreset = (cli: string): AiPreset => {
@@ -87,8 +87,8 @@ export const readModels = async (home = homedir(), available = installed, codexH
 export const validateSelection = async (p: AiPreset, catalog: ModelChoice[], available = installed): Promise<void> => {
   assertEffort(p.effort, p.model, p.cli)
   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 (!p.provider && !p.model && !p.effort && p.cli !== 'agy') return
+  const model = catalog.find((m) => m.cli === p.cli && m.provider === p.provider && 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.')
 }