@jc_stack/ez-agents 0.1.0-beta.12

package/src/approval-cli.ts

@@ -0,0 +1,59 @@
+import { loadControlConfig } from './config.js'
+import { ApprovalStore } from './approval.js'
+import { RunStore } from './runs.js'
+
+const args = process.argv.slice(2).filter((arg) => arg !== '--')
+if (args.includes('--help') || args.includes('-h')) {
+  console.log('Usage: ezenciel-agents-approval --prompt "..." --action-id "..." [--reply-to <id>]')
+  console.log('   or: ezenciel-agents-approval --check <action-id>')
+  process.exit(0)
+}
+
+let prompt: string | undefined
+let actionId: string | undefined
+let checkId: string | undefined
+let replyTo: number | undefined
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--prompt' && args[i + 1]) {
+    prompt = args[++i]
+  } else if (args[i] === '--action-id' && args[i + 1]) {
+    actionId = args[++i]
+  } else if (args[i] === '--check' && args[i + 1]) {
+    checkId = args[++i]
+  } else if (args[i] === '--reply-to' && args[i + 1]) {
+    replyTo = parseInt(args[++i], 10)
+  }
+}
+
+const config = loadControlConfig()
+const approvalStore = new ApprovalStore(config.controlDir)
+
+if (checkId) {
+  const record = await approvalStore.getDecision(checkId)
+  console.log(JSON.stringify({
+    ok: true,
+    actionId: checkId,
+    decision: record?.decision || 'pending',
+    decidedAt: record?.decidedAt,
+    decidedBy: record?.decidedBy,
+  }))
+  process.exit(0)
+}
+
+if (!prompt || !actionId) {
+  console.error('Usage: ezenciel-agents-approval --prompt "..." --action-id "..." [--reply-to <id>]')
+  console.error('   or: ezenciel-agents-approval --check <action-id>')
+  process.exit(1)
+}
+
+const runId = process.env.EZ_RUN_ID?.trim()
+if (!runId) {
+  console.error('EZ_RUN_ID is required to request approval')
+  process.exit(1)
+}
+
+const runStore = new RunStore(config.controlDir)
+await approvalStore.requestApproval(actionId, prompt, runId)
+const item = await runStore.enqueueApproval(runId, prompt, actionId, { replyToMessageId: replyTo })
+console.log(JSON.stringify({ ok: true, run: runId, actionId, outbox_id: item.id, status: 'requested' }))

package/src/approval.ts

