@inetafrica/open-claudia 3.1.4 → 3.1.8

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## v3.1.8 — Hosted pods can actually send voice notes
+
+- **FFMPEG is discovered on PATH.** Provisioned pods ship `/usr/bin/ffmpeg` but never set `FFMPEG=` in config, and `config.js` read only the explicit setting — so `FFMPEG` resolved empty and every TTS route (`pocketToVoice`, ElevenLabs, `say`) silently returned null: voice input got text-only replies. `FFMPEG` now falls back to PATH discovery via the existing `executableCandidate` helper; an explicit `FFMPEG=` still wins.
+- **The system prompt's voice-notes flag reflects real TTS capability.** It gated on `WHISPER_CLI && FFMPEG` — the pre-gateway local-Whisper world — so whisper-less hosted pods told the model "Voice notes: disabled" and it refused user requests (the smart-euvy report), even with working gateway speech. New `media.canSpeak()` mirrors the actual pocket → ElevenLabs → macOS `say` fallback chain and now drives the flag; local Whisper is irrelevant to speaking.
+- **New `open-claudia say "<text>"` CLI verb.** `send-voice` needs a ready-made ogg and the model had no way to synthesize one on request. `say` runs `textToVoice` and sends the result through the loopback voice path (same egress guardrail), and is documented in the Delivery prompt block.
+- Regression coverage in `test-media-speech.js`: a whisper-less pod shape must report `canSpeak() === true`, the prompt gate must key on it, and FFMPEG resolution precedence (explicit > PATH discovery > empty) is asserted via subprocess config loads.
+
+## v3.1.7 — CI spawn-race hardening (first published build of the v3.1.5 changes)
+
+- v3.1.6 also never published. The loaded shared CI runner (node cold-boot 100-370ms vs ~50ms locally) keeps picking off the next-tightest spawn-timing test: this time `test-utility-provider-policy`'s shutdown-drain case, which flat-slept 100ms then cancelled — killing the fake agent before it booted, so its SIGTERM handler never wrote the expected signal capture (pipeline 10383; the v3.1.6 run-lifecycle fix itself passed there).
+- Instead of fixing one test per failed pipeline, audited all 13 fake-agent-spawning test files for the pattern and hardened the three racy ones: `test-utility-provider-policy` (abort and drain cases now wait for the child's boot capture before cancelling; timeout case widened to 2500ms deadline / 400ms kill grace; helper wait deadlines to 15s), `test-provider-enforcer` (timeout verdict widened to 2500ms so the hung child's boot capture and SIGTERM record exist before assertions; kill grace 300ms), `test-provider-subagent` (helper wait deadline to 15s). Semantics unchanged everywhere — the same hangs, kills, aborts, and drains are asserted, just on deterministic readiness signals instead of guessed sleeps.
+- Ships everything listed under v3.1.5 below; no product code changes.
+
+## v3.1.6 — CI test-timing fix (also never published — see v3.1.7)
+
+- The v3.1.5 tag never published: its CI build failed twice on `test-provider-run-lifecycle`'s forced-termination case, whose 120ms timeout lost the node-boot race on the loaded shared runner (the fake agent was SIGTERMed before it could write the descendant capture). Widened to 2000ms timeout / 500ms kill grace — semantics unchanged (agent still hangs, is force-killed, and the detached TERM-resistant descendant must survive).
+- Ships everything listed under v3.1.5 below; no other code changes.
+
+## v3.1.5 — Pod-identity hosted speech + dream memory access
+
+- **Hosted speech now authenticates with the pod's own identity.** The speech-gateway bearer becomes `AGENTSPACE_POD_TOKEN` (minted per pod at provisioning, injected via the `openclaw-secrets` secret) with `SPEECH_API_KEY` kept as fallback — so provisioned bot pods get Pocket TTS/STT without any shared API key. The gateway introspects the token against the Agent Space backend (`/pods/self/speech-authorization`), which scopes it to `speech.tts`/`speech.stt` for bot pods only. Wired through config, media, router, runner, voice-policy, and `/doctor` (which now reports which credential the speech path is using). New hermetic `test-media-speech.js` covers bearer selection and fallback order.
+- **Dream introspection can read memory again.** The nightly dream pass's introspection step was denied read access to the memory substrate; it now runs with explicit read grants (provider allow-list + utility-agent pass-through), with regressions in the claude-provider and dream test suites.
+
 ## v3.1.4 — Preserve Kazee inbound image captions
 
 - Maps Kazee media message content onto the transport-neutral inbound `caption` field, so image instructions reach the agent prompt instead of being replaced by the generic image-description fallback.

package/bin/cli.js

@@ -277,6 +277,24 @@ switch (command) {
     break;
   }
 
