@jc_stack/ez-agents 0.1.0-beta.38 → 0.1.0-beta.39

package/.env.example

@@ -19,6 +19,8 @@ EZ_EXECUTOR_CLI=codex
 
 # Optional: Audio transcription (STT) and voice synthesis (TTS)
 # GEMINI_API_KEY=
+# EZ_SPEECH_VOICE_EN=Kore
+# EZ_SPEECH_VOICE_ES=Kore
 # OPENAI_API_KEY=
 
 # Optional: OpenRouter API key for OpenCode CLI (Nemotron 3.5 Lightning)

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.0-beta.39
+
+- Render completed, binding-scoped application replies as WAV speech with
+  configurable English and Spanish voices, while retaining Ogg/Opus for Telegram.
+  Recheck the original application binding after synthesis and report depleted
+  speech credits without provider details.
+- Preserve live delivery sockets during upgrade backups and restart Linux host
+  services after a successful core replacement.
+
 ## 0.1.0-beta.38
 
 - Remove the retired Antigravity CLI integration and its unused engine paths.

package/docs/application-channel.md

@@ -10,6 +10,24 @@ Run admission, status and inbox receipts include the immutable `preset` captured
 for that run so an application can label delivered messages with the engine choice
 that actually produced them.
 
+## Speech playback
+
+`POST /v1/runs/<id>/speech` renders the last delivered text reply of a completed
+application run as `audio/wav` (24 kHz mono). It uses the same binding/owner
+authorization as run readback, rechecked after synthesis, and accepts no client
+text or provider credentials. Replies are limited to 8,000 characters. An
+unfinished run returns 409, missing speech configuration 503, and provider
+failure 502. Depleted Gemini credits return 503 with
+`code: speech_credits_depleted`. Audio responses have `Cache-Control: no-store`.
+
+Configure `GEMINI_API_KEY` on the relay. The existing speech renderer uses
+`gemini-3.8-flash-lite-tts`; Telegram still receives Ogg Opus. Applications should
+send `{"language":"en"}` or `{"language":"es"}` to select
+`EZ_SPEECH_VOICE_EN` or `EZ_SPEECH_VOICE_ES` (both default to Kore). Telegram
+voice notes use the English voice setting. Applications should retain the returned
+audio for local replay; each POST generates fresh audio.
+Speech is a rendering operation and does not start another agent turn.
+
 ## Shared runtime controls
 
 Register with `--share-owner` (the existing `--share-telegram` spelling is an

package/docs/host-service.md

@@ -24,7 +24,7 @@ Environment=EZ_DEPLOYMENT_DIR=/absolute/private/agents/family
 Environment=PATH=/absolute/node/bin:/absolute/package-manager/bin:/absolute/cli/bin:/usr/local/bin:/usr/bin:/bin
 EnvironmentFile=-%h/.config/ez/family-provider.env
 ExecStart=/absolute/ez-package/package/bin/ezenciel-agents-host
-Restart=on-failure
+Restart=always
 RestartSec=5
 
 [Install]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.38",
+  "version": "0.1.0-beta.39",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

package/src/application-channel.ts

@@ -11,6 +11,7 @@ import { MAX_INCOMING_ATTACHMENT_BYTES, stageChatAttachment } from './files.js'
 import { assertEffort } from './model-policy.js'
 import { ApprovalStore } from './approval.js'
 import { Tasks } from './tasks.js'
+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]))
@@ -74,6 +75,7 @@ export class ApplicationChannel {
     controlDir: string; workspace?: string; initial: AiPreset
     wake: () => void
     cancel: (id: string) => Promise<void>
+    speech?: (text: string, language: 'en' | 'es') => Promise<{ buffer: Buffer; mimeType: string }>
     createTelegramPairing?: (bindingId: string, owner: Owner) => Promise<{ connected: true } | { connected: false; url: string; expiresAt: string }>
     telegramAvailable?: () => boolean
     aiControls?: {
@@ -385,6 +387,31 @@ export class ApplicationChannel {
         const admitted = await this.runs.attachTelegramApplication(target.id, application)
         send(200, { id: admitted.id, scope, status: admitted.status }); return
       }
+      const speechMatch = path.match(/^\/v1\/runs\/(r_(?:app|schedule)_[a-f0-9]{64})\/speech$/)
+      if (speechMatch && request.method === 'POST') {
+        const chunks: Buffer[] = []; let size = 0
+        for await (const chunk of request) { size += chunk.length; if (size > 128) throw new Error('Invalid speech request'); chunks.push(chunk) }
+        const input = Buffer.concat(chunks).toString('utf8').trim()
+        const language = input ? (JSON.parse(input) as { language?: unknown }).language : 'en'
+        if (language !== 'en' && language !== 'es') { send(400, { error: 'Invalid speech language' }); return }
+        const snapshot = await this.snapshot(binding.bindingId, speechMatch[1])
+        if (snapshot.status !== 'completed') { send(409, { error: 'Speech requires a completed reply' }); return }
+        const text = snapshot.messages.at(-1)?.text?.trim()
+        if (!text || text.length > 8000) { send(400, { error: 'Speech requires a reply of 1–8000 characters' }); return }
+        if (!this.options.speech) { send(503, { error: 'Speech is not configured' }); return }
+        let audio: { buffer: Buffer; mimeType: string }
+        try { audio = await this.options.speech(text, language) }
+        catch (error) {
+          if (error instanceof SpeechCreditsDepletedError) { send(503, { error: 'Speech credits are depleted', code: 'speech_credits_depleted' }); return }
+          send(502, { error: 'Speech generation failed' }); return
+        }
+        // A binding can be revoked while the provider is generating audio.
+        const currentBinding = await this.bindings.authenticate(request.headers.authorization!.slice(7))
+        if (currentBinding.bindingId !== binding.bindingId) throw new Error('Application authority revoked')
+        await this.snapshot(binding.bindingId, speechMatch[1])
+        response.writeHead(200, { 'content-type': audio.mimeType, 'cache-control': 'no-store' })
+        response.end(audio.buffer); return
+      }
       const match = path.match(/^\/v1\/runs\/(r_(?:app|schedule)_[a-f0-9]{64})(\/cancel)?$/)
       if (match && ((!match[2] && request.method === 'GET') || (match[2] && request.method === 'POST'))) {
         await this.snapshot(binding.bindingId, match[1])

package/src/audio.ts

@@ -7,6 +7,10 @@ export type AudioOptions = {
   voice?: string
 }
 
+export class SpeechCreditsDepletedError extends Error {
+  constructor() { super('Gemini speech credits are depleted') }
+}
+
 export const pcmToWav = (pcm: Buffer, sampleRate = 24000, channels = 1): Buffer => {
   const header = Buffer.alloc(44)
   const byteRate = sampleRate * channels * 2
@@ -135,7 +139,7 @@ export const transcribeAudio = async (
 
 export const synthesizeSpeech = async (
   text: string,
-  options: AudioOptions = {},
+  options: AudioOptions & { format?: 'wav' | 'ogg' } = {},
 ): Promise<{ buffer: Buffer; mimeType: string }> => {
   const trimmed = text.trim()
   if (!trimmed) throw new Error('Cannot synthesize speech for empty text')
@@ -143,7 +147,7 @@ export const synthesizeSpeech = async (
   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'
+      'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-lite-tts:generateContent'
     const voiceName = options.voice || 'Kore'
     const response = await fetch(url, {
       method: 'POST',
@@ -153,14 +157,15 @@ export const synthesizeSpeech = async (
         contents: [{ parts: [{ text: trimmed }] }],
         generationConfig: {
           responseModalities: ['AUDIO'],
-          speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName } } },
+          responseFormat: { audio: { mimeType: 'AUDIO_L16', sampleRate: 24000 } },
+          speechConfig: { voiceConfig: { voice: voiceName } },
         },
       }),
     })
 
     if (!response.ok) {
-      const err = await response.text().catch(() => '')
-      throw new Error(`Gemini speech synthesis error ${response.status}: ${err}`)
+      if (response.status === 402) throw new SpeechCreditsDepletedError()
+      throw new Error(`Gemini speech synthesis error ${response.status}`)
     }
 
     const payload = (await response.json()) as any
@@ -173,6 +178,9 @@ export const synthesizeSpeech = async (
       throw new Error(`Gemini returned no audio data (${candidate?.finishReason || 'no candidate'})`)
 
     const rawPcm = Buffer.from(inline.data, 'base64')
+    if (!/^audio\/l16(?:;|$)/i.test(inline.mimeType) || !rawPcm.length || rawPcm.length % 2)
+      throw new Error('Gemini returned an unsupported speech format')
+    if (options.format === 'wav') return { buffer: pcmToWav(rawPcm), mimeType: 'audio/wav' }
     const encoded = await encodeOggOpus(rawPcm, 24000, 1)
     return {
       buffer: encoded,

package/src/config.ts

@@ -25,6 +25,8 @@ export type Config = ControlConfig & {
   applicationPort?: number
   applicationHost?: string
   geminiApiKey?: string
+  speechVoiceEn?: string
+  speechVoiceEs?: string
   openaiApiKey?: string
 }
 
@@ -84,6 +86,8 @@ export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
     channelBackendUrl: env.EZ_CHANNEL_BACKEND_URL?.trim(),
     channelBackendToken: env.EZ_CHANNEL_BACKEND_TOKEN?.trim(),
     geminiApiKey: env.GEMINI_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/index.ts

@@ -103,6 +103,11 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
   const applicationChannel = new ApplicationChannel({
     controlDir: config.controlDir, workspace: config.workspace, initial: aiMenu.initial,
     aiControls: aiMenu,
+    speech: config.geminiApiKey ? (text, language) => synthesizeSpeech(text, {
+      geminiApiKey: config.geminiApiKey,
+      voice: language === 'es' ? config.speechVoiceEs : config.speechVoiceEn,
+      format: 'wav',
+    }) : undefined,
     wake: () => { void drainSources().catch(error => console.error('Application queue unavailable', safeError(error))) },
     createTelegramPairing: async (bindingId, owner) => {
       const username = bot?.botInfo?.username
@@ -581,6 +586,7 @@ export const createRelay = (config: Config, launch = startExecutorJob) => {
             const { buffer } = await synthesizeSpeech(item.voiceText, {
               geminiApiKey: config.geminiApiKey,
               openaiApiKey: config.openaiApiKey,
+              voice: config.speechVoiceEn,
             })
             await paceSend()
             await authorizeChannelDelivery()

package/src/updates/runtime.mjs

@@ -31,6 +31,9 @@ export function execute(command,args,options={}) {
 export async function textAtomic(file,text) {
   const tmp=file+'.update.tmp';await fs.writeFile(tmp,text,{mode:0o600});await fs.rename(tmp,file);
 }
+export async function backupStateDirectory(source,destination) {
+  await fs.cp(source,destination,{recursive:true,filter:async entry=>!(await fs.lstat(entry)).isSocket()});
+}
 export const pluginArgs = record => ['compose','--project-name',record.project,'--file',record.compose];
 export async function packageManager(root,run=execute) {
   const {packageManager:required}=await read(path.join(root,'package.json'));
@@ -116,7 +119,7 @@ export async function perform(home,job,hooks) {
       job.rollback={env:envValue(oldEnv,'EZ_RELAY_IMAGE',oldImage),packageRoot:config.packageRoot};await save();
       await run('docker',[...relayArgs(config),'stop','relay']);await hooks.stopHost();
       const backup=path.join(dir,'backup');await fs.mkdir(backup,{mode:0o700});
-      for(const name of ['mind','control'])await fs.cp(path.join(config.deploymentDir,name),path.join(backup,name),{recursive:true});
+      for(const name of ['mind','control'])await backupStateDirectory(path.join(config.deploymentDir,name),path.join(backup,name));
       for(const name of ['docker.env','host-executor.json','agent.json','purpose.md','relay.env'])await fs.copyFile(path.join(config.deploymentDir,name),path.join(backup,name));
       let env=oldEnv.split(job.previousRoot+path.sep).join(root+path.sep);env=envValue(env,'EZ_RELAY_IMAGE',image);
       await textAtomic(envFile,env);

package/test/application-channel.test.ts

@@ -100,6 +100,58 @@ test('HTTP auth, idempotency, origin/context isolation, revocation and persisted
   assert.equal((await request('/v1/runs',secondToken,input)).status,401)
 })
 
+test('speech renders only a completed bound reply and rechecks authority after generation', async t => {
+  const root = await mkdtemp(join(tmpdir(), 'ez-app-speech-'))
+  const owned = await owner(root), runs = new RunStore(root)
+  const firstToken = token(), secondToken = token()
+  const spoken: string[] = []
+  let revoke = false, reassign = false
+  const channel = new ApplicationChannel({
+    controlDir: root, initial: initialPreset('codex'), wake: () => {}, cancel: async () => {},
+    speech: async text => {
+      spoken.push(text)
+      if (revoke) await channel.bindings.register('first', null, owned)
+      if (reassign) {
+        await channel.bindings.register('first', token(), owned, false, true)
+        await channel.bindings.register('second', firstToken, owned, false, true)
+      }
+      return { buffer: Buffer.from('audio-fixture'), mimeType: 'audio/wav' }
+    },
+  })
+  t.after(async () => { await channel.stop(); await rm(root, { recursive: true, force: true }) })
+  const first = (await channel.bindings.register('first', firstToken, owned))!
+  await channel.bindings.register('second', secondToken, owned)
+  const run = await channel.submit(first.bindingId, { requestId: 'speech', scope: 'exercise', text: 'Explain this' })
+  const address = await channel.listen(0) as { port: number }
+  const request = (bearer: string) => fetch(`http://127.0.0.1:${address.port}/v1/runs/${run.id}/speech`, {
+    method: 'POST', headers: { Authorization: `Bearer ${bearer}` },
+  })
+  assert.equal((await request(secondToken)).status, 404)
+  assert.equal((await request(firstToken)).status, 409)
+  assert.deepEqual(spoken, [])
+  for (const text of ['Progress', 'Keep the movement controlled.']) {
+    const item = await runs.enqueueMessage(run.id, text)
+    await runs.claimOutbox(item.id)
+    await channel.deliver(run, item)
+  }
+  await runs.patch(run.id, { status: 'completed' })
+  const audio = await request(firstToken)
+  assert.equal(audio.status, 200)
+  assert.equal(audio.headers.get('content-type'), 'audio/wav')
+  assert.equal(audio.headers.get('cache-control'), 'no-store')
+  assert.equal(await audio.text(), 'audio-fixture')
+  assert.deepEqual(spoken, ['Keep the movement controlled.'])
+  reassign = true
+  const beforeReassign = spoken.length
+  assert.notEqual((await request(firstToken)).status, 200)
+  assert.equal(spoken.length, beforeReassign + 1)
+  reassign = false
+  await channel.bindings.register('second', secondToken, owned, false, true)
+  await channel.bindings.register('first', firstToken, owned, false, true)
+  revoke = true
+  assert.notEqual((await request(firstToken)).status, 200)
+})
+
 test('owner replacement invalidates binding and client secrets never enter native environment',async t=>{
   const root=await mkdtemp(join(tmpdir(),'ez-app-owner-'))
   t.after(()=>rm(root,{recursive:true,force:true}))

package/test/audio.test.ts

@@ -1,6 +1,11 @@
 import test from 'node:test'
 import assert from 'node:assert/strict'
-import { pcmToWav, encodeOggOpus, transcribeAudio, synthesizeSpeech } from '../src/audio.js'
+import { pcmToWav, encodeOggOpus, transcribeAudio, synthesizeSpeech, SpeechCreditsDepletedError } from '../src/audio.js'
+
+test('speech reports depleted credits without exposing provider details', async (t) => {
+  t.mock.method(globalThis, 'fetch', async () => new Response('', { status: 402 }))
+  await assert.rejects(synthesizeSpeech('Fixture', { geminiApiKey: 'fixture-key' }), SpeechCreditsDepletedError)
+})
 
 test('speech provider failure stays a failure, never a text or WAV success', async (t) => {
   t.mock.method(
@@ -13,9 +18,15 @@ test('speech provider failure stays a failure, never a text or WAV success', asy
 })
 
 test('speech finds audio beyond the first response part and keeps credentials out of URLs', async (t) => {
+  let calls = 0
   t.mock.method(globalThis, 'fetch', async (url: string, options: RequestInit) => {
+    calls += 1
+    assert.match(url, /gemini-3\.8-flash-lite-tts:generateContent$/)
     assert.equal(url.includes('fixture-key'), false)
     assert.equal(new Headers(options.headers).get('x-goog-api-key'), 'fixture-key')
+    const config = JSON.parse(String(options.body)).generationConfig
+    assert.deepEqual(config.responseFormat, { audio: { mimeType: 'AUDIO_L16', sampleRate: 24000 } })
+    assert.deepEqual(config.speechConfig.voiceConfig, { voice: calls === 3 ? 'voice_r3yhwvxvihxg' : 'Kore' })
     return new Response(
       JSON.stringify({
         candidates: [
@@ -39,6 +50,11 @@ test('speech finds audio beyond the first response part and keeps credentials ou
   const speech = await synthesizeSpeech('Fixture', { geminiApiKey: 'fixture-key' })
   assert.equal(speech.mimeType, 'audio/ogg')
   assert.equal(speech.buffer.subarray(0, 4).toString(), 'OggS')
+  const wav = await synthesizeSpeech('Fixture', { geminiApiKey: 'fixture-key', format: 'wav' })
+  assert.equal(wav.mimeType, 'audio/wav')
+  assert.equal(wav.buffer.subarray(0, 4).toString(), 'RIFF')
+  assert.equal(wav.buffer.length, 24044)
+  await synthesizeSpeech('Fixture', { geminiApiKey: 'fixture-key', voice: 'voice_r3yhwvxvihxg', format: 'wav' })
 })
 
 test('pcmToWav generates a valid 44-byte WAV header', () => {

package/test/updates.test.mjs

@@ -5,16 +5,30 @@ import path from 'node:path';
 import { tmpdir } from 'node:os';
 import { gzipSync } from 'node:zlib';
 import { spawn, execFile } from 'node:child_process';
+import { createServer } from 'node:net';
 import { promisify } from 'node:util';
 import { extract, digest, version, newer, compatible } from '../src/updates/artifact.mjs';
 import { prepare, submit, command, read, jobPath, eligibility, jobs, cleanupStaleBackups, reviewedPluginDeploymentMigration } from '../src/updates/control.mjs';
-import { perform, environment, packageManager } from '../src/updates/runtime.mjs';
+import { perform, environment, packageManager, backupStateDirectory } from '../src/updates/runtime.mjs';
 import { atomic, snapshot, compose, prepareCommand } from '../src/plugins/manager.mjs';
 import { bindUpdates } from '../src/updates/binding.mjs';
 import { status as runtimeStatus } from '../src/updates/status.mjs';
 import { providerEnvironment } from '../src/updates/supervisor.mjs';
 const exec=promisify(execFile);
 
+test('main upgrade backup omits a live plugin socket and keeps private files',async t=>{
+ const root=await fs.mkdtemp('/tmp/ez-upgrade-socket-');
+ t.after(()=>fs.rm(root,{recursive:true,force:true}));
+ const source=path.join(root,'control'),destination=path.join(root,'backup');
+ await fs.mkdir(source);await fs.writeFile(path.join(source,'state.json'),'private state');
+ const socket=path.join(source,'plugin-broker.sock'),server=createServer();
+ await new Promise((resolve,reject)=>server.once('error',reject).listen(socket,resolve));
+ t.after(()=>new Promise(resolve=>server.close(resolve)));
+ await backupStateDirectory(source,destination);
+ assert.equal(await fs.readFile(path.join(destination,'state.json'),'utf8'),'private state');
+ assert.deepEqual(await fs.readdir(destination),['state.json']);
+});
+
 test('supervisor forwards only provider keys declared by the agent installation',()=>{
  const host={agents:[{codexProviders:[{envKey:'OPENROUTER_API_KEY'}]}]};
  assert.deepEqual(providerEnvironment(host,{OPENROUTER_API_KEY:'provider-secret',TELEGRAM_BOT_TOKEN:'relay-secret'}),{OPENROUTER_API_KEY:'provider-secret'});