@@ -0,0 +1,119 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { assertId } from './identity.js'
+
+export type ApprovalDecision = 'pending' | 'approved' | 'denied'
+
+export type ApprovalRecord = {
+  version: 1
+  actionId: string
+  runId?: string
+  prompt: string
+  decision: ApprovalDecision
+  createdAt: string
+  decidedAt?: string
+  decidedBy?: number
+  decisionUpdateId?: number
+}
+
+const isApprovalRecord = (value: unknown): value is ApprovalRecord => {
+  if (!value || typeof value !== 'object') return false
+  const candidate = value as Partial<ApprovalRecord>
+  return (
+    candidate.version === 1 &&
+    typeof candidate.actionId === 'string' &&
+    /^[a-zA-Z0-9_-]{1,40}$/.test(candidate.actionId) &&
+    typeof candidate.prompt === 'string' &&
+    ['pending', 'approved', 'denied'].includes(candidate.decision ?? '') &&
+    typeof candidate.createdAt === 'string' &&
+    Number.isFinite(Date.parse(candidate.createdAt))
+  )
+}
+
+export class ApprovalStore {
+  private readonly approvalsDir: string
+
+  constructor(controlDir: string) {
+    this.approvalsDir = path.join(controlDir, 'approvals')
+  }
+
+  private async ensure(): Promise<void> {
+    await mkdir(this.approvalsDir, { recursive: true, mode: 0o700 })
+  }
+
+  private filePath(actionId: string): string {
+    const safe = assertId(actionId)
+    if (safe.length > 40) throw new Error('Approval identifier must be at most 40 characters')
+    return path.join(this.approvalsDir, `${safe}.json`)
+  }
+
+  async requestApproval(actionId: string, prompt: string, runId?: string): Promise<ApprovalRecord> {
+    if (!prompt.trim()) throw new Error('Approval prompt is empty')
+    if (runId) assertId(runId)
+    await this.ensure()
+    const existing = await this.getDecision(actionId)
+    if (existing) {
+      if (existing.runId !== runId || existing.prompt !== prompt)
+        throw new Error('Approval ID already belongs to another request')
+      return existing
+    }
+
+    const record: ApprovalRecord = {
+      version: 1,
+      actionId,
+      runId,
+      prompt,
+      decision: 'pending',
+      createdAt: new Date().toISOString(),
+    }
+    const file = this.filePath(actionId)
+    const temporary = `${file}.${process.pid}.tmp`
+    await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 })
+    await rename(temporary, file)
+    return record
+  }
+
+  async recordDecision(
+    actionId: string,
+    decision: 'approved' | 'denied',
+    decidedBy: number,
+    decisionUpdateId?: number,
+  ): Promise<ApprovalRecord> {
+    await this.ensure()
+    const existing = await this.getDecision(actionId)
+    if (!existing) throw new Error('Unknown approval request')
+    if (
+      decisionUpdateId !== undefined &&
+      existing.decisionUpdateId === decisionUpdateId &&
+      existing.decidedBy === decidedBy &&
+      existing.decision === decision
+    )
+      return existing
+    if (existing.decision !== 'pending') throw new Error('Approval already decided')
+    if (Date.now() - Date.parse(existing.createdAt) > 900_000) throw new Error('Approval expired')
+    const record: ApprovalRecord = {
+      ...existing,
+      decision,
+      decidedAt: new Date().toISOString(),
+      decidedBy,
+      decisionUpdateId,
+    }
+    const file = this.filePath(actionId)
+    const temporary = `${file}.${process.pid}.tmp`
+    await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 })
+    await rename(temporary, file)
+    return record
+  }
+
+  async getDecision(actionId: string): Promise<ApprovalRecord | null> {
+    try {
+      const parsed: unknown = JSON.parse(await readFile(this.filePath(actionId), 'utf8'))
+      if (!isApprovalRecord(parsed) || parsed.actionId !== actionId)
+        throw new Error('Invalid approval record shape')
+      return parsed
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null
+      throw error
+    }
+  }
+}

package/src/audio.ts

