@acpfx/recorder 0.2.0 → 0.2.3

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-2026 acpfx contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @acpfx/recorder
+
+Records all pipeline events to JSONL and audio tracks to WAV files. Observes the full event stream for debugging and analysis.
+
+## Usage
+
+This package is a pipeline node for [@acpfx/cli](../orchestrator/README.md). See the CLI package for installation and usage.
+
+## Manifest
+
+- **Consumes:** all event types
+- **Emits:** `lifecycle.ready`, `lifecycle.done`
+
+## Settings
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `outputDir` | string | `./recordings` | Directory to write recordings to |
+
+## Pipeline Example
+
+```yaml
+nodes:
+  recorder:
+    use: "@acpfx/recorder"
+    settings: { outputDir: ./recordings }
+```
+
+Wire the recorder as an output of any node whose events you want to capture.
+
+## License
+
+ISC

package/{src/index.ts → dist/index.js}

@@ -1,116 +1,215 @@
-/**
- * recorder node — captures all events to events.jsonl, writes audio tracks
- * to WAV files, generates conversation.wav and timeline.html.
- *
- * Settings (via ACPFX_SETTINGS):
- *   outputDir?: string — output directory (default: ./recordings/<run-id>)
- */
-
+// src/index.ts
 import {
   mkdirSync,
   createWriteStream,
   writeFileSync,
-  readFileSync,
-  type WriteStream,
+  readFileSync as readFileSync2
 } from "node:fs";
 import { open } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { join as join2, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
-import { emit, log, onEvent, handleManifestFlag } from "@acpfx/node-sdk";
-
-handleManifestFlag();
 
-type Settings = {
-  outputDir?: string;
-};
+// ../node-sdk/src/index.ts
+import { createInterface } from "node:readline";
 
-const settings: Settings = JSON.parse(process.env.ACPFX_SETTINGS || "{}");
-const RUN_ID = randomUUID().slice(0, 8);
-const OUTPUT_DIR = resolve(settings.outputDir ?? "./recordings", RUN_ID);
+// ../core/src/config.ts
+import { parse as parseYaml } from "yaml";
 
-const SAMPLE_RATE = 16000;
-const CHANNELS = 1;
-const BYTES_PER_SAMPLE = 2;
+// ../core/src/manifest.ts
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { z as z2 } from "zod";
 
-// State
-let eventsStream: WriteStream;
-let startTime = Date.now();
-const allEvents: Array<Record<string, unknown>> = [];
+// ../core/src/acpfx-flags.ts
+import { z } from "zod";
+var SetupCheckResponseSchema = z.object({
+  needed: z.boolean(),
+  description: z.string().optional()
+});
+var SetupProgressSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("progress"),
+    message: z.string(),
+    pct: z.number().optional()
+  }),
+  z.object({ type: z.literal("complete"), message: z.string() }),
+  z.object({ type: z.literal("error"), message: z.string() })
+]);
+var UnsupportedFlagResponseSchema = z.object({
+  unsupported: z.boolean(),
+  flag: z.string()
+});
 
