@jc_stack/ez-agents 0.1.0-beta.32 → 0.1.0-beta.34

package/docs/setup.md

@@ -67,8 +67,23 @@ not imported into restricted sessions. No workflow prompt is added to input.
 Use the existing owner's host account. Unless a layout was supplied, use
 `${XDG_DATA_HOME:-$HOME/.local/share}/ez/packages/<version>/` for extracted main
 packages and `${XDG_DATA_HOME:-$HOME/.local/share}/ez/agents/` for private deployments.
-Never overwrite an existing package/deployment or extract over its state. Infer
-the agent name and purpose from the owner's request; ask only when missing.
+Never overwrite an existing package/deployment or extract over its state.
+
+Before creation, use your own reasoning and the context already available from
+the owner to write the agent's initial brief. This is not a label or a copy of
+the request. Describe, in concrete language, who the agent serves, what product
+or environment it works in, the outcomes it should help produce, the capabilities
+currently available to it, and important scope boundaries. Include material facts
+you already know about the application; do not invent unknown facts. Omit generic
+personality prose and sections irrelevant to this agent. Keep the result compact
+enough to read on every turn. Ask the owner only when a missing fact would
+materially change the agent being installed.
+
+Pass that generated brief as the purpose. For example, a request to create a
+personal assistant should produce a brief tailored to that person's stated work,
+preferences and connected capabilities—not merely `Personal assistant`. A product
+agent should identify the product, user, current product scope and available
+actions without embedding product-specific behavior in Ez Core.
 
 Before running Node commands, check `command -v node` and `node --version`.
 If Node 22+ or this package's pinned pnpm is missing, provision it using the
@@ -163,20 +178,72 @@ so later service starts use the same build without depending on shell environmen
 
 ```sh
 export EZ_AGENTS_HOME=/absolute/private/agents
-bin/ezenciel-agents-create --name family-shopper --purpose 'Help my family plan shopping.' < /private/bot-token
+bin/ezenciel-agents-create --name family-shopper --purpose 'You are the shopping assistant for the owner and their family. Help plan shared shopping, organize confirmed requests, and use only the installed shopping and messaging capabilities. Do not purchase, message others, or infer household preferences without owner authority.' < /private/bot-token
 export EZ_DEPLOYMENT_DIR="$EZ_AGENTS_HOME/family-shopper"
 ```
 
+Creation records an isolation class. Packaged Codex defaults to `isolated`: the
+native CLI runs inside the relay, which only has that agent's workspace and control mounts.
+Sibling host paths are absent (`ENOENT`), not merely unreadable. Pass
+`--isolation host-capable` only when the owner needs the installer UID (host
+browser, local git, host files). Other installed CLIs default to `host-capable`
+because they are not packaged in the relay; requesting isolated execution for
+them fails closed. Host-capable reuses the host CLI login and is not an OS tenant
+boundary. The class cannot be changed later by flipping Compose; recreate the agent.
+
+Isolated Codex uses the pinned CLI in the relay image and
+`EZ_CODEX_SANDBOX=external` so Codex does not nest a sandbox inside the
+container. Provision that agent's `control/cli/codex/auth.json`; do not bind-mount
+the operator `~/.codex`. The host LaunchAgent is not started. Host-capable agents
+still need [host startup](host-service.md).
+
 Agent creation defaults to the CLI recorded when the initial package was
 installed. It needs no `--cli` argument. A later shell or different available CLI
 does not change that saved default. No installed-binary ranking or Grok fallback
 is used.