+  case "say": {
+    const text = args.slice(1).join(" ").trim();
+    if (!text) {
+      console.error('Usage: open-claudia say "<text>"');
+      process.exit(2);
+    }
+    (async () => {
+      const { textToVoice } = require(path.join(botDir, "core", "media"));
+      const voicePath = await textToVoice(text);
+      if (!voicePath) {
+        console.error("No TTS route available — configure the speech gateway, ElevenLabs, or run on macOS.");
+        process.exit(1);
+      }
+      sendViaLoopback("send-voice", [voicePath]);
+    })();
+    break;
+  }
+
   case "tw":
   case "transcript-window": {
     require("./transcript-window").run(args.slice(1));
@@ -441,6 +459,7 @@ Send tools (only work inside an active bot-spawned task):
   open-claudia send-file <path> [caption]
   open-claudia send-photo <path> [caption]
   open-claudia send-voice <path>
+  open-claudia say "<text>"          Synthesize the text (TTS) and send it as a voice note
 
 Memory tools:
   open-claudia transcript-search <query>     Ranked FTS5 search over indexed transcripts

package/core/config.js

@@ -137,14 +137,19 @@ const TRANSCRIPT_MAX_ENTRY_CHARS = parseInt(config.TRANSCRIPT_MAX_ENTRY_CHARS ||
 const TRANSCRIPTS_DIR = config.TRANSCRIPTS_DIR || process.env.TRANSCRIPTS_DIR || path.join(CONFIG_DIR, "transcripts");
 const WHISPER_CLI = config.WHISPER_CLI || "";
 const WHISPER_MODEL = config.WHISPER_MODEL || "";
-const FFMPEG = config.FFMPEG || "";
+// Hosted pods ship /usr/bin/ffmpeg but never set FFMPEG=, so without PATH
+// discovery every TTS route silently no-ops (smart-euvy "voice notes disabled").
+const FFMPEG = config.FFMPEG || executableCandidate("ffmpeg") || "";
 const ELEVENLABS_API_KEY = config.ELEVENLABS_API_KEY || process.env.ELEVENLABS_API_KEY || "";
 const ELEVENLABS_VOICE_ID = config.ELEVENLABS_VOICE_ID || process.env.ELEVENLABS_VOICE_ID || "EXAVITQu4vr4xnSDxMaL";
 const ELEVENLABS_MODEL = config.ELEVENLABS_MODEL || process.env.ELEVENLABS_MODEL || "eleven_v3";
 const SPEECH_SERVICE_URL = config.SPEECH_SERVICE_URL || process.env.SPEECH_SERVICE_URL || "https://speech.agents.kazee.africa";
 const SPEECH_API_KEY = config.SPEECH_API_KEY || process.env.SPEECH_API_KEY || "";
+const AGENTSPACE_POD_TOKEN = config.AGENTSPACE_POD_TOKEN || process.env.AGENTSPACE_POD_TOKEN || "";
 const POCKET_TTS_VOICE = config.POCKET_TTS_VOICE || process.env.POCKET_TTS_VOICE || "alba";
 const TTS_PROVIDER = config.TTS_PROVIDER || process.env.TTS_PROVIDER || "pocket";
+const rawVoiceReplyMode = String(config.VOICE_REPLY_MODE || process.env.VOICE_REPLY_MODE || "on-voice-input").trim().toLowerCase();
+const VOICE_REPLY_MODE = ["on-voice-input", "always", "never"].includes(rawVoiceReplyMode) ? rawVoiceReplyMode : "on-voice-input";
 const SOUL_FILE = config.SOUL_FILE || path.join(CONFIG_DIR, "soul.md");
 const CRONS_FILE = config.CRONS_FILE || path.join(CONFIG_DIR, "crons.json");
 const JOBS_FILE = config.JOBS_FILE || path.join(CONFIG_DIR, "jobs.json");
@@ -374,7 +379,7 @@ module.exports = {
   TRANSCRIPTS_DIR,
   WHISPER_CLI, WHISPER_MODEL, FFMPEG,
   ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID, ELEVENLABS_MODEL,
-  SPEECH_SERVICE_URL, SPEECH_API_KEY, POCKET_TTS_VOICE, TTS_PROVIDER,
+  SPEECH_SERVICE_URL, SPEECH_API_KEY, AGENTSPACE_POD_TOKEN, POCKET_TTS_VOICE, TTS_PROVIDER, VOICE_REPLY_MODE,
   SOUL_FILE, CRONS_FILE, JOBS_FILE, TASKS_DIR, VAULT_FILE, AUTH_FILE, IDENTITIES_FILE,
   PEOPLE_FILE, INTROS_FILE, AUDIT_FILE,
   STATE_FILE, SESSIONS_FILE,

package/core/doctor.js

@@ -6,7 +6,7 @@ const os = require("os");
 const path = require("path");
 const { execFileSync } = require("child_process");
 const {
-  WHISPER_CLI, WHISPER_MODEL, FFMPEG, WORKSPACE, CONFIG_DIR,
+  WHISPER_CLI, WHISPER_MODEL, FFMPEG, SPEECH_SERVICE_URL, SPEECH_API_KEY, AGENTSPACE_POD_TOKEN, WORKSPACE, CONFIG_DIR,
   botSubprocessEnv,
 } = require("./config");
 const { redactSensitive } = require("./redact");
@@ -149,14 +149,25 @@ function runDoctorChecks(options = {}) {
       : "none",
     action: providerSummary.defaultProvider.providerId ? "" : providerSummary.defaultProvider.reason,
   });
-
-  if (FFMPEG || WHISPER_CLI || WHISPER_MODEL) {
+  const hostedSpeech = !!SPEECH_SERVICE_URL && !!(AGENTSPACE_POD_TOKEN || SPEECH_API_KEY);
+  checks.push({
+    ok: hostedSpeech,
+    warn: !hostedSpeech,
+    label: "Hosted speech",
+    detail: hostedSpeech ? `${SPEECH_SERVICE_URL} (${AGENTSPACE_POD_TOKEN ? "pod identity" : "API key"})` : "not configured",
+    action: hostedSpeech ? "" : "Set AGENTSPACE_POD_TOKEN (managed pods) or SPEECH_API_KEY.",
+  });
+  if (hostedSpeech) {
+    const ff = binaryCheck(FFMPEG || "ffmpeg", "ffmpeg");
+    checks.push({ ...ff, label: "Voice reply transcoder", warn: !ff.ok, action: ff.ok ? "" : "Install ffmpeg or set FFMPEG for Ogg/Opus voice replies." });
+  }
+  if (!hostedSpeech && (FFMPEG || WHISPER_CLI || WHISPER_MODEL)) {
     const ff = binaryCheck(FFMPEG || "ffmpeg", "ffmpeg");
     const wh = binaryCheck(WHISPER_CLI, "Whisper CLI");
     checks.push({ ...ff, action: ff.ok ? "" : "Install ffmpeg or set FFMPEG." });
     checks.push({ ...wh, action: wh.ok ? "" : "Install whisper.cpp or set WHISPER_CLI." });
     checks.push({ ok: !!WHISPER_MODEL && fs.existsSync(WHISPER_MODEL), label: "Whisper model", detail: WHISPER_MODEL || "not configured", action: WHISPER_MODEL ? "Check model path." : "Set WHISPER_MODEL for voice notes." });
-  } else checks.push({ ok: true, warn: true, label: "Voice stack", detail: "not configured (optional)", action: "Set FFMPEG/WHISPER_CLI/WHISPER_MODEL for voice notes." });
+  } else if (!hostedSpeech) checks.push({ ok: true, warn: true, label: "Local voice fallback", detail: "not configured (optional)", action: "Set FFMPEG/WHISPER_CLI/WHISPER_MODEL for local voice-note fallback." });
 
   checks.push(checkWritableDir(WORKSPACE, "Workspace writable"));
   checks.push(checkWritableDir(CONFIG_DIR, "Config dir writable"));

package/core/dream.js

@@ -390,7 +390,7 @@ function parseDream(text) {
       entity_notes: arr("entity_notes"),
       archive: arr("archive"),
       lessons: arr("lessons"),
-      persona: typeof obj.persona === "string" ? obj.persona : null,
+      persona: typeof obj.persona === "string" && obj.persona.trim().toLowerCase() !== "null" ? obj.persona : null,
       tuning: obj.tuning && typeof obj.tuning === "object" && obj.tuning.knob ? obj.tuning : null,
       report: typeof obj.report === "string" ? obj.report.trim() : "",
     };
@@ -774,7 +774,7 @@ function parseIntrospection(text) {
       doc_edits: arr("doc_edits"),
       entity_edits: arr("entity_edits"),
       ideas: arr("ideas"),
-      persona: typeof obj.persona === "string" ? obj.persona : null,
+      persona: typeof obj.persona === "string" && obj.persona.trim().toLowerCase() !== "null" ? obj.persona : null,
       report: typeof obj.report === "string" ? obj.report.trim() : "",
     };
   } catch (e) { return null; }
@@ -1018,7 +1018,14 @@ function negativeHebbianPhase(ev, { cap = 12 } = {}) {
   return { lines, nodes, weakened, pruned };
 }
 
-function dreamUtilityOptions(purpose, { provider = null, timeoutMs, outputSchema, systemPrompt, cwd = process.cwd() } = {}) {
+function dreamUtilityOptions(purpose, {
+  provider = null,
+  timeoutMs,
+  outputSchema,
+  systemPrompt,
+  cwd = process.cwd(),
+  additionalReadOnlyDirectories = null,
+} = {}) {
   return {
     purpose,
     provider,
@@ -1030,6 +1037,7 @@ function dreamUtilityOptions(purpose, { provider = null, timeoutMs, outputSchema
     effort: DREAM_EFFORT,
     timeoutMs,
     cwd,
+    additionalReadOnlyDirectories,
     systemPrompt,
   };
 }
@@ -1202,6 +1210,7 @@ async function runDreamMutation({ trigger = "manual", provider = null, runUtilit
         const introRun = await runUtility(buildIntrospectionPrompt(), dreamUtilityOptions("introspection", {
           provider,
           cwd: CODE_ROOT,
+          additionalReadOnlyDirectories: [CONFIG_DIR],
           timeoutMs: 12 * 60 * 1000,
           outputSchema: INTROSPECTION_OUTPUT_SCHEMA,
           systemPrompt: "You are Open Claudia's nightly self-introspection. You may READ files (your code, memory, soul) to understand yourself, but read-only mode forbids product side effects. After investigating, reply with ONLY the requested JSON object — no prose, no code fences.",

package/core/media.js

@@ -4,11 +4,15 @@
 const fs = require("fs");
 const path = require("path");
 const { execSync } = require("child_process");
-const { WHISPER_CLI, WHISPER_MODEL, FFMPEG, TEMP_DIR, ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID, ELEVENLABS_MODEL, SPEECH_SERVICE_URL, SPEECH_API_KEY, POCKET_TTS_VOICE, TTS_PROVIDER } = require("./config");
+const { WHISPER_CLI, WHISPER_MODEL, FFMPEG, TEMP_DIR, ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID, ELEVENLABS_MODEL, SPEECH_SERVICE_URL, SPEECH_API_KEY, AGENTSPACE_POD_TOKEN, POCKET_TTS_VOICE, TTS_PROVIDER } = require("./config");
 
 const TTS_CMD = process.platform === "darwin" ? "say" : null;
 
-function transcribeAudio(oggPath) {
+function speechBearerToken() {
+  return AGENTSPACE_POD_TOKEN || SPEECH_API_KEY || "";
+}
+
+function transcribeAudioLocal(oggPath) {
   if (!WHISPER_CLI || !FFMPEG) return null;
   const wavPath = oggPath.replace(/\.[^.]+$/, ".wav");
   execSync(`"${FFMPEG}" -i "${oggPath}" -ar 16000 -ac 1 -y "${wavPath}" 2>/dev/null`);
@@ -19,6 +23,30 @@ function transcribeAudio(oggPath) {
     .join(" ").trim();
 }
 
+async function transcribeAudio(oggPath) {
+  const token = speechBearerToken();
+  if (SPEECH_SERVICE_URL && token) {
+    try {
+      const body = new FormData();
+      body.append("file", new Blob([fs.readFileSync(oggPath)]), path.basename(oggPath));
+      const res = await fetch(`${SPEECH_SERVICE_URL.replace(/\/$/, "")}/v1/audio/transcriptions`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}` },
+        body,
+        signal: AbortSignal.timeout(120000),
+      });
+      if (res.ok) {
+        const payload = await res.json();
+        return String(payload.text || "").trim();
+      }
+      console.error(`Hosted STT failed: HTTP ${res.status}`);
+    } catch (e) {
+      console.error("Hosted STT error:", e.message);
+    }
+  }
+  return transcribeAudioLocal(oggPath);
+}
+
 function cleanForTTS(text) {
   return text.replace(/[*_`#>\[\]()]/g, "").replace(/\n{2,}/g, ". ").replace(/\n/g, " ").trim();
 }
@@ -73,12 +101,13 @@ async function elevenLabsToVoice(clean) {
 // Pocket TTS through the Agent Space speech gateway. The gateway returns WAV;
 // Telegram and voice transports receive a compact Ogg/Opus file.
 async function pocketToVoice(clean) {
-  if (TTS_PROVIDER === "elevenlabs" || !SPEECH_API_KEY || !SPEECH_SERVICE_URL || !FFMPEG) return null;
+  const token = speechBearerToken();
+  if (TTS_PROVIDER === "elevenlabs" || !token || !SPEECH_SERVICE_URL || !FFMPEG) return null;
   let wavPath = null;
   try {
     const res = await fetch(`${SPEECH_SERVICE_URL.replace(/\/$/, "")}/v1/audio/speech`, {
       method: "POST",
-      headers: { Authorization: `Bearer ${SPEECH_API_KEY}`, "Content-Type": "application/json" },
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
       body: JSON.stringify({ input: clean, voice: POCKET_TTS_VOICE, response_format: "wav" }),
       signal: AbortSignal.timeout(60000),
     });
@@ -100,6 +129,15 @@ async function pocketToVoice(clean) {
   }
 }
 
+// True when at least one textToVoice route can produce audio. Mirrors the
+// pocket -> ElevenLabs -> say fallback chain; local Whisper is deliberately
+// irrelevant here (hosted pods speak via the gateway without it).
+function canSpeak() {
+  if (!FFMPEG) return false;
+  if (TTS_PROVIDER !== "elevenlabs" && speechBearerToken() && SPEECH_SERVICE_URL) return true;
+  return Boolean(ELEVENLABS_API_KEY || TTS_CMD);
+}
+
 // Natural voice via ElevenLabs, falling back to macOS `say` only on no-key/error.
 async function textToVoice(text) {
   const clean = cleanForTTS(text);
@@ -165,4 +203,4 @@ async function synthSentenceMp3(text) {
   }
 }
 
-module.exports = { transcribeAudio, textToVoice, splitSentences, synthSentenceMp3, pocketToVoice, TTS_CMD };
+module.exports = { transcribeAudio, transcribeAudioLocal, textToVoice, splitSentences, synthSentenceMp3, pocketToVoice, speechBearerToken, canSpeak, TTS_CMD };

package/core/providers/claude.js

@@ -135,6 +135,20 @@ function appendToolLists(args, context) {
   }
 }
 
+function appendReadOnlyDirectories(args, context) {
+  if (context.additionalReadOnlyDirectories === undefined || context.additionalReadOnlyDirectories === null) return;
+  if (!context.readOnly) {
+    throw providerError("INVALID_PROVIDER_CONTEXT", "additionalReadOnlyDirectories requires readOnly mode");
+  }
+  if (!Array.isArray(context.additionalReadOnlyDirectories)
+    || context.additionalReadOnlyDirectories.some((dir) => typeof dir !== "string" || !dir.trim())) {
+    throw providerError("INVALID_PROVIDER_CONTEXT", "additionalReadOnlyDirectories must be an array of non-empty strings");
+  }
+  for (const dir of new Set(context.additionalReadOnlyDirectories.map((entry) => entry.trim()))) {
+    args.push("--add-dir", dir);
+  }
+}
+
 function createClaudeProvider(options = {}) {
   const resolveExecutable = options.resolveExecutable || (() => config.discoverProviderExecutable("claude"));
   const defaultModel = options.defaultModel || CLAUDE_DEFAULT_MODEL;
@@ -195,6 +209,7 @@ function createClaudeProvider(options = {}) {
       || context.transcriptPaths?.directory
       || null;
     if (transcriptDirectory) args.push("--add-dir", String(transcriptDirectory));
+    if (utility) appendReadOnlyDirectories(args, context);
 
     if (!utility) appendSessionArgs(args, context);
     appendModelAndLimits(args, context, defaultModel, utility);

package/core/router.js

@@ -193,7 +193,7 @@ async function handleVoice(envelope) {
     const tStart = Date.now();
     const oggPath = await envelope.adapter.downloadMedia(media);
     const tAfterDownload = Date.now();
-    const transcript = transcribeAudio(oggPath);
+    const transcript = await transcribeAudio(oggPath);
     const tAfterStt = Date.now();
     try { fs.unlinkSync(oggPath); } catch (e) {}
     if (!transcript) return send("Couldn't transcribe. Try typing it.");
@@ -222,7 +222,7 @@ async function handleAudio(envelope) {
     });
     envelope.adapter.typing(envelope.channelId).catch(() => {});
     const p = await envelope.adapter.downloadMedia(media);
-    const t = transcribeAudio(p);
+    const t = await transcribeAudio(p);
     try { fs.unlinkSync(p); } catch (e) {}
     if (!t) return send("Couldn't transcribe.");
     await send(`Heard: "${t}"`, { replyTo: envelope.messageId });

package/core/runner.js

@@ -1654,7 +1654,10 @@ async function deliverForegroundResult(result, runContext, state = currentState(
     if (!sent.ok) throw new Error(`failed to deliver response chunk ${index + 1}`);
   }
 
-  if (result.ok && runContext.lastInputWasVoice) {
+  const { VOICE_REPLY_MODE } = require("./config");
+  const { shouldReplyWithVoice } = require("./voice-policy");
+  const shouldSpeak = shouldReplyWithVoice(VOICE_REPLY_MODE, runContext.lastInputWasVoice);
+  if (result.ok && shouldSpeak) {
     const { currentTransport } = require("./context");
     if (currentTransport() === "voice") {
       const sentences = splitSentences(finalText);
@@ -1668,6 +1671,9 @@ async function deliverForegroundResult(result, runContext, state = currentState(
         if (voicePath) await sendVoice(voicePath);
       }
       await sendVoiceEnd();
+    } else {
+      const voicePath = await textToVoice(finalText);
+      if (voicePath) await sendVoice(voicePath);
     }
   }
   return { ok: true, chunks: chunks.length };

package/core/system-prompt.js

@@ -3,7 +3,8 @@
 
 const fs = require("fs");
 const path = require("path");
-const { SOUL_FILE, CRONS_FILE, VAULT_FILE, FILES_DIR, BOT_DIR, WHISPER_CLI, FFMPEG, config } = require("./config");
+const { SOUL_FILE, CRONS_FILE, VAULT_FILE, FILES_DIR, BOT_DIR, config } = require("./config");
+const { canSpeak } = require("./media");
 const CONFIG_DIR = require("../config-dir");
 const { currentState, getProjectKey, getProviderSession } = require("./state");
 const { currentAdapter, currentChannelId, currentUserId } = require("./context");
@@ -198,7 +199,9 @@ ${listing}`;
 
 function buildCoreInstructionsUncached() {
   const soul = loadSoul();
-  const hasVoice = WHISPER_CLI && FFMPEG;
+  // Gate on actual TTS capability, not local Whisper: hosted pods hear and
+  // speak through the speech gateway with no whisper binary installed.
+  const hasVoice = canSpeak();
   return `
 ${soul}
 ${buildPersonaBlock()}
@@ -230,6 +233,7 @@ Reply normally in your final answer. To send a file, image, or voice clip back t
 - \`open-claudia send-file <path> [caption]\` — any document/binary
 - \`open-claudia send-photo <path> [caption]\` — image with inline preview
 - \`open-claudia send-voice <path>\` — ogg/opus voice note
+- \`open-claudia say "<text>"\` — synthesize the text and send it as a voice note (use this when asked for a voice reply)
 Never print or embed bot tokens in prompts, commands, logs, or messages.
 
 ## Background work

package/core/utility-agent.js

@@ -536,6 +536,9 @@ function createUtilityAgentService(options = {}) {
           fresh: true,
           readOnly: request.readOnly !== false,
           cwd: request.cwd || process.cwd(),
+          ...(request.additionalReadOnlyDirectories !== undefined
+            ? { additionalReadOnlyDirectories: request.additionalReadOnlyDirectories }
+            : {}),
           ...(request.allowedTools !== undefined ? { allowedTools: request.allowedTools } : {}),
           ...(request.disallowedTools !== undefined ? { disallowedTools: request.disallowedTools } : {}),
           ...(request.outputSchema ? { outputSchema: request.outputSchema, outputSchemaPath: schemaResource.file } : {}),

package/core/voice-policy.js

@@ -0,0 +1,7 @@
+"use strict";
+
+function shouldReplyWithVoice(mode, lastInputWasVoice) {
+  return mode === "always" || (mode === "on-voice-input" && !!lastInputWasVoice);
+}
+
+module.exports = { shouldReplyWithVoice };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "3.1.4",
+  "version": "3.1.8",
   "description": "An always-on, provider-agnostic coding-agent harness for Claude Code and OpenAI Codex via chat",
   "main": "bot.js",
   "bin": {

package/test-provider-claude.js

@@ -161,15 +161,28 @@ const utility = validateInvocation(provider.buildUtilityInvocation(deepFreeze({
   tier: "low",
   maxTurns: 2,
   toolHookSettings: "/fixture/utility-hook.json",
+  additionalReadOnlyDirectories: ["/fixture/memory", "/fixture/memory"],
 })));
 assert.ok(utility.args.includes("--no-session-persistence"));
 assert.deepStrictEqual(utility.args.slice(utility.args.indexOf("--allowedTools"), utility.args.indexOf("--allowedTools") + 2), ["--allowedTools", "Read,Glob"]);
 assert.deepStrictEqual(utility.args.slice(utility.args.indexOf("--permission-mode"), utility.args.indexOf("--permission-mode") + 2), ["--permission-mode", "plan"]);
+assert.strictEqual(utility.args.filter((arg) => arg === "/fixture/memory").length, 1, "read-only utility directories are deduplicated");
+assert.deepStrictEqual(utility.args.slice(utility.args.indexOf("/fixture/memory") - 1, utility.args.indexOf("/fixture/memory") + 1), ["--add-dir", "/fixture/memory"]);
 assert.strictEqual(utility.args[utility.args.indexOf("--model") + 1], "claude-haiku-4-5-20251001");
 assert.strictEqual(utility.args[utility.args.indexOf("--json-schema") + 1], JSON.stringify({ type: "object", required: ["ok"] }));
 assert.strictEqual(utility.stdin, "UTILITY PROMPT", "utility prompt uses protected stdin transport");
 assert.ok(!utility.args.includes("UTILITY PROMPT"), "utility prompt is absent from argv");
 
+assert.throws(
+  () => provider.buildUtilityInvocation(simpleContext({ additionalReadOnlyDirectories: ["/fixture/memory"] })),
+  (error) => error && error.code === "INVALID_PROVIDER_CONTEXT",
+  "extra readable directories cannot expand a writable utility invocation",
+);
+assert.throws(
+  () => provider.buildUtilityInvocation(simpleContext({ readOnly: true, additionalReadOnlyDirectories: [""] })),
+  (error) => error && error.code === "INVALID_PROVIDER_CONTEXT",
+);
+
 const decoder = provider.createEventDecoder();
 const raw = decoder.push(Buffer.from('{"type":"system","subtype":"init","session_id":"bound-session"}\n'));
 assert.deepStrictEqual(provider.normalizeEvent(raw[0], richInvocation.parserState), [{ type: "session", sessionId: "bound-session" }]);

package/test-provider-dream.js

@@ -148,6 +148,8 @@ async function providerProbe(kind) {
       readOnly: options.readOnly,
       hasSchema: !!options.outputSchema,
       effort: options.effort,
+      cwd: options.cwd,
+      additionalReadOnlyDirectories: options.additionalReadOnlyDirectories,
       promptBytes: Buffer.byteLength(prompt),
     });
     return utility.spawnUtilityAgent(prompt, options);
@@ -199,6 +201,11 @@ async function providerProbe(kind) {
     assert.strictEqual(call.effort, "max");
     assert.ok(call.promptBytes > 100);
   }
+  assert.strictEqual(calls[0].additionalReadOnlyDirectories, null, "consolidation does not gain memory filesystem access");
+  assert.strictEqual(calls[1].additionalReadOnlyDirectories, null, "applied consolidation does not gain memory filesystem access");
+  assert.deepStrictEqual(calls[2].additionalReadOnlyDirectories, [process.env.OPEN_CLAUDIA_CONFIG_DIR],
+    "introspection explicitly receives the memory config directory");
+  assert.strictEqual(calls[2].cwd, path.resolve(__dirname), "introspection remains rooted in the source tree");
 
   const project = packs.readPack("project");
   const entity = entities.findEntity("Parity Harness");
@@ -241,6 +248,12 @@ async function providerProbe(kind) {
     if (kind === "claude") {
       assert.ok(record.argv.includes("--json-schema"));
       assert.ok(record.argv.includes("max"), "Claude retains maximum dream effort");
+      if (purpose === "introspection") {
+        const memoryIndex = record.argv.indexOf(process.env.OPEN_CLAUDIA_CONFIG_DIR);
+        assert.ok(memoryIndex > 0, "Claude introspection can read memory outside its cwd");
+        assert.strictEqual(record.argv[memoryIndex - 1], "--add-dir");
+        assert.ok(record.argv.includes("plan"), "extra memory access does not expand the read-only boundary");
+      }
     } else {
       assert.ok(record.argv.includes("--output-schema"));
       assert.ok(record.argv.some((arg) => /model_reasoning_effort=.*max/.test(arg)), "max effort passes through natively since codex 0.144 supports it");
@@ -269,6 +282,9 @@ async function providerProbe(kind) {
   assert.match(failed.report, /skipped the AI-led merges/i);
   assert.strictEqual(packs.readPack("family-child").parent, "family", "deterministic filing survives provider failure");
 
+  assert.strictEqual(dream.parseDream('{"persona":"null"}').persona, null, "stringified JSON null is a persona no-op");
+  assert.strictEqual(dream.parseIntrospection('{"persona":" null "}').persona, null, "introspection stringified null is a persona no-op");
+
   return {
     provider: kind,
     mutations: {

package/test-provider-enforcer.js

@@ -87,7 +87,7 @@ async function providerProbe(kind) {
   const utility = createUtilityAgentService({
     registry: registry([entry]),
     env: { ENFORCER_PROVIDER: kind, [`ENFORCER_MODEL_${kind.toUpperCase()}`]: model },
-    killGraceMs: 30,
+    killGraceMs: 300,
   });
   const enforcer = require("./core/enforcer");
   assert.strictEqual(typeof enforcer.createEnforcerService, "function", "enforcer exposes an injectable utility-provider service");
@@ -106,7 +106,9 @@ async function providerProbe(kind) {
   const timeoutService = enforcer.createEnforcerService({
     spawnUtilityAgent: utility.spawnUtilityAgent,
     audit,
-    timeoutMs: 140,
+    // 2500ms so the hung child boots on a loaded CI runner (writing capture #5
+    // and arming its SIGTERM recorder) before the deadline fires.
+    timeoutMs: 2500,
   });
   const timedOut = await timeoutService.vetReply(speaker, "timeout verdict fixture");
 

package/test-provider-language.js

@@ -161,7 +161,32 @@ assert.match(pkg.description, /provider-agnostic coding-agent harness/i);
 // including commit, push, release and deployment.
 // as the preferred voice-note provider, with ElevenLabs fallback and local
 // Whisper transcription unchanged.
-assert.strictEqual(pkg.version, "3.1.4", "release version must remain unchanged without explicit approval");
+// 3.1.5 approved by Sumeet 2026-07-21 ("Yeh" to "Want me to cut 3.1.5 and get
+// going?"): ships pod-identity hosted speech (bearer = AGENTSPACE_POD_TOKEN
+// with SPEECH_API_KEY fallback) so provisioned bot pods can use the Agent
+// Space speech gateway without a shared API key, plus the dream introspection
+// memory-read fix. Release unblocks the fleet pod-voice rollout (canary
+// smart-brenda first).
+// 3.1.6 approved by Sumeet 2026-07-21 ("Go"): identical content to 3.1.5
+// (which CI never published — its build died twice on a 120ms node-boot race
+// in test-provider-run-lifecycle's forced-termination case on the loaded
+// shared runner) plus the test-timing fix (2000ms/500ms). Never retag a
+// failed version — re-cut as +1.
+// 3.1.7 approved by Sumeet 2026-07-21: still the v3.1.5 content, third cut.
+// The 3.1.6 build died on the NEXT tightest spawn race (pipeline 10383:
+// test-utility-provider-policy's drain case flat-slept 100ms then cancelled,
+// killing the fake agent pre-boot so drain-signal.json never appeared; the
+// v3.1.6 run-lifecycle fix itself passed there). Audited all 13 fake-agent
+// test files and hardened the three racy ones (utility-policy, enforcer,
+// subagent): wait on boot captures / generous deadlines, never tight sleeps.
+// 3.1.8 approved by Sumeet 2026-07-21 ("Yeh"): pod voice-note fix. Pods ship
+// /usr/bin/ffmpeg but never set FFMPEG=, so every TTS route silently no-opped,
+// and the system-prompt voice flag still gated on local Whisper — hosted bots
+// told users voice notes were disabled despite a working speech gateway.
+// Fix: FFMPEG PATH discovery in config, media.canSpeak() drives the prompt
+// flag, and a new `open-claudia say "<text>"` verb synthesizes + sends a
+// voice note on request.
+assert.strictEqual(pkg.version, "3.1.8", "release version must remain unchanged without explicit approval");
 for (const keyword of ["claude", "codex", "coding-agent", "provider-agnostic"]) {
   assert.ok(pkg.keywords.includes(keyword), `package keyword missing: ${keyword}`);
 }

package/test-provider-run-lifecycle.js

@@ -342,8 +342,10 @@ async function main() {
         parserState: createClaudeParserState(),
       },
       cwd: processTreeRoot,
-      timeoutMs: 120,
-      killGraceMs: 250,
+      // 120ms lost the node-boot race on loaded CI runners: the parent was
+      // SIGTERMed before spawnDescendantFixture ever ran (pipeline 10381, 2x).
+      timeoutMs: 2000,
+      killGraceMs: 500,
       cleanup: async () => {},
     });
     const treeResult = await realTreeRun;

package/test-provider-subagent.js

@@ -25,7 +25,8 @@ const { HELP, parseAgentArgs } = require("./bin/agent");
 
 function wait(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
 
-async function waitForFile(file, timeoutMs = 2000) {
+// Loaded CI runners stretch node cold-boot far past local timings (pipelines 10381/10383).
+async function waitForFile(file, timeoutMs = 15000) {
   const started = Date.now();
   while (!fs.existsSync(file)) {
     if (Date.now() - started > timeoutMs) throw new Error(`timed out waiting for ${path.basename(file)}`);

package/test-utility-provider-policy.js

@@ -30,7 +30,9 @@ function wait(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-async function waitForFile(file, timeoutMs = 2000) {
+// Loaded CI runners stretch node cold-boot far past local timings (pipelines
+// 10381/10383 died on 100-370ms budgets), so capture waits get generous deadlines.
+async function waitForFile(file, timeoutMs = 15000) {
   const started = Date.now();
   while (!fs.existsSync(file)) {
     if (Date.now() - started > timeoutMs) throw new Error(`timed out waiting for ${path.basename(file)}`);
@@ -38,7 +40,7 @@ async function waitForFile(file, timeoutMs = 2000) {
   }
 }
 
-async function waitForPidExit(pid, timeoutMs = 2000) {
+async function waitForPidExit(pid, timeoutMs = 15000) {
   const started = Date.now();
   while (Date.now() - started <= timeoutMs) {
     try { process.kill(pid, 0); }
@@ -414,12 +416,14 @@ async function main() {
       },
     })),
     env: { UTILITY_PROVIDER: "claude" },
-    killGraceMs: 40,
+    killGraceMs: 400,
   });
   const timeoutStarted = Date.now();
   await assert.rejects(
     timeoutService.spawnUtilityAgent("timeout", {
-      purpose: "subagent", systemPrompt: "timeout", timeoutMs: 180, cwd: root,
+      // 2500ms so the child boots (arming its SIGTERM recorder and spawning
+      // its descendant) on a loaded runner before the deadline fires.
+      purpose: "subagent", systemPrompt: "timeout", timeoutMs: 2500, cwd: root,
     }),
     (error) => {
       assert.ok(error instanceof UtilityAgentError);
@@ -429,7 +433,7 @@ async function main() {
       return true;
     },
   );
-  assert.ok(Date.now() - timeoutStarted >= 180, "timeout settles only after its deadline and process close");
+  assert.ok(Date.now() - timeoutStarted >= 2500, "timeout settles only after its deadline and process close");
   await waitForFile(signalCapture);
   assert.strictEqual(JSON.parse(fs.readFileSync(signalCapture, "utf8")).signal, "SIGTERM");
   await waitForFile(descendantCapture);
@@ -437,9 +441,14 @@ async function main() {
   assert.strictEqual(timeoutService.stats().activeGlobal, 0, "timeout cleanup releases concurrency only after close");
 
   const abortCapture = path.join(root, "abort-signal.json");
+  const abortBootCapture = path.join(root, "abort-boot.json");
   const abortService = createUtilityAgentService({
     registry: registry(providers({
-      codex: { FAKE_AGENT_SCENARIO: "forced-termination", FAKE_AGENT_SIGNAL_CAPTURE: abortCapture },
+      codex: {
+        FAKE_AGENT_SCENARIO: "forced-termination",
+        FAKE_AGENT_SIGNAL_CAPTURE: abortCapture,
+        FAKE_AGENT_CAPTURE: abortBootCapture,
+      },
     })),
     env: { UTILITY_PROVIDER: "codex" },
   });
@@ -447,25 +456,34 @@ async function main() {
   const aborted = abortService.spawnUtilityAgent("abort", {
     purpose: "recall", systemPrompt: "abort", signal: controller.signal, cwd: root,
   });
-  await wait(100);
+  // Abort only after the child demonstrably booted (boot capture exists) so
+  // the TERM lands on an armed signal handler, not a cold spawn.
+  await waitForFile(abortBootCapture);
   controller.abort();
   await assertRejectsCode(aborted, "UTILITY_CANCELLED");
   await waitForFile(abortCapture);
 
   const drainCapture = path.join(root, "drain-signal.json");
+  const drainBootCapture = path.join(root, "drain-boot.json");
   const drainService = createUtilityAgentService({
     registry: registry(providers({
-      claude: { FAKE_AGENT_SCENARIO: "forced-termination", FAKE_AGENT_SIGNAL_CAPTURE: drainCapture },
+      claude: {
+        FAKE_AGENT_SCENARIO: "forced-termination",
+        FAKE_AGENT_SIGNAL_CAPTURE: drainCapture,
+        FAKE_AGENT_CAPTURE: drainBootCapture,
+      },
     })),
     env: { UTILITY_PROVIDER: "claude" },
-    killGraceMs: 40,
+    killGraceMs: 400,
   });
   const drainingRun = drainService.spawnUtilityAgent("shutdown drain", {
     purpose: "review", systemPrompt: "drain", cwd: root,
   });
   const drainingAssertion = assertRejectsCode(drainingRun, "UTILITY_CANCELLED");
-  await wait(100);
-  const drained = await drainService.cancelAll({ timeoutMs: 1000 });
+  // Cancel only after the child booted: pipeline 10383 showed a flat 100ms
+  // sleep kills it pre-boot, so its TERM handler never writes drain-signal.json.
+  await waitForFile(drainBootCapture);
+  const drained = await drainService.cancelAll({ timeoutMs: 5000 });
   await drainingAssertion;
   assert.deepStrictEqual(drained, { drained: true, active: 0 }, "bounded shutdown cancellation waits for utility child cleanup");
   await waitForFile(drainCapture);