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

package/test/codex-context.test.ts

@@ -6,15 +6,67 @@ import {tmpdir} from 'node:os'
 import path from 'node:path'
 import {startExecutorJob} from '../src/executor.js'
 
+test('a package-bin Codex shim cannot retarget another agent home', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-codex-host-cli-'))
+  const hostBin = path.join(root, 'host-bin')
+  const packageBin = path.join(root, 'package-bin')
+  const controlDir = path.join(root, 'agent')
+  const priorHome = process.env.HOME, priorPath = process.env.PATH
+  try {
+    await mkdir(hostBin); await mkdir(packageBin); await mkdir(path.join(root, '.codex'))
+    await writeFile(path.join(root, '.codex/auth.json'), '{}')
+    await writeFile(path.join(packageBin, 'codex'), `#!${process.execPath}
+require('fs').writeFileSync(require('path').join(process.env.HOME, 'hijacked'), 'yes'); process.exit(2)
+`, { mode: 0o700 })
+    await writeFile(path.join(hostBin, 'codex'), `#!${process.execPath}\nconsole.log(process.env.CODEX_HOME)`, { mode: 0o700 })
+    process.env.HOME = root
+    process.env.PATH = hostBin + path.delimiter + (priorPath ?? '')
+    await ownerRun(controlDir, 'r_test')
+    const job = await startExecutorJob(['hello'], {
+      workspace: root, controlDir, binDir: packageBin, cli: 'codex', runId: 'r_test', timeoutMs: 5000,
+    })
+    let output = ''
+    job.child.stdout?.on('data', chunk => output += chunk)
+    assert.equal(await new Promise(resolve => job.child.once('close', resolve)), 0)
+    await job.cleanup()
+    assert.equal(output.trim(), path.join(controlDir, 'cli/codex'))
+    await assert.rejects(readFile(path.join(root, 'hijacked')))
+  } finally {
+    if (priorHome === undefined) delete process.env.HOME; else process.env.HOME = priorHome
+    if (priorPath === undefined) delete process.env.PATH; else process.env.PATH = priorPath
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
+test('a package-bin Codex shim is not a fallback when the host CLI is missing', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-codex-host-cli-missing-'))
+  const packageBin = path.join(root, 'package-bin')
+  const controlDir = path.join(root, 'agent')
+  const priorPath = process.env.PATH
+  try {
+    await mkdir(packageBin)
+    await writeFile(path.join(packageBin, 'codex'), `#!${process.execPath}\nprocess.exit(91)\n`, { mode: 0o700 })
+    process.env.PATH = '/usr/bin:/bin'
+    await ownerRun(controlDir, 'r_test')
+    await assert.rejects(startExecutorJob(['hello'], {
+      workspace: root, controlDir, binDir: packageBin, cli: 'codex', runId: 'r_test', timeoutMs: 5000,
+    }), /Native CLI codex is not executable on the host PATH/)
+  } finally {
+    if (priorPath === undefined) delete process.env.PATH; else process.env.PATH = priorPath
+    await rm(root, { recursive: true, force: true })
+  }
+})
+
 test('Codex shares only auth through a link and keeps each agent runtime state separate',async()=>{
  const root=await mkdtemp(path.join(tmpdir(),'ez-codex-context-'))
- const priorHome=process.env.HOME,priorPath=process.env.PATH
+ const priorHome=process.env.HOME,priorPath=process.env.PATH,priorIsolation=process.env.EZ_ISOLATION
  try{
   await mkdir(path.join(root,'.codex'));await mkdir(path.join(root,'bin'))
   await writeFile(path.join(root,'.codex/auth.json'),'{}')
   await writeFile(path.join(root,'.codex/config.toml'),'# unrelated personal config')
   await writeFile(path.join(root,'bin/codex'),`#!${process.execPath}\nconsole.log(process.env.CODEX_HOME)`,{mode:0o700})
   process.env.HOME=root;process.env.PATH=path.join(root,'bin')+path.delimiter+priorPath
+  delete process.env.EZ_ISOLATION
   for(const agent of ['one','two']){
    const controlDir=path.join(root,agent)
    await ownerRun(controlDir, 'r_test')
@@ -27,9 +79,17 @@ test('Codex shares only auth through a link and keeps each agent runtime state s
    assert.deepEqual(await readdir(home),['auth.json'])
    assert.equal(await readlink(path.join(home,'auth.json')),path.join(root,'.codex/auth.json'))
   }
+  process.env.EZ_ISOLATION='isolated'
+  const isolated=path.join(root,'isolated')
+  await ownerRun(isolated, 'r_test')
+  const isolatedJob=await startExecutorJob(['hello'],{workspace:root,controlDir:isolated,binDir:path.join(root,'bin'),cli:'codex',runId:'r_test',timeoutMs:5000})
+  assert.equal(await new Promise(resolve=>isolatedJob.child.once('close',resolve)),0)
+  await isolatedJob.cleanup()
+  await assert.rejects(readlink(path.join(isolated,'cli/codex/auth.json')),{code:'ENOENT'})
  }finally{
   if(priorHome===undefined)delete process.env.HOME;else process.env.HOME=priorHome
   if(priorPath===undefined)delete process.env.PATH;else process.env.PATH=priorPath
+  if(priorIsolation===undefined)delete process.env.EZ_ISOLATION;else process.env.EZ_ISOLATION=priorIsolation
   await rm(root,{recursive:true,force:true})
  }
 })

package/test/codex-session.test.ts

@@ -43,7 +43,8 @@ if(q.method==='thread/goal/get'){
     child.stdin.write=((chunk:any,...args:any[])=>{try{const q=JSON.parse(String(chunk));if(q.method==='turn/start'){turnPrompt=q.params.input[0].text;turnPolicy=q.params.sandboxPolicy}requests.push(q.method);if(q.method==='thread/start'){threadConfig=q.params.config;threadSandbox=q.params.sandbox}}catch{};return (write as any)(chunk,...args)}) as typeof child.stdin.write
     return child
   }
-  const result=await runCodexSession({workspace:'/tmp',controlDir:'/tmp/control',sharedWorkspace:'/canonical',additionalWorkspaces:['/agent/mind/work'],prompt,
+  const codexProvider=mode==='tool-goal'?{id:'openrouter',name:'OpenRouter',baseUrl:'https://openrouter.ai/api/v1',envKey:'OPENROUTER_API_KEY',models:['open/model']}:undefined
+  const result=await runCodexSession({workspace:'/tmp',controlDir:'/tmp/control',sharedWorkspace:'/canonical',additionalWorkspaces:['/agent/mind/work'],prompt,codexProvider,model:codexProvider?'open/model':undefined,
     ...(mode==='external'?{codexSandbox:'external' as const}:{})},{launch,emit:line=>output.push(line)})
   assert.equal(threadSandbox!,mode==='external'?'danger-full-access':'workspace-write')
   assert.deepEqual(turnPolicy,mode==='external'?{type:'externalSandbox',networkAccess:'enabled'}:undefined)
@@ -52,6 +53,10 @@ if(q.method==='thread/goal/get'){
   if(mode==='long-goal')assert.ok(prompt.length>4000)
   assert.ok(threadConfig['sandbox_workspace_write.writable_roots'].includes('/canonical'))
   assert.ok(threadConfig['sandbox_workspace_write.writable_roots'].includes('/agent/mind/work'))
+  if(codexProvider){
+    assert.equal(threadConfig.model_provider,'openrouter')
+    assert.deepEqual(threadConfig['model_providers.openrouter'],{name:'OpenRouter',base_url:'https://openrouter.ai/api/v1',env_key:'OPENROUTER_API_KEY',wire_api:'responses',supports_websockets:false})
+  }
   assert.equal(result,['external','plain','goal','long-goal','tool-goal'].includes(mode)?0:1)
   assert.equal(requests.filter(x=>x==='turn/start').length,1,'transport must not send goal continuation prompts')
   assert.equal(requests.filter(x=>x==='thread/goal/set').length,0)

package/test/config.test.ts

@@ -65,8 +65,23 @@ test('external Codex isolation requires explicit native local deployment', () =>
   assert.equal(loadConfig(env).codexSandbox, 'external')
   assert.equal(loadConfig({...env,EZ_TELEGRAM_ENABLED:'true',TELEGRAM_BOT_TOKEN:'test'}).codexSandbox, 'external')
   assert.equal(loadConfig({TELEGRAM_BOT_TOKEN:'test'}).codexSandbox, undefined)
-  for (const override of [{EZ_EXECUTOR_TRANSPORT:'host'}, {EZ_EXECUTOR_TRANSPORT:''}, {EZ_CODEX_SANDBOX:'danger-full-access'}])
-    assert.throws(() => loadConfig({...env,...override}), /sandbox|SANDBOX/)
+  assert.equal(loadConfig({...env,EZ_EXECUTOR_TRANSPORT:''}).isolation, 'isolated')
+  assert.throws(() => loadConfig({...env,EZ_EXECUTOR_TRANSPORT:'host'}), /sandbox|SANDBOX|Isolation/)
+  assert.throws(() => loadConfig({...env,EZ_CODEX_SANDBOX:'danger-full-access'}), /sandbox|SANDBOX/)
+})
+
+test('isolation class is isolated by default and rejects host transport mismatch', () => {
+  assert.equal(loadConfig({TELEGRAM_BOT_TOKEN:'test'}).isolation, 'isolated')
+  assert.equal(loadConfig({TELEGRAM_BOT_TOKEN:'test',EZ_ISOLATION:'isolated',EZ_EXECUTOR_TRANSPORT:'local'}).isolation, 'isolated')
+  assert.equal(loadConfig({TELEGRAM_BOT_TOKEN:'test',EZ_EXECUTOR_TRANSPORT:'host'}).isolation, 'host-capable')
+  assert.equal(loadConfig({TELEGRAM_BOT_TOKEN:'test',EZ_ISOLATION:'host-capable',EZ_EXECUTOR_TRANSPORT:'host'}).isolation, 'host-capable')
+  assert.throws(() => loadConfig({TELEGRAM_BOT_TOKEN:'test',EZ_ISOLATION:'isolated',EZ_EXECUTOR_TRANSPORT:'host'}), /Isolation isolated requires EZ_EXECUTOR_TRANSPORT=local/)
+  assert.throws(() => loadConfig({TELEGRAM_BOT_TOKEN:'test',EZ_ISOLATION:'host-capable',EZ_EXECUTOR_TRANSPORT:'local'}), /Isolation host-capable requires EZ_EXECUTOR_TRANSPORT=host/)
+  assert.throws(() => loadConfig({TELEGRAM_BOT_TOKEN:'test',EZ_ISOLATION:'seatbelt'}), /isolated or host-capable/)
+  assert.throws(() => loadConfig({
+    TELEGRAM_BOT_TOKEN:'test',EZ_ISOLATION:'host-capable',EZ_EXECUTOR_TRANSPORT:'host',
+    EZ_CHANNEL_BACKEND_URL:'https://backend.example',EZ_CHANNEL_BACKEND_TOKEN:'secret',
+  }), /Host-capable isolation requires the host native CLI/)
 })
 
 test('optional web launcher preserves reserved commands and accepts only HTTPS without secrets', () => {

package/test/engine-handoff.test.ts

@@ -13,7 +13,7 @@ test('owner, resumed and native scheduled subprocesses receive literal input and
  const root=await mkdtemp(path.join(tmpdir(),'ez-literal-'))
  t.after(()=>rm(root,{recursive:true,force:true}))
  const bin=path.join(root,'bin'),workspace=path.join(root,'mind'),controlDir=path.join(root,'control')
- await mkdir(bin);await initializeWorkspace(workspace)
+ await mkdir(bin);const purpose=path.join(root,'purpose.md');await writeFile(purpose,'Fixture agent\n');await initializeWorkspace(workspace,purpose)
  const fixture=`#!${process.execPath}
 const fs=require('fs'), args=process.argv.slice(2);
 const capture=prompt=>fs.writeFileSync('capture.json',JSON.stringify({prompt,args,env:{run:process.env.EZ_RUN_ID,control:process.env.EZ_CONTROL_DIR,repair:process.env.EZ_REPAIR_ENABLED,secret:process.env.TELEGRAM_BOT_TOKEN}}));
@@ -44,7 +44,10 @@ if(args[0]==='app-server'){
    const captured=JSON.parse(await readFile(path.join(workspace,'capture.json'),'utf8'))
    assert.equal(captured.prompt,text)
    assert.deepEqual(captured.env,{run:runId,control:controlDir,repair:'false'})
-   if(cli==='codex')assert.equal(captured.args.at(-1),'-')
+   if(cli==='codex'){
+    assert.equal(captured.args.at(-1),'-')
+    if(process.platform==='darwin')assert.equal(captured.args[captured.args.indexOf('--sandbox')+1],'danger-full-access')
+   }
    if(['codex','claude'].includes(cli))assert.ok(!captured.args.includes('--help'))
    if(cli==='opencode')assert.equal(captured.args.at(-2),'--')
    if(cli==='agy')assert.ok(captured.args.includes('--print='+text))

package/test/executor.test.ts

@@ -6,7 +6,7 @@ import { mkdtemp, mkdir, rm, writeFile, readFile } from 'node:fs/promises'
 import { spawn } from 'node:child_process'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
-import { EXECUTOR_REGISTRY, antigravityInvocation, executorEnvironment, grokInvocation, grokJobEnv, opencodeInvocation, resolveExecutor, startExecutorJob, terminateJob } from '../src/executor.js'
+import { EXECUTOR_REGISTRY, antigravityInvocation, executorEnvironment, grokInvocation, grokJobEnv, opencodeInvocation, resolveExecutor, resolveHostCommand, startExecutorJob, terminateJob, validateCodexProvider } from '../src/executor.js'
 import { splitTelegramText } from '../src/reply.js'
 import { matchingProcessIds, processSnapshot } from '../src/process-tree.js'
 
@@ -54,6 +54,11 @@ test('Telegram replies are split within the configured message limit', () => {
   assert.ok(chunks.every((chunk) => chunk.length <= 10))
 })
 
+test('native CLIs resolve from the host PATH, not a relative package name', () => {
+  assert.equal(resolveHostCommand('/usr/bin/codex'), '/usr/bin/codex')
+  assert.throws(() => resolveHostCommand('missing-cli-xyz', '/usr/bin'), /not executable on the host PATH/)
+})
+
 test('the executor receives a deliberately small environment', () => {
   const environment = executorEnvironment({ PATH: '/bin', HOME: '/tmp/home', TELEGRAM_BOT_TOKEN: 'secret', PAGERDUTY_ROUTING_KEY: 'secret', AWS_SECRET_ACCESS_KEY: 'secret' })
   assert.deepEqual(environment, { PATH: '/bin', HOME: '/tmp/home' })
@@ -158,6 +163,38 @@ test('Codex jobs disable global memory and host skill discovery', () => {
   assert.equal(args[args.indexOf('skip_host_skill_discovery')-1],'--enable')
 })
 
+test('Codex custom providers use declared runtime state and an environment key reference', () => {
+  const provider=validateCodexProvider({id:'openrouter',name:'OpenRouter',baseUrl:'https://openrouter.ai/api/v1/',envKey:'OPENROUTER_API_KEY',models:['google/gemini-3.8-flash']})
+  const args=EXECUTOR_REGISTRY.codex.buildArgs({workspace:'/agent',model:'google/gemini-3.8-flash',codexProvider:provider},'','hello')
+  assert.ok(args.includes('model_provider="openrouter"'))
+  assert.ok(args.some(value=>value.includes('env_key="OPENROUTER_API_KEY"')))
+  assert.ok(args.includes('google/gemini-3.8-flash'))
+  assert.equal(JSON.stringify(args).includes('provider-secret'),false)
+  assert.throws(()=>validateCodexProvider({...provider,envKey:'TELEGRAM-BOT'}),/environment key/)
+  for (const envKey of ['PATH','HOME','CODEX_HOME','NODE_OPTIONS','EZ_CONTROL_DIR','TELEGRAM_BOT_TOKEN','PAGERDUTY_ROUTING_KEY'])
+    assert.throws(()=>validateCodexProvider({...provider,envKey}),/Reserved/)
+  assert.throws(()=>validateCodexProvider({...provider,models:[]}),/provider models/)
+})
+
+test('a configured Codex provider receives only its declared key and runtime selection', async t => {
+  const root=await mkdtemp(path.join(tmpdir(),'ez-codex-provider-'));t.after(()=>rm(root,{recursive:true,force:true}))
+  const bin=path.join(root,'bin');await mkdir(bin)
+  await writeFile(path.join(bin,'codex'),`#!${process.execPath}\nconst fs=require('fs');let text='';process.stdin.on('data',b=>text+=b);process.stdin.on('end',()=>fs.writeFileSync(${JSON.stringify(path.join(root,'observed.json'))},JSON.stringify({args:process.argv.slice(2),key:process.env.OPENROUTER_API_KEY,telegram:process.env.TELEGRAM_BOT_TOKEN,text})));`,{mode:0o755})
+  const prior={path:process.env.PATH,key:process.env.OPENROUTER_API_KEY,telegram:process.env.TELEGRAM_BOT_TOKEN}
+  const provider=validateCodexProvider({id:'openrouter',name:'OpenRouter',baseUrl:'https://openrouter.ai/api/v1',envKey:'OPENROUTER_API_KEY',models:['google/gemini-3.8-flash']})
+  await ownerRun(root,'r_provider')
+  try {
+    process.env.PATH=bin+path.delimiter+prior.path;process.env.OPENROUTER_API_KEY='provider-secret';process.env.TELEGRAM_BOT_TOKEN='relay-secret'
+    const job=await startExecutorJob(['hello'],{workspace:root,controlDir:root,binDir:bin,runId:'r_provider',timeoutMs:0,cli:'codex',provider:'openrouter',model:'google/gemini-3.8-flash',codexProvider:provider})
+    assert.equal(await new Promise(resolve=>job.child.once('close',resolve)),0);await job.cleanup()
+    const observed=JSON.parse(await readFile(path.join(root,'observed.json'),'utf8'))
+    assert.equal(observed.key,'provider-secret');assert.equal(observed.telegram,undefined);assert.equal(observed.text,'hello')
+    assert.ok(observed.args.includes('model_provider="openrouter"'));assert.ok(observed.args.includes('google/gemini-3.8-flash'))
+  } finally {
+    for(const [key,value] of [['PATH',prior.path],['OPENROUTER_API_KEY',prior.key],['TELEGRAM_BOT_TOKEN',prior.telegram]]) if(value===undefined)delete process.env[key!];else process.env[key!]=value
+  }
+})
+
 test('Codex plugin access stays scoped to the explicitly bound registry', () => {
   const args=EXECUTOR_REGISTRY.codex.buildArgs({workspace:'/agent/mind',controlDir:'/agent/control',toolsHome:'/agent/tools',sharedWorkspace:'/app',additionalWorkspaces:['/agent/mind/work']},'', 'install a plugin')
   assert.deepEqual(args.flatMap((arg,i)=>arg==='--add-dir'?[args[i+1]]:[]),['/agent/control','/app','/agent/mind/work','/agent/tools'])

package/test/failure.test.ts

@@ -15,12 +15,14 @@ import { initialPreset } from '../src/ai.js'
 import { createRelay } from '../src/index.js'
 import { TelegramSource } from '../src/telegram-source.js'
 import { packageVersion } from '../src/version.js'
+import { initializeWorkspace } from '../src/workspace.js'
 import type { Update } from 'grammy/types'
 const exec=promisify(execFile),bin=fileURLToPath(new URL('../bin/ezenciel-agents-schedule.mjs',import.meta.url))
 // This integration test starts subprocesses, persists their receipts, and invokes
 // the schedule CLI. Give a busy CI worker time to settle without changing the
 // production recovery deadline.
 const until=async(check:()=>Promise<boolean>,timeoutMs=15_000)=>{const deadline=Date.now()+timeoutMs;while(!(await check())){if(Date.now()>=deadline)throw new Error(`Timed out after ${timeoutMs}ms`);await new Promise(r=>setTimeout(r,20))}}
+const seedWorkspace=async(dir:string)=>{const purpose=join(dir,'purpose.md');await writeFile(purpose,'Fixture relay agent\n');await initializeWorkspace(dir,purpose)}
 
 test('failure evidence is bounded and redacts configured credentials, headers, tokens, URLs and keys',()=>{
  const token='123456789:abcdefghijklmnopqrstuvwxyz123456789'
@@ -142,6 +144,7 @@ test('relay shutdown waits for executor cleanup and final run state', async () =
 
 test('a fresh relay initializes its bot identity before polling', async () => {
  const dir=await mkdtemp(join(tmpdir(),'ez-cold-start-'))
+ await seedWorkspace(dir)
  const relay=createRelay({workspace:dir,controlDir:dir,pairingTtlMs:1000,executorTimeoutMs:0,executorCli:'grok',telegramBotToken:'fixture'},async()=>{throw new Error('No executor expected')})
  const methods:string[]=[]
  relay.bot.api.config.use(async(_prev,method,_payload,signal)=>{
@@ -165,6 +168,7 @@ test('a fresh relay initializes its bot identity before polling', async () => {
 
 for (const cleanupFails of [false,true]) test(`polling conflict preserves work until an explicit shutdown (cleanup fails: ${cleanupFails})`, async t => {
  const dir=await mkdtemp(join(tmpdir(),'ez-polling-conflict-')),control=new ControlStore(dir,1000),runs=new RunStore(dir)
+ await seedWorkspace(dir)
  let release!:()=>void,entered!:()=>void,releaseDelivery!:()=>void,sending!:()=>void,child:ReturnType<typeof spawn>|undefined,polls=0
  const gate=new Promise<void>(resolve=>{release=resolve}),cleaning=new Promise<void>(resolve=>{entered=resolve})
  const deliveryGate=new Promise<void>(resolve=>{releaseDelivery=resolve}),deliveryStarted=new Promise<void>(resolve=>{sending=resolve})
@@ -285,6 +289,7 @@ test('group members can inspect failures and wake review without exposing other
 
 for (const failure of [400,401,503,'programming'] as const) test(`setup failure ${failure} retries only transient errors`,async t=>{
  const dir=await mkdtemp(join(tmpdir(),'ez-setup-failure-'))
+ await seedWorkspace(dir)
  const relay=createRelay({workspace:dir,controlDir:dir,pairingTtlMs:1000,executorTimeoutMs:0,executorCli:'grok',telegramBotToken:'fixture'},async()=>{throw Error('No executor expected')})
  let commands=0,polls=0
  relay.bot.botInfo={id:999,is_bot:true,first_name:'Fixture',username:'fixture_bot'} as any
@@ -310,6 +315,7 @@ for (const failure of [400,401,503,'programming'] as const) test(`setup failure
 
 test('shutdown aborts a pending bot initialization without starting polling',async()=>{
  const dir=await mkdtemp(join(tmpdir(),'ez-init-stop-'))
+ await seedWorkspace(dir)
  const relay=createRelay({workspace:dir,controlDir:dir,pairingTtlMs:1000,executorTimeoutMs:0,executorCli:'grok',telegramBotToken:'fixture'},async()=>{throw Error('No executor expected')})
  let initSignal:Parameters<typeof relay.bot.init>[0],polls=0
  relay.bot.api.config.use(async(_prev,method,_payload,signal)=>{

package/test/host-executor.test.ts

@@ -41,6 +41,12 @@ test('legacy host lock fails closed while its PID is alive',async()=>{
   }finally{await rm(root,{recursive:true,force:true})}
 })
 
+test('isolated installations cannot start host transport', async () => {
+  const abort=new AbortController()
+  await assert.rejects(serveHostExecutor({cli:'grok',isolation:'isolated',agents:[]},abort.signal),/Isolated agents run the native CLI in the relay/)
+  abort.abort()
+})
+
 test('host restart clears dead native lease only after proving previous CLI stopped',async()=>{
   const root=await mkdtemp(path.join(tmpdir(),'ez-native-recovery-'));
   const workspace=path.join(root,'mind'),controlDir=path.join(root,'control'),toolsHome=path.join(root,'tools'),directory=path.join(controlDir,'host-executor');

package/test/install-config.test.ts

@@ -14,8 +14,10 @@ test('configure preserves custom paths and unknown settings, keeps token private
   const root = await mkdtemp(path.join(tmpdir(), 'ez-configure-'))
   try {
     await writeFile(path.join(root, '.env'), 'EZ_AGENT_WORKSPACE="my mind"\nEZ_CONTROL_DIR="private control"\nEXTRA="keep me"\n')
+    const purpose = path.join(root, 'purpose.md')
+    await writeFile(purpose, 'Configured assistant\n')
     const token = '123456789:' + 'a'.repeat(30)
-    const result = await configureInstallation(root, 'codex', token)
+    const result = await configureInstallation(root, 'codex', token, purpose)
     assert.equal(result.tokenConfigured, true)
     assert.equal(JSON.stringify(result).includes(token), false)
     const env = parseEnv(await readFile(result.envFile, 'utf8'))
@@ -24,12 +26,12 @@ test('configure preserves custom paths and unknown settings, keeps token private
     assert.equal(env.EZ_AGENT_WORKSPACE, path.join(root, 'my mind'))
     assert.equal((await stat(result.envFile)).mode & 0o777, 0o600)
     assert.equal(await readActiveExecutor(result.envFile), 'codex')
-    const soul = path.join(result.workspace, 'SOUL.md')
-    await writeFile(soul, 'Customized purpose')
+    const agents = path.join(result.workspace, 'AGENTS.md')
+    await writeFile(agents, 'Customized purpose')
     const repeated = await configureInstallation(root, 'codex')
     assert.deepEqual(repeated.created, [])
     assert.equal(repeated.tokenConfigured, true)
-    assert.equal(await readFile(soul, 'utf8'), 'Customized purpose')
+    assert.match(await readFile(agents, 'utf8'), /Customized purpose/)
     await assert.rejects(stat(result.controlDir), { code: 'ENOENT' }) // No control/owner mutation.
   } finally { await rm(root, { recursive: true, force: true }) }
 })
@@ -56,15 +58,24 @@ test('packaged configure accepts token through stdin without echo or extra initi
   const root = await mkdtemp(path.join(tmpdir(), 'ez-configure-cli-'))
   try {
     const token = '123456789:' + 'b'.repeat(30)
+    const purpose = path.join(root, 'purpose.md')
+    await writeFile(purpose, 'Packaged assistant\n')
     const bin = fileURLToPath(new URL('../bin/ezenciel-agents-setup.mjs', import.meta.url))
-    const result = spawnSync(process.execPath, [bin, 'configure', 'codex', '--token-stdin'], { cwd: root, input: token, encoding: 'utf8', timeout: 10000 })
+    const result = spawnSync(process.execPath, [bin, 'configure', 'codex', '--purpose-file', purpose, '--token-stdin'], { cwd: root, input: token, encoding: 'utf8', timeout: 10000 })
     assert.equal(result.status, 0, result.stderr)
     assert.equal((result.stdout + result.stderr).includes(token), false)
-    assert.equal(JSON.parse(result.stdout).created.length, 3)
+    assert.deepEqual(JSON.parse(result.stdout).created, ['AGENTS.md'])
     assert.equal(parseEnv(await readFile(path.join(root, '.env'), 'utf8')).TELEGRAM_BOT_TOKEN, token)
   } finally { await rm(root, { recursive: true, force: true }) }
 })
 
+test('fresh configure refuses to invent a generic purpose', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-configure-purpose-'))
+  try {
+    await assert.rejects(configureInstallation(root, 'codex'), /purpose file is required/)
+  } finally { await rm(root, { recursive: true, force: true }) }
+})
+
 test('Docker startup uses explicit deployment binding and literal paths without secrets or host supervisors', () => {
   const definition = serviceDefinition('/tmp/my agent $literal')
   assert.equal(definition.command, 'docker')

package/test/install-tools.test.mjs

@@ -24,6 +24,12 @@ test('installation status separates files, pairing and current-owner Telegram de
   const write=(name,obj)=>fs.writeFile(path.join(control,name),JSON.stringify(obj));
   await write('heartbeat.json',{at:Date.now(),polling:true});await write('host-executor/heartbeat.json',{at:Date.now()});
   assert.equal((await installationStatus(root)).stage,'awaiting-owner');
+  await fs.writeFile(path.join(root,'agent.json'),JSON.stringify({isolation:'isolated'}));
+  await fs.rm(path.join(control,'host-executor/heartbeat.json'));
+  assert.equal((await installationStatus(root)).stage,'awaiting-owner');
+  await fs.writeFile(path.join(root,'agent.json'),'private');
+  await write('host-executor/heartbeat.json',{at:Date.now()});
+  assert.equal((await installationStatus(root)).stage,'awaiting-owner');
   const owner={telegramUserId:123,telegramChatId:123,pairedAt:new Date(Date.now()-10000).toISOString()};await write('control-state.json',{owner});
   assert.equal((await installationStatus(root)).stage,'awaiting-telegram-reply');
   const item={runId:'tg_12',chatId:123,receipt:{messageIds:[42],deliveredAt:new Date().toISOString()}};

package/test/plugin-manager.test.mjs

@@ -169,7 +169,7 @@ test('host-owned private networks survive registered-call Compose regeneration',
  config.hostConfig=await fs.realpath(f.hostConfig);
  await fs.writeFile(path.join(f.home,'config.json'),JSON.stringify(config));
  const file=path.join(f.home,'packages/sample/compose.json');await fs.writeFile(file,'{}');
- await f.call('sample','read');
+ await exec(path.join(f.home,'bin','ez'),['sample','read'],{cwd:f.workspace,env:f.env});
  const c=JSON.parse(await fs.readFile(file,'utf8'));
  assert.deepEqual(c.networks.default,{});
  const [key,network]=Object.entries(c.networks).find(([name])=>name!=='default');
@@ -323,8 +323,8 @@ test('standalone rejects relay binding and preserves literal plugin arguments ac
  }
  const log=(await fs.readFile(f.log,'utf8')).trim().split('\n').map(JSON.parse);
  assert(log.every(call=>call.secret===undefined));
- await fs.writeFile(path.join(f.home,'config.json'),JSON.stringify({schemaVersion:1,workspace:f.workspace,catalog:{},deploymentDir:'/missing'}));
- await assert.rejects(exec(launcher,['status']),/deployment-bound/); // never hide a broken relay binding
+ await fs.writeFile(path.join(f.home,'config.json'),JSON.stringify({schemaVersion:1,workspace:await fs.realpath(f.workspace),catalog:{},deploymentDir:'/missing'}));
+ await assert.rejects(exec(launcher,['status'],{cwd:f.workspace,env:f.env}),/deployment-bound/); // never hide a broken relay binding
 });
 
 test('existing folders are read-only, persistent and fail closed when missing', async t => {
@@ -349,6 +349,27 @@ test('existing folders are read-only, persistent and fail closed when missing',
  assert.deepEqual(JSON.parse((await f.call('plugins','folders','sample')).stdout),[]);
 });
 
+test('relay registry rejects foreign callers and ungranted host folders', async t => {
+ const f=await fixture(t);await init(f.home,f.workspace);const p=await snapshot(f.source);
+ await f.call('plugins','install','sample','--source',f.source,'--revision',p.revision);
+ await fs.mkdir(path.join(f.root,'allowed'));await fs.mkdir(path.join(f.root,'denied'));
+ const allowed=await fs.realpath(path.join(f.root,'allowed')),denied=await fs.realpath(path.join(f.root,'denied'));
+ const host={cli:'synthetic',agents:[{name:'sample',workspace:f.workspace,controlDir:f.control,binDir:path.join(f.home,'bin'),toolsHome:f.home,pluginFolderRoots:{sample:[allowed]}}]};
+ await fs.writeFile(f.hostConfig,JSON.stringify(host));
+ const config=JSON.parse(await fs.readFile(path.join(f.home,'config.json'),'utf8'));
+ config.hostConfig=await fs.realpath(f.hostConfig);await fs.writeFile(path.join(f.home,'config.json'),JSON.stringify(config));
+ const launcher=path.join(f.home,'bin','ez'),foreign={cwd:f.source,env:f.env};
+ const before=await fs.readFile(f.log,'utf8');
+ await assert.rejects(exec(launcher,['sample','read'],foreign),/Registry belongs/);
+ await assert.rejects(exec(launcher,['--for-workspace',f.workspace,'sample','read'],foreign),/Registry belongs/);
+ assert.equal(await fs.readFile(f.log,'utf8'),before);
+ assert.deepEqual(JSON.parse((await exec(launcher,['sample','read'],{cwd:f.workspace,env:f.env})).stdout),['read']);
+ await exec(launcher,['plugins','folder-bind','sample','--service','sample','--source',allowed,'--target','/data/files'],{cwd:f.workspace,env:f.env});
+ const saved=await fs.readFile(path.join(f.home,'config.json'),'utf8');
+ await assert.rejects(exec(launcher,['plugins','folder-bind','sample','--service','sample','--source',denied,'--target','/data/files'],{cwd:f.workspace,env:f.env}),/not granted/);
+ assert.equal(await fs.readFile(path.join(f.home,'config.json'),'utf8'),saved);
+});
+
 test('folder bindings survive compatible descriptors and reject incompatible updates',async t=>{
  const f=await fixture(t);const p=await snapshot(f.source);
  const record={...p,project:'ezp-test-sample'};

package/test/scheduler.test.ts

@@ -78,10 +78,10 @@ test('pause, edit, removal, owner revocation, corrupt records and traversal fail
 })
 test('task workspaces are distinct and cannot escape through symlinks',async t=>{
  const f=await fixture(t)
- await writeFile(join(f.dir,'SOUL.md'),'Owner context')
+ await writeFile(join(f.dir,'private.md'),'Owner context')
  const first=await taskWorkspace(f.dir,'r_one'),second=await taskWorkspace(f.dir,'r_two')
  assert.notEqual(first,second)
- await assert.rejects(readFile(join(first,'SOUL.md'),'utf8'),{code:'ENOENT'})
+ await assert.rejects(readFile(join(first,'private.md'),'utf8'),{code:'ENOENT'})
  await assert.rejects(readFile(join(first,'AGENTS.md'),'utf8'),{code:'ENOENT'})
  await assert.rejects(taskWorkspace(f.dir,'../escape'))
  const other=join(f.dir,'other');await mkdir(other)

package/test/updates.test.mjs

@@ -9,10 +9,19 @@ import { promisify } from 'node:util';
 import { extract, digest, version, newer, compatible } from '../src/updates/artifact.mjs';
 import { prepare, submit, command, read, jobPath, eligibility, jobs } from '../src/updates/control.mjs';
 import { perform, environment, packageManager } from '../src/updates/runtime.mjs';
-import { atomic, snapshot, compose } from '../src/plugins/manager.mjs';
+import { atomic, snapshot, compose, prepareCommand } from '../src/plugins/manager.mjs';
 import { bindUpdates } from '../src/updates/binding.mjs';
 import { status as runtimeStatus } from '../src/updates/status.mjs';
+import { providerEnvironment } from '../src/updates/supervisor.mjs';
 const exec=promisify(execFile);
+
+test('supervisor forwards only provider keys declared by the agent installation',()=>{
+ const host={agents:[{codexProviders:[{envKey:'OPENROUTER_API_KEY'}]}]};
+ assert.deepEqual(providerEnvironment(host,{OPENROUTER_API_KEY:'provider-secret',TELEGRAM_BOT_TOKEN:'relay-secret'}),{OPENROUTER_API_KEY:'provider-secret'});
+ assert.throws(()=>providerEnvironment({agents:[{codexProviders:[{envKey:'bad-key'}]}]},{}),/environment key/);
+ for(const envKey of ['PATH','HOME','CODEX_HOME','NODE_OPTIONS','EZ_CONTROL_DIR','TELEGRAM_BOT_TOKEN','PAGERDUTY_ROUTING_KEY'])
+  assert.throws(()=>providerEnvironment({agents:[{codexProviders:[{envKey}]}]},{}),/Reserved Codex provider environment key/);
+});
 const contract=kind=>({protocol:1,kind,stateSchema:1,mainProtocol:1});
 function tar(entries) {
  const chunks=[];
@@ -83,7 +92,7 @@ test('status distinguishes installed, running, legacy and stale main versions wi
  }
  await fs.writeFile(relay,'broken');s=await command(f.home,['status']);assert.equal(s.main.state,'unknown');
  await fs.rm(relay);s=await command(f.home,['status']);assert.equal(s.main.state,'offline');
- const result=await exec(process.execPath,[new URL('../bin/ezenciel-agents-tools.mjs',import.meta.url).pathname,'--home',f.home,'status']);
+ const result=await exec(process.execPath,[new URL('../bin/ezenciel-agents-tools.mjs',import.meta.url).pathname,'--home',f.home,'status'],{cwd:f.agent.workspace});
  assert.equal(JSON.parse(result.stdout).main.installedVersion,'0.1.0');
 });
 test('relay healthcheck emits bounded predicate evidence without state contents',async t=>{
@@ -191,6 +200,29 @@ test('stopped plugins remain stopped; removed plugins and expanded mounts reject
  const reg=await read(path.join(f.home,'registry.json'));delete reg.plugins.sample;await atomic(path.join(f.home,'registry.json'),reg);
  await assert.rejects(prepare(f.home,'sample',{file:await f.pack()}),/not installed/);
 });
+test('plugin updates register additive command routes on an unchanged deployment',async t=>{
+ const f=await fixture(t,'plugin'),manifest=await read(path.join(f.source,'ez-plugin.json')),deployment=await read(path.join(f.source,'ez-deployment.json'));
+ manifest.commands.query={executable:'bin/example.mjs',args:[],channelQuery:true,exposure:{receivesExternalContent:true,sendsExternally:false,changesRecords:false,requiresReview:false}};
+ deployment.commands.query={service:'sample',argv:['node','/app/bin/example.mjs','query']};
+ await atomic(path.join(f.source,'ez-plugin.json'),manifest);await atomic(path.join(f.source,'ez-deployment.json'),deployment);
+ assert.equal((await eligibility(f.home,'sample',f.source,false)).pkg.version,'0.1.1');
+ const job=await queued(f),r=runtime(f);assert.equal((await perform(f.home,job,r)).status,'completed');
+ const registry=await read(path.join(f.home,'registry.json'));assert.equal(registry.commands.query,'sample');
+ const dispatch=await prepareCommand(f.home,'query',[]);assert.deepEqual(dispatch.argv.slice(-4),['node','sample','/app/bin/example.mjs','query']);
+ assert(r.calls.some(call=>call.includes('up')));
+});
+test('plugin command additions ignore object key order but reject collisions and changed routes',async t=>{
+ const f=await fixture(t,'plugin'),deployment=await read(path.join(f.source,'ez-deployment.json'));
+ deployment.services.sample={healthcheck:deployment.services.sample.healthcheck,volumes:deployment.services.sample.volumes,buildTarget:deployment.services.sample.buildTarget};
+ await atomic(path.join(f.source,'ez-deployment.json'),deployment);assert.equal((await eligibility(f.home,'sample',f.source,false)).pkg.version,'0.1.1');
+ const manifest=await read(path.join(f.source,'ez-plugin.json'));manifest.commands.other={executable:'bin/example.mjs',args:[]};deployment.commands.other={service:'sample',argv:['node','/app/bin/example.mjs','other']};
+ await atomic(path.join(f.source,'ez-plugin.json'),manifest);await atomic(path.join(f.source,'ez-deployment.json'),deployment);
+ const registry=await read(path.join(f.home,'registry.json'));registry.commands.other='different';await atomic(path.join(f.home,'registry.json'),registry);
+ await assert.rejects(eligibility(f.home,'sample',f.source,false),/alias collision/);
+ delete registry.commands.other;await atomic(path.join(f.home,'registry.json'),registry);
+ deployment.commands.sample.argv.push('--changed');await atomic(path.join(f.source,'ez-deployment.json'),deployment);
+ await assert.rejects(eligibility(f.home,'sample',f.source,false),/deployment/i);
+});
 test('interrupted activation recovers previous code; rollback failure is explicit and blocks further jobs',async t=>{
  const f=await fixture(t),job=await queued(f),r=runtime(f);await perform(f.home,job,r);
  const interrupted=await read(path.join(jobPath(f.home,job.id),'job.json'));interrupted.status='applying';

package/test/workspace-confine.test.ts

@@ -0,0 +1,47 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { spawn } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { macosWorkspaceProfile, workspaceSiblingDenies } from '../src/workspace-confine.js'
+
+test('sibling confinement skips $HOME and filesystem root', () => {
+  assert.deepEqual(workspaceSiblingDenies('/Users/ada/agent', '/Users/ada'), [])
+  assert.deepEqual(workspaceSiblingDenies('/', '/Users/ada'), [])
+})
+
+test('sibling confinement denies the tenant farm, not the bound workspace', () => {
+  assert.deepEqual(workspaceSiblingDenies('/data/tenants/juan', '/Users/ada'), [
+    { deny: '/data/tenants', allow: '/data/tenants/juan' },
+  ])
+})
+
+test('macos profile blocks sibling reads and writes', async (t) => {
+  if (process.platform !== 'darwin') { t.skip(); return }
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-confine-'))
+  t.after(() => rm(root, { recursive: true, force: true }))
+  const mine = path.join(root, 'juan')
+  const other = path.join(root, 'other')
+  const shared = path.join(root, 'shared')
+  const additional = path.join(root, 'additional')
+  await mkdir(mine); await mkdir(other); await mkdir(shared); await mkdir(additional)
+  await writeFile(path.join(mine, 'own.txt'), 'own')
+  await writeFile(path.join(other, 'secret.txt'), 'secret')
+  await writeFile(path.join(shared, 'shared.txt'), 'shared')
+  await writeFile(path.join(additional, 'additional.txt'), 'additional')
+  const profile = path.join(root, 'workspace.sb')
+  await writeFile(profile, macosWorkspaceProfile(workspaceSiblingDenies(mine, '/Users/ada'), [shared, additional]))
+  const run = (file: string) => new Promise<{ code: number | null; stderr: string }>(resolve => {
+    const child = spawn('sandbox-exec', ['-f', profile, '/bin/cat', file], { stdio: ['ignore', 'pipe', 'pipe'] })
+    let stderr = ''
+    child.stderr.on('data', chunk => { stderr += chunk })
+    child.on('close', code => resolve({ code, stderr }))
+  })
+  assert.equal((await run(path.join(mine, 'own.txt'))).code, 0)
+  assert.equal((await run(path.join(shared, 'shared.txt'))).code, 0)
+  assert.equal((await run(path.join(additional, 'additional.txt'))).code, 0)
+  const blocked = await run(path.join(other, 'secret.txt'))
+  assert.notEqual(blocked.code, 0)
+  assert.match(blocked.stderr, /not permitted|Operation not permitted/i)
+})

package/test/workspace.test.ts

@@ -38,14 +38,18 @@ test('fresh mind is private; repeat initialization preserves customization and o
   const root = await mkdtemp(path.join(tmpdir(), 'ez-mind-'))
   const workspace = path.join(root, 'agent')
   try {
-    assert.equal((await initializeWorkspace(workspace)).length, 3)
-    assert.equal((await stat(path.join(workspace, 'SOUL.md'))).mode & 0o777, 0o600)
+    const purpose = path.join(root, 'purpose.md')
+    await writeFile(purpose, 'Research partner\n')
+    assert.deepEqual(await initializeWorkspace(workspace, purpose), ['AGENTS.md'])
+    assert.equal((await stat(path.join(workspace, 'AGENTS.md'))).mode & 0o777, 0o600)
+    assert.ok(!(await readdir(workspace)).includes('SOUL.md'))
+    assert.ok(!(await readdir(workspace)).includes('USER.md'))
     assert.ok(!(await readdir(workspace)).includes('MEMORY.md'))
-    await writeFile(path.join(workspace, 'SOUL.md'), 'A customized research partner')
+    await writeFile(path.join(workspace, 'AGENTS.md'), 'A customized research partner')
     await writeFile(path.join(workspace, 'MEMORY.md'), 'Existing knowledge')
     await writeFile(path.join(workspace, 'AGENT.md'), 'Legacy custom guidance')
     assert.deepEqual(await initializeWorkspace(workspace), [])
-    assert.equal(await readFile(path.join(workspace, 'SOUL.md'), 'utf8'), 'A customized research partner')
+    assert.match(await readFile(path.join(workspace, 'AGENTS.md'), 'utf8'), /A customized research partner/)
     assert.equal(await readFile(path.join(workspace, 'MEMORY.md'), 'utf8'), 'Existing knowledge')
     assert.equal(await readFile(path.join(workspace, 'AGENT.md'), 'utf8'), 'Legacy custom guidance')
     assert.ok(!(await readdir(workspace)).some(name => name.endsWith('.tmp')))
@@ -53,27 +57,36 @@ test('fresh mind is private; repeat initialization preserves customization and o
   } finally { await rm(root, { recursive: true, force: true }) }
 })
 
+test('fresh workspace refuses to invent a generic purpose', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'ez-purpose-required-'))
+  try {
+    await assert.rejects(initializeWorkspace(path.join(root, 'mind'), undefined), /purpose file is required/)
+  } finally { await rm(root, {recursive:true, force:true}) }
+})
+
 test('seed refuses a symlink without overwriting its target', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'ez-mind-'))
   try {
     const target = path.join(root, 'outside.md')
     await writeFile(target, 'untouched')
-    await symlink(target, path.join(root, 'SOUL.md'))
+    await symlink(target, path.join(root, 'AGENTS.md'))
     await assert.rejects(initializeWorkspace(root), /regular file/)
     assert.equal(await readFile(target, 'utf8'), 'untouched')
   } finally { await rm(root, { recursive: true, force: true }) }
 })
 
-test('new agents seed their own purpose once and preserve subsequent mind edits', async () => {
+test('new agents seed a purpose-scoped AGENTS.md once and preserve subsequent edits', async () => {
   const root = await mkdtemp(path.join(tmpdir(), 'ez-purpose-'))
   try {
     const purpose = path.join(root, 'purpose.md')
     const workspace = path.join(root, 'mind')
-    await writeFile(purpose, 'Family shopping assistant\n')
+    await writeFile(purpose, 'You are the shopping assistant for this family.\n\n### Responsibilities\n\nOrganize confirmed household shopping requests.\n')
     await initializeWorkspace(workspace, purpose)
-    assert.equal(await readFile(path.join(workspace, 'SOUL.md'), 'utf8'), 'Family shopping assistant\n')
-    await writeFile(path.join(workspace, 'SOUL.md'), 'My evolving purpose\n')
+    const agents = await readFile(path.join(workspace, 'AGENTS.md'), 'utf8')
+    assert.match(agents, /## Purpose\n\nYou are the shopping assistant for this family\./)
+    assert.match(agents, /### Responsibilities\n\nOrganize confirmed household shopping requests\./)
+    await writeFile(path.join(workspace, 'AGENTS.md'), 'My evolving purpose\n')
     await initializeWorkspace(workspace, purpose)
-    assert.equal(await readFile(path.join(workspace, 'SOUL.md'), 'utf8'), 'My evolving purpose\n')
+    assert.match(await readFile(path.join(workspace, 'AGENTS.md'), 'utf8'), /My evolving purpose/)
   } finally { await rm(root, {recursive:true, force:true}) }
 })

package/templates/agent/SOUL.md

@@ -1,11 +0,0 @@
-# Identity and purpose
-
-You are one person-shaped assistant serving one owner. Start as a practical
-personal assistant until the owner supplies a more specific purpose.
-
-Be concise, resourceful, and candid. Take useful reversible steps within the
-owner's request. Ask only when missing information changes what you should do.
-Verify real outcomes before claiming success. Get approval for purchases,
-spending, destructive actions, and other actions requiring owner permission.
-
-Adapt your purpose and working style from the owner's confirmed needs.

package/templates/agent/USER.md

@@ -1,5 +0,0 @@
-# Owner context
-
-No personal details have been provided yet. Record only relevant information
-the owner supplies or confirms: preferences, purpose, and working context.
-Keep detailed project or organization knowledge with its work in work/.