+
+Custom Codex providers such as OpenRouter currently require an explicitly
+host-capable agent: their keys are supplied by the private host-service
+environment. The isolated relay has no custom-provider key injection path.
+Register the provider and initial model set as non-secret installation metadata;
+repeat `--codex-model` for every model the agent may select:
+
+```sh
+bin/ezenciel-agents-create \
+  --name family-shopper \
+  --purpose 'Help my family plan shopping.' \
+  --isolation host-capable \
+  --codex-provider openrouter \
+  --codex-provider-name OpenRouter \
+  --codex-base-url https://openrouter.ai/api/v1 \
+  --codex-env-key OPENROUTER_API_KEY \
+  --codex-model google/gemini-3.8-flash \
+  --codex-model deepseek/deepseek-v4.1-flash \
+  < /private/bot-token
+```
+
+This stores provider configuration and model IDs in `host-executor.json`, never
+the API key. The key belongs only in the private host-service environment. The
+agent or owner can later change the active provider/model through the existing
+runtime control without reinstalling or editing an environment file:
+
+```sh
+ezenciel-agents-ai list
+ezenciel-agents-ai select --cli codex --provider openrouter \
+  --model google/gemini-3.8-flash
+```
+
+Changing provider starts a fresh native session so a session is never resumed
+against a different backend. Queued work retains the provider/model captured
+when it was admitted.
 The creator writes `host-executor.json`, private secrets, mind/control paths,
 purpose and unique plugin volume names. Duplicate names fail without overwriting.
 `ezenciel-agents-create --list` lists deployments without secrets.
 
-Before starting that host transport, initialize the main package’s built-in plugin manager. It runs on the host
+Before starting a host-capable transport, initialize the main package’s built-in plugin manager. It runs on the host
 for Docker access and adds no separate package or provider library. The packaged catalog is empty so the relay installs independently.
+Isolated agents still initialize this registry for plugin discovery; they do not
+start `ezenciel-agents-host`.
 Use its empty default catalog. Plugin preparation follows the verified Telegram
 handoff, not this step. Run:
 
@@ -202,16 +269,21 @@ the plugin skill through onboarding and verified use under that same request.
    Registry initialization itself does not connect accounts or start plugins.
 Never silently reuse a global `ez` from the old sandbox runtime.
 
-4. Follow [host startup templates](host-service.md). Register `bin/ezenciel-agents-host` with the host's native service manager,
-   binding `EZ_DEPLOYMENT_DIR` and the user's existing CLI PATH/HOME. On macOS use
-   a LaunchAgent; on Linux use a user service. Use the absolute Node/package
+4. Isolated agents skip host transport. Run `bin/ezenciel-agents-docker up -d --wait`
+   from the deployment directory. Do not register `ezenciel-agents-host` for them;
+   starting it fails closed.
+
+   Host-capable agents follow [host startup templates](host-service.md). Register
+   `bin/ezenciel-agents-host` with the host's native service manager, binding
+   `EZ_DEPLOYMENT_DIR` and the user's existing CLI PATH/HOME. On macOS use a
+   LaunchAgent; on Linux use a user service. Use the absolute Node/package
    paths. This generic transport is the only host execution bridge. Do not start
    another host relay or install another CLI. Verify its heartbeat, then run
    `bin/ezenciel-agents-docker up -d --wait`.
 
    `ezenciel-agents-setup service` is Docker-only startup: run it from the
    deployment directory containing `docker.env`. It starts the relay and does
-   not install or start the host-executor user service. Complete the host
+   not install or start the host-executor user service. Complete host-capable
    registration above separately.
 
 5. Ask the owner to message the exact bot. Verify the pending numeric identity,
@@ -224,8 +296,8 @@ Never silently reuse a global `ez` from the old sandbox runtime.
    stopped to verify repairs, then restore the poller; never replay uncertain
    user actions merely to test delivery.
 
-The main runtime is fully installer-owned: build it, register its host
-transport, bring its Compose project up, and verify restart persistence. Plugins
+The main runtime is fully installer-owned: build it, register host transport
+only for host-capable agents, bring its Compose project up, and verify restart persistence. Plugins
 are installed by the working Telegram agent when the owner requests their
 capability there; account onboarding and provider confirmation follow that request.
 Never use a missing plugin as a reason
@@ -238,9 +310,11 @@ current heartbeats and owner-bound completed-run delivery receipts without sendi
 messages or exposing tokens. Receipt evidence is historical: separately verify
 the current conversation and restart persistence before declaring setup complete.
 
