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

package/src/audio.ts

@@ -6,6 +6,10 @@ export type AudioOptions = {
   geminiApiKey?: string
   openaiApiKey?: string
   voice?: string
+  speechProvider?: 'gemini' | 'openrouter'
+  speechModel?: string
+  openrouterApiKey?: string
+  signal?: AbortSignal
 }
 
 export class SpeechCreditsDepletedError extends Error {
@@ -32,27 +36,12 @@ export const pcmToWav = (pcm: Buffer, sampleRate = 24000, channels = 1): Buffer
   return Buffer.concat([header, pcm])
 }
 
-export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1): Promise<Buffer> => {
+const convertSpeech = (audio: Buffer, input: 's16le' | 'mp3', format: 'wav' | 'ogg', sampleRate = 24000, channels = 1): Promise<Buffer> => {
   return new Promise((resolve, reject) => {
     const invocation = executorInvocation(
       'ffmpeg',
-      [
-        '-f',
-        's16le',
-        '-ar',
-        String(sampleRate),
-        '-ac',
-        String(channels),
-        '-i',
-        '-',
-        '-c:a',
-        'libopus',
-        '-b:a',
-        '32k',
-        '-f',
-        'ogg',
-        '-',
-      ],
+      [...(input === 's16le' ? ['-f', 's16le', '-ar', String(sampleRate), '-ac', String(channels)] : ['-f', 'mp3']),
+        '-i', '-', ...(format === 'ogg' ? ['-c:a', 'libopus', '-b:a', '32k', '-f', 'ogg'] : ['-ar', '24000', '-ac', '1', '-f', 's16le']), '-'],
     )
     const child = spawn(invocation.command, invocation.args,
       { env: executorEnvironment(), stdio: ['pipe', 'pipe', 'pipe'] })
@@ -60,7 +49,8 @@ export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1): Pr
     const output: Buffer[] = []
     let error = ''
 
-    child.stdout.on('data', (chunk) => output.push(chunk))
+    let outputBytes = 0
+    child.stdout.on('data', (chunk) => { outputBytes += chunk.length; if(outputBytes > 16 * 1024 * 1024) { child.kill('SIGKILL'); reject(new Error('Encoded speech exceeds limit')) } else output.push(chunk) })
     child.stderr.on('data', (chunk) => {
       error = (error + chunk.toString()).slice(-2048)
     })
@@ -70,16 +60,18 @@ export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1): Pr
 
     child.on('close', (code) => {
       if (code === 0 && output.length > 0) {
-        resolve(Buffer.concat(output))
+        resolve(format === 'wav' ? pcmToWav(Buffer.concat(output)) : Buffer.concat(output))
       } else {
         reject(new Error(`Voice encoding failed (${code}): ${error}`))
       }
     })
 
-    child.stdin.end(pcm)
+    child.stdin.end(audio)
   })
 }
 
