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

package/src/application-channel.ts

@@ -1,12 +1,12 @@
 import { createServer, type Server, type IncomingMessage, type ServerResponse } from 'node:http'
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto'
-import { mkdir, readFile, writeFile, rename, open, unlink } from 'node:fs/promises'
+import { mkdir, readFile, writeFile, rename, open, unlink, stat, chown } from 'node:fs/promises'
 import { join } from 'node:path'
 import { ControlStore, sessionTitle, telegramOwner, type ControlGuard, type Owner, sameOwner, validOwner, ownerId, ownerEpoch } from './control-state.js'
 import { RunStore, type RunRecord, type OutboxItem } from './runs.js'
 import { ownsRun } from './identity.js'
 import { applicationId, validApplicationOrigin } from './application-origin.js'
-import { isPreset, type AiPreset, type ModelChoice } from './ai.js'
+import { isPreset, sameChoice, sameEngine, type AiPreset, type ModelChoice } from './ai.js'
 import { MAX_INCOMING_ATTACHMENT_BYTES, stageChatAttachment } from './files.js'
 import { assertEffort } from './model-policy.js'
 import { ApprovalStore } from './approval.js'
@@ -16,7 +16,11 @@ import { SpeechCreditsDepletedError } from './audio.js'
 
 const hash = (value: string) => createHash('sha256').update(value).digest('hex')
 export const applicationScope = (bindingId: string, scope: string) => hash(JSON.stringify([bindingId, scope]))
-type Binding = { id: string; bindingId: string; tokenHash: string; owner: Owner; shareTelegram?: boolean }
+export type TaskLaunch = { command: string; args: string[]; tasks: "all" | string[] }
+export const validTaskLaunch = (v: unknown): v is TaskLaunch => {
+  const x=v as TaskLaunch; return !!x && Object.keys(x).every(k=>["command","args","tasks"].includes(k)) && /^[a-zA-Z0-9_-]{1,100}$/.test(x.command) && Array.isArray(x.args) && x.args.length>0 && x.args.length<=8 && (x.tasks==="all" || (Array.isArray(x.tasks) && x.tasks.length>0 && x.tasks.length<=128 && x.tasks.every(t=>/^task_[a-f0-9]{32}$/.test(t)))) && x.args.every(a=>typeof a==="string" && a.length<=200 && !/[\x00-\x1f\x7f]/.test(a))
+}
+export type Binding = { id: string; bindingId: string; tokenHash: string; owner: Owner; shareTelegram?: boolean; taskLaunch?: TaskLaunch }
 
 export function validateApplicationRegistration(id: string, token: string | null): void {
   if (!applicationId(id) || (token !== null && !/^[A-Za-z0-9_-]{43,200}$/.test(token))) throw new Error('Use a simple application ID and a random token of at least 256 bits encoded as base64url')
@@ -27,7 +31,7 @@ export class ApplicationBindings {
   async list(): Promise<Binding[]> {
     try {
       const bindings = JSON.parse(await readFile(join(this.controlDir, 'application-bindings.json'), 'utf8'))
-      if (!Array.isArray(bindings) || bindings.some(binding => !applicationId(binding?.id) || !/^[a-f0-9-]{36}$/.test(binding.bindingId) || !/^[a-f0-9]{64}$/.test(binding.tokenHash) || !validOwner(binding.owner) || (binding.shareTelegram !== undefined && typeof binding.shareTelegram !== 'boolean')) || ['tokenHash','id','bindingId'].some(key => new Set(bindings.map(b => b[key])).size !== bindings.length)) throw new Error('Invalid application binding state')
+      if (!Array.isArray(bindings) || bindings.some(binding => !applicationId(binding?.id) || !/^[a-f0-9-]{36}$/.test(binding.bindingId) || !/^[a-f0-9]{64}$/.test(binding.tokenHash) || !validOwner(binding.owner) || (binding.taskLaunch !== undefined && !validTaskLaunch(binding.taskLaunch)) || (binding.shareTelegram !== undefined && typeof binding.shareTelegram !== 'boolean')) || ['tokenHash','id','bindingId'].some(key => new Set(bindings.map(b => b[key])).size !== bindings.length)) throw new Error('Invalid application binding state')
       return bindings
     } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []; throw error }
   }
@@ -51,6 +55,23 @@ export class ApplicationBindings {
       return binding
     } finally { await lock.close(); await unlink(`${file}.lock`) }
   }