@@ -0,0 +1,184 @@
+import { spawn } from 'node:child_process'
+import { readRequest } from './read-request.js'
+
+export type AudioOptions = {
+  geminiApiKey?: string
+  openaiApiKey?: string
+  voice?: string
+}
+
+export const pcmToWav = (pcm: Buffer, sampleRate = 24000, channels = 1): Buffer => {
+  const header = Buffer.alloc(44)
+  const byteRate = sampleRate * channels * 2
+  const blockAlign = channels * 2
+  header.write('RIFF', 0)
+  header.writeUInt32LE(36 + pcm.length, 4)
+  header.write('WAVE', 8)
+  header.write('fmt ', 12)
+  header.writeUInt32LE(16, 16)
+  header.writeUInt16LE(1, 20)
+  header.writeUInt16LE(channels, 22)
+  header.writeUInt32LE(sampleRate, 24)
+  header.writeUInt32LE(byteRate, 28)
+  header.writeUInt16LE(blockAlign, 32)
+  header.writeUInt16LE(16, 34)
+  header.write('data', 36)
+  header.writeUInt32LE(pcm.length, 40)
+  return Buffer.concat([header, pcm])
+}
+
+export const encodeOggOpus = (pcm: Buffer, sampleRate = 24000, channels = 1): Promise<Buffer> => {
+  return new Promise((resolve, reject) => {
+    const child = spawn(
+      'ffmpeg',
+      [
+        '-f',
+        's16le',
+        '-ar',
+        String(sampleRate),
+        '-ac',
+        String(channels),
+        '-i',
+        '-',
+        '-c:a',
+        'libopus',
+        '-b:a',
+        '32k',
+        '-f',
+        'ogg',
+        '-',
+      ],
+      { stdio: ['pipe', 'pipe', 'pipe'] },
+    )
+
+    const output: Buffer[] = []
+    let error = ''
+
+    child.stdout.on('data', (chunk) => output.push(chunk))
+    child.stderr.on('data', (chunk) => {
+      error = (error + chunk.toString()).slice(-2048)
+    })
+    child.stdin.on('error', reject)
+
+    child.on('error', reject)
+
+    child.on('close', (code) => {
+      if (code === 0 && output.length > 0) {
+        resolve(Buffer.concat(output))
+      } else {
+        reject(new Error(`Voice encoding failed (${code}): ${error}`))
+      }
+    })
+
+    child.stdin.end(pcm)
+  })
+}
+
+export const transcribeAudio = async (
+  audioBytes: Buffer,
+  mimeType: string,
+  options: AudioOptions = {},
+): Promise<string> => {
+  const geminiKey = (options.geminiApiKey ?? process.env.GEMINI_API_KEY)?.trim()
+  if (geminiKey) {
+    const url = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent'
+    const payload = await readRequest(
+      'Gemini transcription',
+      url,
+      {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'x-goog-api-key': geminiKey },
+        signal: AbortSignal.timeout(60_000),
+        body: JSON.stringify({
+          contents: [
+            {
+              parts: [
+                {
+                  text: 'Transcribe this audio faithfully. Return only the transcript, preserving its language.',
+                },
+                { inlineData: { mimeType: mimeType || 'audio/ogg', data: audioBytes.toString('base64') } },
+              ],
+            },
+          ],
+        }),
+      },
+      (response) => response.json(),
+    )
+    const transcript = payload?.candidates?.[0]?.content?.parts?.[0]?.text?.trim()
+    if (!transcript) throw new Error('Gemini returned an empty transcript')
+    return transcript
+  }
+
+  const openaiKey = options.openaiApiKey?.trim() || process.env.OPENAI_API_KEY?.trim()
+  if (openaiKey) {
+    const form = new FormData()
+    form.set('model', 'whisper-1')
+    form.set('response_format', 'text')
+    form.set('file', new Blob([new Uint8Array(audioBytes)], { type: mimeType || 'audio/ogg' }), 'audio.ogg')
+
+    const transcript = await readRequest(
+      'OpenAI transcription',
+      'https://api.openai.com/v1/audio/transcriptions',
+      {
+        method: 'POST',
+        headers: { authorization: `Bearer ${openaiKey}` },
+        body: form,
+      },
+      (response) => response.text(),
+    )
+    if (!transcript.trim()) throw new Error('OpenAI returned an empty transcript')
+    return transcript.trim()
+  }
+
+  throw new Error('No audio transcription API key configured (set GEMINI_API_KEY or OPENAI_API_KEY)')
+}
+
+export const synthesizeSpeech = async (
+  text: string,
+  options: AudioOptions = {},
+): Promise<{ buffer: Buffer; mimeType: string }> => {
+  const trimmed = text.trim()
+  if (!trimmed) throw new Error('Cannot synthesize speech for empty text')
+
+  const geminiKey = (options.geminiApiKey ?? process.env.GEMINI_API_KEY)?.trim()
+  if (geminiKey) {
+    const url =
+      'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent'
+    const voiceName = options.voice || 'Kore'
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-goog-api-key': geminiKey },
+      signal: AbortSignal.timeout(60_000),
+      body: JSON.stringify({
+        contents: [{ parts: [{ text: trimmed }] }],
+        generationConfig: {
+          responseModalities: ['AUDIO'],
+          speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName } } },
+        },
+      }),
+    })
+
+    if (!response.ok) {
+      const err = await response.text().catch(() => '')
+      throw new Error(`Gemini speech synthesis error ${response.status}: ${err}`)
+    }
+
+    const payload = (await response.json()) as any
+    const candidate = payload?.candidates?.[0]
+    const inline = candidate?.content?.parts?.find(
+      (part: { inlineData?: { data?: string; mimeType?: string } }) =>
+        part.inlineData?.mimeType?.startsWith('audio/') && part.inlineData?.data,
+    )?.inlineData
+    if (!inline?.data)
+      throw new Error(`Gemini returned no audio data (${candidate?.finishReason || 'no candidate'})`)
+
+    const rawPcm = Buffer.from(inline.data, 'base64')
+    const encoded = await encodeOggOpus(rawPcm, 24000, 1)
+    return {
+      buffer: encoded,
+      mimeType: 'audio/ogg',
+    }
+  }
+
+  throw new Error('No speech synthesis API key configured (set GEMINI_API_KEY)')
+}