+export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1) => convertSpeech(pcm, 's16le', 'ogg', sampleRate, channels)
+
 export const transcribeAudio = async (
   audioBytes: Buffer,
   mimeType: string,
@@ -146,6 +138,29 @@ export const synthesizeSpeech = async (
   const trimmed = text.trim()
   if (!trimmed) throw new Error('Cannot synthesize speech for empty text')
 
+  if ((options.speechProvider ?? process.env.EZ_SPEECH_PROVIDER) === 'openrouter') {
+    const key = (options.openrouterApiKey ?? process.env.OPENROUTER_API_KEY)?.trim()
+    if (!key) throw new Error('OpenRouter speech is not configured')
+    const response = await fetch('https://openrouter.ai/api/v1/audio/speech', {
+      method: 'POST', signal: options.signal ?? AbortSignal.timeout(60000),
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+      body: JSON.stringify({ model: options.speechModel ?? process.env.EZ_SPEECH_MODEL ?? 'fish-audio/s2.1-pro-free:free',
+        input: trimmed, response_format: 'mp3', ...(options.voice ? { voice: options.voice } : {}) })
+    })
+    if (!response.ok) { await response.body?.cancel(); throw new Error(`OpenRouter speech synthesis error ${response.status}`) }
+    const chunks: Buffer[] = []; let size = 0
+    const reader = response.body?.getReader()
+    if (!reader) throw new Error('OpenRouter returned no audio')
+    try {
+      for (;;) { const {done,value} = await reader.read(); if(done) break
+        size += value.length; if(size > 16 * 1024 * 1024) throw new Error('Speech audio exceeds limit')
+        chunks.push(Buffer.from(value)) }
+    } finally { await reader.cancel() }
+    if (!size) throw new Error('OpenRouter returned no audio')
+    const buffer = await convertSpeech(Buffer.concat(chunks), 'mp3', options.format ?? 'ogg')
+    return { buffer, mimeType: options.format === 'wav' ? 'audio/wav' : 'audio/ogg' }
+  }
+
   const geminiKey = (options.geminiApiKey ?? process.env.GEMINI_API_KEY)?.trim()
   if (geminiKey) {
     const url =
@@ -154,7 +169,7 @@ export const synthesizeSpeech = async (
     const response = await fetch(url, {
       method: 'POST',
       headers: { 'content-type': 'application/json', 'x-goog-api-key': geminiKey },
-      signal: AbortSignal.timeout(60_000),
+      signal: options.signal ?? AbortSignal.timeout(60_000),
       body: JSON.stringify({
         contents: [{ parts: [{ text: trimmed }] }],
         generationConfig: {

package/src/client-defaults.ts

@@ -78,7 +78,7 @@ export const grokSettings = (text: string): { model?: string; effort?: string }
 }
 
 export const discoverDefaults = async (cwd: string, options: {
-  home?: string; codexHome?: string; nativeCodexFallback?: boolean; available?: typeof installed; run?: typeof command; codex?: typeof codexDefaults
+  home?: string; codexHome?: string; claudeHome?: string; nativeCodexFallback?: boolean; available?: typeof installed; run?: typeof command; codex?: typeof codexDefaults
 } = {}): Promise<AiPreset[]> => {
   const home = options.home ?? homedir()
   const available = options.available ?? installed
@@ -99,7 +99,8 @@ export const discoverDefaults = async (cwd: string, options: {
         model = value(config.model); effort = value(config.effort)
       } else if (cli === 'claude') {
         // Match Claude's documented user -> project -> local settings precedence.
-        const settings = Object.assign({}, await json(join(home, '.claude/settings.json')),
+        // User settings come from the agent-bound CLAUDE_CONFIG_DIR when bound.
+        const settings = Object.assign({}, await json(join(options.claudeHome ?? join(home, '.claude'), 'settings.json')),
           await json(join(cwd, '.claude/settings.json')), await json(join(cwd, '.claude/settings.local.json')))
         model = value(settings.model); effort = value(settings.effortLevel)
       } else if (cli === 'opencode') {

package/src/config.ts

@@ -19,12 +19,16 @@ export type Config = ControlConfig & {
   isolation?: IsolationClass
   codexSandbox?: 'external'
   codexAutoCompactTokens?: number
+  scheduledConcurrency?: number
   executorCli: string
   channelBackendUrl?: string
   channelBackendToken?: string
   applicationPort?: number
   applicationHost?: string
   geminiApiKey?: string
+  speechProvider?: 'gemini' | 'openrouter'
+  speechModel?: string
+  openrouterApiKey?: string
   speechVoiceEn?: string
   speechVoiceEs?: string
   openaiApiKey?: string
@@ -69,6 +73,7 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
   const codexSandbox = env.EZ_CODEX_SANDBOX?.trim()
   if (codexSandbox && codexSandbox !== 'external') throw new Error('EZ_CODEX_SANDBOX must be external or unset')
   if (codexSandbox && (env.EZ_CHANNEL_BACKEND_URL || transport !== 'local')) throw new Error('External Codex sandbox requires native local execution')
+  if (env.EZ_SPEECH_PROVIDER && !['gemini','openrouter'].includes(env.EZ_SPEECH_PROVIDER)) throw new Error('Invalid EZ_SPEECH_PROVIDER')
   return {
     ...loadControlConfig(env),
     telegramEnabled,
@@ -80,12 +85,16 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
     isolation,
     codexSandbox: codexSandbox === 'external' ? 'external' : undefined,
     codexAutoCompactTokens: !env.EZ_CODEX_AUTO_COMPACT_TOKENS?.trim() ? undefined : positiveInteger(env.EZ_CODEX_AUTO_COMPACT_TOKENS, 'EZ_CODEX_AUTO_COMPACT_TOKENS'),
+    scheduledConcurrency: positiveInteger(env.EZ_SCHEDULED_CONCURRENCY, 'EZ_SCHEDULED_CONCURRENCY', 6),
     executorCli: env.EZ_EXECUTOR_CLI?.trim() || 'codex',
     applicationPort: env.EZ_APPLICATION_PORT ? positiveInteger(env.EZ_APPLICATION_PORT, 'EZ_APPLICATION_PORT') : undefined,
     applicationHost: env.EZ_APPLICATION_HOST?.trim() || '127.0.0.1',
     channelBackendUrl: env.EZ_CHANNEL_BACKEND_URL?.trim(),
     channelBackendToken: env.EZ_CHANNEL_BACKEND_TOKEN?.trim(),
     geminiApiKey: env.GEMINI_API_KEY?.trim(),
+    speechProvider: env.EZ_SPEECH_PROVIDER as Config['speechProvider'],
+    speechModel: env.EZ_SPEECH_MODEL?.trim(),
+    openrouterApiKey: env.OPENROUTER_API_KEY?.trim(),
     speechVoiceEn: env.EZ_SPEECH_VOICE_EN?.trim(),
     speechVoiceEs: env.EZ_SPEECH_VOICE_ES?.trim(),
     openaiApiKey: env.OPENAI_API_KEY?.trim(),

package/src/control-state.ts

@@ -755,7 +755,9 @@ export class ControlStore {
       const state = await this.readState()
       await requireControlGuard(state, guard)
       if (!state.ai) throw new Error('AI settings not initialized')
-      if (state.ai.presets.length >= 12 && !state.ai.presets.some((p) => p.id === preset.id))
+      // Auto-detected client defaults come and go with installed clients; only
+      // owner-saved choices count toward the cap.
+      if (state.ai.presets.filter((p) => !p.id.startsWith('detected_')).length >= 12 && !state.ai.presets.some((p) => p.id === preset.id))
         throw new Error('Keep it small: at most 12 saved AIs.')
       state.ai.presets = [...state.ai.presets.filter((p) => p.id !== preset.id), persistedPreset(preset)]
       await this.writeState(state)

package/src/delivery-socket-client.d.mts

@@ -2,3 +2,5 @@ export type DeliverySocketRequest = { op: string; payload?: unknown }
 export function deliverySocketPath(controlDir: string): string
 export function callDeliverySocket(socketPath: string, op: DeliverySocketRequest, timeoutMs?: number): Promise<unknown>
 export function deliverySocketAlive(socketPath: string, timeoutMs?: number): Promise<boolean>
+
+export function callLocalSocket(socketPath:string, envelope:Record<string,unknown>, timeoutMs?:number):Promise<unknown>

package/src/delivery-socket-client.mjs

@@ -67,6 +67,8 @@ const exchange = (connect, envelope, timeoutMs, target) => new Promise((resolve,
   socket.write(encode(envelope))
 })
 
+export const callLocalSocket = (socketPath, envelope, timeoutMs = 130000) => exchange(() => createConnection(socketPath), envelope, timeoutMs, socketPath)
+
 const readEndpoint = async controlDir => {
   try {
     const value = JSON.parse(await readFile(path.join(controlDir, endpointName), 'utf8'))

package/src/delivery-socket.ts

@@ -1,3 +1,5 @@
+import { sameOwner } from './control-state.js'
+import { ApplicationBindings } from './application-channel.js'
 import { createServer, type Server, type Socket } from 'node:net'
 import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { rename, rm, writeFile } from 'node:fs/promises'
@@ -8,6 +10,9 @@ import { ApprovalStore } from './approval.js'
 import { deliveredMessages } from './message-history.js'
 import { readOnlyOwner, requireOwnerExecution } from './execution-authority.js'
 import { telegramOwner } from './control-state.js'
+import { Scheduler } from './scheduler.js'
+import {Tasks} from './tasks.js'
+import { runEvidence, type EvidenceOptions } from './run-evidence.js'
 
 // Stateless pipe transport. The relay owns the runs/outbox ledger in process
 // memory; engine children, plugin children and the host executor reach it
@@ -27,15 +32,19 @@ export { deliverySocketPath }
 export type DeliverySocketOp =
   | { op: 'ping' }
   | { op: 'status' }
+  | { op: 'schedulePreflight'; payload?: Record<string, unknown> }
+  | { op: 'triggerSchedule'; payload: { scheduleId: string; revision: string; key: string; callerRunId?: string } }
   | { op: 'enqueue'; payload: Record<string, unknown> }
   | { op: 'wait'; payload: { id: string; timeoutMs?: number } }
   | { op: 'get'; payload: { runId: string } }
   | { op: 'list'; payload?: Record<string, never> }
   | { op: 'patch'; payload: { runId: string; change: Record<string, unknown> } }
+  | { op: 'taskApplication'; payload: {runId:string;ticketHash:string} }
   | { op: 'authorize'; payload: { runId: string } }
   | { op: 'receipt'; payload: { context: unknown; id: string } }
   | { op: 'history'; payload: { runId: string; limit?: number; messageId?: number } }
   | { op: 'deliveryStatus'; payload?: Record<string, never> }
+  | { op: 'evidence'; payload: EvidenceOptions }
   | { op: 'approvalCheck'; payload: { actionId: string } }
   | { op: 'latestReply'; payload?: Record<string, never> }
 
@@ -208,6 +217,30 @@ export const createLedgerHandler = (controlDir: string, hooks: LedgerHooks): Del
           queued: all.filter((run) => run.status === 'queued').length,
         }
       }
+      case 'schedulePreflight': {
+        const {scheduleId,revision}=op.payload ?? {}
+        if(!nonEmptyString(scheduleId) || !nonEmptyString(revision)) throw Error('Schedule preflight identity required')
+        const scheduler=new Scheduler(controlDir),s=await scheduler.get(scheduleId),owner=await readOnlyOwner(controlDir)
+        if(!owner || !sameOwner(owner,s.owner) || !s.enabled || s.revision!==revision || !s.preflight) throw Error('Schedule preflight binding unavailable')
+        if(s.delivery) {
+          const binding=(await new ApplicationBindings(controlDir).list()).find(b=>b.bindingId===s.delivery!.bindingId)
+          if(!binding || !sameOwner(owner,binding.owner)) throw Error('Schedule preflight delivery revoked')
+        }
+        return s.preflight
+      }
+      case 'triggerSchedule': {
+        const {scheduleId,revision,key,callerRunId}=op.payload ?? {}
+        if (!nonEmptyString(scheduleId) || !nonEmptyString(revision) || !nonEmptyString(key)) throw new Error('Task ID, revision and request key are required')
+        if (callerRunId !== undefined) {
+          const caller=await requireOwnerExecution(controlDir,callerRunId)
+          if (caller.replyOnly || caller.script || (caller.scheduled && caller.scheduled.pairedAt !== (await readOnlyOwner(controlDir))?.pairedAt)) throw new Error('Scheduling requires an active owner-authorized run')
+        }
+        const owner=await readOnlyOwner(controlDir)
+        if (!owner) throw new Error('Pair an owner before scheduling')
+        const run=await new Scheduler(controlDir).trigger(scheduleId,revision,key,owner,runs)
+        hooks.wake()
+        return run
+      }
       case 'enqueue': {
         const envelope = (op.payload ?? {}) as Record<string, unknown>
         if (envelope.kind === 'owner') {
@@ -287,6 +320,10 @@ export const createLedgerHandler = (controlDir: string, hooks: LedgerHooks): Del
         if (!payload.change || typeof payload.change !== 'object') throw new Error('Patch change is required')
         return runs.patch(payload.runId, payload.change as never)
       }
+      case 'taskApplication': {
+        const p=op.payload as {runId:string;ticketHash:string}
+        return new Tasks(controlDir).authorizeApplicationLaunch(p.runId,p.ticketHash)
+      }
       case 'authorize': {
         const runId = (op.payload as { runId?: unknown } | undefined)?.runId
         if (typeof runId !== 'string' || !runId) throw new Error('Run ID is required')
@@ -306,6 +343,7 @@ export const createLedgerHandler = (controlDir: string, hooks: LedgerHooks): Del
           ...(payload.messageId === undefined ? {} : { messageId: payload.messageId as number }),
         })
       }
+      case 'evidence': return runEvidence(controlDir, op.payload ?? {})
       case 'deliveryStatus': return runs.deliveryStatus()
       case 'approvalCheck': {
         const actionId = (op.payload as { actionId?: unknown } | undefined)?.actionId
@@ -351,4 +389,3 @@ export const deliverySocketAlive = (socketPath: string, timeoutMs = 2000): Promi
 // closed DeliverySocketOp union.
 export const callDeliverySocket = (socketPath: string, op: DeliverySocketOp, timeoutMs = 130_000): Promise<unknown> =>
   callSocket(socketPath, op, timeoutMs)
-

package/src/event-sources.ts

@@ -27,11 +27,11 @@ async function atomic(path: string, data: unknown) {
   try { await fd.writeFile(JSON.stringify(data)); await fd.sync() } finally { await fd.close() }
   await rename(tmp, path)
 }
-export function sourceCall(socketPath: string, command: string, args = {}): Promise<any> {
+export function sourceCall(socketPath: string, command: string, args = {}, maxResponseBytes = 256000): Promise<any> {
   return new Promise((resolve, reject) => {
     const req = request({ socketPath, path: '/', method: 'POST', timeout: 3000 }, res => {
       let body = ''
-      res.on('data', chunk => { body += chunk; if (Buffer.byteLength(body) > 256000) req.destroy(new Error('Event-source response too large')) })
+      res.on('data', chunk => { body += chunk; if (Buffer.byteLength(body) > maxResponseBytes) req.destroy(new Error('Event-source response too large')) })
       res.on('error', () => reject(new Error('Event-source response interrupted')))
       res.on('end', () => {
         try { const result = JSON.parse(body); if (res.statusCode !== 200 || result.ok !== true) throw new Error(); resolve(result.data) }

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

@@ -13,6 +13,7 @@ import { readModels, validateSelection, validateOpencodeProviders, type ModelCho
 import type { ChildProcess } from 'node:child_process'
 import { packageVersion } from './version.js'
 import { installedPluginVersions } from './software-status.js'
+import { assertScheduledModel } from './model-policy.js'
 import { processSnapshot } from './process-tree.js'
 
 export type PluginNetworkRoute = { revisions:string[]; bindings:{service:string;network:string}[] }
@@ -51,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'),
@@ -160,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?.()
@@ -194,26 +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
-              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)
+              // 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)
+              }
               active.set(base,job.child)
               await writeFile(base+'.process.json',JSON.stringify({pid:job.child.pid}),{mode:0o600})
               if(signal.aborted)terminateJob(job.child)