+  async taskLaunch(id: string, launch: TaskLaunch | null): Promise<void> {
+    if (launch !== null && !validTaskLaunch(launch)) throw Error('Invalid task launch command')
+    const file=join(this.controlDir,'application-bindings.json'), lock=await open(`${file}.lock`,'wx',0o600)
+    try {
+      const bindings=await this.list(), binding=bindings.find(b=>b.id===id)
+      const owner=(await new ControlStore(this.controlDir,900000).status()).owner
+      if(!binding || !sameOwner(binding.owner,owner))throw Error('Application authority revoked')
+      if(launch)binding.taskLaunch=launch; else delete binding.taskLaunch
+      const previous=await stat(file),tmp=`${file}.${randomUUID()}.tmp`
+      try {
+        await writeFile(tmp,JSON.stringify(bindings),{mode:0o600,flag:'wx'})
+        const created=await stat(tmp)
+        if(created.uid!==previous.uid || created.gid!==previous.gid)await chown(tmp,previous.uid,previous.gid)
+        await rename(tmp,file)
+      }finally{await unlink(tmp).catch(error=>{if((error as NodeJS.ErrnoException).code!=='ENOENT')throw error})}
+    }finally{await lock.close();await unlink(`${file}.lock`)}
+  }
   async authenticate(token: string): Promise<Binding> {
     if (!/^[A-Za-z0-9_-]{43,200}$/.test(token)) throw new Error('Unauthorized application')
     const fingerprint = Buffer.from(hash(token), 'hex')
@@ -65,6 +86,7 @@ export class ApplicationBindings {
     const owner = (await new ControlStore(this.controlDir, 900000).status()).owner
     const binding = (await this.list()).find(item => item.bindingId === origin.bindingId)
     if (!binding || !sameOwner(binding.owner, owner) || !ownsRun(owner, run)) throw new Error('Application authority revoked')
+    if(run.application?.taskAccess)await new Tasks(this.controlDir).applicationAccess(run.application.taskAccess,binding.bindingId)
   }
 }
 
