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

package/src/files.ts

@@ -1,4 +1,4 @@
-import { mkdir, writeFile, realpath, stat } from 'node:fs/promises'
+import { mkdir, readFile, writeFile, realpath, stat } from 'node:fs/promises'
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 
@@ -43,28 +43,55 @@ export const sanitizeFileName = (name: string): string => {
   return base || 'file'
 }
 
+// Runtime inbound staging lives under the agent control directory, never the
+// workspace mind folder. The engine resolves the absolute path regardless of
+// its working directory; the prompt carries no workspace-relative prefix.
 export const stageIncomingFile = async (
-  workspaceDir: string,
+  stagingRoot: string,
   fileName: string,
   bytes: Buffer,
 ): Promise<{ relativePath: string; fullPath: string; fileType: DetectedFileType }> => {
   const fileType = detectFileType(bytes)
   if (fileType === 'unknown' || bytes.length > 20 * 1024 * 1024)
     throw new Error('Unsupported or oversized attachment')
-  const inboxDir = path.join(workspaceDir, 'inbox')
-  await mkdir(inboxDir, { recursive: true, mode: 0o700 })
+  const attachmentsDir = path.join(stagingRoot, 'attachments')
+  await mkdir(attachmentsDir, { recursive: true, mode: 0o700 })
   const sanitized = sanitizeFileName(fileName)
   const targetName = `${randomUUID()}_${sanitized}`
-  await workspaceFile(workspaceDir, 'inbox', false)
-  const fullPath = path.join(inboxDir, targetName)
+  await workspaceFile(stagingRoot, 'attachments', false)
+  const fullPath = path.join(attachmentsDir, targetName)
   await writeFile(fullPath, bytes, { mode: 0o600 })
   return {
-    relativePath: path.join('inbox', targetName),
+    relativePath: path.join('attachments', targetName),
     fullPath,
     fileType,
   }
 }
 