-// Audio track writers
-type TrackWriter = {
-  stream: WriteStream;
-  path: string;
-  bytesWritten: number;
-};
-const tracks = new Map<string, TrackWriter>();
+// ../core/src/manifest.ts
+var ArgumentTypeSchema = z2.enum(["string", "number", "boolean"]);
+var ManifestArgumentSchema = z2.object({
+  type: ArgumentTypeSchema,
+  default: z2.unknown().optional(),
+  description: z2.string().optional(),
+  required: z2.boolean().optional(),
+  enum: z2.array(z2.unknown()).optional()
+});
+var ManifestEnvFieldSchema = z2.object({
+  required: z2.boolean().optional(),
+  description: z2.string().optional()
+});
+var NodeManifestSchema = z2.object({
+  name: z2.string(),
+  description: z2.string().optional(),
+  consumes: z2.array(z2.string()),
+  emits: z2.array(z2.string()),
+  arguments: z2.record(z2.string(), ManifestArgumentSchema).optional(),
+  additional_arguments: z2.boolean().optional(),
+  env: z2.record(z2.string(), ManifestEnvFieldSchema).optional()
+});
+function handleAcpfxFlags(manifestPath) {
+  const acpfxFlag = process.argv.find((a) => a.startsWith("--acpfx-"));
+  const legacyManifest = process.argv.includes("--manifest");
+  if (!acpfxFlag && !legacyManifest) return;
+  const flag = acpfxFlag ?? "--acpfx-manifest";
+  switch (flag) {
+    case "--acpfx-manifest":
+      printManifest(manifestPath);
+      break;
+    case "--acpfx-setup-check":
+      process.stdout.write(JSON.stringify({ needed: false }) + "\n");
+      process.exit(0);
+      break;
+    default:
+      process.stdout.write(
+        JSON.stringify({ unsupported: true, flag }) + "\n"
+      );
+      process.exit(0);
+  }
+}
+function handleManifestFlag(manifestPath) {
+  handleAcpfxFlags(manifestPath);
+}
+function printManifest(manifestPath) {
+  if (!manifestPath) {
+    const script = process.argv[1];
+    const scriptDir = dirname(script);
+    const scriptBase = script.replace(/\.[^.]+$/, "");
+    const colocated = `${scriptBase}.manifest.json`;
+    try {
+      readFileSync(colocated);
+      manifestPath = colocated;
+    } catch {
+      manifestPath = join(scriptDir, "manifest.json");
+    }
+  }
+  try {
+    const content = readFileSync(manifestPath, "utf8");
+    process.stdout.write(content.trim() + "\n");
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Failed to read manifest: ${err}
+`);
+    process.exit(1);
+  }
+}
 
+// ../node-sdk/src/index.ts
+var NODE_NAME = process.env.ACPFX_NODE_NAME ?? "unknown";
+function emit(event) {
+  process.stdout.write(JSON.stringify(event) + "\n");
+}
+function log(level, message) {
+  emit({ type: "log", level, component: NODE_NAME, message });
+}
+log.info = (message) => log("info", message);
+log.warn = (message) => log("warn", message);
+log.error = (message) => log("error", message);
+log.debug = (message) => log("debug", message);
+function onEvent(handler) {
+  const rl2 = createInterface({ input: process.stdin });
+  rl2.on("line", (line) => {
+    if (!line.trim()) return;
+    try {
+      const event = JSON.parse(line);
+      handler(event);
+    } catch {
+    }
+  });
+  return rl2;
+}
 
-function createWavHeader(dataSize: number, sr: number, ch: number): Buffer {
+// src/index.ts
+handleManifestFlag();
+var settings = JSON.parse(process.env.ACPFX_SETTINGS || "{}");
+var RUN_ID = randomUUID().slice(0, 8);
+var OUTPUT_DIR = resolve(settings.outputDir ?? "./recordings", RUN_ID);
+var SAMPLE_RATE = 16e3;
+var CHANNELS = 1;
+var BYTES_PER_SAMPLE = 2;
+var eventsStream;
+var startTime = Date.now();
+var allEvents = [];
+var tracks = /* @__PURE__ */ new Map();
+function createWavHeader(dataSize, sr, ch) {
   const bitsPerSample = 16;
-  const byteRate = (sr * ch * bitsPerSample) / 8;
-  const blockAlign = (ch * bitsPerSample) / 8;
+  const byteRate = sr * ch * bitsPerSample / 8;
+  const blockAlign = ch * bitsPerSample / 8;
   const header = Buffer.alloc(44);
   let off = 0;
-  header.write("RIFF", off); off += 4;
-  header.writeUInt32LE(dataSize + 36, off); off += 4;
-  header.write("WAVE", off); off += 4;
-  header.write("fmt ", off); off += 4;
-  header.writeUInt32LE(16, off); off += 4;
-  header.writeUInt16LE(1, off); off += 2;
-  header.writeUInt16LE(ch, off); off += 2;
-  header.writeUInt32LE(sr, off); off += 4;
-  header.writeUInt32LE(byteRate, off); off += 4;
-  header.writeUInt16LE(blockAlign, off); off += 2;
-  header.writeUInt16LE(bitsPerSample, off); off += 2;
-  header.write("data", off); off += 4;
+  header.write("RIFF", off);
+  off += 4;
+  header.writeUInt32LE(dataSize + 36, off);
+  off += 4;
+  header.write("WAVE", off);
+  off += 4;
+  header.write("fmt ", off);
+  off += 4;
+  header.writeUInt32LE(16, off);
+  off += 4;
+  header.writeUInt16LE(1, off);
+  off += 2;
+  header.writeUInt16LE(ch, off);
+  off += 2;
+  header.writeUInt32LE(sr, off);
+  off += 4;
+  header.writeUInt32LE(byteRate, off);
+  off += 4;
+  header.writeUInt16LE(blockAlign, off);
+  off += 2;
+  header.writeUInt16LE(bitsPerSample, off);
+  off += 2;
+  header.write("data", off);
+  off += 4;
   header.writeUInt32LE(dataSize, off);
   return header;
 }
-
-function getOrCreateTrack(trackId: string): TrackWriter {
+function getOrCreateTrack(trackId) {
   let tw = tracks.get(trackId);
   if (tw) return tw;
-
   const filename = `${trackId}.wav`;
-  const path = join(OUTPUT_DIR, filename);
+  const path = join2(OUTPUT_DIR, filename);
   const stream = createWriteStream(path);
-  // Write placeholder header
   stream.write(Buffer.alloc(44));
   tw = { stream, path, bytesWritten: 0 };
   tracks.set(trackId, tw);
   return tw;
 }
-
-async function finalizeTrack(tw: TrackWriter): Promise<void> {
-  await new Promise<void>((res, rej) => {
+async function finalizeTrack(tw) {
+  await new Promise((res, rej) => {
     tw.stream.end(() => res());
     tw.stream.on("error", rej);
   });
-
   const header = createWavHeader(tw.bytesWritten, SAMPLE_RATE, CHANNELS);
   const fd = await open(tw.path, "r+");
   await fd.write(header, 0, header.length, 0);
   await fd.close();
 }
-
-function generateConversationWav(): void {
-  // Merge input (mic) and output (tts) tracks into a single timeline WAV.
-  // We place them sequentially: input audio, then a gap, then output audio.
-  // Timeline positions come from event timestamps.
-
+function generateConversationWav() {
   const micTrack = tracks.get("mic");
   const ttsTrack = tracks.get("tts");
   if (!micTrack && !ttsTrack) return;
-
-  // Find the first and last audio chunk timestamps for each track
   let micStartMs = Infinity, micEndMs = 0;
   let ttsStartMs = Infinity, ttsEndMs = 0;
-
   for (const ev of allEvents) {
     if (ev.type === "audio.chunk") {
-      const ts = (ev.ts as number) ?? 0;
-      const dur = (ev.durationMs as number) ?? 0;
+      const ts = ev.ts ?? 0;
+      const dur = ev.durationMs ?? 0;
       if (ev.trackId === "mic" || ev._from === "mic") {
         micStartMs = Math.min(micStartMs, ts);
         micEndMs = Math.max(micEndMs, ts + dur);
@@ -121,35 +220,25 @@ function generateConversationWav(): void {
       }
     }
   }
-
-  // Calculate total duration and offsets relative to the earliest timestamp
   const globalStart = Math.min(
     micStartMs === Infinity ? Infinity : micStartMs,
-    ttsStartMs === Infinity ? Infinity : ttsStartMs,
+    ttsStartMs === Infinity ? Infinity : ttsStartMs
   );
   if (globalStart === Infinity) return;
-
   const globalEnd = Math.max(micEndMs, ttsEndMs);
   const totalDurationMs = globalEnd - globalStart;
-  const totalSamples = Math.ceil((totalDurationMs / 1000) * SAMPLE_RATE);
+  const totalSamples = Math.ceil(totalDurationMs / 1e3 * SAMPLE_RATE);
   const totalBytes = totalSamples * CHANNELS * BYTES_PER_SAMPLE;
-
-  // Create a silent buffer for the full duration
   const pcm = Buffer.alloc(totalBytes);
-
-  // Write mic audio at correct timeline position
   for (const ev of allEvents) {
     if (ev.type !== "audio.chunk") continue;
-    const ts = (ev.ts as number) ?? 0;
-    const trackId = (ev.trackId as string) ?? (ev._from as string) ?? "";
+    const ts = ev.ts ?? 0;
+    const trackId = ev.trackId ?? ev._from ?? "";
     if (trackId !== "mic" && trackId !== "tts") continue;
-
     const offsetMs = ts - globalStart;
-    const offsetSamples = Math.floor((offsetMs / 1000) * SAMPLE_RATE);
+    const offsetSamples = Math.floor(offsetMs / 1e3 * SAMPLE_RATE);
     const offsetBytes = offsetSamples * CHANNELS * BYTES_PER_SAMPLE;
-    const data = Buffer.from((ev.data as string) ?? "", "base64");
-
-    // Mix: add samples (clamped to int16 range)
+    const data = Buffer.from(ev.data ?? "", "base64");
     for (let i = 0; i < data.length && offsetBytes + i + 1 < pcm.length; i += 2) {
       const existing = pcm.readInt16LE(offsetBytes + i);
       const incoming = data.readInt16LE(i);
@@ -157,48 +246,32 @@ function generateConversationWav(): void {
       pcm.writeInt16LE(mixed, offsetBytes + i);
     }
   }
-
-  const convPath = join(OUTPUT_DIR, "conversation.wav");
+  const convPath = join2(OUTPUT_DIR, "conversation.wav");
   const header = createWavHeader(pcm.length, SAMPLE_RATE, CHANNELS);
   writeFileSync(convPath, Buffer.concat([header, pcm]));
   log.info(`Wrote conversation.wav (${totalDurationMs}ms)`);
 }
-
-function generateTimelineHtml(): void {
-  // Read WAV files as base64 for embedding
+function generateTimelineHtml() {
   let inputWavB64 = "";
   let outputWavB64 = "";
-  const micPath = join(OUTPUT_DIR, "mic.wav");
-  const ttsPath = join(OUTPUT_DIR, "tts.wav");
-  try { inputWavB64 = readFileSync(micPath).toString("base64"); } catch {}
-  try { outputWavB64 = readFileSync(ttsPath).toString("base64"); } catch {}
-
-  // Prepare event markers
-  const markers = allEvents
-    .filter((ev) => {
-      const t = ev.type as string;
-      return (
-        t === "speech.partial" ||
-        t === "speech.delta" ||
-        t === "speech.final" ||
-        t === "speech.pause" ||
-        t === "agent.submit" ||
-        t === "agent.delta" ||
-        t === "agent.complete" ||
-        t === "control.interrupt"
-      );
-    })
-    .map((ev) => ({
-      time: ((ev.ts as number) - startTime) / 1000,
-      type: ev.type,
-      text:
-        (ev as any).text ??
-        (ev as any).delta ??
-        (ev as any).pendingText ??
-        (ev as any).reason ??
-        "",
-    }));
-
+  const micPath = join2(OUTPUT_DIR, "mic.wav");
+  const ttsPath = join2(OUTPUT_DIR, "tts.wav");
+  try {
+    inputWavB64 = readFileSync2(micPath).toString("base64");
+  } catch {
+  }
+  try {
+    outputWavB64 = readFileSync2(ttsPath).toString("base64");
+  } catch {
+  }
+  const markers = allEvents.filter((ev) => {
+    const t = ev.type;
+    return t === "speech.partial" || t === "speech.delta" || t === "speech.final" || t === "speech.pause" || t === "agent.submit" || t === "agent.delta" || t === "agent.complete" || t === "control.interrupt";
+  }).map((ev) => ({
+    time: (ev.ts - startTime) / 1e3,
+    type: ev.type,
+    text: ev.text ?? ev.delta ?? ev.pendingText ?? ev.reason ?? ""
+  }));
   const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -291,71 +364,51 @@ function playPause() {
 </script>
 </body>
 </html>`;
-
-  const htmlPath = join(OUTPUT_DIR, "timeline.html");
+  const htmlPath = join2(OUTPUT_DIR, "timeline.html");
   writeFileSync(htmlPath, html);
   log.info(`Wrote timeline.html`);
 }
-
-async function finalize(): Promise<void> {
-  // Close events stream
+async function finalize() {
   if (eventsStream) {
-    await new Promise<void>((res) => eventsStream.end(() => res()));
+    await new Promise((res) => eventsStream.end(() => res()));
   }
-
-  // Finalize all audio tracks
   for (const tw of tracks.values()) {
     await finalizeTrack(tw);
   }
-
-  // Generate conversation.wav
   try {
     generateConversationWav();
   } catch (err) {
     log.error(`Error generating conversation.wav: ${err}`);
   }
-
-  // Generate timeline.html
   try {
     generateTimelineHtml();
   } catch (err) {
     log.error(`Error generating timeline.html: ${err}`);
   }
-
   log.info(`Recording saved to ${OUTPUT_DIR}`);
 }
-
-// --- Main ---
-
 mkdirSync(OUTPUT_DIR, { recursive: true });
-eventsStream = createWriteStream(join(OUTPUT_DIR, "events.jsonl"));
+eventsStream = createWriteStream(join2(OUTPUT_DIR, "events.jsonl"));
 startTime = Date.now();
-
 emit({ type: "lifecycle.ready", component: "recorder" });
 log.info(`Recording to ${OUTPUT_DIR}`);
-
-const rl = onEvent((event) => {
-  // Record every event to events.jsonl
+var rl = onEvent((event) => {
   allEvents.push(event);
   eventsStream.write(JSON.stringify(event) + "\n");
-
-  // Capture audio tracks
   if (event.type === "audio.chunk") {
-    const trackId = (event.trackId as string) ?? (event._from as string) ?? "unknown";
+    const trackId = event.trackId ?? event._from ?? "unknown";
     const tw = getOrCreateTrack(trackId);
-    const pcm = Buffer.from((event.data as string) ?? "", "base64");
+    const pcm = Buffer.from(event.data ?? "", "base64");
     tw.stream.write(pcm);
     tw.bytesWritten += pcm.length;
   }
 });
-
 rl.on("close", () => {
   finalize().then(() => {
     emit({ type: "lifecycle.done", component: "recorder" });
     process.exit(0);
   });
 });
-
 process.on("SIGTERM", () => {
   finalize().then(() => process.exit(0));
 });

package/dist/manifest.json

@@ -0,0 +1 @@
+{"name":"recorder","description":"Records all events to JSONL and audio tracks to WAV files","consumes":["audio.chunk","audio.level","speech.partial","speech.delta","speech.final","speech.pause","agent.submit","agent.delta","agent.complete","agent.thinking","agent.tool_start","agent.tool_done","control.interrupt","control.state","control.error","lifecycle.ready","lifecycle.done","log","player.status"],"emits":["lifecycle.ready","lifecycle.done"],"arguments":{"outputDir":{"type":"string","description":"Directory to write recordings to (default: ./recordings)"}}}

package/manifest.yaml

@@ -24,3 +24,7 @@ consumes:
 emits:
   - lifecycle.ready
   - lifecycle.done
+arguments:
+  outputDir:
+    type: string
+    description: "Directory to write recordings to (default: ./recordings)"

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@acpfx/recorder",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "type": "module",
   "bin": {
     "acpfx-recorder": "./dist/index.js"
   },
   "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "manifest.yaml"
+  ],
   "dependencies": {
-    "@acpfx/core": "0.2.0",
-    "@acpfx/node-sdk": "0.2.0"
+    "@acpfx/core": "0.4.0",
+    "@acpfx/node-sdk": "0.3.0"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external"
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external && node ../../scripts/copy-manifest.js"
   }
 }

package/CHANGELOG.md

@@ -1,21 +0,0 @@
-# @acpfx/recorder
-
-## 0.2.0
-
-### Minor Changes
-
-- d757640: Initial release: type-safe contracts, Rust orchestrator, manifest-driven event filtering
-
-  - Rust schema crate as canonical event type source of truth with codegen to TypeScript + Zod
-  - Node manifests (manifest.yaml) declaring consumes/emits contracts
-  - Orchestrator event filtering: nodes only receive declared events
-  - Rust orchestrator with ratatui TUI (--ui flag)
-  - node-sdk with structured logging helpers
-  - CI/CD with GitHub Actions and changesets
-  - Platform-specific npm packages for Rust binaries (esbuild-style distribution)
-
-### Patch Changes
-
-- Updated dependencies [d757640]
-  - @acpfx/core@0.2.0
-  - @acpfx/node-sdk@0.2.0