@app-vitals/agent-runtime 0.0.0-stage → 0.1.0

package/voice.ts

@@ -0,0 +1,315 @@
+import { type SpawnOptions, spawn } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolvePiperVoicePaths, validatePiperVoice } from "./piper-voice.ts";
+
+const VOICE_DIR = join(tmpdir(), "shipwright-agent-voice");
+const WHISPER_MAX_BYTES = 25 * 1024 * 1024; // 25MB
+
+export interface VoiceConfig {
+  groqApiKey?: string;
+  elevenLabsApiKey?: string;
+  voiceId?: string;
+  piperVoice?: string;
+  whisperServiceUrl?: string;
+}
+
+// DI seam for the whisper-svc HTTP client — replaces spawnFn from the old local-Whisper path
+export type WhisperClientFn = (
+  audioBuffer: Buffer,
+  audioPath: string,
+) => Promise<string | null>;
+
+type SpawnFn = (
+  command: string,
+  args: string[],
+  options?: SpawnOptions,
+) => ReturnType<typeof spawn>;
+
+const defaultSpawn: SpawnFn = (cmd, args, opts) => spawn(cmd, args, opts ?? {});
+
+/**
+ * Creates an HTTP client that transcribes audio via the self-hosted Whisper pod
+ * the chart ships: onerahmet/openai-whisper-asr-webservice.
+ *
+ * That image exposes a single ASR endpoint — `POST /asr` — with the audio
+ * attached as the multipart field `audio_file`. The behaviour is selected via
+ * query params; with `output=txt` the service returns the transcription as a
+ * plain-text body (NOT JSON). We pin:
+ *   - task=transcribe   (transcribe, not translate-to-English)
+ *   - output=txt        (plain text body, simplest to consume)
+ *   - encode=true        (let ffmpeg inside the image decode arbitrary input)
+ *
+ * Accepts an optional fetchFn for dependency injection in tests (avoids
+ * global.fetch mocking).
+ */
+export function makeWhisperSvcClient(
+  serviceUrl: string,
+  fetchFn: typeof fetch = globalThis.fetch,
+): WhisperClientFn {
+  return async (
+    audioBuffer: Buffer,
+    audioPath: string,
+  ): Promise<string | null> => {
+    const formData = new FormData();
+    const blob = new Blob([new Uint8Array(audioBuffer)]);
+    // onerahmet's ASR endpoint reads the upload from the `audio_file` field.
+    formData.append(
+      "audio_file",
+      blob,
+      audioPath.split("/").pop() ?? "audio.wav",
+    );
+
+    const base = serviceUrl.replace(/\/+$/, "");
+    const url = `${base}/asr?encode=true&task=transcribe&output=txt`;
+
+    let resp: Response;
+    try {
+      resp = await fetchFn(url, {
+        method: "POST",
+        body: formData,
+      });
+    } catch (err) {
+      console.warn("[voice] whisper-svc request failed:", err);
+      return null;
+    }
+
+    if (!resp.ok) {
+      console.warn(
+        "[voice] whisper-svc transcription failed:",
+        resp.status,
+        await resp.text(),
+      );
+      return null;
+    }
+
+    // output=txt → the body IS the transcription (no JSON envelope).
+    const text = (await resp.text()).trim();
+    return text.length > 0 ? text : null;
+  };
+}
+
+/**
+ * Transcribe an audio file via Groq Whisper API.
+ * Returns the transcription text, or null on any error.
+ */
+async function transcribeGroq(
+  audioPath: string,
+  fileBuffer: Buffer,
+  apiKey: string,
+  fetchFn: typeof fetch = globalThis.fetch,
+): Promise<string | null> {
+  const formData = new FormData();
+  const blob = new Blob([new Uint8Array(fileBuffer)]);
+  formData.append("file", blob, audioPath.split("/").pop() ?? "audio.webm");
+  formData.append("model", "whisper-large-v3");
+
+  let resp: Response;
+  try {
+    resp = await fetchFn(
+      "https://api.groq.com/openai/v1/audio/transcriptions",
+      {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}` },
+        body: formData,
+      },
+    );
+  } catch (err) {
+    console.error("[voice] Groq STT request failed:", err);
+    return null;
+  }
+
+  if (!resp.ok) {
+    console.error("[voice] Groq STT failed:", resp.status, await resp.text());
+    return null;
+  }
+
+  const data = (await resp.json()) as { text: string };
+  return data.text ?? null;
+}
+
+/**
+ * Transcribe an audio file.
+ * Fallback chain: Groq (if key set) → whisper-svc HTTP (if URL set or client injected) → null
+ *
+ * Accepts an optional fetchFn for DI in tests (avoids global.fetch mocking).
+ * Accepts an optional whisperClientFn for tests that inject a custom WhisperClientFn directly.
+ */
+export async function transcribeAudio(
+  audioPath: string,
+  voiceConfig: VoiceConfig = {},
+  fetchFn?: typeof fetch,
+  whisperClientFn?: WhisperClientFn,
+): Promise<string | null> {
+  let fileBuffer: Buffer;
+  try {
+    fileBuffer = await readFile(audioPath);
+  } catch (err) {
+    console.warn("[voice] could not read audio file:", err);
+    return null;
+  }
+
+  if (fileBuffer.byteLength > WHISPER_MAX_BYTES) {
+    console.warn(
+      `[voice] audio file exceeds 25MB limit (${fileBuffer.byteLength} bytes) — skipping transcription`,
+    );
+    return null;
+  }
+
+  const resolvedFetch = fetchFn ?? globalThis.fetch;
+
+  const apiKey = voiceConfig.groqApiKey;
+  if (apiKey) {
+    const groqResult = await transcribeGroq(
+      audioPath,
+      fileBuffer,
+      apiKey,
+      resolvedFetch,
+    );
+    if (groqResult !== null) {
+      return groqResult;
+    }
+    console.warn(
+      "[voice] Groq transcription failed — falling back to whisper-svc",
+    );
+  }
+
+  const clientFn =
+    whisperClientFn ??
+    (voiceConfig.whisperServiceUrl
+      ? makeWhisperSvcClient(voiceConfig.whisperServiceUrl, resolvedFetch)
+      : null);
+
+  if (!clientFn) return null;
+  return clientFn(fileBuffer, audioPath);
+}
+
+/**
+ * Synthesize speech from text using ElevenLabs (if key available) or the
+ * self-hosted Piper TTS binary baked into the image.
+ * Returns the path to the generated audio file, or null on failure.
+ *
+ * Accepts an optional fetchFn for DI in tests (avoids global.fetch mocking).
+ * Accepts an optional spawnFn for Piper subprocess injection in tests.
+ */
+export async function synthesizeSpeech(
+  text: string,
+  voiceConfig: VoiceConfig = {},
+  fetchFn?: typeof fetch,
+  spawnFn: SpawnFn = defaultSpawn,
+): Promise<string | null> {
+  mkdirSync(VOICE_DIR, { recursive: true });
+
+  const elevenKey = voiceConfig.elevenLabsApiKey;
+  if (elevenKey) {
+    return synthesizeElevenLabs(
+      text,
+      elevenKey,
+      voiceConfig.voiceId,
+      fetchFn ?? globalThis.fetch,
+    );
+  }
+
+  return synthesizePiper(text, voiceConfig, spawnFn);
+}
+
+async function synthesizeElevenLabs(
+  text: string,
+  apiKey: string,
+  voiceId?: string,
+  fetchFn: typeof fetch = globalThis.fetch,
+): Promise<string | null> {
+  const vid = voiceId ?? "CwhRBWXzGAHq8TQ4Fs17"; // Roger
+
+  let resp: Response;
+  try {
+    resp = await fetchFn(`https://api.elevenlabs.io/v1/text-to-speech/${vid}`, {
+      method: "POST",
+      headers: {
+        "xi-api-key": apiKey,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ text, model_id: "eleven_flash_v2_5" }),
+    });
+  } catch (err) {
+    console.error("[voice] ElevenLabs TTS request failed:", err);
+    return null;
+  }
+
+  if (!resp.ok) {
+    console.error(
+      "[voice] ElevenLabs TTS failed:",
+      resp.status,
+      await resp.text(),
+    );
+    return null;
+  }
+
+  const outPath = join(VOICE_DIR, `${Date.now()}-response.mp3`);
+  await writeFile(outPath, Buffer.from(await resp.arrayBuffer()));
+  return outPath;
+}
+
+/**
+ * Synthesize speech via the self-hosted Piper TTS binary baked into the
+ * image. Unlike a network-based TTS provider, Piper is a local
+ * binary that reads text from stdin and writes audio directly to
+ * `--output_file`. It never requires the network and produces WAV — not
+ * MP3 — output, since ffmpeg stays absent from the image (no transcode
+ * step; Piper's native WAV output is used directly).
+ *
+ * The voice is resolved via validatePiperVoice() (falls back to
+ * DEFAULT_PIPER_VOICE when voiceConfig.piperVoice is unset or not
+ * discovered) and resolvePiperVoicePaths() (only the .onnx model path is
+ * needed for --model — Piper auto-discovers the sibling .onnx.json).
+ *
+ * Never throws — resolves null on every failure path (spawn error, non-zero
+ * exit), mirroring synthesizeElevenLabs's never-throw contract.
+ */
+function synthesizePiper(
+  text: string,
+  voiceConfig: VoiceConfig = {},
+  spawnFn: SpawnFn = defaultSpawn,
+): Promise<string | null> {
+  const outPath = join(VOICE_DIR, `${Date.now()}-response.wav`);
+
+  const voiceName = validatePiperVoice(voiceConfig.piperVoice);
+  const { onnxPath } = resolvePiperVoicePaths(voiceName);
+
+  return new Promise((resolve) => {
+    let proc: ReturnType<typeof spawn>;
+    try {
+      proc = spawnFn("piper", ["--model", onnxPath, "--output_file", outPath]);
+    } catch (err) {
+      console.error("[voice] piper spawn error:", err);
+      resolve(null);
+      return;
+    }
+
+    const stderrChunks: Buffer[] = [];
+    proc.stderr?.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+
+    let errorFired = false;
+    proc.on("error", (err) => {
+      errorFired = true;
+      console.error("[voice] piper spawn error:", err);
+      resolve(null);
+    });
+
+    proc.on("close", (code) => {
+      if (errorFired) return;
+      if (code !== 0) {
+        const stderr = Buffer.concat(stderrChunks).toString();
+        console.error("[voice] piper failed with exit code", code, stderr);
+        resolve(null);
+        return;
+      }
+      resolve(outPath);
+    });
+
+    proc.stdin?.write(text);
+    proc.stdin?.end();
+  });
+}

