@jc_stack/ez-agents 0.1.0-beta.47 → 0.1.0-beta.48

package/src/executor.ts

@@ -11,6 +11,7 @@ import { createInterface } from 'node:readline'
 import { fileURLToPath } from 'node:url'
 import { DESKTOP_UNAVAILABLE } from './desktop-bridge.js'
 import { macosWorkspaceProfile, workspaceSiblingDenies } from './workspace-confine.js'
+import { Scripts, type ScriptRunRef } from './scripts.js'
 
 export type ExecutorOptions = {
   repairEnabled?: boolean
@@ -38,8 +39,12 @@ export type ExecutorOptions = {
   codexAutoCompactTokens?: number
   codexProvider?: CodexProviderBinding
   onSession?: (id: string) => Promise<void>
+  // Registered script occurrence: invoke it directly, never a native CLI.
+  script?: ScriptLaunch
 }
 
+export type ScriptLaunch = ScriptRunRef & { scheduleId: string; scheduleRevision: string; dueAt: string }
+
 export type CodexProviderBinding = {
   id: string
   name: string
@@ -71,7 +76,7 @@ export const executorEnvironment = (environment: NodeJS.ProcessEnv = process.env
 }
 
 export const executorJobEnv = (
-  options: Pick<ExecutorOptions, 'runId' | 'controlDir' | 'binDir' | 'toolsHome' | 'repairEnabled'>,
+  options: Pick<ExecutorOptions, 'runId' | 'controlDir' | 'binDir' | 'toolsHome' | 'repairEnabled'> & { workspace?: string },
   environment: NodeJS.ProcessEnv = process.env,
 ): NodeJS.ProcessEnv => {
   const base = executorEnvironment(environment)
@@ -81,6 +86,7 @@ export const executorJobEnv = (
     PATH: pathValue,
     EZ_RUN_ID: options.runId,
     EZ_CONTROL_DIR: options.controlDir,
+    ...(options.workspace ? { EZ_AGENT_WORKSPACE: options.workspace } : {}),
     EZ_DELIVERY_SOCKET: deliverySocketPath(options.controlDir),
     EZ_REPAIR_ENABLED: String(options.repairEnabled !== false),
     ...(options.toolsHome ? {BUILDX_CONFIG:path.join(options.toolsHome,'buildx')} : {}),
@@ -155,6 +161,8 @@ export const EXECUTOR_REGISTRY: Record<string, CliAdapter> = {
         args.push('--session-id', opts.sessionId)
       }
       args.push('--print', '--dangerously-skip-permissions')
+      for (const directory of [opts.controlDir, opts.sharedWorkspace, ...(opts.additionalWorkspaces ?? []), opts.toolsHome])
+        if (directory) args.push('--add-dir', directory)
       if (opts.model) args.push('--model', opts.model)
       if (opts.effort) args.push('--effort', opts.effort)
       return args
@@ -285,6 +293,9 @@ export const opencodeDataHome = (controlDir: string): string | undefined => {
   } catch { return undefined }
 }
 
+// Agent-bound Claude Code configuration directory (CLAUDE_CONFIG_DIR).
+export const claudeConfigHome = (controlDir: string): string => path.join(controlDir, 'cli', 'claude')
+
 // Pi resolves its provider/model catalog from an agent dir (settings.json,
 // auth.json). Only a path is ever returned, never a secret.
 export const piAgentDir = (controlDir: string): string | undefined => {
@@ -323,6 +334,7 @@ export const startExecutorJob = async (
   texts: string[],
   options: ExecutorOptions,
 ): Promise<{ child: ChildProcess; cleanup: () => Promise<void>; stdout: string }> => {
+  if (options.script && process.env.EZ_EXECUTOR_TRANSPORT !== 'host') return startScriptJob(options as ExecutorOptions & { script: ScriptLaunch })
   options = executionDefaults(executorKey(options.cli), options)
   // Routing is caller-owned: a restricted task run goes to the task runner
   // unless the host transport must ship it across the boundary first.
@@ -387,6 +399,32 @@ export const startExecutorJob = async (
     }
     environment.CODEX_HOME = home
   }
+  if (!host && !gui && key === 'claude') {
+    // Mirror the Codex binding: agent-bound settings, memory, plugins and
+    // sessions; never the user's personal ~/.claude configuration.
+    const home = claudeConfigHome(options.controlDir)
+    await mkdir(home, {recursive:true,mode:0o700})
+    environment.CLAUDE_CONFIG_DIR = home
+    // Host-capable agents share the installer login only. An empty secure
+    // storage dir makes Claude use its default credential store (macOS
+    // Keychain entry or ~/.claude/.credentials.json) in place, so token
+    // refreshes stay shared rather than diverging through a copy. Isolated
+    // agents keep their own login inside CLAUDE_CONFIG_DIR. The host executor
+    // runs unlabelled, so this matches the Codex auth-link check, not
+    // resolveIsolation().
+    if (process.env.EZ_ISOLATION !== 'isolated') environment.CLAUDE_SECURESTORAGE_CONFIG_DIR = ''
+    // Optional owner-provisioned long-lived token (`claude setup-token`). It
+    // never refreshes, so one file can be copied to every agent without the
+    // agents invalidating each other's OAuth session.
+    const token = await readFile(path.join(home, 'oauth-token'), 'utf8').then(value => value.trim(), (error: NodeJS.ErrnoException) => {
+      if (error.code === 'ENOENT') return undefined
+      throw error
+    })
+    if (token !== undefined) {
+      if (!/^[A-Za-z0-9._-]{20,512}$/.test(token)) throw new Error('Invalid Claude token binding')
+      environment.CLAUDE_CODE_OAUTH_TOKEN = token
+    }
+  }
   if (!host && !gui && key === 'opencode') {
     // Point OpenCode at the agent-bound data home (cli/opencode/auth.json)
     // when the owner provisioned it. Host runs keep the installer login;
@@ -459,6 +497,39 @@ export const startExecutorJob = async (
 
 export const startGrokJob = startExecutorJob
 
+// Spawn a verified registered script with the executor identity, environment
+// allowlist and workspace confinement. No shell, model, prompt or native session.
+export const startScriptJob = async (
+  options: ExecutorOptions & { script: ScriptLaunch },
+): Promise<{ child: ChildProcess; cleanup: () => Promise<void>; stdout: string }> => {
+  const { script } = options
+  for (const value of [options.runId, script.scheduleId, script.scheduleRevision]) if (!/^[a-zA-Z0-9_-]+$/.test(value)) throw new Error('Invalid script run binding')
+  if (!Number.isFinite(Date.parse(script.dueAt))) throw new Error('Invalid script due time')
+  const environment: NodeJS.ProcessEnv = {
+    ...executorJobEnv(options),
+    EZ_SCHEDULE_ID: script.scheduleId, EZ_SCHEDULE_REVISION: script.scheduleRevision, EZ_DUE_AT: script.dueAt,
+    EZ_SCRIPT_ID: script.id, EZ_SCRIPT_REVISION: script.revision, EZ_SCRIPT_SHA256: script.sha256,
+  }
+  const verified = await new Scripts(options.controlDir).verifiedInvocation(script, options.workspace, environment.PATH)
+  let invocation = executorInvocation(verified.command, verified.args)
+  let profileDirectory: string | undefined
+  const denies = process.platform === 'darwin' ? workspaceSiblingDenies(options.workspace) : []
+  if (denies.length) {
+    profileDirectory = await mkdtemp(path.join(tmpdir(), 'ezenciel-agents-'))
+    const profile = path.join(profileDirectory, 'workspace.sb')
+    await writeFile(profile, macosWorkspaceProfile(denies, [options.controlDir, options.binDir, options.toolsHome, options.sharedWorkspace,
+      ...(options.additionalWorkspaces ?? [])].filter((value): value is string => Boolean(value))), { mode: 0o600 })
+    invocation = { command: 'sandbox-exec', args: ['-f', profile, invocation.command, ...invocation.args] }
+  }
+  const cleanup = async () => { if (profileDirectory) await rm(profileDirectory, { recursive: true, force: true }) }
+  const child = spawn(invocation.command, invocation.args, {
+    cwd: options.workspace, env: environment, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32', shell: false,
+  })
+  await new Promise<void>((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject) })
+    .catch(async (error) => { await cleanup(); throw error })
+  return { child, cleanup, stdout: '' }
+}
+
 // Structured client events only. Model text is never interpreted or sent to chat.
 export const nativeSessionId = (cli: string, line: string): string | undefined => {
   try {

package/src/files.ts

@@ -1,8 +1,10 @@
-import { mkdir, readFile, writeFile, realpath, stat } from 'node:fs/promises'
+import { mkdir, readFile, writeFile, realpath, stat, mkdtemp, readdir, rm, unlink } from 'node:fs/promises'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
 import { randomUUID } from 'node:crypto'
 import path from 'node:path'
 
-export type DetectedFileType = 'pdf' | 'jpeg' | 'png' | 'webp' | 'text' | 'unknown'
+export type DetectedFileType = 'pdf' | 'jpeg' | 'png' | 'webp' | 'text' | 'mp4' | 'unknown'
 
 export const detectFileType = (buffer: Buffer): DetectedFileType => {
   if (buffer.length >= 5 && buffer.subarray(0, 5).toString('ascii') === '%PDF-') {
@@ -31,6 +33,9 @@ export const detectFileType = (buffer: Buffer): DetectedFileType => {
   ) {
     return 'webp'
   }
+  // ISO-BMFF also carries HEIF/AVIF stills and audio-only M4A; only video brands are MP4.
+  if (buffer.length >= 12 && buffer.subarray(4,8).toString('ascii') === 'ftyp' &&
+    !/^(hei[cmsx]|hev[cmsx]|mif1|msf1|avi[fs]|M4[ABP] |F4A )$/.test(buffer.subarray(8,12).toString('latin1'))) return 'mp4'
   try {
     new TextDecoder('utf-8', { fatal: true }).decode(buffer)
     if (!buffer.includes(0)) return 'text'
@@ -108,7 +113,46 @@ export const stageChatAttachment = async (stagingRoot: string, name: string, byt
   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(stagingRoot, name, bytes)
-  const kind = ['jpeg', 'png', 'webp'].includes(staged.fileType) ? 'image' : 'document'
+  const kind = ['jpeg', 'png', 'webp'].includes(staged.fileType) ? 'image' : staged.fileType === 'mp4' ? 'video' : 'document'
   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 }
 }
+
+// Shared inbound staging/validation with Telegram; restricted correspondence
+// can read only this already-authorized input, never arbitrary workspace paths.
+export async function readChatAttachment(stagingRoot: string, name: string, bytes: Buffer) {
+  const staged = await stageChatAttachment(stagingRoot, name, bytes, '')
+  // Untrusted media parsers never inherit relay secrets.
+  const execute = (command: string, args: string[], options: {timeout:number;maxBuffer:number}) =>
+    promisify(execFile)(command, args, {...options, env: {PATH: process.env.PATH ?? '/usr/bin:/bin'}})
+  try {
+    if (['jpeg','png','webp'].includes(staged.attachment.type)) return {name:sanitizeFileName(name),type:staged.attachment.type,bytes:bytes.length,image:{data:bytes.toString('base64'),mimeType:`image/${staged.attachment.type}`}}
+    if (staged.attachment.type === 'mp4') {
+      const directory = await mkdtemp(path.join(stagingRoot,'video-'))
+      try {
+        const probe = JSON.parse((await execute('ffprobe',['-v','error','-protocol_whitelist','file,pipe','-show_entries','format=duration:stream=codec_type','-of','json',staged.fullPath],{timeout:3000,maxBuffer:8000})).stdout)
+        const durationSeconds = Number(probe.format?.duration)
+        if (!Number.isFinite(durationSeconds) || durationSeconds <= 0 || durationSeconds > 120 || !probe.streams?.some((stream:{codec_type:string})=>stream.codec_type==='video')) throw Error('Video must contain a visual track and be at most 120 seconds')
+        await execute('ffmpeg',['-v','error','-nostdin','-protocol_whitelist','file,pipe','-enable_drefs','0','-use_absolute_path','0','-i',staged.fullPath,'-an','-vf',`fps=fps=${8/durationSeconds}:start_time=0,scale=640:-2`,'-frames:v','8','-q:v','3',path.join(directory,'frame-%02d.jpg')],{timeout:20000,maxBuffer:8000})
+        const names=(await readdir(directory)).filter(name=>/^frame-\d{2}\.jpg$/.test(name)).sort()
+        const images=[];let total=0
+        for (const frame of names) {
+          const image=await readFile(path.join(directory,frame));total+=image.length
+          if (total>1024*1024 || detectFileType(image)!=='jpeg') throw Error('Video frames exceed the bounded image limit')
+          images.push({data:image.toString('base64'),mimeType:'image/jpeg'})
+        }
+        if (!images.length) throw Error('Video has no decodable frames')
+        return {name:sanitizeFileName(name),type:'mp4',bytes:bytes.length,durationSeconds,frames:images.map((_,index)=>({frame:index+1,seconds:index*durationSeconds/8})),images}
+      } finally { await rm(directory,{recursive:true,force:true}) }
+    }
+    const limit = 256000
+    const text = staged.attachment.type === 'text' ? new TextDecoder('utf-8', {fatal:true}).decode(bytes)
+      : (await execute('pdftotext', ['-enc','UTF-8','-layout',staged.fullPath,'-'], {timeout:20000,maxBuffer:limit + 1}).catch(error => {
+        if ((error as {code?:unknown}).code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') throw Error('Extracted document exceeds the 256000-byte text limit')
+        throw error
+      })).stdout
+    if (!text.trim()) throw Error('Document has no extractable text; scanned PDFs require OCR')
+    if (Buffer.byteLength(text) > limit) throw Error('Extracted document exceeds the 256000-byte text limit')
+    return { name: sanitizeFileName(name), type: staged.attachment.type, bytes: bytes.length, text }
+  } finally { await unlink(staged.fullPath) }
+}

package/src/host-executor.ts

@@ -52,7 +52,7 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
   let catalogRefresh: Promise<void> | undefined
   const locks: string[] = []
   const sharedWorkspaces = new Map<HostBinding, string>()
-  const activeWorkspaces = new Map<HostBinding, { lanes: Set<boolean>; release?: () => Promise<void> }>()
+  const activeWorkspaces = new Map<HostBinding, { lanes: Map<string, boolean>; release?: () => Promise<void> }>()
   const additionalWorkspaces = new Map<HostBinding, string[]>()
   const catalog = async (agent: HostBinding) => {
     const discovered = await readModels(undefined, undefined, path.join(agent.controlDir, 'cli', 'codex'),
@@ -161,18 +161,18 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
           const base=path.join(directory,id)
           const scheduled = Boolean(run?.scheduled)
           let workspace = activeWorkspaces.get(agent)
-          if (workspace?.lanes.has(scheduled)) continue
+          if (!scheduled && workspace && [...workspace.lanes.values()].includes(false)) continue
           if (!workspace) {
             const release = agent.toolsHome
               ? await (await import('./plugins/workspace-lease.mjs')).workspaceLease(agent.toolsHome,{kind:'native',runId:id}) : undefined
             if (agent.toolsHome && !release) continue
-            workspace = { lanes: new Set(), release }
+            workspace = { lanes: new Map(), release }
             activeWorkspaces.set(agent, workspace)
           }
-          workspace.lanes.add(scheduled)
-          // Keep plugin workspace invocations excluded until both streams finish.
+          workspace.lanes.set(id, scheduled)
+          // Keep plugin workspace invocations excluded until all native jobs finish.
           const releaseWorkspace = async () => {
-            workspace.lanes.delete(scheduled)
+            workspace.lanes.delete(id)
             if (!workspace.lanes.size) {
               activeWorkspaces.delete(agent)
               await workspace.release?.()
@@ -195,30 +195,39 @@ export const serveHostExecutor = async (installation: HostInstallation, signal:
                 await new Tasks(agent.controlDir).authorize(run, false)
               } else await authorizeRun(agent.controlDir, path.basename(base))
               const opts=request.options as ExecutorOptions
-              if (run?.scheduled) {
-                assertScheduledModel(run.execution?.preset.model)
-                if (opts.model !== run.execution!.preset.model) throw new Error('Scheduled run model does not match its saved task model')
+              // Script occurrences come from the authorized run record, never the request.
+              if (run?.script) {
+                if (!run.scheduled) throw new Error('Script runs require a scheduled occurrence')
+                const options:ExecutorOptions={workspace:agent.workspace,controlDir:agent.controlDir,binDir:agent.binDir,toolsHome:agent.toolsHome,sharedWorkspace,additionalWorkspaces:additionalWorkspaces.get(agent),
+                  runId:path.basename(base),timeoutMs:0,repairEnabled:opts.repairEnabled,
+                  script:{...run.script,scheduleId:run.scheduled.id,scheduleRevision:run.scheduled.revision,dueAt:run.scheduled.dueAt}}
+                job=await launch(request.texts,options)
+              } else {
+                if (run?.scheduled) {
+                  assertScheduledModel(run.execution?.preset.model)
+                  if (opts.model !== run.execution!.preset.model) throw new Error('Scheduled run model does not match its saved task model')
+                }
+                const cli = opts.cli || installation.cli
+                resolveExecutor(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')
+                // Admission and execution must use the same catalog snapshot. A
+                // transient native-client probe failure must not reject a model
+                // that the host just advertised to the relay and application.
+                if (cli !== installation.cli) await validateSelection({id:'selected',name:'Selected model',cli,provider:opts.provider,model,effort:opts.effort},JSON.parse(await readFile(path.join(directory,'models.json'),'utf8')))
+                const options:ExecutorOptions={workspace: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,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)
               }
-              const cli = opts.cli || installation.cli
-              resolveExecutor(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')
-              // Admission and execution must use the same catalog snapshot. A
-              // transient native-client probe failure must not reject a model
-              // that the host just advertised to the relay and application.
-              if (cli !== installation.cli) await validateSelection({id:'selected',name:'Selected model',cli,provider:opts.provider,model,effort:opts.effort},JSON.parse(await readFile(path.join(directory,'models.json'),'utf8')))
-              const options:ExecutorOptions={workspace: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,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})
               if(signal.aborted)terminateJob(job.child)

package/src/index.ts

@@ -11,6 +11,8 @@ import { dispatchChannel } from './channel-backend.js'
 import { randomUUID } from 'node:crypto'
 import { stat } from 'node:fs/promises'
 import { Scheduler } from './scheduler.js'
+import { Scripts } from './scripts.js'
+import { redactFailure } from './failure.js'
 import { ownedScheduledTasks, scheduledTaskDetailText, scheduledTasksText } from './scheduled-tasks.js'
 import { EventSources, eventRunId, batchReady, type SourceEvent } from './event-sources.js'
 import {removeTaskAttachments} from './task-attachments.js'
@@ -25,7 +27,7 @@ import { InboxStore, type IncomingItem } from './inbox.js'
 import { loadConfig, type Config } from './config.js'
 import { ControlStore, telegramOwner, ownerId, ownerEpoch } from './control-state.js'
 import { ApprovalStore } from './approval.js'
-import { startExecutorJob, terminateJob, opencodeDataHome } from './executor.js'
+import { startExecutorJob, terminateJob, opencodeDataHome, claudeConfigHome } from './executor.js'
 import { assertScheduledModel } from './model-policy.js'
 import { RunStore, type RunRecord } from './runs.js'
 import { splitTelegramText } from './reply.js'
@@ -44,7 +46,7 @@ import { softwareStatus } from './software-status.js'
 export const createRelay = (config: Config, launch = startExecutorJob) => {
   const safeError = (error: unknown): string => {
     let message = error instanceof Error ? error.message : typeof error === 'string' ? error : 'Unknown error'
-    for (const secret of [config.channelBackendToken, config.telegramBotToken, config.geminiApiKey, config.openaiApiKey]) {
+    for (const secret of [config.channelBackendToken, config.telegramBotToken, config.geminiApiKey, config.openaiApiKey, config.openrouterApiKey]) {
       if (secret) message = message.replaceAll(secret, '[redacted]')
     }
     return message
@@ -60,7 +62,9 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const scheduler = new Scheduler(config.controlDir)
   const background = new Map<string, ChildProcess>()
   const completions = new Set<Promise<void>>()
-  const tasks = new Tasks(config.controlDir)
+  const speechOptions = { geminiApiKey: config.geminiApiKey, openrouterApiKey: config.openrouterApiKey, speechProvider: config.speechProvider, speechModel: config.speechModel }
+  const speechConfigured = config.speechProvider === 'openrouter' ? Boolean(config.openrouterApiKey) : Boolean(config.geminiApiKey)
+  const tasks = new Tasks(config.controlDir, speechConfigured ? (text) => synthesizeSpeech(text, { ...speechOptions, voice: config.speechVoiceEn, signal: AbortSignal.timeout(20000) }) : undefined)
   const processTaskRequests = taskRequests(tasks)
   let taskWork: Promise<void> | undefined
   const drainTaskRequests = (): Promise<void> => {
@@ -103,8 +107,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const applicationChannel = new ApplicationChannel({
     controlDir: config.controlDir, workspace: config.workspace, isolation: config.isolation, initial: aiMenu.initial,
     aiControls: aiMenu,
-    speech: config.geminiApiKey ? (text, language) => synthesizeSpeech(text, {
-      geminiApiKey: config.geminiApiKey,
+    speech: speechConfigured ? (text, language) => synthesizeSpeech(text, {
+      ...speechOptions,
       voice: language === 'es' ? config.speechVoiceEs : config.speechVoiceEn,
       format: 'wav',
     }) : undefined,
@@ -207,8 +211,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       }
       if (run.scheduled && !(await scheduler.get(run.scheduled.id)).enabled) return
       // A long scheduled turn must not occupy the owner's chat stream.
-      // Each stream remains serial, with separate native sessions.
-      if (run.scheduled ? background.size > 0 : activeChild !== null) return
+      // Foreground stays serial; scheduled jobs have independent native sessions.
+      if (run.scheduled ? background.size >= (config.scheduledConcurrency ?? 6) : activeChild !== null) return
       let texts = run.texts
       if (run.external) {
         // Availability failures leave durable queued work for a later check.
@@ -235,14 +239,23 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       try {
         const launchStarted = performance.now()
         const started = await runs.patch(run.id, { status: 'running', startedAt: new Date().toISOString() })
-        if (!started.execution && !run.taskId) throw new Error('Legacy queued work has no pinned AI. Resend the request after /new.')
+        // A registered script occurrence: no model, prompt or native session.
+        const script = run.script && run.scheduled
+          ? { registration: await new Scripts(config.controlDir).owned(run.script.id, owner), ref: run.script, scheduled: run.scheduled }
+          : undefined
+        if (run.script && !script) throw new Error('Script runs require a scheduled occurrence')
+        if (!started.execution && !run.taskId && !script) throw new Error('Legacy queued work has no pinned AI. Resend the request after /new.')
         const startsOwnSession = Boolean(run.external || run.taskId || run.scheduled)
         const session = startsOwnSession
           ? { sessionId: randomUUID(), hasStarted: false, nativeSessionId: undefined }
           : await control.executionSession(started.execution!)
-        const selected = run.taskId ? (started.execution?.preset.cli === 'codex' ? started.execution.preset : initialPreset('codex')) : started.execution!.preset
-        if (run.scheduled) assertScheduledModel(selected.model)
-        const { child, cleanup } = await launch(texts, {
+        const selected = script ? initialPreset('codex') : run.taskId ? (started.execution?.preset.cli === 'codex' ? started.execution.preset : initialPreset('codex')) : started.execution!.preset
+        if (run.scheduled && !script) assertScheduledModel(selected.model)
+        const { child, cleanup } = await launch(texts, script ? {
+          workspace: config.workspace, timeoutMs: 0, repairEnabled: config.repairEnabled, runId: started.id,
+          controlDir: config.controlDir, binDir,
+          script: { ...script.ref, scheduleId: script.scheduled.id, scheduleRevision: script.scheduled.revision, dueAt: script.scheduled.dueAt },
+        } : {
           workspace: config.workspace,
           timeoutMs: config.executorTimeoutMs,
           repairEnabled: config.repairEnabled,
@@ -265,9 +278,14 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         const executionStarted = performance.now()
         // Attach before disk writes: a fast child can close while PID persistence
         // is pending, and Node drains its remaining pipes during process close.
-        let failureReason = 'executor-exit', errorTail = '', interrupted = false
+        let failureReason = 'executor-exit', errorTail = '', interrupted = false, outputTail = '', timedOut = false
+        // Script output is bounded diagnostics for run inspection, never chat.
+        if (script) child.stdout?.setEncoding('utf8').on('data', (chunk: string) => { outputTail = (outputTail + chunk).slice(-16384) })
+        const scriptTimer = script ? setTimeout(() => { timedOut = true; terminateJob(child) }, script.registration.timeoutSeconds * 1000) : undefined
+        child.once('close', () => clearTimeout(scriptTimer))
         child.stderr?.setEncoding('utf8').on('data', (chunk: string) => {
           errorTail = (errorTail + chunk).slice(-16384)
+          if (script) outputTail = (outputTail + chunk).slice(-16384)
           if (chunk.includes('Host CLI executor is offline')) failureReason = 'host-executor-offline'
           if (chunk.includes('Host executor client interrupted by')) {
             failureReason = 'host-executor-transport-interrupted'
@@ -288,7 +306,8 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
         console.info('run started', {
           run_id: started.id,
           pid: child.pid,
-          cli: selected.cli,
+          cli: script ? 'script' : selected.cli,
+          ...(script ? { script: script.ref.id, script_revision: script.ref.revision } : {}),
           session: session.sessionId,
           isResume: session.hasStarted,
         })
@@ -306,8 +325,12 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
               try {
                 await cleanup()
                 if (code === 0 && !run.external && !run.taskId && !run.scheduled) await control.markSessionStarted(session.sessionId)
-                const cancelled = ownerStopped.has(child) || Boolean(run.scheduled && await scheduler.cancelled(run.id))
-                await runs.patch(started.id, { status: cancelled ? 'cancelled' : code === 0 ? 'completed' : 'failed', endedAt: new Date().toISOString(), exitCode: code, ...(code !== 0 && !cancelled ? { failureReason, interrupted, failure: await failureEvidence(config.controlDir, safeError(errorTail || `Executor exited with ${code === null ? 'a signal' : `code ${code}`}`)) } : {}) })
+                const cancelled = !timedOut && (ownerStopped.has(child) || Boolean(run.scheduled && await scheduler.cancelled(run.id)))
+                if (timedOut) failureReason = 'script-timeout'
+                const failed = !cancelled && (code !== 0 || timedOut)
+                await runs.patch(started.id, { status: cancelled ? 'cancelled' : failed ? 'failed' : 'completed', endedAt: new Date().toISOString(), exitCode: code,
+                  ...(script ? { output: redactFailure(safeError(outputTail)), ...(timedOut ? { timedOut } : {}) } : {}),
+                  ...(failed ? { failureReason, interrupted, failure: await failureEvidence(config.controlDir, safeError(timedOut ? `Script exceeded its ${script!.registration.timeoutSeconds}s timeout and was terminated` : errorTail || `Executor exited with ${code === null ? 'a signal' : `code ${code}`}`)) } : {}) })
                 await releaseExternal(run)
               } catch (error) {
                 await runs.patch(started.id, { status: ownerStopped.has(child) ? 'cancelled' : 'failed', failureReason: 'session-finalization', failure: await failureEvidence(config.controlDir, safeError(error)), endedAt: new Date().toISOString() })
@@ -587,8 +610,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
           } else if (item.type === 'voice' && item.voiceText) {
             await bot!.api.sendChatAction(item.chatId, 'record_voice')
             const { buffer } = await synthesizeSpeech(item.voiceText, {
-              geminiApiKey: config.geminiApiKey,
-              openaiApiKey: config.openaiApiKey,
+              ...speechOptions,
               voice: config.speechVoiceEn,
             })
             await paceSend()
@@ -719,7 +741,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
     const delivery = await runs.deliveryStatus()
     const ai = await control.aiState(aiMenu.initial)
     const selected = ai.presets.find((p) => p.id === ai.selectedId)!
-    const discovered = await discoverDefaults(config.workspace, { codexHome, nativeCodexFallback: true })
+    const discovered = await discoverDefaults(config.workspace, { codexHome, claudeHome: claudeConfigHome(config.controlDir), nativeCodexFallback: true })
     const displayedSelected = statusPreset(selected, discovered)
     const scheduled = all.filter(run => run.scheduled && run.status === 'running').length
     const queued = all.filter(run => run.status === 'queued').length
@@ -743,6 +765,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
       '',
       'Work',
       `Current: ${running ? (waitingForHost ? 'waiting for the workspace' : 'running') : 'idle'}`,
+      `Scheduled limit: ${config.scheduledConcurrency ?? 6}`,
       `Background: ${scheduled ? `${scheduled} scheduled task${scheduled === 1 ? '' : 's'} running` : 'none'}`,
       `Queue: ${queued || incoming.pending ? `${queued} run${queued === 1 ? '' : 's'}; ${incoming.pending} incoming message${incoming.pending === 1 ? '' : 's'}` : 'empty'}`,
       ...(attention.length ? ['', 'Needs attention', ...attention] : []),

package/src/install-tools.mjs

@@ -16,13 +16,14 @@ export const hostEnvironment=()=>Object.fromEntries(['HOME','PATH','LANG','LC_AL
 async function atomic(file,value) {
   const tmp=file+'.'+randomUUID()+'.tmp';await fs.writeFile(tmp,JSON.stringify(value)+'\n',{mode:0o600,flag:'wx'});await fs.rename(tmp,file);
 }
-export function run(command,args,{cwd,log,timeout=15000}={}) {
+export function run(command,args,{cwd,log,timeout=15000,stdoutOnly=false}={}) {
   return new Promise((resolve,reject)=>{
-    const child=spawn(command,args,{cwd,env:hostEnvironment(),stdio:['ignore',log??'pipe',log??'pipe']});let output='';
-    for(const stream of [child.stdout,child.stderr])stream?.on('data',b=>output=(output+b).slice(-200000));
+    const child=spawn(command,args,{cwd,env:hostEnvironment(),stdio:['ignore',log??'pipe',log??'pipe']});let output='',stdout='';
+    child.stdout?.on('data',b=>{output=(output+b).slice(-200000);if(stdoutOnly)stdout=(stdout+b).slice(-200000);});
+    child.stderr?.on('data',b=>output=(output+b).slice(-200000));
     const timer=setTimeout(()=>child.kill('SIGTERM'),timeout);
     child.once('error',e=>{clearTimeout(timer);reject(e);});
-    child.once('close',code=>{clearTimeout(timer);if(code!==0)reject(Error(`${command} failed (${code})${log===undefined?': '+output.trim():''}`));else resolve(output.trim());});
+    child.once('close',code=>{clearTimeout(timer);if(code!==0)reject(Error(`${command} failed (${code})${log===undefined?': '+output.trim():''}`));else resolve((stdoutOnly?stdout:output).trim());});
   });
 }
 export const defaultHome=()=>path.join(process.env.XDG_DATA_HOME||path.join(homedir(),'.local/share'),'ez');
@@ -115,7 +116,9 @@ export async function migrateLedger({ deployment } = {}) {
 }
 
 export async function latestCodexVersion(invoke,manager={command:"npm",args:[]}) {
-  const version=JSON.parse(await invoke(manager.command,[...manager.args,'view','@openai/codex@latest','version','--json','--registry','https://registry.npmjs.org/']));
+  const output=await invoke(manager.command,[...manager.args,'view','@openai/codex@latest','version','--json','--registry','https://registry.npmjs.org/'],{stdoutOnly:true});
+  let version;
+  try {version=JSON.parse(output);}catch {throw Error('Codex version discovery returned invalid JSON on stdout');}
   if(typeof version!=='string'||!/^\d+\.\d+\.\d+$/.test(version))throw Error('Invalid latest Codex version');
   return version;
 }

package/src/menu.ts

@@ -6,6 +6,7 @@ import { InlineKeyboard, type Context } from 'grammy'
 import { ControlStore, type ControlGuard } from './control-state.js'
 import { chatPreset, installed, persistedPreset, presetLabel, presetProvider, readModels, validateSelection, type AiPreset, type ModelChoice } from './ai.js'
 import { discoverDefaults } from './client-defaults.js'
+import { claudeConfigHome } from './executor.js'
 
 export const mainCommands = [
   { command: 'new', description: 'New conversation' },
@@ -38,14 +39,15 @@ export const createAiMenu = (control: ControlStore, cli: string, catalog = readM
   // directory, but the default catalog probed the process home instead. Bind it
   // to the same agent-bound home so /ai lists the models Codex can actually run.
   else if (codexHome && catalog === readModels) catalog = () => readModels(undefined, isInstalled, codexHome, undefined, opencodeDataHome, undefined, process.env.EZ_CONTROL_DIR)
-  const refresh = async () => control.syncClientPresets(initial, host ? [] : await discoverDefaults(workspace, { codexHome }))
+  const claudeHome = process.env.EZ_CONTROL_DIR ? claudeConfigHome(process.env.EZ_CONTROL_DIR) : undefined
+  const refresh = async () => control.syncClientPresets(initial, host ? [] : await discoverDefaults(workspace, { codexHome, claudeHome }))
   const validate = async (preset: AiPreset) => {
     assertEffort(preset.effort, preset.model, preset.cli)
     if (preset.id === initial.id) return
     if (preset.id.startsWith('detected_')) {
       if (host) await validateSelection(preset, await catalog(), async name => (await catalog()).some(model => model.cli === name))
       else {
-        const detected = await discoverDefaults(workspace, { codexHome })
+        const detected = await discoverDefaults(workspace, { codexHome, claudeHome })
         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)

package/src/plugin-broker.mjs

@@ -1,4 +1,6 @@
+import { combinePreflight } from './schedule-preflight.js';
 import * as fs from 'node:fs/promises';
+import {callDeliverySocket} from './delivery-socket-client.mjs';
 import path from 'node:path';
 import { createServer } from 'node:net';
 import { randomBytes, randomUUID, createHash } from 'node:crypto';
@@ -223,23 +225,37 @@ const managerCommand = async (binding, args, signal, runId) => new Promise((reso
   });
 });
 
-const invokePlugin = async (binding, request, signal) => {
+const authorizeTaskLaunch=async(binding,request)=>{
+  const input=JSON.parse(request.stdin)
+  if(Object.keys(input).some(k=>!['taskId','taskToken','expiresAt'].includes(k)) || typeof input.taskToken!=='string' || !/^[a-f0-9]{64}$/.test(input.taskToken))throw Error('Invalid task launch input')
+  const ticketHash=createHash('sha256').update(input.taskToken).digest('hex')
+  const grant=await callDeliverySocket(deliverySocketPath(binding.controlDir),{op:'taskApplication',payload:{runId:request.runId,ticketHash}})
+  if(input.taskId!==grant.taskId || input.expiresAt!==grant.expiresAt)throw Error('Task launch authority mismatch')
+  return grant.launch
+}
+const invokePlugin = async (binding, request, signal, scheduledPreflight = false) => {
   const startedAt = new Date().toISOString();
   let plugin = request.alias;
   let revision = request.revision;
   let result;
   let failure;
   try {
-    await authorize(binding, request.runId);
+    if (!scheduledPreflight) {
+      if(request.operation==='task-launch') {
+        const launch=await authorizeTaskLaunch(binding,request)
+        if(launch.command!==request.alias || JSON.stringify(launch.args)!==JSON.stringify(request.args))throw Error('Task launch command changed')
+      }else await authorize(binding, request.runId);
+    }
     const current = await registry(binding.home);
     const selected = recordForAlias(current, request.alias);
+    if (scheduledPreflight && (!selected.command.exposure || selected.command.exposure.changesRecords !== false || selected.command.exposure.sendsExternally !== false)) throw Error('Scheduled preflight requires an explicitly read-only plugin command');
     plugin = selected.plugin;
     revision = selected.record.revision;
     if (selected.record.revision !== request.revision) throw Error('Plugin changed; discover again');
     const command = await prepareCommand(binding.home, request.alias, request.args, {
       revision: request.revision,
       invocation: true,
-      environment: { EZ_CONTROL_DIR: binding.controlDir, EZ_RUN_ID: request.runId, EZ_DELIVERY_SOCKET: process.env.EZ_DELIVERY_SOCKET ?? deliverySocketPath(binding.controlDir) },
+      environment: { EZ_CONTROL_DIR: binding.controlDir, ...(scheduledPreflight ? {} : {EZ_RUN_ID: request.runId}), EZ_DELIVERY_SOCKET: process.env.EZ_DELIVERY_SOCKET ?? deliverySocketPath(binding.controlDir) },
     });
     try {
       result = await dockerRun(command.argv, {
@@ -282,8 +298,17 @@ const invokePlugin = async (binding, request, signal) => {
 
 export async function validateBrokerRequest(request, workspace) {
   if (!request || typeof request !== 'object' || request.version !== 1 || !REQUEST_ID.test(request.id)) throw Error('Invalid plugin broker request');
-  if (!['resolve', 'invoke', 'manager'].includes(request.operation)) throw Error('Unknown plugin broker operation');
+  if(request.operation === 'preflight') {
+    validId(request.scheduleId,RUN_ID,'schedule ID'); validId(request.revision,/^[a-f0-9-]{36}$/,'schedule revision');
+    if(Object.keys(request).some(k=>!['version','id','operation','scheduleId','revision'].includes(k))) throw Error('Unexpected schedule preflight field');
+    return request;
+  }
+  if (!['resolve', 'invoke', 'manager','task-launch'].includes(request.operation)) throw Error('Unknown plugin broker operation');
   validId(request.runId, RUN_ID, 'plugin run ID');
+  if(request.operation==='task-launch') {
+    if(Object.keys(request).some(k=>!['version','id','operation','runId','stdin'].includes(k)))throw Error('Unexpected task launch field')
+    boundedString(request.stdin,1024,'task launch stdin');return request
+  }
   if (request.operation === 'manager') {
     await validateManagerArgs(request.args, workspace);
     if (Object.keys(request).some(key => !['version', 'id', 'operation', 'runId', 'args'].includes(key))) throw Error('Unexpected broker management field');
@@ -328,6 +353,18 @@ export async function servePluginBroker(binding, signal = new AbortController().
       (async () => {
         try {
           await validateBrokerRequest(request, binding.workspace);
+          if (request.operation === 'preflight') {
+            const condition=await (await import('./delivery-socket-client.mjs')).callDeliverySocket(deliverySocketPath(binding.controlDir),{op:'schedulePreflight',payload:{scheduleId:request.scheduleId,revision:request.revision}});
+            const values=[];
+            for(const check of condition.checks) {
+              const selected=recordForAlias(await registry(binding.home),check.alias);
+              const result=await invokePlugin(binding,{alias:check.alias,args:check.args,revision:selected.record.revision,runId:`preflight_${request.scheduleId}`,id:randomUUID()},abort.signal,true);
+              if(!result.ok || result.code!==0) throw Error('Scheduled plugin preflight unavailable');
+              values.push(JSON.parse(result.stdout));
+            }
+            response(socket,{version:1,id:request.id,ok:true,result:combinePreflight(values)});
+            return;
+          }
           if (request.operation === 'resolve') {
             await authorize(binding, request.runId);
             const selected = recordForAlias(await registry(binding.home), request.alias);
@@ -338,6 +375,12 @@ export async function servePluginBroker(binding, signal = new AbortController().
             response(socket, { version: 1, id: request.id, ok: true, plugin: selected.plugin, alias: request.alias, revision: selected.record.revision, capability });
             return;
           }
+          if(request.operation==='task-launch') {
+            const launch=await authorizeTaskLaunch(binding,request)
+            const selected=recordForAlias(await registry(binding.home),launch.command)
+            const result=await invokePlugin(binding,{...request,alias:launch.command,args:launch.args,revision:selected.record.revision},abort.signal)
+            response(socket,{version:1,id:request.id,...result});return
+          }
           if (request.operation === 'manager') {
             await authorize(binding, request.runId);
             const result = await managerCommand(binding, request.args, abort.signal, request.runId);