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

package/src/executor.ts

@@ -4,6 +4,7 @@ import { RunStore } from './runs.js'
 import { startTaskExecutor } from './task-executor.js'
 import { requireOwnerExecution } from './execution-authority.js'
 import { mkdtemp, rm, writeFile, mkdir, symlink, readFile } from 'node:fs/promises'
+import { accessSync, constants as fsConstants } from 'node:fs'
 import { tmpdir, homedir } from 'node:os'
 import path from 'node:path'
 import { spawn, type ChildProcess } from 'node:child_process'
@@ -11,6 +12,7 @@ import { processSnapshot, matchingProcessIds } from './process-tree.js'
 import { createInterface } from 'node:readline'
 import { fileURLToPath } from 'node:url'
 import { DESKTOP_UNAVAILABLE } from './desktop-bridge.js'
+import { macosWorkspaceProfile, workspaceSiblingDenies } from './workspace-confine.js'
 
 export type ExecutorOptions = {
   repairEnabled?: boolean
@@ -28,11 +30,21 @@ export type ExecutorOptions = {
   eventSource?: string
   model?: string
   effort?: string
+  provider?: string
   codexSandbox?: 'external'
   codexAutoCompactTokens?: number
+  codexProvider?: CodexProviderBinding
   onSession?: (id: string) => Promise<void>
 }
 
+export type CodexProviderBinding = {
+  id: string
+  name: string
+  baseUrl: string
+  envKey: string
+  models: string[]
+}
+
 const allowedEnvironmentKeys = [
   'HOME',
   'LANG',
@@ -71,12 +83,27 @@ export const executorJobEnv = (
 
 export const grokJobEnv = executorJobEnv
 
+// Package binDir is Ez tools (ezenciel-agents-message). Native CLIs come from the
+// host PATH so one agent's wrapper cannot retarget another agent's CODEX_HOME.
+export const resolveHostCommand = (command: string, pathValue = process.env.PATH): string => {
+  if (!command || command.includes(path.sep) || command.includes('/')) return command
+  for (const directory of (pathValue ?? '').split(path.delimiter)) {
+    if (!directory) continue
+    const candidate = path.join(directory, command)
+    try {
+      accessSync(candidate, fsConstants.X_OK)
+      return candidate
+    } catch { /* try the next PATH entry */ }
+  }
+  throw new Error(`Native CLI ${command} is not executable on the host PATH`)
+}
+
 export type CliAdapter = {
   name: string
   command: string
   description: string
   buildArgs: (
-    options: Pick<ExecutorOptions, 'workspace' | 'sessionId' | 'isResume' | 'model' | 'effort' | 'toolsHome' | 'sharedWorkspace' | 'additionalWorkspaces' | 'codexAutoCompactTokens' | 'codexSandbox'> & { controlDir?: string },
+    options: Pick<ExecutorOptions, 'workspace' | 'sessionId' | 'isResume' | 'model' | 'effort' | 'toolsHome' | 'sharedWorkspace' | 'additionalWorkspaces' | 'codexAutoCompactTokens' | 'codexSandbox' | 'codexProvider'> & { controlDir?: string },
     promptFile: string,
     promptText: string,
   ) => string[]
@@ -88,6 +115,13 @@ export const EXECUTOR_REGISTRY: Record<string, CliAdapter> = {
     buildArgs: (opts, _file, prompt) => {
       if (opts.codexSandbox !== undefined && opts.codexSandbox !== 'external') throw new Error('Invalid Codex sandbox selection')
       const args = ['exec', '--skip-git-repo-check', '--json', '--sandbox', opts.codexSandbox === 'external' ? 'danger-full-access' : 'workspace-write', '--disable', 'memories', '--enable', 'skip_host_skill_discovery', '-c', 'approval_policy="never"']
+      if (opts.codexProvider) {
+        const provider = validateCodexProvider(opts.codexProvider)
+        args.push(
+          '-c', `model_provider=${JSON.stringify(provider.id)}`,
+          '-c', `model_providers.${provider.id}={name=${JSON.stringify(provider.name)},base_url=${JSON.stringify(provider.baseUrl)},env_key=${JSON.stringify(provider.envKey)},wire_api="responses",supports_websockets=false}`,
+        )
+      }
       const limit = opts.codexAutoCompactTokens
       if (limit !== undefined) {
         if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error('Invalid Codex compaction token limit')
@@ -194,6 +228,32 @@ export const executorKey = (name?: string): string => {
   return resolvedKey
 }
 
+const providerToken = (value: unknown, label: string, pattern: RegExp, limit = 160): string => {
+  if (typeof value !== 'string' || value.length > limit || !pattern.test(value)) throw new Error(`Invalid Codex provider ${label}`)
+  return value
+}
+
+export const validateCodexProvider = (value: CodexProviderBinding): CodexProviderBinding => {
+  if (!value || typeof value !== 'object') throw new Error('Invalid Codex provider binding')
+  const id = providerToken(value.id, 'id', /^[a-z][a-z0-9_-]{0,31}$/)
+  const name = providerToken(value.name, 'name', /^[^\r\n\0]{1,80}$/, 80)
+  const envKey = validateCodexProviderEnvironmentKey(value.envKey)
+  let url: URL
+  try { url = new URL(value.baseUrl) } catch { throw new Error('Invalid Codex provider URL') }
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash) throw new Error('Invalid Codex provider URL')
+  const models = value.models?.map(model => providerToken(model, 'model', /^[a-zA-Z0-9_./:-]{1,160}$/))
+  if (!models?.length || models.length > 64 || new Set(models).size !== models.length) throw new Error('Invalid Codex provider models')
+  return {id,name,baseUrl:url.toString().replace(/\/$/,''),envKey,models}
+}
+
+export const validateCodexProviderEnvironmentKey = (value: unknown): string => {
+  const envKey = providerToken(value, 'environment key', /^[A-Z][A-Z0-9_]{1,63}$/, 64)
+  if (allowedEnvironmentKeys.includes(envKey as typeof allowedEnvironmentKeys[number]) || envKey === 'CODEX_HOME' || envKey === 'NODE_OPTIONS' ||
+      envKey.startsWith('EZ_') || envKey.startsWith('TELEGRAM_') || envKey.startsWith('PAGERDUTY_'))
+    throw new Error('Reserved Codex provider environment key')
+  return envKey
+}
+
 export const resolveExecutor = (name?: string): CliAdapter => EXECUTOR_REGISTRY[executorKey(name)]
 
 export const grokInvocation = (
@@ -261,15 +321,27 @@ export const startExecutorJob = async (
 
   const adapter = resolveExecutor(options.cli)
   const command = adapter.command
-  const args = host || nativeSession || key === 'codex-gui' ? [] : adapter.buildArgs(options, promptFile, promptText)
-  const invocation = host
+  const denies = process.platform === 'darwin' && !host && !gui && options.codexSandbox !== 'external'
+    ? workspaceSiblingDenies(options.workspace) : []
+  // Codex must not apply a nested Seatbelt; this process is already confined.
+  const launchOptions = denies.length && command === 'codex' ? { ...options, codexSandbox: 'external' as const } : options
+  const args = host || nativeSession || key === 'codex-gui' ? [] : adapter.buildArgs(launchOptions, promptFile, promptText)
+  let invocation = host
     ? executorInvocation(process.execPath, ['--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)), fileURLToPath(new URL('./host-executor-client.ts', import.meta.url)), options.controlDir, options.runId])
     : nativeSession
       ? executorInvocation(process.execPath, ['--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)), fileURLToPath(new URL('./codex-session.ts', import.meta.url))])
     : gui
       ? executorInvocation(process.execPath, ['--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)), fileURLToPath(new URL('./desktop-bridge.ts', import.meta.url))])
-      : executorInvocation(command, args)
+      : executorInvocation(resolveHostCommand(command, executorEnvironment().PATH), args)
   const environment = executorJobEnv(options)
+  if (!host && !gui && key === 'codex' && options.provider && !options.codexProvider)
+    throw new Error('Selected Codex provider is not configured for this agent')
+  if (!host && !gui && key === 'codex' && options.codexProvider) {
+    const provider = validateCodexProvider(options.codexProvider)
+    const secret = process.env[provider.envKey]
+    if (!secret) throw new Error(`Missing Codex provider credential ${provider.envKey}`)
+    environment[provider.envKey] = secret
+  }
   if (!host && !gui && command === 'codex') {
     // Share the existing authentication, never the user's memory/config/sessions.
     const base = path.join(options.controlDir, 'cli', 'codex')
@@ -282,16 +354,26 @@ export const startExecutorJob = async (
       try{await writeFile(path.join(home,'config.toml'),await readFile(path.join(base,'config.toml')),{flag:'wx',mode:0o600})}
       catch(error){if(!['ENOENT','EEXIST'].includes((error as NodeJS.ErrnoException).code || ''))throw error}
     }
-    // Tasks inherit this agent's auth binding, including an operator-provisioned
-    // private credential after host migration. Never replace an existing binding.
-    const authLinks = [[path.join(base, 'auth.json'), path.join(homedir(), '.codex', 'auth.json')]]
-    if (nativeSession) authLinks.push([path.join(home, 'auth.json'), path.join(base, 'auth.json')])
+    // Isolated agents keep auth in this CODEX_HOME. Host-capable may link the
+    // installer login. Never replace an existing binding.
+    const authLinks = process.env.EZ_ISOLATION === 'isolated'
+      ? nativeSession ? [[path.join(home, 'auth.json'), path.join(base, 'auth.json')]] : []
+      : [[path.join(base, 'auth.json'), path.join(homedir(), '.codex', 'auth.json')],
+        ...(nativeSession ? [[path.join(home, 'auth.json'), path.join(base, 'auth.json')]] : [])]
     for (const [link, target] of authLinks) {
       try { await symlink(target, link) }
       catch(error) { if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error }
     }
     environment.CODEX_HOME = home
   }
+  if (denies.length) {
+    const profile = path.join(outputDirectory, 'workspace.sb')
+    await writeFile(profile, macosWorkspaceProfile(denies, [
+      options.controlDir, options.binDir, options.toolsHome, options.sharedWorkspace,
+      ...(options.additionalWorkspaces ?? []), outputDirectory,
+    ].filter((value): value is string => Boolean(value))), { mode: 0o600 })
+    invocation = { command: 'sandbox-exec', args: ['-f', profile, invocation.command, ...invocation.args] }
+  }
   const child = spawn(invocation.command, invocation.args, {
     cwd: options.workspace,
     env: environment,
@@ -307,7 +389,7 @@ export const startExecutorJob = async (
   })
   child.stdin?.end(host
     ? JSON.stringify({texts,options:{...options,onSession:undefined,codexSandbox:undefined}})
-    : nativeSession ? JSON.stringify({...options,onSession:undefined,prompt:promptText})
+    : nativeSession ? JSON.stringify({...launchOptions,onSession:undefined,prompt:promptText})
     : gui ? JSON.stringify({prompt:promptText,options:{...options,onSession:undefined}})
     : ['codex', 'claude'].includes(key) ? promptText : undefined)
   const timeout = options.timeoutMs > 0 ? setTimeout(() => terminateJob(child), options.timeoutMs) : undefined

package/src/host-executor.ts

@@ -7,7 +7,8 @@ import { mkdir, readFile, writeFile, readdir, rename, rm, appendFile, realpath }
 import path from 'node:path'
 import { isHostRunId } from './host-executor-protocol.js'
 import { fileURLToPath } from 'node:url'
-import { startExecutorJob, terminateJob, resolveExecutor, type ExecutorOptions } from './executor.js'
+import { startExecutorJob, terminateJob, resolveExecutor, validateCodexProvider, type CodexProviderBinding, type ExecutorOptions } from './executor.js'
+import { parseIsolationClass, type IsolationClass } from './isolation.js'
 import { readModels, validateSelection } from './ai.js'
 import type { ChildProcess } from 'node:child_process'
 import { taskWorkspace } from './task-workspace.js'
@@ -16,12 +17,14 @@ import { installedPluginVersions } from './software-status.js'
 import { processSnapshot } from './process-tree.js'
 
 export type PluginNetworkRoute = { revisions:string[]; bindings:{service:string;network:string}[] }
-export type HostBinding = { name: string; workspace: string; controlDir: string; binDir: string; toolsHome?: string; sharedWorkspace?: string; additionalWorkspaces?: string[]; pluginNetworkBindings?: Record<string, PluginNetworkRoute> }
-export type HostInstallation = { cli: string; agents: HostBinding[] }
+export type HostBinding = { name: string; workspace: string; controlDir: string; binDir: string; toolsHome?: string; sharedWorkspace?: string; additionalWorkspaces?: string[]; pluginNetworkBindings?: Record<string, PluginNetworkRoute>; pluginFolderRoots?: Record<string,string[]>; codexProviders?: CodexProviderBinding[] }
+export type HostInstallation = { cli: string; isolation?: IsolationClass; agents: HostBinding[] }
 
 const processStart = async (pid:number) => (await processSnapshot()).get(pid)?.birth
 
 export const serveHostExecutor = async (installation: HostInstallation, signal: AbortSignal, launch = startExecutorJob) => {
+  if (installation.isolation !== undefined) parseIsolationClass(installation.isolation)
+  if (installation.isolation === 'isolated') throw new Error('Isolated agents run the native CLI in the relay; do not start host transport')
   resolveExecutor(installation.cli)
   if (new Set(installation.agents.map(a=>a.workspace)).size !== installation.agents.length ||
       new Set(installation.agents.map(a=>a.controlDir)).size !== installation.agents.length)
@@ -31,10 +34,17 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
   const locks: string[] = []
   const sharedWorkspaces = new Map<HostBinding, string>()
   const additionalWorkspaces = new Map<HostBinding, string[]>()
-  const catalog = (agent: HostBinding) => readModels(undefined, undefined, path.join(agent.controlDir, 'cli', 'codex'))
+  const catalog = async (agent: HostBinding) => {
+    const discovered = await readModels(undefined, undefined, path.join(agent.controlDir, 'cli', 'codex'))
+    const providers = (agent.codexProviders ?? []).map(validateCodexProvider)
+    const declared = providers.flatMap(provider => provider.models.map(model => ({cli:'codex',provider:provider.id,model,name:`${provider.name} · ${model}`.slice(0,80),efforts:[]})))
+    return [...discovered, ...declared]
+  }
   try {
     for (const agent of installation.agents) {
       if (![agent.workspace,agent.controlDir,agent.binDir].every(path.isAbsolute)) throw new Error('Host bindings require absolute paths')
+      const providers=(agent.codexProviders ?? []).map(validateCodexProvider)
+      if (new Set(providers.map(provider=>provider.id)).size !== providers.length) throw new Error('Codex provider IDs must be unique')
       if (agent.sharedWorkspace && !path.isAbsolute(agent.sharedWorkspace)) throw new Error('Shared workspace requires an absolute path')
       if (agent.sharedWorkspace) sharedWorkspaces.set(agent, await realpath(agent.sharedWorkspace))
       if (agent.additionalWorkspaces) {
@@ -129,10 +139,19 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
               const opts=request.options as ExecutorOptions
               const cli = opts.cli || installation.cli
               resolveExecutor(cli)
-              if (cli !== installation.cli) await validateSelection({id:'selected',name:'Selected model',cli,model:opts.model,effort:opts.effort},await catalog(agent))
+              const provider = cli === 'codex' && opts.provider
+                ? (agent.codexProviders ?? []).map(validateCodexProvider).find(candidate=>candidate.id===opts.provider)
+                : undefined
+              if (opts.provider && !provider) throw new Error('Selected Codex provider is not installed for this agent')
+              const model = opts.model
+              if (provider && !model) throw new Error('Selected Codex provider requires a declared model')
+              if (provider && model && !provider.models.includes(model)) throw new Error('Selected model is not declared for this Codex provider')
+              if (!provider && model && (agent.codexProviders ?? []).some(binding=>binding.models.includes(model)))
+                throw new Error('Selected Codex provider is required for this model')
+              if (cli !== installation.cli) await validateSelection({id:'selected',name:'Selected model',cli,provider:opts.provider,model,effort:opts.effort},await catalog(agent))
               const options:ExecutorOptions={workspace:run?.scheduled ? await taskWorkspace(agent.workspace,id) : agent.workspace,controlDir:agent.controlDir,binDir:agent.binDir,toolsHome:agent.toolsHome,sharedWorkspace,additionalWorkspaces:additionalWorkspaces.get(agent),cli,
                 runId:path.basename(base),timeoutMs:0,repairEnabled:opts.repairEnabled,
-                sessionId:opts.sessionId,isResume:opts.isResume,eventSource:opts.eventSource,model:opts.model,effort:opts.effort,codexAutoCompactTokens:opts.codexAutoCompactTokens}
+                sessionId:opts.sessionId,isResume:opts.isResume,eventSource:opts.eventSource,model,effort:opts.effort,provider:opts.provider,codexAutoCompactTokens:opts.codexAutoCompactTokens,codexProvider:provider}
               job=await launch(request.texts,options)
               active.set(base,job.child)
               await writeFile(base+'.process.json',JSON.stringify({pid:job.child.pid}),{mode:0o600})

package/src/index.ts

@@ -240,6 +240,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           cli: selected.cli,
           model: selected.model,
           effort: selected.effort,
+          provider: selected.provider,
           codexAutoCompactTokens: config.codexAutoCompactTokens,
           codexSandbox: !run.taskId && selected.cli === 'codex' ? config.codexSandbox : undefined,
           sessionId: session.nativeSessionId || session.sessionId,

package/src/install-config.ts

@@ -11,7 +11,7 @@ const inside = (parent: string, child: string) => {
 }
 
 // Configuration only: no provider calls, owner approval, service start, or AI turn.
-export const configureInstallation = async (directory: string, cli: string, token?: string) => {
+export const configureInstallation = async (directory: string, cli: string, token?: string, purposeFile?: string) => {
   let executor: string
   try { executor = resolveExecutor(cli).name }
   catch { throw new Error('Unsupported executor. See ezenciel-agents-setup status.') }
@@ -44,7 +44,7 @@ export const configureInstallation = async (directory: string, cli: string, toke
     if (!quote) throw new Error('Existing .env has a value requiring manual quoting; it was not changed.')
     return `${key}=${quote}${value}${quote}\n`
   }).join('')
-  const created = await initializeWorkspace(workspace)
+  const created = await initializeWorkspace(workspace, purposeFile)
   const temporary = `${envFile}.${randomUUID()}.tmp`
   try {
     await writeFile(temporary, content, { mode: 0o600, flag: 'wx' })

package/src/install-tools.mjs

@@ -49,7 +49,9 @@ export async function installationStatus(deployment) {
   const paired=Boolean(owner&&Number.isSafeInteger(owner.telegramUserId)&&owner.telegramUserId>0&&Number.isSafeInteger(owner.telegramChatId)&&(owner.kind==='group'?owner.telegramChatId<0:owner.kind===undefined&&owner.telegramChatId>0)&&Number.isFinite(Date.parse(owner.pairedAt)));
   const relay=await read(path.join(control,'heartbeat.json')).catch(absent),host=await read(path.join(control,'host-executor/heartbeat.json')).catch(absent);
   const fresh=(h,ms)=>Boolean(h&&Number.isFinite(h.at)&&h.at<=Date.now()+1000&&Date.now()-h.at<ms);
-  const runtimeReady=Boolean(relay?.polling&&fresh(relay,20000)&&fresh(host,15000));
+  let isolated=false;
+  try { isolated=(await read(path.join(deployment,'agent.json'))).isolation==='isolated'; } catch { isolated=false; }
+  const runtimeReady=Boolean(relay?.polling&&fresh(relay,20000)&&(isolated||fresh(host,15000)));
   let reply=null;
   if(paired)for(const name of await fs.readdir(path.join(control,'outbox')).catch(e=>{if(e.code==='ENOENT')return [];throw e;})) {
     if(!name.endsWith('.sent.json'))continue;

package/src/isolation.ts

@@ -0,0 +1,25 @@
+export type IsolationClass = 'isolated' | 'host-capable'
+
+export const isolationTransport = (isolation: IsolationClass): 'local' | 'host' =>
+  isolation === 'host-capable' ? 'host' : 'local'
+
+export const parseIsolationClass = (value: string): IsolationClass => {
+  if (value !== 'isolated' && value !== 'host-capable') throw new Error('Isolation must be isolated or host-capable')
+  return value
+}
+
+// Isolated runs the native CLI in the relay. Host-capable reuses the installer UID.
+// Unlabeled host transport stays host-capable so existing deployments are not flipped.
+export const resolveIsolation = (env: NodeJS.ProcessEnv = process.env): IsolationClass => {
+  const labeled = env.EZ_ISOLATION?.trim()
+  if (labeled) parseIsolationClass(labeled)
+  const transport = env.EZ_EXECUTOR_TRANSPORT?.trim() || ''
+  if (env.EZ_CHANNEL_BACKEND_URL?.trim()) {
+    if (labeled === 'host-capable' || transport === 'host') throw new Error('Host-capable isolation requires the host native CLI, not a channel backend')
+    return labeled ? parseIsolationClass(labeled) : 'isolated'
+  }
+  const isolation = labeled ? parseIsolationClass(labeled) : transport === 'host' ? 'host-capable' : 'isolated'
+  const expected = isolationTransport(isolation)
+  if ((transport || expected) !== expected) throw new Error(`Isolation ${isolation} requires EZ_EXECUTOR_TRANSPORT=${expected}`)
+  return isolation
+}

package/src/menu.ts

@@ -23,7 +23,7 @@ export const mainKeyboard = () => new InlineKeyboard()
 const clientLabel = (cli: string) => cli === 'codex-gui' ? 'codex-gui (desktop)' : cli
 
 const matchesModel = (preset: AiPreset, model: ModelChoice) =>
-  model.cli === preset.cli && (preset.model === undefined || model.model === preset.model) &&
+  model.cli === preset.cli && model.provider === preset.provider && (preset.model === undefined || model.model === preset.model) &&
   (preset.effort === undefined || model.efforts.includes(preset.effort))
 
 // Short-lived opaque button IDs: no model names or executable arguments from callbacks.
@@ -38,8 +38,11 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     assertEffort(preset.effort, preset.model, preset.cli)
     if (preset.id === initial.id) return
     if (preset.id.startsWith('detected_')) {
-      const detected = await discoverDefaults(workspace, { codexHome })
-      if (!detected.some((p) => p.id === preset.id)) throw new Error('Client settings changed. Refresh available AIs and select the updated choice.')
+      if (host) await validateSelection(preset, await catalog(), async name => (await catalog()).some(model => model.cli === name))
+      else {
+        const detected = await discoverDefaults(workspace, { codexHome })
+        if (!detected.some((p) => p.id === preset.id)) throw new Error('Client settings changed. Refresh available AIs and select the updated choice.')
+      }
     } else await validateSelection(preset, await catalog(), host ? async name => (await catalog()).some(model => model.cli === name) : isInstalled)
   }
   const buttons = new Map<string, { expires: number; action: (ctx: Context) => Promise<void> }>()
@@ -56,7 +59,7 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     const state = (await control.status()).ai
     if (!state) throw new Error('AI settings not initialized')
     const current = state.presets.find((p) => p.id === state.selectedId)!
-    const fresh = current.cli !== preset.cli || Boolean(session && !session.cli)
+    const fresh = current.cli !== preset.cli || current.provider !== preset.provider || Boolean(session && !session.cli)
     if (!await control.selectPreset(preset.id, expectedSession, fresh, guard)) throw new Error('AI binding changed. Refresh available AIs before trying again.')
     return { preset, fresh }
   }
@@ -116,9 +119,9 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
     const state = (await control.status()).ai
     if (!state) throw new Error('AI settings not initialized')
     const candidate: AiPreset = { id: randomBytes(8).toString('hex'),
-      name: `${model.name}${effort ? ` · ${effort}` : ''}`.slice(0, 80), cli: model.cli, model: model.model, effort }
+      name: `${model.name}${effort ? ` · ${effort}` : ''}`.slice(0, 80), cli: model.cli, provider:model.provider, model: model.model, effort }
     const stored = persistedPreset(candidate)
-    const existing = state.presets.find((preset) => preset.cli === stored.cli && preset.model === stored.model && preset.effort === stored.effort)
+    const existing = state.presets.find((preset) => preset.cli === stored.cli && preset.provider === stored.provider && preset.model === stored.model && preset.effort === stored.effort)
     const preset = existing ?? candidate
     await validateSelection(preset, await catalog(), host ? async name => (await catalog()).some(model => model.cli === name) : isInstalled)
     await control.savePreset(preset, guard)

package/src/plugins/manager.mjs

@@ -188,10 +188,49 @@ export function folderMounts(config, record) {
   }
   return mounts;
 }
-export async function checkFolders(config, record) {
+async function hostFolderRoots(config, record, home) {
+  const configuredHost = config.hostConfig ?? (typeof config.deploymentDir === 'string' && path.isAbsolute(config.deploymentDir) ? path.join(config.deploymentDir, 'host-executor.json') : undefined);
+  if (configuredHost === undefined) return null;
+  if (!home || typeof configuredHost !== 'string' || !path.isAbsolute(configuredHost)) throw Error('Invalid host folder binding');
+  home = realpathSync(home);
+  const hostConfig = realpathSync(configuredHost);
+  if (hostConfig !== configuredHost || path.basename(hostConfig) !== 'host-executor.json' || childOf(hostConfig, home))
+    throw Error('Host folder bindings require an external host config');
+  const host = JSON.parse(readFileSync(hostConfig, 'utf8'));
+  if (!host || typeof host !== 'object' || !Array.isArray(host.agents)) throw Error('Invalid host folder bindings');
+  const candidates = host.agents.filter(agent => agent && typeof agent === 'object' && typeof agent.toolsHome === 'string' && realpathSync(agent.toolsHome) === home);
+  if (candidates.length !== 1) throw Error('Host folder binding does not belong to this registry');
+  const agent = candidates[0], deployment = path.dirname(hostConfig);
+  if (typeof agent.workspace !== 'string' || typeof agent.controlDir !== 'string' ||
+      realpathSync(agent.workspace) !== config.workspace || realpathSync(path.join(deployment, 'mind')) !== config.workspace ||
+      realpathSync(path.join(deployment, 'control')) !== realpathSync(agent.controlDir) ||
+      childOf(hostConfig, config.workspace) || childOf(hostConfig, realpathSync(agent.controlDir)))
+    throw Error('Invalid host folder binding deployment');
+  const configured = agent.pluginFolderRoots;
+  if (configured !== undefined && (!configured || typeof configured !== 'object' || Array.isArray(configured)))
+    throw Error('Invalid host folder roots');
+  for (const [plugin, roots] of Object.entries(configured || {})) {
+    id(plugin); strings(roots);
+    for (const root of roots) {
+      if (!path.isAbsolute(root) || root === '/' || realpathSync(root) !== root) throw Error('Invalid host folder root');
+      if (!((await fs.stat(root)).isDirectory())) throw Error('Invalid host folder root');
+    }
+  }
+  const roots = [config.workspace];
+  if (agent.sharedWorkspace !== undefined) {
+    if (typeof agent.sharedWorkspace !== 'string' || !path.isAbsolute(agent.sharedWorkspace)) throw Error('Invalid shared workspace folder root');
+    roots.push(realpathSync(agent.sharedWorkspace));
+  }
+  roots.push(...(configured?.[record.manifest.id] || []).map(root => realpathSync(root)));
+  return roots;
+}
+export async function checkFolders(config, record, home) {
+  const allowed = await hostFolderRoots(config, record, home);
   for (const { source } of folderMounts(config, record)) {
     if (await fs.realpath(source) !== source || !(await fs.stat(source)).isDirectory())
       throw Error('Folder source must remain an existing real directory');
+    if (allowed && !allowed.some(root => childOf(source, root)))
+      throw Error('Folder source is not granted to this agent');
   }
 }
 const childOf = (candidate, parent) => candidate === parent || candidate.startsWith(parent + path.sep);
@@ -346,7 +385,7 @@ export async function prepareCommand(home,alias,args,{revision,exclude,publish,i
     const record=r.plugins[r.commands[alias]],binding=record?.deployment.commands[alias];
     if(!binding||r.commands[alias]===exclude)throw Error('Unknown or unavailable registered CLI');
     if(revision!==undefined&&revision!==record.revision)throw Error('Plugin changed; discover again');
-    await checkFolders(config,record);
+    await checkFolders(config,record,home);
     const secrets=await json(path.join(home,'packages',record.manifest.id,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
     await atomic(record.compose,await compose(config,record,secrets,home));
     const container=`${record.project}-call-${randomUUID()}`;
@@ -431,6 +470,10 @@ export async function main(args) {
   home=await fs.realpath(home);
   const config=await json(path.join(home,'config.json'));
   if(config.schemaVersion!==1 || !path.isAbsolute(config.workspace)) throw Error('Invalid binding');
+  if(config.hostConfig || config.deploymentDir) {
+    const cwd=await fs.realpath(process.cwd());
+    if(!childOf(cwd,config.workspace)) throw Error(`Registry belongs to ${config.workspace}; invoke its launcher only from that owning workspace`);
+  }
   const [group,action,...rest]=args;
   if(group==='status'){if(args.length!==1)throw Error('Use status without arguments');await registry(home);return emit(await (await import('../updates/status.mjs')).status(home));}
   if(group==='updates')return emit(await (await import('../updates/control.mjs')).command(home,args.slice(1)));
@@ -439,7 +482,7 @@ export async function main(args) {
     return (await import('./connection.mjs')).connect(home,rest[0],rest.slice(1),{publish:port,serve:true});
   }
   if(group==='tools'&&action==='connect')return (await import('./connection.mjs')).connect(home,rest[0],rest.slice(1));
-  if(group==='--help'||!group) return emit({commands:['status','updates check|policy|prepare|apply|status','plugins available|catalog-add|list|inspect|install|start|stop|status|logs|uninstall|export','tools list [--details]|exposure|connect <alias> <args...>|serve <host-port:container-port> <alias> <args...>','<registered CLI> ...'],scope:home});
+  if(group==='--help'||!group) return emit({commands:['status','updates check|policy|prepare|apply|status','plugins available|catalog-add|list|inspect|install|start|stop|status|logs|uninstall|export','tools list [--details]|exposure|connect <alias> <args...>|serve <host-port:container-port> <alias> <args...>','<registered CLI> ...'],foreignWorkspace:'Relay-bound registries run only from their owning agent workspace',scope:home});
   if(group==='plugins'&&(!action||args.includes('--help'))) return emit({commands:['available','list','inspect <id>','install <id>','start <id>','stop <id>','status <id>','logs <id>','uninstall <id>','catalog-add <id> --source PATH --revision HASH','export <id> <artifact> --output PATH','folder-bind <id> --service NAME --source PATH --target PATH [--writable]','folder-unbind <id> --service NAME --target PATH','folders <id>','shared-enable <id> <service>','shared-disable <id> <service>','shared-status <id> <service>'],uninstall:'Stops and removes containers/network and unregisters aliases; retains all volumes and secrets. No data deletion flag.',scope:home});
   if(group==='plugins'||group==='tools') {
     args=rest;args=args.filter(a=>a!=='--json');
@@ -490,7 +533,7 @@ export async function main(args) {
         const folders=(settings.folders?.[name] || []).filter(f => f.service !== service || f.target !== target);
         if(action === 'folder-bind') folders.push({service,source,target,...(writable ? {writable:true} : {})});
         settings.folders={...settings.folders,[name]:folders};
-        await checkFolders(settings,latest);
+        await checkFolders(settings,latest,home);
         const secrets=await json(path.join(home,'packages',name,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
         const generated=await compose(settings,latest,secrets,home);
         await atomic(path.join(home,'config.json'),settings);
@@ -506,7 +549,7 @@ export async function main(args) {
         const current = await registry(home), latest = current.plugins[name];
         if (latest?.revision !== record.revision) throw Error('Plugin changed during shared service request');
         const currentConfig=await json(path.join(home,'config.json'));
-        await checkFolders(currentConfig, latest);
+        await checkFolders(currentConfig, latest,home);
         const result = action === 'shared-enable' ? await sharedService(latest, key, 'enable', run) : { state: 'detached' };
         latest.sharedEnabled = [...new Set([...(latest.sharedEnabled || []).filter(k => k !== key), ...(action === 'shared-enable' ? [key] : [])])];
         const secrets = await json(path.join(home, 'packages', name, 'secrets.json')).catch(e => { if (e.code === 'ENOENT') return {}; throw e; });
@@ -534,7 +577,7 @@ export async function main(args) {
       const current=await registry(home);if(current.plugins[name]?.revision!==record.revision)throw Error('Plugin changed during lifecycle request');
       if(action==='start') {
         const currentConfig=await json(path.join(home,'config.json'));
-        await checkFolders(currentConfig,current.plugins[name]);
+        await checkFolders(currentConfig,current.plugins[name],home);
         const secrets=await json(path.join(home,'packages',name,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
         await atomic(record.compose,await compose(currentConfig,current.plugins[name],secrets,home));
       }

package/src/reply-context.ts

@@ -20,7 +20,6 @@ export async function ownerConversationContext(controlDir: string, run: RunRecor
       try { const item = JSON.parse(await readFile(join(controlDir, 'outbox', file), 'utf8')); if (item.chatId === run.chatId && recentResults.some(r => r.id === item.runId)) messages.push({ runId: item.runId, text: item.text, createdAt: item.createdAt }) } catch {}
     }
     return { request: run.texts, selectedAI: run.execution?.preset, recent: recent.map(r => ({ id: r.id, texts: r.texts.join('\n').slice(-1600), status: r.status })), replies: messages.sort((a,b) => String(a.createdAt).localeCompare(String(b.createdAt))).slice(-8).map(m => ({...m,text:String(m.text || '').slice(-2400)})),
-      agent: workspace ? await snapshot(join(workspace, 'SOUL.md')) : undefined, owner: workspace ? await snapshot(join(workspace, 'USER.md')) : undefined,
       work: await Promise.all(active.map(async r => ({ id: r.id, name: r.scheduled?.id, status: r.status, startedAt: r.startedAt, endedAt: r.endedAt,
         request: r.texts.join('\n').slice(0,800), exitCode: r.exitCode, failureReason: r.failureReason, interrupted: r.interrupted,
         hostStarted: await snapshot(join(controlDir, 'host-executor', r.id + '.process.json')) ? true : await snapshot(join(controlDir, 'host-executor', r.id + '.request.json')) ? false : undefined,

package/src/setup.ts

@@ -113,7 +113,7 @@ export const runCli = async (): Promise<void> => {
   const envFilePath = path.resolve(process.cwd(), '.env')
 
   if (args[0] === '--help' || args[0] === '-h') {
-    console.log('Usage: ezenciel-agents-setup configure <executor> [--token-stdin] | service | init | status | <executor>\nconfigure writes private .env paths and seeds missing mind files; it does not start or pair the bot.\n--token-stdin accepts the BotFather token without putting it in command arguments or output.\nservice starts only the Docker Compose relay bound by docker.env in the current directory. It does not install the host-executor service; follow docs/host-service.md. It does not pair the owner.\nFollow docs/setup.md through a real Telegram reply; package installation alone is incomplete.')
+    console.log('Usage: ezenciel-agents-setup configure <executor> [--purpose-file PATH] [--token-stdin] | service | init [--purpose-file PATH] | status | <executor>\nFresh workspace setup requires a concise purpose file written from the owner request. configure writes private .env paths and seeds missing mind files; it does not start or pair the bot.\n--token-stdin accepts the BotFather token without putting it in command arguments or output.\nservice starts only the Docker Compose relay bound by docker.env in the current directory. It does not install the host-executor service; follow docs/host-service.md. It does not pair the owner.\nFollow docs/setup.md through a real Telegram reply; package installation alone is incomplete.')
     return
   }
 
@@ -124,10 +124,13 @@ export const runCli = async (): Promise<void> => {
   }
 
   if (args[0] === 'configure') {
-    if (!args[1] || args.length > 3 || (args[2] && args[2] !== '--token-stdin'))
-      throw new Error('Usage: ezenciel-agents-setup configure <executor> [--token-stdin]')
+    const tail = args.slice(2), purposeAt = tail.indexOf('--purpose-file'), tokenAt = tail.indexOf('--token-stdin')
+    const purposeFile = purposeAt >= 0 ? tail[purposeAt + 1] : undefined
+    const consumed = new Set([...(purposeAt >= 0 ? [purposeAt, purposeAt + 1] : []), ...(tokenAt >= 0 ? [tokenAt] : [])])
+    if (!args[1] || (purposeAt >= 0 && !purposeFile) || tail.some((_, index) => !consumed.has(index)))
+      throw new Error('Usage: ezenciel-agents-setup configure <executor> [--purpose-file PATH] [--token-stdin]')
     let token: string | undefined
-    if (args[2]) {
+    if (tokenAt >= 0) {
       if (process.stdin.isTTY) throw new Error('Supply the token through stdin, not a command argument.')
       let input = ''
       for await (const chunk of process.stdin) {
@@ -136,14 +139,15 @@ export const runCli = async (): Promise<void> => {
       }
       token = input.trim()
     }
-    console.log(JSON.stringify(await configureInstallation(process.cwd(), args[1], token)))
+    console.log(JSON.stringify(await configureInstallation(process.cwd(), args[1], token, purposeFile && path.resolve(purposeFile))))
     return
   }
 
   if (args[0] === 'init') {
-    if (args.length !== 1) throw new Error('Usage: ezenciel-agents-setup init (uses EZ_AGENT_WORKSPACE or ./agent)')
+    if (args.length !== 1 && !(args.length === 3 && args[1] === '--purpose-file'))
+      throw new Error('Usage: ezenciel-agents-setup init [--purpose-file PATH] (uses EZ_AGENT_WORKSPACE or ./agent)')
     const workspace = path.resolve(process.env.EZ_AGENT_WORKSPACE?.trim() || './agent')
-    const created = await initializeWorkspace(workspace)
+    const created = await initializeWorkspace(workspace, args[2] && path.resolve(args[2]))
     const config = loadControlConfig()
     await new ControlStore(config.controlDir, config.pairingTtlMs).syncClientPresets(
       chatPreset(await readActiveExecutor(envFilePath)), await discoverDefaults(workspace,

package/src/task-executor.ts

@@ -53,7 +53,10 @@ export async function startTaskExecutor(options: ExecutorOptions) {
     await mkdir(directory, { mode: 0o700 }); await mkdir(home, { mode: 0o700 })
     const catalog = await promisify(execFile)('codex', ['debug', 'models', '--bundled'], { env: environment, maxBuffer: 4 * 1024 * 1024 })
     await writeFile(join(temporary, 'models.json'), JSON.stringify(taskModelCatalog(JSON.parse(catalog.stdout))), { mode: 0o600 })
-    await symlink(join(homedir(), '.codex', 'auth.json'), join(home, 'auth.json'))
+    const auth = process.env.EZ_ISOLATION === 'isolated'
+      ? join(options.controlDir, 'cli', 'codex', 'auth.json')
+      : join(homedir(), '.codex', 'auth.json')
+    await symlink(auth, join(home, 'auth.json'))
     const broker = [process.execPath, '--import', fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs', import.meta.url)),
       fileURLToPath(new URL('./task-mcp.ts', import.meta.url)), options.controlDir, options.runId, options.toolsHome ?? '', JSON.stringify(task.capabilities ?? [])]
     const prompt = JSON.stringify({event: run.external ? 'correspondence_received' : 'task_activated', taskId: run.taskId})

package/src/updates/control.mjs

@@ -44,6 +44,14 @@ export async function check(home) {
   }
   return results;
 }
+const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'?Object.fromEntries(Object.keys(value).sort().map(key=>[key,canonical(value[key])])):value;
+const same=(left,right)=>JSON.stringify(canonical(left))===JSON.stringify(canonical(right));
+function additiveCommands(previous,next) {
+  const before={...previous,commands:{}},after={...next,commands:{}};
+  if(!same(before,after))return false;
+  for(const [name,command] of Object.entries(previous.commands||{}))if(!same(next.commands?.[name],command))return false;
+  return Object.values(next.commands||{}).every(command=>next.services?.[command.service]);
+}
 export async function eligibility(home,target,root,automatic) {
   const old=await installed(home,target),pkg=await read(path.join(root,'package.json')),kind=target==='main'?'main':'plugin';
   if(pkg.name!==old.pkg.name)throw Error('Package identity mismatch');
@@ -54,7 +62,9 @@ export async function eligibility(home,target,root,automatic) {
   if(kind==='plugin') {
     const s=await snapshot(root);revision=s.revision;
     if(s.manifest.id!==target||s.manifest.version!==pkg.version)throw Error('Plugin identity/version mismatch');
-    if(JSON.stringify(s.deployment)!==JSON.stringify(old.record.deployment))throw Error('Deployment permissions/layout changed; a separately reviewed migration is required');
+    if(!additiveCommands(old.record.deployment,s.deployment))throw Error('Deployment permissions/layout changed; a separately reviewed migration is required');
+    const registry=await read(path.join(home,'registry.json'));
+    for(const alias of Object.keys(s.manifest.commands))if(registry.commands[alias]&&registry.commands[alias]!==target)throw Error('CLI alias collision');
   }else {
     for(const file of ['compose.yaml','compose.whatsapp.yaml'])if(!Buffer.from(await fs.readFile(path.join(root,file))).equals(await fs.readFile(path.join(old.root,file))))throw Error('Runtime deployment changed; a separately reviewed migration is required');
   }

package/src/updates/runtime.mjs

@@ -111,7 +111,7 @@ export async function perform(home,job,hooks) {
       const secrets=await read(path.join(home,'packages',job.target,'secrets.json')).catch(e=>{if(e.code==='ENOENT')return {};throw e;});
       const s=await snapshot(root),candidate={...old,source:root,revision:s.revision,manifest:s.manifest,deployment:s.deployment,sharedRevisions:s.sharedRevisions};
       for (const key of old.sharedEnabled || []) if (sharedIdentity(old, key).fingerprint !== sharedIdentity(candidate, key).fingerprint) throw Error('Shared worker changed; disable this client and coordinate an explicit shared worker upgrade before updating');
-      await checkFolders(config,candidate);
+      await checkFolders(config,candidate,home);
       const stage={...candidate,compose:path.join(dir,'compose.json')};await atomic(stage.compose,await compose(config,stage,secrets,home));
       for(const [service,spec] of Object.entries(stage.deployment.services))await run('docker',[...pluginArgs(stage),spec.image?'pull':'build',service]);
       const running=Boolean((await run('docker',[...pluginArgs(old),'ps','-q'])).trim());
@@ -122,7 +122,9 @@ export async function perform(home,job,hooks) {
       for(const name of volumes)await backupVolume(run,old,name,backup);
       await atomic(old.compose,await compose(config,candidate,secrets,home));
       if(running)await run('docker',[...pluginArgs(candidate),'up','-d','--wait','--wait-timeout','90','--no-build']);
-      r.plugins[job.target]=candidate;await atomic(path.join(home,'registry.json'),r);
+      r.plugins[job.target]=candidate;
+      for(const alias of Object.keys(candidate.manifest.commands))r.commands[alias]=job.target;
+      await atomic(path.join(home,'registry.json'),r);
       job.runtimeVerified=running;
     }
     job.status='completed';job.endedAt=new Date().toISOString();await save();return job;