package/voice.unit.test.ts

@@ -0,0 +1,105 @@
+/**
+ * agent/src/runtime/voice.unit.test.ts
+ *
+ * Documents and locks the contract between makeWhisperSvcClient and the
+ * self-hosted Whisper pod the chart ships (onerahmet/openai-whisper-asr-webservice).
+ *
+ * That image exposes a single ASR endpoint:
+ *   POST /asr?encode=true&task=transcribe&output=txt
+ * with the audio attached as the multipart field `audio_file`, and (with
+ * output=txt) returns the transcription as a plain-text body — NOT JSON.
+ *
+ * These tests use an injected fetchFn (no global.fetch mutation) per the
+ * test-isolation contract.
+ *
+ * synthesizeSpeech dispatch coverage (ElevenLabs vs Piper, including the
+ * fs-touching Piper success/failure paths) lives in voice.integration.test.ts
+ * — this file is pure logic, no I/O of any kind, per docs/test-readiness/test-system.md.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+import { makeWhisperSvcClient } from "./voice.ts";
+
+describe("makeWhisperSvcClient — onerahmet /asr contract", () => {
+  test("POSTs to the /asr endpoint of the service URL", async () => {
+    const fetchFn = mock(
+      async (_url: string, _opts: RequestInit) =>
+        new Response("hello world", { status: 200 }),
+    );
+    const client = makeWhisperSvcClient(
+      "http://whisper:9000",
+      fetchFn as unknown as typeof fetch,
+    );
+
+    await client(Buffer.from("audio"), "clip.webm");
+
+    const [url] = fetchFn.mock.calls[0] as [string, RequestInit];
+    expect(url.startsWith("http://whisper:9000/asr")).toBe(true);
+  });
+
+  test("includes the onerahmet query params (task=transcribe, output=txt, encode=true)", async () => {
+    const fetchFn = mock(
+      async (_url: string, _opts: RequestInit) =>
+        new Response("ok", { status: 200 }),
+    );
+    const client = makeWhisperSvcClient(
+      "http://whisper:9000",
+      fetchFn as unknown as typeof fetch,
+    );
+
+    await client(Buffer.from("audio"), "clip.webm");
+
+    const [url] = fetchFn.mock.calls[0] as [string, RequestInit];
+    const qs = new URL(url).searchParams;
+    expect(qs.get("task")).toBe("transcribe");
+    expect(qs.get("output")).toBe("txt");
+    expect(qs.get("encode")).toBe("true");
+  });
+
+  test("attaches the audio under the `audio_file` multipart field", async () => {
+    const bodies: FormData[] = [];
+    const fetchFn = mock(async (_url: string, opts: RequestInit) => {
+      bodies.push(opts.body as FormData);
+      return new Response("ok", { status: 200 });
+    });
+    const client = makeWhisperSvcClient(
+      "http://whisper:9000",
+      fetchFn as unknown as typeof fetch,
+    );
+
+    await client(Buffer.from("audio"), "/tmp/recording.webm");
+
+    const form = bodies[0];
+    expect(form).toBeInstanceOf(FormData);
+    const file = form.get("audio_file") as File | null;
+    expect(file).not.toBeNull();
+    expect(file?.name).toBe("recording.webm");
+  });
+
+  test("parses the plain-text (output=txt) body as the transcription", async () => {
+    const fetchFn = mock(
+      async (_url: string, _opts: RequestInit) =>
+        new Response("  transcribed words  ", { status: 200 }),
+    );
+    const client = makeWhisperSvcClient(
+      "http://whisper:9000",
+      fetchFn as unknown as typeof fetch,
+    );
+
+    const result = await client(Buffer.from("audio"), "clip.webm");
+    expect(result).toBe("transcribed words");
+  });
+
+  test("returns null on a non-2xx ASR response", async () => {
+    const fetchFn = mock(async () => new Response("boom", { status: 500 }));
+    const client = makeWhisperSvcClient(
+      "http://whisper:9000",
+      fetchFn as unknown as typeof fetch,
+    );
+    const warn = console.warn;
+    console.warn = () => {};
+    const result = await client(Buffer.from("audio"), "clip.webm");
+    console.warn = warn;
+    expect(result).toBeNull();
+  });
+});

package/workspace/BOOTSTRAP.md.template

@@ -0,0 +1,43 @@
+# Bootstrap
+
+_You're seeing this because this is a fresh workspace. Run the ritual, then delete this file._
+
+## First-Run Ritual
+
+1. **Introduce yourself** — open with: "Hey. I just came online. Who am I? Who are you?"
+2. **Discover your identity** — learn your name, role, vibe, and emoji collaboratively
+3. **Determine deployment type** — is this a solo deployment (one human) or a team?
+4. **Update IDENTITY.md** — fill in the fields and add the correct import:
+   - Solo: add `@USER.md` at the bottom
+   - Team: add `@TEAM.md` at the bottom
+5. **Create USER.md or TEAM.md** — fill it in with context about your human(s)
+6. **Clone the repo** — `git clone <repo-url> repos/<repo>` so it's available for research
+7. **Walk through the dev loop** — explain that `shipwright-dev-task`, `shipwright-review`, and
+   `shipwright-patch` are enabled by default, each running every minute via `/shipwright:dev-task`,
+   `/shipwright:review`, and `/shipwright:patch` respectively. But none of them self-discovers
+   work — they're explicit-target-only executors. Candidate selection happens once per tick in the
+   `shipwright-loop` cron: it merges candidates from all enabled phases and dispatches exactly one
+   winning item via strict age-based FIFO, with the target task id or `org/repo#number` embedded
+   directly in the prompt. A standalone phase cron with `shipwright-loop` disabled is silently inert
+   — its prompt carries no target, so every tick just responds `[silent]`.
+   Note: `shipwright-deploy` is another phase cron on the same every-minute schedule, but it's
+   opt-in — enable it via the accounts API when the agent is ready for autonomous deployment.
+8. **Delete this file** — once bootstrap is complete, remove BOOTSTRAP.md
+
+## What You're Building
+
+After bootstrap, the load chain looks like:
+
+```
+CLAUDE.md
+  @SOUL.md        ← personality/tone — yours to evolve
+  @IDENTITY.md    ← who you are + who you work with
+    @USER.md      ← solo: your human's context
+    (or @TEAM.md) ← team: the whole crew
+```
+
+SOUL.md is yours — it won't be overwritten on upgrades. Make it accurate.
+
+---
+
+_Delete this file when the ritual is complete._

package/workspace/BOOTSTRAP.md.template.content.test.ts

@@ -0,0 +1,48 @@
+/**
+ * BOOTSTRAP.md.template content regression guard — ABF-1.1
+ *
+ * Verifies the first-run bootstrap template's cron-walkthrough step describes
+ * the shipwright-loop-driven, explicit-target-only pipeline model (mirrors
+ * the former CLAUDE template content test / DPF-1.1), not the stale "every 30 min,
+ * self-discovering pickup of approved todos" model it replaced.
+ *
+ * Content-assertion only: readFileSync, no I/O beyond local file reads.
+ */
+import { describe, expect, it } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// The template sits beside this test, so this works in any repo layout.
+const TEMPLATE_PATH = join(import.meta.dir, "BOOTSTRAP.md.template");
+
+function readTemplate(): string {
+  return readFileSync(TEMPLATE_PATH, "utf8");
+}
+
+describe("BOOTSTRAP.md.template — shipwright-loop model", () => {
+  it("mentions the shipwright-loop cron as the driver", () => {
+    expect(readTemplate()).toContain("shipwright-loop");
+  });
+
+  it("describes dev-task/review/patch as explicit-target-only executors", () => {
+    expect(readTemplate().toLowerCase()).toContain("explicit-target-only");
+  });
+
+  it("mentions strict age-based FIFO work selection", () => {
+    expect(readTemplate().toLowerCase()).toContain("fifo");
+  });
+
+  it("notes a standalone phase cron with shipwright-loop disabled is silently inert", () => {
+    expect(readTemplate().toLowerCase()).toContain("silently inert");
+  });
+
+  it("does not claim the phase crons run every 30 minutes", () => {
+    expect(readTemplate()).not.toContain("30 min");
+  });
+
+  it("does not claim approved todos are picked up automatically without a driving loop", () => {
+    expect(readTemplate()).not.toContain(
+      "Once a task is approved, it gets picked up automatically.",
+    );
+  });
+});

package/workspace/IDENTITY.md.template

@@ -0,0 +1,8 @@
+# Identity
+
+- **Name:** _(fill in during bootstrap)_
+- **Role:** _(AI assistant? team member?)_
+- **Vibe:** _(direct? warm? grounded?)_
+- **Emoji:** _(pick one)_
+
+<!-- Bootstrap: add @USER.md or @TEAM.md here once you've created the right file -->