+// Reads a staged attachment produced by stageIncomingFile. Relative paths
+// resolve under the first containing root (backward compatible with
+// workspace inbox staging); absolute paths must stay inside one of the roots.
+export const readStagedAttachment = async (roots: (string | undefined)[], file: string): Promise<Buffer> => {
+  const candidates = [...new Set(roots.filter((root): root is string => Boolean(root)))]
+  if (!path.isAbsolute(file)) {
+    for (const root of candidates) {
+      try { return await readFile(await workspaceFile(root, file)) } catch {}
+    }
+    throw new Error('File is outside the workspace')
+  }
+  const target = await realpath(file).catch(() => { throw new Error('File is outside the workspace') })
+  for (const root of candidates) {
+    const base = await realpath(root).catch(() => null)
+    if (!base) continue
+    const relative = path.relative(base, target)
+    if (!relative.startsWith('..') && !path.isAbsolute(relative) && relative !== '') {
+      if (!(await stat(target)).isFile()) throw new Error('Expected a regular file')
+      return readFile(target)
+    }
+  }
+  throw new Error('File is outside the workspace')
+}
+
 export const workspaceFile = async (workspace: string, file: string, regular = true): Promise<string> => {
   const root = await realpath(workspace)
   const target = await realpath(path.resolve(root, file))
@@ -76,12 +103,12 @@ export const workspaceFile = async (workspace: string, file: string, regular = t
 
 // Canonical native-engine attachment metadata for every inbound channel.
 export const MAX_INCOMING_ATTACHMENT_BYTES = 10 * 1024 * 1024
-export const stageChatAttachment = async (workspace: string, name: string, bytes: Buffer, comment: string) => {
+export const stageChatAttachment = async (stagingRoot: string, name: string, bytes: Buffer, comment: string) => {
   const type = detectFileType(bytes)
   if (!bytes.length || bytes.length > MAX_INCOMING_ATTACHMENT_BYTES || type === 'unknown' ||
     (type === 'text' && !/\.(txt|md|markdown)$/i.test(name))) throw new Error('Invalid application attachment: unsupported type or size')
-  const staged = await stageIncomingFile(workspace, name, bytes)
+  const staged = await stageIncomingFile(stagingRoot, name, bytes)
   const kind = ['jpeg', 'png', 'webp'].includes(staged.fileType) ? 'image' : 'document'
-  return { text: `[Attached ${kind} staged at ${staged.relativePath} (type: ${staged.fileType}, size: ${bytes.length} bytes)]${comment ? `\n\nCaption: ${comment}` : ''}`,
-    attachment: {path: staged.relativePath, type: staged.fileType}, fullPath: staged.fullPath }
+  return { text: `[Attached ${kind} staged at ${staged.fullPath} (type: ${staged.fileType}, size: ${bytes.length} bytes)]${comment ? `\n\nCaption: ${comment}` : ''}`,
+    attachment: {path: staged.fullPath, type: staged.fileType}, fullPath: staged.fullPath }
 }

package/src/host-executor.ts

@@ -1,13 +1,14 @@
-import { installAgentGuidance } from './agent-guidance.js'
 import { redactFailure } from './failure.js'
-import { RunStore } from './runs.js'
 import { Tasks } from './tasks.js'
-import { requireOwnerExecution } from './execution-authority.js'
+import { ControlStore } from './control-state.js'
+import { authorizeRun, readRun } from './delivery-socket.js'
+import { runPromptSuffix } from './prompt-suffix.js'
 import { mkdir, readFile, writeFile, readdir, rename, rm, appendFile, realpath } from 'node:fs/promises'
 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,23 @@ 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 => {
+      const native = discovered.find(candidate => candidate.cli === 'codex' && !candidate.provider && candidate.model === model)
+      return {cli:'codex',provider:provider.id,model,name:`${provider.name} · ${model}`.slice(0,80),efforts:native?.efforts ?? []}
+    }))
+    const declaredModels = new Set(declared.map(model => model.model))
+    const isReplacedByProvider = (model: {cli:string; model?:string}) =>
+      model.model !== undefined && declaredModels.has(model.model) && model.cli === 'codex'
+    return [...discovered.filter(model => !isReplacedByProvider(model)), ...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) {
@@ -61,8 +77,10 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
       catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
       await writeFile(lock,JSON.stringify({pid:process.pid,started:await processStart(process.pid)}),{mode:0o600,flag:'wx'})
       locks.push(lock)
-      await installAgentGuidance(agent.workspace)
-      await writeFile(path.join(directory,'models.json'),JSON.stringify(await catalog(agent)),{mode:0o600})
+      const models = await catalog(agent)
+      await new ControlStore(agent.controlDir, 900000).normalizeProviderBindings(models)
+      const modelsFile=path.join(directory,'models.json')
+      await writeFile(modelsFile+'.tmp',JSON.stringify(models),{mode:0o600});await rename(modelsFile+'.tmp',modelsFile)
       // A host crash is terminal for a claimed job. Never replay an action.
       for (const file of await readdir(directory)) if (file.endsWith('.running.json')) {
         const base=path.join(directory,file.slice(0,-13))
@@ -78,27 +96,32 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
       if (agent.toolsHome) await (await import('./plugins/workspace-lease.mjs')).recoverNativeLease(agent.toolsHome)
     }
     let catalogAt=Date.now()
+    const catalogSeen=new Map<HostBinding,string>()
     while (!signal.aborted) {
       const parent=Number(process.env.EZ_HOST_SUPERVISOR_PID)
       if(parent) { try { process.kill(parent,0) } catch { break } }
       if(Date.now()-catalogAt>30000){
         for(const agent of installation.agents){
-          const models=JSON.stringify(await catalog(agent))
+          const catalogModels = await catalog(agent)
+          const models=JSON.stringify(catalogModels)
+          if(catalogSeen.get(agent)===models)continue
+          await new ControlStore(agent.controlDir, 900000).normalizeProviderBindings(catalogModels)
           const file=path.join(agent.controlDir,'host-executor/models.json')
           await writeFile(file+'.tmp',models,{mode:0o600});await rename(file+'.tmp',file)
+          catalogSeen.set(agent,models)
         }
         catalogAt=Date.now()
       }
       for (const agent of installation.agents) {
         const directory=path.join(agent.controlDir,'host-executor')
-        await writeFile(path.join(directory,'heartbeat.tmp'),JSON.stringify({at:Date.now(),pid:process.pid,version:packageVersion,plugins:await installedPluginVersions(agent.toolsHome)}),{mode:0o600})
+        await writeFile(path.join(directory,'heartbeat.tmp'),JSON.stringify({at:Date.now(),pid:process.pid,version:packageVersion,platform:process.platform,arch:process.arch,plugins:await installedPluginVersions(agent.toolsHome)}),{mode:0o600})
         await rename(path.join(directory,'heartbeat.tmp'),path.join(directory,'heartbeat.json'))
         for (const file of await readdir(directory)) {
           if (!file.endsWith('.request.json') || !isHostRunId(file.slice(0,-13))) continue
           const id=file.slice(0,-13)
           let run
           try {
-            run = await new RunStore(agent.controlDir).get(id)
+            run = await readRun(agent.controlDir, id)
             if(id.startsWith('r_schedule_') && !run?.scheduled) throw new Error('Missing scheduled run')
           } catch {
             await appendFile(path.join(directory,id+'.events'),JSON.stringify({stream:'exit',code:1})+'\n',{mode:0o600})
@@ -121,18 +144,28 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
               try { await readFile(base+'.cancel'); throw new Error('Cancelled') } catch(error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
               const request=JSON.parse(await readFile(base+'.running.json','utf8'))
               if (!Array.isArray(request.texts) || request.texts.some((text:unknown)=>typeof text!=='string')) throw new Error('Invalid job')
-              const run = await new RunStore(agent.controlDir).get(path.basename(base))
+              const run = await readRun(agent.controlDir, path.basename(base))
               if (run?.taskId) {
                 if (run.status !== 'running') throw new Error('No active task run')
                 await new Tasks(agent.controlDir).authorize(run, false)
-              } else await requireOwnerExecution(agent.controlDir, path.basename(base))
+              } else await authorizeRun(agent.controlDir, path.basename(base))
               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 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,
+              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.controlDir,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,model,effort:opts.effort,provider:opts.provider,codexAutoCompactTokens:opts.codexAutoCompactTokens,codexProvider:provider,
+                promptSuffix:runPromptSuffix(run),taskRun:Boolean(run?.taskId),nativeSession:Boolean(run?.scheduled)}
               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/inbox.ts

@@ -1,5 +1,3 @@
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
 import type { Update } from 'grammy/types'
 import { isExecutionChoice, type ExecutionChoice } from './ai.js'
 import { isOwner } from './identity.js'
@@ -21,58 +19,26 @@ type Entry = { update: Update; receivedAt: number; execution?: ExecutionChoice }
 export type InboxBatch = { id: string; entries: Entry[]; status: 'pending' | 'failed' | 'cancelled' }
 type State = { version: 1; seen: number[]; waiting: Entry[]; batches: InboxBatch[] }
 
-// One relay writer. Serialize read/modify/rename, including commands arriving during STT.
+// Stateless pipe: process memory only. Intake dedup lives in the relay that
+// polls Telegram, so no other process reads this journal. A restart drops
+// unprocessed updates by design; Telegram redelivery is the replay mechanism.
+const statesByDirectory = new Map<string, State>()
+
+const stateFor = (directory: string): State => {
+  let state = statesByDirectory.get(directory)
+  if (!state) { state = { version: 1, seen: [], waiting: [], batches: [] }; statesByDirectory.set(directory, state) }
+  return state
+}
+
 export class InboxStore {
   private lock: Promise<unknown> = Promise.resolve()
-  private readonly file: string
   constructor(
     private readonly directory: string,
     private readonly now = Date.now,
-  ) {
-    this.file = join(directory, 'inbox.json')
-  }
-
-  private async read(): Promise<State> {
-    try {
-      const state = JSON.parse(await readFile(this.file, 'utf8')) as State
-      const entry = (e: Entry) =>
-        e && Number.isSafeInteger(e.update?.update_id) && Number.isFinite(e.receivedAt) &&
-        (e.execution === undefined || isExecutionChoice(e.execution))
-      if (
-        state.version !== 1 ||
-        !Array.isArray(state.seen) ||
-        !state.seen.every(Number.isSafeInteger) ||
-        !Array.isArray(state.waiting) ||
-        !state.waiting.every(entry) ||
-        !Array.isArray(state.batches) ||
-        !state.batches.every(
-          (b) =>
-            /^tg_\d+$/.test(b.id) &&
-            ['pending', 'failed', 'cancelled'].includes(b.status) &&
-            Array.isArray(b.entries) &&
-            b.entries.length > 0 &&
-            b.entries.every(entry),
-        )
-      )
-        throw new Error('Invalid inbox shape')
-      return state
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT')
-        return { version: 1, seen: [], waiting: [], batches: [] }
-      throw new Error('Inbox unreadable; restore the local journal before accepting messages')
-    }
-  }
+  ) {}
 
   private change<T>(work: (state: State) => T): Promise<T> {
-    const next = this.lock.then(async () => {
-      const state = await this.read()
-      const result = work(state)
-      await mkdir(this.directory, { recursive: true, mode: 0o700 })
-      const temporary = `${this.file}.${process.pid}.tmp`
-      await writeFile(temporary, JSON.stringify(state), { mode: 0o600 })
-      await rename(temporary, this.file)
-      return result
-    })
+    const next = this.lock.then(async () => work(stateFor(this.directory)))
     this.lock = next.catch(() => {})
     return next
   }
@@ -163,12 +129,12 @@ export class InboxStore {
 
   async pending(id: string): Promise<boolean> {
     await this.lock
-    return (await this.read()).batches.some((b) => b.id === id && b.status === 'pending')
+    return stateFor(this.directory).batches.some((b) => b.id === id && b.status === 'pending')
   }
 
   async status(): Promise<{ pending: number; failed: number }> {
     await this.lock
-    const state = await this.read()
+    const state = stateFor(this.directory)
     return {
       pending:
         state.waiting.length +