package/src/client-defaults.ts

@@ -0,0 +1,101 @@
+import { execFile, spawn } from 'node:child_process'
+import { promisify } from 'node:util'
+import { createInterface } from 'node:readline'
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+import { installed, type AiPreset } from './ai.js'
+import { executorEnvironment } from './executor.js'
+
+const record = (v: unknown): Record<string, unknown> =>
+  v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {}
+const value = (v: unknown): string | undefined =>
+  typeof v === 'string' && /^[a-zA-Z0-9_./:-]{1,160}$/.test(v) ? v : undefined
+const command = async (cli: string, args: string[], cwd: string): Promise<string> =>
+  (await promisify(execFile)(cli, args, { cwd, env: executorEnvironment(), timeout: 8000, maxBuffer: 2 * 1024 * 1024 })).stdout
+
+// Native config/read resolves Codex's layers; do not reimplement TOML or start a turn.
+export const codexDefaults = (cwd: string): Promise<Record<string, unknown>> => new Promise((resolve) => {
+  const child = spawn('codex', ['app-server'], { cwd, env: executorEnvironment(), stdio: ['pipe', 'pipe', 'ignore'] })
+  const lines = createInterface({ input: child.stdout })
+  let done = false
+  const finish = (config: Record<string, unknown> = {}) => {
+    if (done) return
+    done = true
+    clearTimeout(timer); lines.close(); child.stdin.end(); child.kill(); resolve(config)
+  }
+  const timer = setTimeout(() => finish(), 8000)
+  const send = (message: unknown) => child.stdin.write(`${JSON.stringify(message)}\n`)
+  child.on('error', () => finish())
+  child.stdin.on('error', () => finish())
+  child.on('close', () => finish())
+  lines.on('line', (line) => {
+    try {
+      const message = JSON.parse(line)
+      if (message.id === 0 && message.result) {
+        send({ method: 'initialized', params: {} })
+        send({ id: 1, method: 'config/read', params: { includeLayers: false, cwd } })
+      } else if (message.id === 1) {
+        const config = record(message.result?.config)
+        const managed = record(record(config.models).new_thread)
+        finish({ model: managed.model ?? config.model,
+          effort: managed.model_reasoning_effort ?? config.model_reasoning_effort })
+      }
+    } catch { finish() }
+  })
+  send({ id: 0, method: 'initialize', params: { clientInfo: { name: 'ez_defaults', version: '1' } } })
+})
+
+// Only the two simple, documented Grok [models] strings are read. Unsupported
+// syntax stays unspecified so the native client resolves it, rather than guessing.
+export const grokSettings = (text: string): { model?: string; effort?: string } => {
+  const section = (text.split(/^\[models\][ \t]*\r?$/m)[1] || '').split(/^\[/m)[0]
+  const get = (key: string) => value(section.match(new RegExp(`^\\s*${key}\\s*=\\s*["']([^"'\\r\\n]+)["']\\s*(?:#.*)?$`, 'm'))?.[1])
+  return { model: get('default'), effort: get('default_reasoning_effort') }
+}
+
+export const discoverDefaults = async (cwd: string, options: {
+  home?: string; available?: typeof installed; run?: typeof command; codex?: typeof codexDefaults
+} = {}): Promise<AiPreset[]> => {
+  const home = options.home ?? homedir()
+  const available = options.available ?? installed
+  const run = options.run ?? command
+  const text = async (file: string) => { try { return await readFile(file, 'utf8') } catch { return '' } }
+  const json = async (file: string) => { try { return record(JSON.parse(await text(file))) } catch { return {} } }
+  const clients = ['grok', 'codex', 'claude', 'opencode']
+  const results = await Promise.all(clients.map(async (cli): Promise<AiPreset | undefined> => {
+    if (!(await available(cli))) return
+    let model: string | undefined, effort: string | undefined
+    try {
+      if (cli === 'grok') {
+        const settings = grokSettings(await text(join(home, '.grok/config.toml')))
+        model = settings.model ?? value((await run(cli, ['models'], cwd)).match(/^Default model:\s*(\S+)/m)?.[1])
+        effort = settings.effort
+      } else if (cli === 'codex') {
+        const config = await (options.codex ?? codexDefaults)(cwd)
+        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')),
+          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') {
+        const config = record(JSON.parse(await run(cli, ['debug', 'config'], cwd)))
+        model = value(config.model)
+      }
+    } catch { /* Unavailable metadata: expose client default, never invent values. */ }
+    const id = 'detected_' + createHash('sha256').update(JSON.stringify([cli, model, effort])).digest('hex').slice(0, 12)
+    return { id, cli, model, effort,
+      name: `${cli} · ${model || 'client default'}${effort ? ` · ${effort}` : ''}`.slice(0, 80) }
+  }))
+  const discovered = results.filter((p): p is AiPreset => Boolean(p))
+  if (await available('codex-gui')) {
+    const source = discovered.find((preset) => preset.cli === 'codex')
+    const model = source?.model, effort = source?.effort
+    const id = 'detected_' + createHash('sha256').update(JSON.stringify(['codex-gui', model, effort])).digest('hex').slice(0, 12)
+    discovered.push({ id, cli: 'codex-gui', model, effort,
+      name: `codex-gui · ${model || 'desktop'}${effort ? ` · ${effort}` : ''}`.slice(0, 80) })
+  }
+  return discovered
+}

package/src/config.ts

@@ -0,0 +1,48 @@
+import path from 'node:path'
+import { homedir } from 'node:os'
+
+export type ControlConfig = {
+  controlDir: string
+  pairingTtlMs: number
+}
+
+export type Config = ControlConfig & {
+  telegramBotToken: string
+  workspace: string
+  executorTimeoutMs: number
+  executorCli: string
+  geminiApiKey?: string
+  openaiApiKey?: string
+}
+
+const positiveInteger = (value: string | undefined, name: string, fallback: number): number => {
+  if (!value) return fallback
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer`)
+  }
+  return parsed
+}
+
+export const loadControlConfig = (env: NodeJS.ProcessEnv = process.env): ControlConfig => {
+  const stateHome = env.XDG_STATE_HOME?.trim() || path.join(homedir(), '.local', 'state')
+  return {
+    controlDir: path.resolve(env.EZ_CONTROL_DIR?.trim() || path.join(stateHome, 'ezenciel-agents')),
+    pairingTtlMs: positiveInteger(env.EZ_PAIRING_TTL_SECONDS, 'EZ_PAIRING_TTL_SECONDS', 900) * 1_000,
+  }
+}
+
+export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
+  const telegramBotToken = env.TELEGRAM_BOT_TOKEN?.trim()
+  if (!telegramBotToken) throw new Error('TELEGRAM_BOT_TOKEN is required')
+
+  return {
+    ...loadControlConfig(env),
+    telegramBotToken,
+    workspace: path.resolve(env.EZ_AGENT_WORKSPACE?.trim() || './agent'),
+    executorTimeoutMs: positiveInteger(env.EZ_EXECUTOR_TIMEOUT_SECONDS, 'EZ_EXECUTOR_TIMEOUT_SECONDS', 300) * 1_000,
+    executorCli: env.EZ_EXECUTOR_CLI?.trim() || 'agy',
+    geminiApiKey: env.GEMINI_API_KEY?.trim(),
+    openaiApiKey: env.OPENAI_API_KEY?.trim(),
+  }
+}