-Purpose seeds SOUL.md once; future customization survives restart. Conversations,
-pairing, files and plugin accounts are separate. The existing host CLI login is
-shared, so this is not a security sandbox against other agents under that user.
+Purpose scopes AGENTS.md once; future customization survives restart. Conversations,
+pairing, files and plugin accounts are separate. Isolated agents use the relay
+mount namespace as the filesystem boundary. Host-capable agents share the
+installer UID and CLI login; that class is not a security sandbox against other
+agents under that user.
 Plugins run in their own containers and own their authentication. Install and
 register them only for the requested agent. Never clone another agent's plugin
 credentials. See [runtime, migration and QA](docker-runtime.md).
@@ -256,7 +330,7 @@ default. Existing queued jobs retain their captured execution choice.
 | Symptom | Inspect and recover |
 |---|---|
 | Docker unavailable | Check engine and Compose, start the supported installation; complete any required OS consent. |
-| Bot stays silent | Check pending owner identity, relay health, host heartbeat and outbox; approve only the verified owner. |
+| Bot stays silent | Check pending owner identity, relay health, host heartbeat (host-capable only) and outbox; approve only the verified owner. |
 | CLI exits without reply | Inspect the actual tool result and delivery receipt; stdout is not Telegram output. |
 | Exit 73 | An existing writer holds this deployment; stop the exact duplicate, never delete the kernel lock. |
 | Plugin absent | Check the bound catalog and install/start the reviewed package explicitly; no plugin ships by default. |

package/docs/standalone-cli.md

@@ -32,8 +32,9 @@ Use `ez tools list --details` for generated installed-plugin descriptions, help
 Add that instruction to its existing project instructions without replacing them.
 Use the absolute launcher, or prepend its bin directory to that session's PATH.
 Never overwrite another global `ez`; it may belong to a different installation.
-A company registry remains explicit even when invoked from a different directory.
-Other projects/accounts should use separate registries and private plugin state.
+A standalone company registry remains explicit even when invoked from a different
+directory. A relay-bound registry rejects calls from outside its workspace. Other
+projects/accounts must use separate registries and private plugin state.
 
 ## Install and verify a capability
 
@@ -54,9 +55,9 @@ Native client plugins/connectors are not converted into Ez plugins automatically
 
 A relay can coexist with CLI-only registries on the same machine. It retains its
 own pairing, single-writer queue, mind and plugin registry. Calling its existing
-bound launcher explicitly reuses that registry and its accounts; never initialize
-over it or silently select it from another workspace. Coordinate writes with its
-active jobs. Separate registries do not automatically share credentials or data.
+bound launcher must be run from the owning agent workspace. Never initialize over
+it or select it from another workspace. Coordinate writes with its active jobs.
+Separate registries do not automatically share credentials or data.
 
 Continuous monitoring requires a configured event consumer/relay and the plugin's
 supported watcher. CLI-only installation does not create background agent turns.

package/docs/upgrades.md

@@ -174,10 +174,12 @@ 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
+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.
 

package/package.json

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

package/scripts/smoke-scheduler.ts

@@ -15,7 +15,8 @@ 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))

package/src/agent-install.ts

@@ -2,7 +2,9 @@ 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 { isolationTransport, parseIsolationClass, type IsolationClass } from './isolation.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,18 +32,25 @@ 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
 }) => {
   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 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})
@@ -54,6 +63,9 @@ export const createAgent = async (options: {
       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,
+      ...(isolation === 'isolated' && cli === 'codex' ? { EZ_CODEX_SANDBOX: 'external' } : {}),
       EZ_AGENT_WORKSPACE: join(deploymentDir, 'mind'),
       EZ_CONTROL_DIR: join(deploymentDir, 'control'),
       EZ_WHATSAPP_IPC_VOLUME: `${project}-whatsapp-ipc`,
@@ -64,8 +76,8 @@ export const createAgent = async (options: {
     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')}]}
+    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'),...(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 +96,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'},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})))
     }
   } 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.')
 }