@@ -136,7 +158,7 @@ export class ApplicationChannel {
     const value = input as {action?: unknown; expectedSession?: unknown; sessionId?: unknown; presetId?: unknown; cli?: unknown; provider?: unknown; model?: unknown; effort?: unknown}
     if (!value || !['new','switch','select','model'].includes(String(value.action)) ||
       !(value.expectedSession === null || (typeof value.expectedSession === 'string' && /^[a-f0-9-]{36}$/.test(value.expectedSession)))) throw new Error('Invalid application control request')
-    const fields = {new:[],switch:['sessionId'],select:['presetId'],model:['cli','provider','model','effort']}[value.action as 'new'|'switch'|'select'|'model']!
+    const fields = {new:[],switch:['sessionId'],select:['presetId'],model:['cli','provider','authProfile','model','effort']}[value.action as 'new'|'switch'|'select'|'model']!
     if (Object.keys(value).some(key => !['action','expectedSession',...fields].includes(key))) throw new Error('Invalid application control fields')
     const control = new ControlStore(this.options.controlDir, 900000)
     const expected = value.expectedSession as string | null
@@ -159,7 +181,7 @@ export class ApplicationChannel {
       await controls.select(preset, expected, guard)
     }
     if (value.action === 'model') {
-      const model = (await controls.catalog()).find(item => item.cli === value.cli && item.provider === value.provider && item.model === value.model)
+      const model = (await controls.catalog()).find(item => sameEngine(item, value as {cli?:string;authProfile?:string}) && item.provider === value.provider && item.model === value.model)
       if (!model || (value.effort !== undefined && (typeof value.effort !== 'string' || !model.efforts.includes(value.effort)))) throw new Error('Invalid application model selection')
       await this.sharedBinding(bindingId)
       const preset = await controls.saveSelection(model, value.effort as string | undefined, guard)
@@ -189,10 +211,10 @@ export class ApplicationChannel {
     const owner = await this.sharedBinding(bindingId, false)
     const controls = this.options.aiControls
     if (!controls) throw new Error('Application controls unavailable')
-    const value = input as {action?:unknown; expectedSession?:unknown; presetId?:unknown; cli?:unknown; provider?:unknown; model?:unknown; effort?:unknown}
+    const value = input as {action?:unknown; expectedSession?:unknown; presetId?:unknown; cli?:unknown; provider?:unknown; authProfile?:unknown; model?:unknown; effort?:unknown}
     if (!value || !['new','select','model'].includes(String(value.action)) ||
       !(value.expectedSession===null || (typeof value.expectedSession==='string' && /^[a-f0-9-]{36}$/.test(value.expectedSession)))) throw new Error('Invalid application control request')
-    const fields = {new:[],select:['presetId'],model:['cli','provider','model','effort']}[value.action as 'new'|'select'|'model']!
+    const fields = {new:[],select:['presetId'],model:['cli','provider','authProfile','model','effort']}[value.action as 'new'|'select'|'model']!
     if (Object.keys(value).some(key=>!['action','expectedSession',...fields].includes(key))) throw new Error('Invalid application control fields')
     const hashedScope = applicationScope(bindingId,scope)
     const guard:ControlGuard = {owner,applicationScope:hashedScope,expectedSession:value.expectedSession as string|null,
@@ -209,7 +231,7 @@ export class ApplicationChannel {
       await controls.validate(preset)
     }
     if (value.action==='model') {
-      const model = (await controls.catalog()).find(item=>item.cli===value.cli && item.provider===value.provider && item.model===value.model)
+      const model = (await controls.catalog()).find(item=>sameEngine(item,value as {cli?:string;authProfile?:string}) && item.provider===value.provider && item.model===value.model)
       if (!model || (value.effort!==undefined && (typeof value.effort!=='string' || !model.efforts.includes(value.effort)))) throw new Error('Invalid application model selection')
       preset = await controls.saveSelection(model,value.effort as string|undefined,guard)
     }
@@ -224,7 +246,18 @@ export class ApplicationChannel {
         if ('followTelegram' in rest) throw new Error('Invalid application request: choose one conversation option')
         input = {...rest, followTelegram: followOwner}
       }
-      const value = input as { requestId?: unknown; scope?: unknown; text?: unknown; attachment?: { name?: unknown; data?: unknown }; context?: Record<string, unknown>; expectedNativeSessionId?: unknown; activateTelegram?: unknown; followTelegram?: unknown; ai?: { cli?: unknown; provider?: unknown; model?: unknown; effort?: unknown } }
+      if(input && typeof input==='object' && 'taskToken' in input) {
+        const v=input as Record<string,unknown>
+        if(Object.keys(v).some(k=>!['requestId','scope','text','taskToken'].includes(k)) || !applicationId(v.requestId) || typeof v.text!=='string' || !v.text.trim() || v.text.length>16000 || typeof v.taskToken!=='string' || !/^[a-f0-9]{64}$/.test(v.taskToken))throw Error('Invalid application task request')
+        const ticketHash=hash(v.taskToken), access=await new Tasks(this.options.controlDir).applicationAccess(ticketHash,bindingId)
+        const scope='task:'+access.task.id
+        if(v.scope!==scope)throw Error('Invalid application task scope')
+        const id=`r_app_${hash(JSON.stringify([bindingId,v.requestId]))}`, existing=await this.runs.get(id)
+        if(existing){await this.bindings.authorize(existing);if(existing.application?.taskAccess!==ticketHash || existing.texts[0]!==v.text || existing.taskId!==access.task.id)throw Error('Application request ID conflicts with prior task');return existing}
+        const run=await this.runs.create({id,ownerId:ownerId(access.task.owner),ownerEpoch:ownerEpoch(access.task.owner),taskId:access.task.id,texts:[v.text],execution:access.execution,application:{bindingId,scope,requestId:v.requestId,taskAccess:ticketHash}})
+        this.options.wake();return run
+      }
+      const value = input as { requestId?: unknown; scope?: unknown; text?: unknown; attachment?: { name?: unknown; data?: unknown }; context?: Record<string, unknown>; expectedNativeSessionId?: unknown; activateTelegram?: unknown; followTelegram?: unknown; ai?: { cli?: unknown; provider?: unknown; authProfile?: unknown; model?: unknown; effort?: unknown } }
       if (!value || !applicationId(value.requestId) || !applicationId(value.scope) || typeof value.text !== 'string' || (!value.text.trim() && value.attachment === undefined) || value.text.length > 16000 || Object.keys(value).some(key => !['requestId','scope','text','attachment','context','expectedNativeSessionId','activateTelegram','followTelegram','ai'].includes(key))) throw new Error('Invalid application request')
       if (value.expectedNativeSessionId !== undefined && (typeof value.expectedNativeSessionId !== 'string' || !/^[a-zA-Z0-9_-]{1,160}$/.test(value.expectedNativeSessionId))) throw new Error('Invalid application native session assertion')
       if (value.activateTelegram !== undefined && typeof value.activateTelegram !== 'boolean') throw new Error('Invalid application Telegram activation')
@@ -233,7 +266,7 @@ export class ApplicationChannel {
       let requestedPreset: AiPreset | undefined
       if (value.ai !== undefined) {
         const candidate = { ...value.ai, id: 'application', name: 'Application selection' }
-        if (!value.ai || Object.keys(value.ai).some(key => !['cli', 'provider', 'model', 'effort'].includes(key)) || !isPreset(candidate)) throw new Error('Invalid application AI selection')
+        if (!value.ai || Object.keys(value.ai).some(key => !['cli', 'provider', 'authProfile', 'model', 'effort'].includes(key)) || !isPreset(candidate)) throw new Error('Invalid application AI selection')
         assertEffort(candidate.effort, candidate.model, candidate.cli)
         requestedPreset = candidate
       }
@@ -256,7 +289,7 @@ export class ApplicationChannel {
       const existing = await this.runs.get(id)
       if (existing) {
         await this.bindings.authorize(existing)
-        if (requestedPreset && (existing.execution?.preset.cli !== requestedPreset.cli || existing.execution?.preset.provider !== requestedPreset.provider || existing.execution?.preset.model !== requestedPreset.model || existing.execution?.preset.effort !== requestedPreset.effort)) throw new Error('Application request ID conflicts with prior AI selection')
+        if (requestedPreset && (!existing.execution || !sameChoice(existing.execution.preset, requestedPreset))) throw new Error('Application request ID conflicts with prior AI selection')
         if (Boolean(existing.application?.followTelegram) !== Boolean(value.followTelegram) || existing.application?.scope !== value.scope || (existing.application?.inputText ?? existing.texts[0]) !== value.text || existing.application?.attachmentHash !== attachmentHash) throw new Error('Application request ID conflicts with prior scope or text')
         return existing // Retried context never replaces already admitted capabilities.
       }
@@ -299,6 +332,13 @@ export class ApplicationChannel {
       if (request.method === 'GET' && path === '/v1/registration') {
         send(200, {ownerId: ownerId(binding.owner), bindingId: binding.bindingId, channel: binding.id}); return
       }
+      if(request.method==='POST' && path==='/v1/registration') {
+        let raw='';for await(const chunk of request){raw+=chunk;if(Buffer.byteLength(raw)>1024)throw Error('Invalid application task request')}
+        const v=JSON.parse(raw)
+        if(Object.keys(v).length!==1 || typeof v.taskToken!=='string' || !/^[a-f0-9]{64}$/.test(v.taskToken))throw Error('Invalid application task request')
+        const access=await new Tasks(this.options.controlDir).applicationAccess(hash(v.taskToken),binding.bindingId)
+        send(200,{taskId:access.task.id,expiresAt:access.expiresAt,purpose:access.task.purpose});return
+      }
       if (path === '/v1/telegram' && request.method === 'GET') {
         if ([...url.searchParams.keys()].length) throw new Error('Invalid application Telegram request')
         if (!binding.shareTelegram) { send(403, { error: 'Application authority does not permit Telegram connection' }); return }

package/src/application-cli.ts

@@ -8,11 +8,12 @@ import { applicationId } from './application-origin.js'
 
 async function main() {
   const { values } = parseArgs({ options: {
+    'task-launch-command': {type:'string'}, 'task-launch-args':{type:'string'}, 'task-launch-tasks':{type:'string'}, 'disable-task-launch':{type:'boolean'},
     owner: {type:'string'}, id: {type:'string'}, 'token-file': {type:'string'}, revoke: {type:'boolean'}, list: {type:'boolean'}, help: {type:'boolean'},
     'owner-id': {type:'string'}, rotate: {type:'boolean'}, 'share-owner': {type:'boolean'}, 'share-active': {type:'boolean'},
     'import-scope': {type:'string'}, 'native-session': {type:'string'}, cli: {type:'string'}, 'share-telegram': {type:'boolean'},
   } })
-  if (values.help) { console.log('ezenciel-agents-application --id CHANNEL --token-file PRIVATE_FILE [--owner-id VERIFIED_OWNER_ID] [--share-owner] [--rotate] | --id CHANNEL --revoke | --list | --id CHANNEL --import-scope SCOPE --native-session ID --cli CLI'); return }
+  if (values.help) { console.log('ezenciel-agents-application --id CHANNEL --token-file PRIVATE_FILE [--owner-id VERIFIED_OWNER_ID] [--share-owner] [--rotate] | --id CHANNEL --task-launch-command COMMAND --task-launch-args JSON --task-launch-tasks JSON | --id CHANNEL --disable-task-launch | --id CHANNEL --revoke | --list | --id CHANNEL --import-scope SCOPE --native-session ID --cli CLI'); return }
   if (process.env.EZ_RUN_ID) throw new Error('Application authority is configured by the installing administrator outside agent turns')
   const config = loadControlConfig(), control = new ControlStore(config.controlDir, config.pairingTtlMs)
   if (values.owner && values['owner-id']) throw new Error('Choose one owner registration form')
@@ -25,6 +26,11 @@ async function main() {
   const bindings = new ApplicationBindings(config.controlDir)
   if (values.list) { console.log(JSON.stringify((await bindings.list()).map(({id,bindingId}) => ({id,bindingId})))); return }
   if (!values.id || !applicationId(values.id)) throw new Error('Application ID required')
+  if(values['task-launch-command'] || values['disable-task-launch']) {
+    if(values['token-file'] || values.revoke || values.rotate || values['import-scope'] || (values['task-launch-command'] && values['disable-task-launch']))throw Error('Task launch settings cannot be combined with registration')
+    await bindings.taskLaunch(values.id,values['disable-task-launch'] ? null : {command:values['task-launch-command']!,args:JSON.parse(values['task-launch-args'] ?? '[]'),tasks:JSON.parse(values['task-launch-tasks'] ?? 'null')})
+    console.log(JSON.stringify({ok:true,id:values.id,taskLaunch:!values['disable-task-launch']}));return
+  }
   if (values['import-scope']) {
     const binding = (await bindings.list()).find(item => item.id === values.id)
     if (!binding || !sameOwner(binding.owner, owner) || !applicationId(values['import-scope']) || !values['native-session'] || !/^[a-zA-Z0-9_-]{1,160}$/.test(values['native-session']) || !values.cli) throw new Error('Current application binding, scope, native session and CLI required')

package/src/application-origin.ts

@@ -2,6 +2,7 @@ export type ApplicationOrigin = {
   bindingId: string
   scope: string
   requestId: string
+  taskAccess?: string
   followTelegram?: boolean
   inputText?: string
   attachmentHash?: string
@@ -12,6 +13,7 @@ export const applicationId = (value: unknown): value is string =>
 export const validApplicationOrigin = (value: unknown): value is ApplicationOrigin => {
   const origin = value as ApplicationOrigin | undefined
   return !!origin && /^[a-f0-9-]{36}$/.test(origin.bindingId) && applicationId(origin.scope) && applicationId(origin.requestId) &&
+    (origin.taskAccess === undefined || /^[a-f0-9]{64}$/.test(origin.taskAccess)) &&
     (origin.followTelegram === undefined || typeof origin.followTelegram === 'boolean') &&
     (origin.inputText === undefined || (typeof origin.inputText === 'string' && origin.inputText.length <= 16000)) &&
     (origin.attachmentHash === undefined || /^[a-f0-9]{64}$/.test(origin.attachmentHash)) &&

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/auth-profile.ts

@@ -0,0 +1,53 @@
+import { lstat, readdir, readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+// Owner-provisioned named credential homes beside the agent default binding.
+// Unset keeps control/cli/<cli>; a name selects control/cli/profiles/<name>/<cli>
+// with its own credentials, configuration and native sessions. Ez never stores,
+// copies or prints credentials; the native CLI logs in inside the home.
+export const AUTH_PROFILE_CLIS: readonly string[] = ['codex', 'claude']
+export const isAuthProfile = (value: unknown): value is string =>
+  typeof value === 'string' && /^[a-z][a-z0-9-]{0,31}$/.test(value)
+
+export const cliHome = (controlDir: string, cli: string, authProfile?: string): string => {
+  if (authProfile === undefined) return path.join(controlDir, 'cli', cli)
+  if (!isAuthProfile(authProfile) || !AUTH_PROFILE_CLIS.includes(cli)) throw new Error('Invalid auth profile selection')
+  return path.join(controlDir, 'cli', 'profiles', authProfile, cli)
+}
+
+const realDirectory = (directory: string) => lstat(directory).then(stat => stat.isDirectory(), () => false)
+
+// A named home exists only once the owner provisioned it as a real directory.
+// Execution never creates, links or falls back from it.
+export const provisionedHome = async (controlDir: string, cli: string, authProfile?: string): Promise<string> => {
+  const home = cliHome(controlDir, cli, authProfile)
+  if (authProfile !== undefined && !await realDirectory(home)) throw new Error(`Auth profile ${authProfile} is not provisioned for ${cli}`)
+  return home
+}
+
+export const listAuthProfiles = async (controlDir?: string): Promise<{ cli: string; authProfile: string }[]> => {
+  if (!controlDir) return []
+  const names = await readdir(path.join(controlDir, 'cli', 'profiles')).catch(() => [] as string[])
+  const found: { cli: string; authProfile: string }[] = []
+  for (const authProfile of names.filter(isAuthProfile).sort())
+    for (const cli of AUTH_PROFILE_CLIS)
+      if (await realDirectory(cliHome(controlDir, cli, authProfile))) found.push({ cli, authProfile })
+  return found
+}
+
+// Claude credentials for one home. Host-capable default homes share the
+// installer login in place; named homes and isolated agents use only their
+// own store, plus an optional owner-provisioned long-lived `oauth-token`.
+export const claudeAuthEnvironment = async (home: string, authProfile?: string, isolated = process.env.EZ_ISOLATION === 'isolated'): Promise<NodeJS.ProcessEnv> => {
+  const environment: NodeJS.ProcessEnv = { CLAUDE_CONFIG_DIR: home }
+  if (!isolated && authProfile === undefined) environment.CLAUDE_SECURESTORAGE_CONFIG_DIR = ''
+  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
+  }
+  return environment
+}

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/codex-session.ts

@@ -5,6 +5,7 @@ import { createInterface } from 'node:readline'
 import { fileURLToPath } from 'node:url'
 import path from 'node:path'
 import { terminateJob, validateCodexProvider, type CodexProviderBinding } from './executor.js'
+import { codexRejection, codexResetAt, startupLine } from './setup-fallback.js'
 
 type Options = {workspace:string;controlDir:string;toolsHome?:string;sharedWorkspace?:string;additionalWorkspaces?:string[];model?:string;effort?:string;prompt:string;codexSandbox?:'external';codexProvider?:CodexProviderBinding}
 type Message = {id?:number;method?:string;params?:any;result?:any;error?:{message:string;code?:number}}
@@ -17,7 +18,7 @@ export async function runCodexSession(options:Options, io:{launch?:()=>ChildProc
   const provider = options.codexProvider ? validateCodexProvider(options.codexProvider) : undefined
   const child=io.launch?.() ?? spawn('codex',['app-server','--stdio','--disable','memories','--enable','skip_host_skill_discovery'],{cwd:options.workspace,env:process.env,stdio:['pipe','pipe','pipe']})
   const emit=io.emit ?? (line=>process.stdout.write(line+'\n'))
-  let id=0,threadId:string|undefined,activeTurn:string|undefined,finished=false,sawTurn=false,hadGoal=false
+  let id=0,threadId:string|undefined,activeTurn:string|undefined,finished=false,sawTurn=false,hadGoal=false,workBegan=false,resetAt:string|undefined
   let resolveDone!:(code:number)=>void
   const done=new Promise<number>(resolve=>{resolveDone=resolve})
   const pending=new Map<number,{resolve:(value:any)=>void;reject:(error:Error)=>void;timer:ReturnType<typeof setTimeout>}>()
@@ -38,7 +39,10 @@ export async function runCodexSession(options:Options, io:{launch?:()=>ChildProc
     finish(0)
   }
   child.stderr?.pipe(process.stderr)
-  child.on('error',fail)
+  child.on('error',error=>{
+    if((error as NodeJS.ErrnoException).code==='ENOENT')emit(startupLine({workBegan:false,rejection:{category:'cli-unavailable'}}))
+    fail(error)
+  })
   child.stdin?.on('error',fail)
   child.once('close',()=>{
     for(const p of pending.values()){clearTimeout(p.timer);p.reject(new Error('Codex app-server closed'))}
@@ -57,16 +61,23 @@ export async function runCodexSession(options:Options, io:{launch?:()=>ChildProc
       // Never turn an unexpected approval/elicitation request into permission.
       send({id:message.id,error:{code:-32601,message:`Unsupported unattended request: ${message.method}`}});fail(new Error(`Codex requires attention: ${message.method}`));return
     }
+    if(message.method==='account/rateLimits/updated')resetAt=codexResetAt(message.params?.rateLimits) ?? resetAt
     if(message.params?.threadId!==threadId)return
     if(message.method==='turn/started'){activeTurn=message.params.turn.id;sawTurn=true}
+    // Any item beyond the echoed input means the provider accepted the turn.
+    if(message.method==='item/started' && message.params.item?.type!=='userMessage' && !workBegan){workBegan=true;emit(startupLine({workBegan}))}
     if(message.method==='thread/goal/updated')settled(message.params.goal)
     if(message.method==='thread/goal/cleared')settled(null)
     if(message.method==='turn/completed'){
       if(activeTurn===message.params.turn.id)activeTurn=undefined
       if(message.params.turn.status!=='completed'){
         if(message.params.turn.status==='interrupted')finish(130)
-        else fail(new Error(redactFailure(typeof message.params.turn.error?.message==='string'
+        else {
+          const category=workBegan ? undefined : codexRejection(message.params.turn.error?.codexErrorInfo)
+          if(category)emit(startupLine({workBegan,rejection:{category,...(category==='quota' && resetAt ? {resetAt} : {})}}))
+          fail(new Error(redactFailure(typeof message.params.turn.error?.message==='string'
           ? message.params.turn.error.message : 'Native turn failed without error details')))
+        }
         return
       }
       // Completion of a turn is not completion of a native goal. The native

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(),