@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/util/unhandled.test.mjs

@@ -1,216 +0,0 @@
-/**
- * lib/util/unhandled.test.mjs
- *
- * node:test coverage for the process-level unhandled-failure handlers. Every test
- * drives an injected fake process (a real EventEmitter so listener registration /
- * removal behaves exactly like Node's) and an injected exit + counter, so a
- * simulated rejection/exception is captured WITHOUT touching the test runner's
- * own process or actually exiting.
- *
- * Covered:
- *  - install captures a simulated unhandledRejection via onEvent (log + keep running)
- *  - the rejection is counted via the injected bump (loud, durable)
- *  - install captures a simulated uncaughtException and exits (fatal) by default
- *  - exitOnUncaught:false logs the exception but does NOT exit
- *  - install is idempotent: a second install does not double-register
- *  - uninstall removes the listeners; a later emit is not captured
- *  - a throwing onEvent sink is isolated (no second uncaught throw)
- *  - non-Error rejection values are described, not dropped
- *
- * Run: cd /Users/layla/maestro && node --test lib/util/unhandled.test.mjs
- */
-
-import test from "node:test";
-import assert from "node:assert/strict";
-import { EventEmitter } from "node:events";
-
-import {
-  installUnhandledHandlers,
-  isInstalled,
-  UNHANDLED_COUNTERS,
-} from "./unhandled.mjs";
-
-/** A fake process: a real EventEmitter so on/removeListener semantics match. */
-function fakeProcess() {
-  const ee = new EventEmitter();
-  ee.exited = [];
-  ee.exit = (code) => ee.exited.push(code);
-  return ee;
-}
-
-test("captures a simulated unhandledRejection via onEvent and keeps running", () => {
-  const proc = fakeProcess();
-  const events = [];
-  const { uninstall, installed } = installUnhandledHandlers({
-    process: proc,
-    onEvent: (e) => events.push(e),
-    bump: () => {},
-  });
-  assert.equal(installed, true);
-  try {
-    // Simulate Node emitting an unhandled rejection.
-    proc.emit("unhandledRejection", new Error("boom-reject"));
-    assert.equal(events.length, 1);
-    assert.equal(events[0].kind, "unhandledRejection");
-    assert.equal(events[0].fatal, false);
-    assert.equal(events[0].error.message, "boom-reject");
-    // Log + keep running: a rejection must NEVER exit.
-    assert.deepEqual(proc.exited, []);
-  } finally {
-    uninstall();
-  }
-});
-
-test("an unhandledRejection is counted via the injected bump", () => {
-  const proc = fakeProcess();
-  const counts = [];
-  const { uninstall } = installUnhandledHandlers({
-    process: proc,
-    bump: (name, attrs) => counts.push({ name, attrs }),
-  });
-  try {
-    proc.emit("unhandledRejection", new Error("count-me"));
-    assert.equal(counts.length, 1);
-    assert.equal(counts[0].name, UNHANDLED_COUNTERS.REJECTION);
-    assert.equal(counts[0].attrs.message, "count-me");
-    assert.equal(counts[0].attrs.fatal, false);
-  } finally {
-    uninstall();
-  }
-});
-
-test("captures an uncaughtException, counts it, and exits (fatal) by default", () => {
-  const proc = fakeProcess();
-  const events = [];
-  const counts = [];
-  const { uninstall } = installUnhandledHandlers({
-    process: proc,
-    onEvent: (e) => events.push(e),
-    bump: (name, attrs) => counts.push({ name, attrs }),
-    exit: (code) => proc.exit(code),
-    exitCode: 7,
-  });
-  try {
-    proc.emit("uncaughtException", new Error("fatal-boom"));
-    assert.equal(events.length, 1);
-    assert.equal(events[0].kind, "uncaughtException");
-    assert.equal(events[0].fatal, true);
-    assert.equal(events[0].error.message, "fatal-boom");
-    assert.equal(counts[0].name, UNHANDLED_COUNTERS.EXCEPTION);
-    // Loud exit so launchd restarts a clean process.
-    assert.deepEqual(proc.exited, [7]);
-  } finally {
-    uninstall();
-  }
-});
-
-test("exitOnUncaught:false logs the exception but does not exit", () => {
-  const proc = fakeProcess();
-  const events = [];
-  const { uninstall } = installUnhandledHandlers({
-    process: proc,
-    onEvent: (e) => events.push(e),
-    bump: () => {},
-    exitOnUncaught: false,
-    exit: (code) => proc.exit(code),
-  });
-  try {
-    proc.emit("uncaughtException", new Error("non-fatal"));
-    assert.equal(events.length, 1);
-    assert.equal(events[0].kind, "uncaughtException");
-    assert.deepEqual(proc.exited, [], "must NOT exit when exitOnUncaught is false");
-  } finally {
-    uninstall();
-  }
-});
-
-test("install is idempotent: a second install does not double-register", () => {
-  const proc = fakeProcess();
-  const events = [];
-  const first = installUnhandledHandlers({ process: proc, onEvent: (e) => events.push(e), bump: () => {} });
-  const second = installUnhandledHandlers({ process: proc, onEvent: (e) => events.push(e), bump: () => {} });
-  try {
-    assert.equal(first.installed, true);
-    assert.equal(second.installed, false, "second install must be a no-op");
-    assert.equal(proc.listenerCount("unhandledRejection"), 1, "exactly one listener");
-    assert.equal(proc.listenerCount("uncaughtException"), 1);
-    // One emit → one captured event (not two from a double-registration).
-    proc.emit("unhandledRejection", new Error("once"));
-    assert.equal(events.length, 1);
-  } finally {
-    first.uninstall();
-  }
-});
-
-test("uninstall removes the listeners and isInstalled flips", () => {
-  const proc = fakeProcess();
-  const events = [];
-  const { uninstall } = installUnhandledHandlers({ process: proc, onEvent: (e) => events.push(e), bump: () => {} });
-  assert.equal(isInstalled(proc), true);
-  uninstall();
-  assert.equal(isInstalled(proc), false);
-  assert.equal(proc.listenerCount("unhandledRejection"), 0);
-  assert.equal(proc.listenerCount("uncaughtException"), 0);
-  // A later emit is no longer captured.
-  proc.emit("unhandledRejection", new Error("after-uninstall"));
-  assert.equal(events.length, 0);
-});
-
-test("a re-install after uninstall works (installed:true again)", () => {
-  const proc = fakeProcess();
-  const a = installUnhandledHandlers({ process: proc, bump: () => {} });
-  a.uninstall();
-  const b = installUnhandledHandlers({ process: proc, bump: () => {} });
-  try {
-    assert.equal(b.installed, true);
-    assert.equal(proc.listenerCount("unhandledRejection"), 1);
-  } finally {
-    b.uninstall();
-  }
-});
-
-test("a throwing onEvent sink is isolated (no second uncaught throw)", () => {
-  const proc = fakeProcess();
-  const { uninstall } = installUnhandledHandlers({
-    process: proc,
-    onEvent: () => { throw new Error("sink exploded"); },
-    bump: () => {},
-  });
-  try {
-    // The handler must swallow the sink's throw rather than re-throwing.
-    assert.doesNotThrow(() => proc.emit("unhandledRejection", new Error("x")));
-  } finally {
-    uninstall();
-  }
-});
-
-test("a throwing bump counter is isolated and onEvent still fires", () => {
-  const proc = fakeProcess();
-  const events = [];
-  const { uninstall } = installUnhandledHandlers({
-    process: proc,
-    onEvent: (e) => events.push(e),
-    bump: () => { throw new Error("counter blew up"); },
-  });
-  try {
-    assert.doesNotThrow(() => proc.emit("unhandledRejection", new Error("y")));
-    assert.equal(events.length, 1, "onEvent fires even if the counter throws");
-  } finally {
-    uninstall();
-  }
-});
-
-test("describes non-Error rejection values rather than dropping them", () => {
-  const proc = fakeProcess();
-  const events = [];
-  const { uninstall } = installUnhandledHandlers({ process: proc, onEvent: (e) => events.push(e), bump: () => {} });
-  try {
-    proc.emit("unhandledRejection", "just a string");
-    proc.emit("unhandledRejection", { code: "ECUSTOM", detail: 1 });
-    assert.equal(events.length, 2);
-    assert.equal(events[0].error.message, "just a string");
-    assert.equal(typeof events[1].error.message, "string");
-  } finally {
-    uninstall();
-  }
-});