package/src/application-channel.ts

@@ -105,10 +105,10 @@ export class ApplicationChannel {
     const owner = await this.sharedBinding(bindingId)
     const controls = this.options.aiControls
     if (!controls) throw new Error('Application controls unavailable')
-    const value = input as {action?: unknown; expectedSession?: unknown; sessionId?: unknown; presetId?: unknown; cli?: unknown; model?: unknown; effort?: unknown}
+    const value = input as {action?: unknown; expectedSession?: unknown; sessionId?: unknown; presetId?: unknown; cli?: unknown; provider?: unknown; model?: unknown; effort?: unknown}
     if (!value || !['new','switch','select','model'].includes(String(value.action)) ||
       !(value.expectedSession === null || (typeof value.expectedSession === 'string' && /^[a-f0-9-]{36}$/.test(value.expectedSession)))) throw new Error('Invalid application control request')
-    const fields = {new:[],switch:['sessionId'],select:['presetId'],model:['cli','model','effort']}[value.action as 'new'|'switch'|'select'|'model']!
+    const fields = {new:[],switch:['sessionId'],select:['presetId'],model:['cli','provider','model','effort']}[value.action as 'new'|'switch'|'select'|'model']!
     if (Object.keys(value).some(key => !['action','expectedSession',...fields].includes(key))) throw new Error('Invalid application control fields')
     const control = new ControlStore(this.options.controlDir, 900000)
     const expected = value.expectedSession as string | null
@@ -131,7 +131,7 @@ export class ApplicationChannel {
       await controls.select(preset, expected, guard)
     }
     if (value.action === 'model') {
-      const model = (await controls.catalog()).find(item => item.cli === value.cli && item.model === value.model)
+      const model = (await controls.catalog()).find(item => item.cli === value.cli && item.provider === value.provider && item.model === value.model)
       if (!model || (value.effort !== undefined && (typeof value.effort !== 'string' || !model.efforts.includes(value.effort)))) throw new Error('Invalid application model selection')
       await this.sharedBinding(bindingId)
       const preset = await controls.saveSelection(model, value.effort as string | undefined, guard)
@@ -160,10 +160,10 @@ export class ApplicationChannel {
     const owner = await this.sharedBinding(bindingId, false)
     const controls = this.options.aiControls
     if (!controls) throw new Error('Application controls unavailable')
-    const value = input as {action?:unknown; expectedSession?:unknown; presetId?:unknown; cli?:unknown; model?:unknown; effort?:unknown}
+    const value = input as {action?:unknown; expectedSession?:unknown; presetId?:unknown; cli?:unknown; provider?:unknown; model?:unknown; effort?:unknown}
     if (!value || !['new','select','model'].includes(String(value.action)) ||
       !(value.expectedSession===null || (typeof value.expectedSession==='string' && /^[a-f0-9-]{36}$/.test(value.expectedSession)))) throw new Error('Invalid application control request')
-    const fields = {new:[],select:['presetId'],model:['cli','model','effort']}[value.action as 'new'|'select'|'model']!
+    const fields = {new:[],select:['presetId'],model:['cli','provider','model','effort']}[value.action as 'new'|'select'|'model']!
     if (Object.keys(value).some(key=>!['action','expectedSession',...fields].includes(key))) throw new Error('Invalid application control fields')
     const hashedScope = applicationScope(bindingId,scope)
     const guard:ControlGuard = {owner,applicationScope:hashedScope,expectedSession:value.expectedSession as string|null,
@@ -180,7 +180,7 @@ export class ApplicationChannel {
       await controls.validate(preset)
     }
     if (value.action==='model') {
-      const model = (await controls.catalog()).find(item=>item.cli===value.cli && item.model===value.model)
+      const model = (await controls.catalog()).find(item=>item.cli===value.cli && item.provider===value.provider && item.model===value.model)
       if (!model || model.cli==='agy' || (value.effort!==undefined && (typeof value.effort!=='string' || !model.efforts.includes(value.effort)))) throw new Error('Invalid application model selection')
       preset = await controls.saveSelection(model,value.effort as string|undefined,guard)
     }
@@ -195,7 +195,7 @@ export class ApplicationChannel {
         if ('followTelegram' in rest) throw new Error('Invalid application request: choose one conversation option')
         input = {...rest, followTelegram: followOwner}
       }
-      const value = input as { requestId?: unknown; scope?: unknown; text?: unknown; attachment?: { name?: unknown; data?: unknown }; context?: Record<string, unknown>; expectedNativeSessionId?: unknown; activateTelegram?: unknown; followTelegram?: unknown; ai?: { cli?: unknown; model?: unknown; effort?: unknown } }
+      const value = input as { requestId?: unknown; scope?: unknown; text?: unknown; attachment?: { name?: unknown; data?: unknown }; context?: Record<string, unknown>; expectedNativeSessionId?: unknown; activateTelegram?: unknown; followTelegram?: unknown; ai?: { cli?: unknown; provider?: unknown; model?: unknown; effort?: unknown } }
       if (!value || !applicationId(value.requestId) || !applicationId(value.scope) || typeof value.text !== 'string' || (!value.text.trim() && value.attachment === undefined) || value.text.length > 16000 || Object.keys(value).some(key => !['requestId','scope','text','attachment','context','expectedNativeSessionId','activateTelegram','followTelegram','ai'].includes(key))) throw new Error('Invalid application request')
       if (value.expectedNativeSessionId !== undefined && (typeof value.expectedNativeSessionId !== 'string' || !/^[a-zA-Z0-9_-]{1,160}$/.test(value.expectedNativeSessionId))) throw new Error('Invalid application native session assertion')
       if (value.activateTelegram !== undefined && typeof value.activateTelegram !== 'boolean') throw new Error('Invalid application Telegram activation')
@@ -204,7 +204,7 @@ export class ApplicationChannel {
       let requestedPreset: AiPreset | undefined
       if (value.ai !== undefined) {
         const candidate = { ...value.ai, id: 'application', name: 'Application selection' }
-        if (!value.ai || Object.keys(value.ai).some(key => !['cli', 'model', 'effort'].includes(key)) || !isPreset(candidate)) throw new Error('Invalid application AI selection')
+        if (!value.ai || Object.keys(value.ai).some(key => !['cli', 'provider', 'model', 'effort'].includes(key)) || !isPreset(candidate)) throw new Error('Invalid application AI selection')
         assertEffort(candidate.effort, candidate.model, candidate.cli)
         requestedPreset = candidate
       }
@@ -227,7 +227,7 @@ export class ApplicationChannel {
       const existing = await this.runs.get(id)
       if (existing) {
         await this.bindings.authorize(existing)
-        if (requestedPreset && (existing.execution?.preset.cli !== requestedPreset.cli || existing.execution?.preset.model !== requestedPreset.model || existing.execution?.preset.effort !== requestedPreset.effort)) throw new Error('Application request ID conflicts with prior AI selection')
+        if (requestedPreset && (existing.execution?.preset.cli !== requestedPreset.cli || existing.execution?.preset.provider !== requestedPreset.provider || existing.execution?.preset.model !== requestedPreset.model || existing.execution?.preset.effort !== requestedPreset.effort)) throw new Error('Application request ID conflicts with prior AI selection')
         if (Boolean(existing.application?.followTelegram) !== Boolean(value.followTelegram) || existing.application?.scope !== value.scope || (existing.application?.inputText ?? existing.texts[0]) !== value.text || existing.application?.attachmentHash !== attachmentHash) throw new Error('Application request ID conflicts with prior scope or text')
         return existing // Retried context never replaces already admitted capabilities.
       }
@@ -252,7 +252,7 @@ export class ApplicationChannel {
     await this.bindings.authorize(run)
     const state = await new ControlStore(this.options.controlDir, 900000).status()
     const session = state.activeSession?.sessionId === run.execution?.sessionId ? state.activeSession : state.sessions?.find(item => item.sessionId === run.execution?.sessionId)
-    return { ...(session ? { sessionId: session.sessionId, nativeSessionId: session.nativeSessionId, cli: session.cli } : {}), ...(run.scheduled?.originRunId ? {originRunId:run.scheduled.originRunId} : {}), id: run.id, scope: (run.application ?? run.delivery)!.scope, status: run.status, messages: await this.runs.applicationMessages(run.id), approvals:await this.runs.applicationApprovals(run.id), ...(run.status === 'failed' ? { error: 'Agent execution failed; inspect the core run' } : {}) }
+    return { ...(session ? { sessionId: session.sessionId, nativeSessionId: session.nativeSessionId, cli: session.cli } : {}), ...(run.execution?.preset ? {preset:run.execution.preset} : {}), ...(run.scheduled?.originRunId ? {originRunId:run.scheduled.originRunId} : {}), id: run.id, scope: (run.application ?? run.delivery)!.scope, status: run.status, messages: await this.runs.applicationMessages(run.id), approvals:await this.runs.applicationApprovals(run.id), ...(run.status === 'failed' ? { error: 'Agent execution failed; inspect the core run' } : {}) }
   }
   async deliver(run: RunRecord, item: OutboxItem): Promise<void> {
     await this.bindings.authorize(run)

package/src/codex-session.ts

@@ -3,9 +3,9 @@ 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'
+import { terminateJob, validateCodexProvider, type CodexProviderBinding } from './executor.js'
 
-type Options = {workspace:string;controlDir:string;toolsHome?:string;sharedWorkspace?:string;additionalWorkspaces?:string[];model?:string;effort?:string;prompt:string;codexSandbox?:'external'}
+type Options = {workspace:string;controlDir:string;toolsHome?:string;sharedWorkspace?:string;additionalWorkspaces?:string[];model?:string;effort?:string;prompt:string;codexSandbox?:'external';codexProvider?:CodexProviderBinding}
 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;
@@ -13,6 +13,7 @@ type Message = {id?:number;method?:string;params?:any;result?:any;error?:{messag
 export async function runCodexSession(options:Options, io:{launch?:()=>ChildProcess;emit?:(line:string)=>void}={}):Promise<number> {
   options = executionDefaults('codex', options)
   if (options.codexSandbox !== undefined && options.codexSandbox !== 'external') throw new Error('Invalid Codex sandbox selection')
+  const provider = options.codexProvider ? validateCodexProvider(options.codexProvider) : undefined
   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=false
@@ -73,7 +74,8 @@ export async function runCodexSession(options:Options, io:{launch?:()=>ChildProc
     const result=await request('thread/start',{
       cwd:options.workspace,approvalPolicy:'never',sandbox:options.codexSandbox === 'external' ? 'danger-full-access' : 'workspace-write',model:options.model,
       config:{project_root_markers:['AGENTS.md','.git'],'sandbox_workspace_write.writable_roots':[options.controlDir,...(options.toolsHome?[options.toolsHome]:[]),...(options.sharedWorkspace?[options.sharedWorkspace]:[]),...(options.additionalWorkspaces ?? [])],
-        'sandbox_workspace_write.network_access':Boolean(options.toolsHome),...(options.effort?{model_reasoning_effort:options.effort}:{})},
+        'sandbox_workspace_write.network_access':Boolean(options.toolsHome),...(options.effort?{model_reasoning_effort:options.effort}:{}),
+        ...(provider?{model_provider:provider.id,[`model_providers.${provider.id}`]:{name:provider.name,base_url:provider.baseUrl,env_key:provider.envKey,wire_api:'responses',supports_websockets:false}}:{})},
     })
     threadId=result.thread?.id
     if(!threadId)throw new Error('Codex did not return a native thread ID')

package/src/config.ts

@@ -1,5 +1,6 @@
 import { parseWebLauncher, type WebLauncher } from './web-launcher.js'
 import { repairEnabled } from './repair-policy.js'
+import { isolationTransport, resolveIsolation, type IsolationClass } from './isolation.js'
 import path from 'node:path'
 import { homedir } from 'node:os'
 
@@ -15,6 +16,7 @@ export type Config = ControlConfig & {
   telegramBotToken: string
   workspace: string
   executorTimeoutMs: number
+  isolation?: IsolationClass
   codexSandbox?: 'external'
   codexAutoCompactTokens?: number
   executorCli: string
@@ -56,9 +58,11 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
 
   if (env.EZ_CHANNEL_BACKEND_URL && !env.EZ_CHANNEL_BACKEND_TOKEN?.trim()) throw new Error('EZ_CHANNEL_BACKEND_TOKEN is required')
   if (env.EZ_APPLICATION_PORT && env.EZ_CHANNEL_BACKEND_URL) throw new Error('Application input requires the native Ez executor, not a channel backend')
+  const isolation = resolveIsolation(env)
+  const transport = env.EZ_EXECUTOR_TRANSPORT?.trim() || isolationTransport(isolation)
   const codexSandbox = env.EZ_CODEX_SANDBOX?.trim()
   if (codexSandbox && codexSandbox !== 'external') throw new Error('EZ_CODEX_SANDBOX must be external or unset')
-  if (codexSandbox && (env.EZ_CHANNEL_BACKEND_URL || env.EZ_EXECUTOR_TRANSPORT !== 'local')) throw new Error('External Codex sandbox requires native local execution')
+  if (codexSandbox && (env.EZ_CHANNEL_BACKEND_URL || transport !== 'local')) throw new Error('External Codex sandbox requires native local execution')
   const pagerDutyRoutingKey = env.PAGERDUTY_ROUTING_KEY?.trim()
   const pagerDutyStocksHealthUrl = env.EZ_PAGERDUTY_STOCKS_HEALTH_URL?.trim()
   if (pagerDutyStocksHealthUrl && !pagerDutyRoutingKey)
@@ -78,6 +82,7 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
     repairEnabled: repairEnabled(env.EZ_REPAIR_ENABLED),
     workspace: path.resolve(env.EZ_AGENT_WORKSPACE?.trim() || './agent'),
     executorTimeoutMs: 0,
+    isolation,
     codexSandbox: codexSandbox === 'external' ? 'external' : undefined,
     codexAutoCompactTokens: !env.EZ_CODEX_AUTO_COMPACT_TOKENS?.trim() ? undefined : positiveInteger(env.EZ_CODEX_AUTO_COMPACT_TOKENS, 'EZ_CODEX_AUTO_COMPACT_TOKENS'),
     executorCli: env.EZ_EXECUTOR_CLI?.trim() || 'agy',

package/src/control-state.ts

@@ -470,7 +470,18 @@ export class ControlStore {
       const preset = state.ai.presets.find((p) => p.id === state.ai!.selectedId)!
       state.activeSession ??= { sessionId: crypto.randomUUID(), hasStarted: false, cli: preset.cli }
       if (!state.activeSession.cli && !state.activeSession.hasStarted) state.activeSession.cli = preset.cli
-      if (state.activeSession.cli === preset.cli) state.activeSession.preset = preset
+      if (state.activeSession.cli === preset.cli) {
+        const previous = state.activeSession.preset
+        // Same CLI, different provider/model: web/Telegram must not resume the old native thread.
+        // Undefined is the native client default and is a distinct selection.
+        if (state.activeSession.hasStarted && previous &&
+            (previous.provider !== preset.provider || previous.model !== preset.model)) {
+          ;(state.sessions ??= []).push(state.activeSession)
+          state.activeSession = { sessionId: crypto.randomUUID(), hasStarted: false, cli: preset.cli, preset }
+        } else {
+          state.activeSession.preset = preset
+        }
+      }
       if (!state.activeSession.title && !state.activeSession.hasStarted && title?.trim())
         state.activeSession.title = title.replace(/\s+/g, ' ').trim().slice(0, 80)
       await this.writeState(state)