package/lib/voice/outbound.test.mjs

@@ -1,69 +0,0 @@
-/**
- * outbound.test.mjs — node:test coverage for outbound voice.
- *
- * No real network: synthesizeSpeech, Baileys, Slack, Twilio all stubbed
- * via dependency injection / process.env manipulation.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { pickTransport } from "./outbound.mjs";
-import { pickDefaultVoice, ttsCostEstimate } from "./tts.mjs";
-
-// ---------------------------------------------------------------------------
-// pickTransport
-// ---------------------------------------------------------------------------
-
-test("pickTransport: explicit override wins", () => {
-  assert.equal(pickTransport({ to: "+14155551234", transport: "pstn" }), "pstn");
-  assert.equal(pickTransport({ to: "C12345678", transport: "whatsapp" }), "whatsapp");
-});
-
-test("pickTransport: Slack channel id (C/D/G prefix)", () => {
-  assert.equal(pickTransport({ to: "C012345678" }), "slack");
-  assert.equal(pickTransport({ to: "D099N1JE7NE" }), "slack");
-  assert.equal(pickTransport({ to: "GABC123456" }), "slack");
-});
-
-test("pickTransport: WhatsApp JID", () => {
-  assert.equal(pickTransport({ to: "447825004124@s.whatsapp.net" }), "whatsapp");
-  assert.equal(pickTransport({ to: "120363041234567890@g.us" }), "whatsapp");
-});
-
-test("pickTransport: E.164 without WA → pstn", () => {
-  // agentRoot pointing at a tmp dir without state/whatsapp/auth/creds.json
-  assert.equal(pickTransport({ to: "+14155551234", agentRoot: "/tmp/no-wa-here-xyz" }), "pstn");
-});
-
-test("pickTransport: refuses ambiguous targets", () => {
-  assert.throws(() => pickTransport({ to: "" }), /to required/);
-  assert.throws(() => pickTransport({ to: "Alex" }), /cannot infer/);
-  assert.throws(() => pickTransport({ to: "alex@example.com" }), /cannot infer/);
-});
-
-// ---------------------------------------------------------------------------
-// TTS helpers
-// ---------------------------------------------------------------------------
-
-test("pickDefaultVoice: maps Realtime-only voices to TTS equivalents", () => {
-  assert.equal(pickDefaultVoice({ voice: "cedar" }), "ash");
-  assert.equal(pickDefaultVoice({ voice: "marin" }), "shimmer");
-});
-
-test("pickDefaultVoice: passes through valid TTS voices", () => {
-  for (const v of ["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse"]) {
-    assert.equal(pickDefaultVoice({ voice: v }), v);
-  }
-});
-
-test("pickDefaultVoice: fallback to alloy on unknown/empty", () => {
-  assert.equal(pickDefaultVoice({}), "alloy");
-  assert.equal(pickDefaultVoice({ voice: "nonexistent" }), "alloy");
-});
-
-test("ttsCostEstimate: matches OpenAI's $0.015/1k chars", () => {
-  assert.equal(ttsCostEstimate(""), 0);
-  assert.equal(ttsCostEstimate("x".repeat(1000)), 0.015);
-  assert.equal(ttsCostEstimate("x".repeat(10000)), 0.15);
-});

package/lib/voice/session-rotation.test.mjs

@@ -1,114 +0,0 @@
-/**
- * Tests for shouldRotate — the voice-session rotation decision.
- *
- * These tests exist because the clock became an argument. Before that, the
- * `max_duration` rule read `Date.now()` internally, so the only way to observe
- * it firing was to hold a real voice session open for four minutes. That is not
- * a test anyone writes, which is why there were none.
- *
- * @module lib/voice/session-rotation.test
- */
-
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import {
-  shouldRotate,
-  SESSION_ROTATION_DEFAULTS,
-} from "./session-rotation.mjs";
-
-const T0 = 1_700_000_000_000; // a fixed instant; any would do
-const { max_duration_ms: MAX_MS, max_turns: MAX_TURNS } = SESSION_ROTATION_DEFAULTS;
-
-/** A session started at T0 with no turns and no latency history. */
-const fresh = (over = {}) => ({
-  turns: 0,
-  started_at: T0,
-  recent_latencies_ms: [],
-  ...over,
-});
-
-describe("shouldRotate: no state", () => {
-  it("does not rotate when there is no session", () => {
-    assert.deepEqual(shouldRotate(null), { rotate: false });
-    assert.deepEqual(shouldRotate(undefined), { rotate: false });
-  });
-});
-
-describe("shouldRotate: the duration boundary", () => {
-  it("holds one millisecond before the limit", () => {
-    const r = shouldRotate(fresh(), { now: T0 + MAX_MS - 1 });
-    assert.equal(r.rotate, false);
-  });
-
-  it("rotates exactly ON the limit", () => {
-    const r = shouldRotate(fresh(), { now: T0 + MAX_MS });
-    assert.deepEqual(r, { rotate: true, reason: "max_duration" });
-  });
-
-  it("rotates well past the limit", () => {
-    const r = shouldRotate(fresh(), { now: T0 + MAX_MS * 10 });
-    assert.equal(r.reason, "max_duration");
-  });
-
-  it("honours an overridden limit", () => {
-    const r = shouldRotate(fresh(), { now: T0 + 100, max_duration_ms: 50 });
-    assert.deepEqual(r, { rotate: true, reason: "max_duration" });
-  });
-
-  it("treats a missing started_at as age zero rather than as epoch", () => {
-    // The pre-existing semantics: `now - (started_at || now)` === 0. Pinned so a
-    // future refactor cannot silently turn an unknown start into a 55-year age.
-    const r = shouldRotate({ turns: 0, recent_latencies_ms: [] }, { now: T0 });
-    assert.equal(r.rotate, false);
-  });
-});
-
-describe("shouldRotate: turn count takes precedence", () => {
-  it("rotates on max_turns even inside the duration window", () => {
-    const r = shouldRotate(fresh({ turns: MAX_TURNS }), { now: T0 });
-    assert.deepEqual(r, { rotate: true, reason: "max_turns" });
-  });
-
-  it("holds one turn below the limit", () => {
-    assert.equal(shouldRotate(fresh({ turns: MAX_TURNS - 1 }), { now: T0 }).rotate, false);
-  });
-
-  it("reports max_turns, not max_duration, when both are exceeded", () => {
-    const r = shouldRotate(fresh({ turns: MAX_TURNS }), { now: T0 + MAX_MS * 5 });
-    assert.equal(r.reason, "max_turns");
-  });
-});
-
-describe("shouldRotate: latency drift", () => {
-  it("ignores latency until there are five samples", () => {
-    const slow = [9999, 9999, 9999, 9999];
-    assert.equal(shouldRotate(fresh({ recent_latencies_ms: slow }), { now: T0 }).rotate, false);
-  });
-
-  it("rotates once five samples drift past p95", () => {
-    const slow = [9999, 9999, 9999, 9999, 9999];
-    const r = shouldRotate(fresh({ recent_latencies_ms: slow }), { now: T0 });
-    assert.deepEqual(r, { rotate: true, reason: "latency_drift" });
-  });
-
-  it("does not rotate on five fast samples", () => {
-    const fast = [10, 12, 11, 9, 13];
-    assert.equal(shouldRotate(fresh({ recent_latencies_ms: fast }), { now: T0 }).rotate, false);
-  });
-});
-
-describe("shouldRotate: determinism", () => {
-  it("is a pure function of (state, opts) — same inputs, same answer", () => {
-    const state = fresh({ turns: 3, recent_latencies_ms: [10, 20, 30, 40, 50] });
-    const a = shouldRotate(state, { now: T0 + 1000 });
-    const b = shouldRotate(state, { now: T0 + 1000 });
-    assert.deepEqual(a, b);
-  });
-
-  it("does not mutate the state it is given", () => {
-    const state = fresh({ turns: 2, recent_latencies_ms: [5, 4, 3, 2, 1] });
-    const before = JSON.stringify(state);
-    shouldRotate(state, { now: T0 + 5 });
-    assert.equal(JSON.stringify(state), before);
-  });
-});

package/lib/voice/stt.test.mjs

@@ -1,226 +0,0 @@
-/**
- * Tests for lib/voice/stt.mjs — speech-to-text over an OpenAI-compatible
- * /audio/transcriptions endpoint.
- *
- * Network is fully stubbed: global.fetch is replaced per-test so no real
- * HTTP call is ever made. We assert the request URL, the Authorization
- * header, the multipart field names/values (model, language, file), the
- * parsed result shape, default model/baseUrl, the filePath read path, and
- * error handling on a 401 stub.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtemp, writeFile, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { transcribeAudioFile } from "./stt.mjs";
-
-const realFetch = global.fetch;
-
-function jsonResponse(obj, { ok = true, status = 200 } = {}) {
-  return {
-    ok,
-    status,
-    async json() {
-      return obj;
-    },
-    async text() {
-      return JSON.stringify(obj);
-    },
-  };
-}
-
-function installFetchStub(handler) {
-  const calls = [];
-  global.fetch = async (url, init) => {
-    calls.push({ url, init });
-    return handler(url, init, calls);
-  };
-  return calls;
-}
-
-function restoreFetch() {
-  global.fetch = realFetch;
-}
-
-// Read multipart fields from a FormData body without making a network call.
-async function readForm(init) {
-  assert.ok(init && init.body instanceof FormData, "body must be a FormData instance");
-  const form = init.body;
-  return {
-    model: form.get("model"),
-    language: form.get("language"),
-    prompt: form.get("prompt"),
-    file: form.get("file"),
-  };
-}
-
-test("buffer path: posts multipart to default URL with auth + field names, parses result", async () => {
-  const calls = installFetchStub(() => jsonResponse({ text: "hello world", language: "en" }));
-  try {
-    const out = await transcribeAudioFile({
-      buffer: Buffer.from("FAKEAUDIOBYTES"),
-      apiKey: "sk-test-123",
-      language: "en",
-      fileName: "note.mp3",
-      mime: "audio/mpeg",
-    });
-
-    assert.equal(calls.length, 1, "exactly one fetch call");
-    const { url, init } = calls[0];
-
-    // URL + method
-    assert.equal(url, "https://api.openai.com/v1/audio/transcriptions");
-    assert.equal(init.method, "POST");
-
-    // Auth header
-    assert.equal(init.headers.Authorization, "Bearer sk-test-123");
-    // Caller must NOT hand-set Content-Type for FormData (fetch adds boundary).
-    assert.ok(
-      !init.headers["Content-Type"] && !init.headers["content-type"],
-      "Content-Type must not be set manually for multipart",
-    );
-
-    // Multipart fields
-    const fields = await readForm(init);
-    assert.equal(fields.model, "whisper-1", "default model");
-    assert.equal(fields.language, "en");
-    assert.equal(fields.prompt, null, "no prompt field when not provided");
-    assert.ok(fields.file instanceof Blob, "file part is a Blob");
-    assert.equal(fields.file.type, "audio/mpeg", "blob carries supplied mime");
-
-    // Parsed result
-    assert.equal(out.text, "hello world");
-    assert.deepEqual(out.raw, { text: "hello world", language: "en" });
-  } finally {
-    restoreFetch();
-  }
-});
-
-test("filePath path: reads file, derives fileName, honours baseUrl + model overrides", async () => {
-  const calls = installFetchStub(() => jsonResponse({ text: "from disk" }));
-  const dir = await mkdtemp(join(tmpdir(), "stt-test-"));
-  const fp = join(dir, "voicemail.wav");
-  await writeFile(fp, Buffer.from("RIFFfakewav"));
-  try {
-    const out = await transcribeAudioFile({
-      filePath: fp,
-      apiKey: "sk-abc",
-      model: "gpt-4o-transcribe",
-      baseUrl: "https://compat.example.com/v1/", // trailing slash should be normalized
-      prompt: "Northwind",
-    });
-
-    const { url, init } = calls[0];
-    assert.equal(url, "https://compat.example.com/v1/audio/transcriptions", "trailing slash trimmed");
-
-    const fields = await readForm(init);
-    assert.equal(fields.model, "gpt-4o-transcribe");
-    assert.equal(fields.prompt, "Northwind");
-    assert.ok(fields.file instanceof Blob);
-    // fileName defaults to the basename of filePath; assert via the part name.
-    assert.equal(fields.file.name, "voicemail.wav", "fileName derived from filePath basename");
-
-    assert.equal(out.text, "from disk");
-  } finally {
-    restoreFetch();
-    await rm(dir, { recursive: true, force: true });
-  }
-});
-
-test("apiKey falls back to process.env.OPENAI_API_KEY", async () => {
-  const calls = installFetchStub(() => jsonResponse({ text: "env key works" }));
-  const prev = process.env.OPENAI_API_KEY;
-  process.env.OPENAI_API_KEY = "sk-from-env";
-  try {
-    const out = await transcribeAudioFile({ buffer: Buffer.from("x") });
-    assert.equal(calls[0].init.headers.Authorization, "Bearer sk-from-env");
-    assert.equal(out.text, "env key works");
-  } finally {
-    restoreFetch();
-    if (prev === undefined) delete process.env.OPENAI_API_KEY;
-    else process.env.OPENAI_API_KEY = prev;
-  }
-});
-
-test("throws clear error when no apiKey available", async () => {
-  const prev = process.env.OPENAI_API_KEY;
-  delete process.env.OPENAI_API_KEY;
-  // fetch must never be called.
-  const calls = installFetchStub(() => {
-    throw new Error("fetch should not be called");
-  });
-  try {
-    await assert.rejects(
-      () => transcribeAudioFile({ buffer: Buffer.from("x") }),
-      /OPENAI_API_KEY not set/,
-    );
-    assert.equal(calls.length, 0, "no network call without a key");
-  } finally {
-    restoreFetch();
-    if (prev !== undefined) process.env.OPENAI_API_KEY = prev;
-  }
-});
-
-test("throws when neither filePath nor buffer is provided", async () => {
-  const calls = installFetchStub(() => jsonResponse({ text: "nope" }));
-  try {
-    await assert.rejects(
-      () => transcribeAudioFile({ apiKey: "sk-x" }),
-      /provide either filePath or buffer/,
-    );
-    assert.equal(calls.length, 0);
-  } finally {
-    restoreFetch();
-  }
-});
-
-test("error handling: non-2xx (401) surfaces status + body", async () => {
-  installFetchStub(() =>
-    jsonResponse({ error: { message: "Invalid API key" } }, { ok: false, status: 401 }),
-  );
-  try {
-    await assert.rejects(
-      () => transcribeAudioFile({ buffer: Buffer.from("x"), apiKey: "sk-bad" }),
-      (err) => {
-        assert.match(err.message, /stt failed: HTTP 401/);
-        assert.match(err.message, /Invalid API key/);
-        return true;
-      },
-    );
-  } finally {
-    restoreFetch();
-  }
-});
-
-test("error handling: 2xx but missing text field", async () => {
-  installFetchStub(() => jsonResponse({ language: "en" }));
-  try {
-    await assert.rejects(
-      () => transcribeAudioFile({ buffer: Buffer.from("x"), apiKey: "sk-x" }),
-      /response missing text/,
-    );
-  } finally {
-    restoreFetch();
-  }
-});
-
-test("timeout: AbortError is reported as a timeout", async () => {
-  global.fetch = async (_url, init) => {
-    // Simulate the runtime aborting the request.
-    const err = new Error("aborted");
-    err.name = "AbortError";
-    void init;
-    throw err;
-  };
-  try {
-    await assert.rejects(
-      () => transcribeAudioFile({ buffer: Buffer.from("x"), apiKey: "sk-x", timeoutMs: 5 }),
-      /request timed out after 5ms/,
-    );
-  } finally {
-    restoreFetch();
-  }
-});