@alexkroman1/aai 1.2.3 → 1.3.1

package/dist/host/runtime.d.ts

@@ -9,6 +9,7 @@ import { type ToolSchema } from "../sdk/_internal-types.ts";
 import type { Kv } from "../sdk/kv.ts";
 import type { ClientSink } from "../sdk/protocol.ts";
 import { type ReadyConfig } from "../sdk/protocol.ts";
+import type { LlmProvider, SttProvider, TtsProvider } from "../sdk/providers.ts";
 import type { AgentDef } from "../sdk/types.ts";
 import type { Logger, S2SConfig } from "./runtime-config.ts";
 import type { CreateS2sWebSocket } from "./s2s.ts";
@@ -89,6 +90,22 @@ export type RuntimeOptions = {
      * their own fetch wrapper.
      */
     fetch?: typeof globalThis.fetch | undefined;
+    /**
+     * Pluggable STT provider. Must be set together with `llm` and `tts` to
+     * route sessions through the pipeline path; leave all three unset for
+     * the default AssemblyAI Streaming Speech-to-Speech (S2S) path.
+     */
+    stt?: SttProvider | undefined;
+    /**
+     * Pluggable LLM provider (Vercel AI SDK `LanguageModel`). Must be set
+     * together with `stt` and `tts` to route sessions through the pipeline path.
+     */
+    llm?: LlmProvider | undefined;
+    /**
+     * Pluggable TTS provider. Must be set together with `stt` and `llm` to
+     * route sessions through the pipeline path.
+     */
+    tts?: TtsProvider | undefined;
 };
 /**
  * The agent runtime returned by {@link createRuntime}.

package/dist/host/s2s.d.ts

@@ -62,6 +62,11 @@ export type S2sEvents = {
 export type S2sHandle = {
     on<K extends keyof S2sEvents>(event: K, cb: S2sEvents[K]): Unsubscribe;
     sendAudio(audio: Uint8Array): void;
+    /**
+     * Send a pre-encoded audio wire frame. For perf-critical callers (load tests)
+     * that batch-encode up front. Skips logging; caller owns wire format.
+     */
+    sendAudioRaw(jsonFrame: string): void;
     sendToolResult(callId: string, result: string): void;
     updateSession(config: S2sSessionConfig): void;
     resumeSession(sessionId: string): void;

package/dist/host/session-ctx.d.ts

@@ -25,15 +25,18 @@ export type SessionDeps = {
     readonly maxHistory: number;
 };
 /**
- * Session context threaded through event handlers.
+ * Transport-agnostic session context shared by S2S and pipeline sessions.
+ *
+ * Owns reply lifecycle, conversation history (with sliding-window truncation),
+ * and per-turn tool-call step enforcement. Transport-specific fields (e.g.
+ * `s2s` for S2S, `stt`/`tts` for the pipeline) live on the extending types.
  *
  * Split into three layers:
  * - {@link SessionDeps} — immutable dependencies (set once)
  * - {@link ReplyState} via `reply` — per-reply mutable state (reset on beginReply/cancelReply)
- * - Remaining fields — connection, conversation, and lifecycle methods
+ * - Remaining fields — conversation and lifecycle methods
  */
-export type S2sSessionCtx = SessionDeps & {
-    s2s: S2sHandle | null;
+export type BaseSessionCtx = SessionDeps & {
     reply: ReplyState;
     turnPromise: Promise<void> | null;
     conversationMessages: Message[];
@@ -43,6 +46,21 @@ export type S2sSessionCtx = SessionDeps & {
     cancelReply(): void;
     chainTurn(p: Promise<void>): void;
 };
+/**
+ * S2S session context — {@link BaseSessionCtx} plus the S2S WebSocket handle.
+ */
+export type S2sSessionCtx = BaseSessionCtx & {
+    s2s: S2sHandle | null;
+};
+export declare function _buildBaseCtx(opts: {
+    id: string;
+    agent: string;
+    client: ClientSink;
+    agentConfig: AgentConfig;
+    executeTool: ExecuteTool;
+    log: Logger;
+    maxHistory?: number | undefined;
+}): BaseSessionCtx;
 export declare function buildCtx(opts: {
     id: string;
     agent: string;

package/dist/host/to-vercel-tools.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Converts agent {@link ToolSchema}[] to Vercel AI SDK tools with `execute`
+ * delegation to the agent's {@link ExecuteTool} function.
+ *
+ * The pipeline orchestrator passes the output to `streamText({ tools })`.
+ * Each produced tool's `execute` closure calls
+ * `ctx.executeTool(name, args, sessionId, messages(), { signal, toolCallId })`,
+ * so the existing agent tool infrastructure (argument validation, KV, hooks,
+ * timeout) remains the single source of truth for tool behavior.
+ *
+ * Per-call `options.abortSignal` (forwarded by `streamText` when the
+ * outer turn is aborted, e.g. barge-in) takes precedence over the
+ * bag-level `ctx.signal` so individual invocations respect streamText
+ * aborts.
+ */
+import { type Tool } from "ai";
+import type { ExecuteTool, ToolSchema } from "../sdk/_internal-types.ts";
+import type { Message } from "../sdk/types.ts";
+export interface ToVercelToolsContext {
+    /** The agent's tool-execution function (from the runtime). */
+    executeTool: ExecuteTool;
+    /** Session id threaded to {@link executeTool}. */
+    sessionId: string;
+    /**
+     * Returns the current conversation history at call-time. The orchestrator
+     * calls this per invocation; `toVercelTools` snapshots the returned array
+     * before forwarding to `executeTool` so concurrent mutations cannot leak
+     * across tool calls.
+     */
+    messages: () => readonly Message[];
+    /**
+     * Bag-level abort signal. Used as a fallback when the per-call
+     * `options.abortSignal` from Vercel's `ToolExecutionOptions` is absent.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Convert an array of {@link ToolSchema} to a Vercel AI SDK `ToolSet`
+ * (record keyed by tool name).
+ *
+ * Uses the v6 `tool()` helper with `inputSchema: jsonSchema(...)` wrapping
+ * the agent's JSON Schema `parameters`. Execution is delegated to
+ * `ctx.executeTool` so validation, KV, timeouts, and hooks keep working.
+ */
+export declare function toVercelTools(schemas: readonly ToolSchema[], ctx: ToVercelToolsContext): Record<string, Tool>;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { _ as WS_OPEN, a as DEFAULT_SHUTDOWN_TIMEOUT_MS, c as FETCH_TIMEOUT_MS, d as MAX_PAGE_CHARS, f as MAX_TOOL_RESULT_CHARS, g as TOOL_EXECUTION_TIMEOUT_MS, h as RUN_CODE_TIMEOUT_MS, i as DEFAULT_SESSION_START_TIMEOUT_MS, l as MAX_HTML_BYTES, m as MAX_WS_PAYLOAD_BYTES, n as DEFAULT_IDLE_TIMEOUT_MS, o as DEFAULT_STT_SAMPLE_RATE, p as MAX_VALUE_SIZE, r as DEFAULT_MAX_HISTORY, s as DEFAULT_TTS_SAMPLE_RATE, t as AGENT_CSP, u as MAX_MESSAGE_BUFFER_SIZE } from "./constants-VTFoymJ-.js";
+import { _ as TOOL_EXECUTION_TIMEOUT_MS, a as DEFAULT_SHUTDOWN_TIMEOUT_MS, c as FETCH_TIMEOUT_MS, d as MAX_PAGE_CHARS, f as MAX_TOOL_RESULT_CHARS, g as RUN_CODE_TIMEOUT_MS, h as PIPELINE_FLUSH_TIMEOUT_MS, i as DEFAULT_SESSION_START_TIMEOUT_MS, l as MAX_HTML_BYTES, m as MAX_WS_PAYLOAD_BYTES, n as DEFAULT_IDLE_TIMEOUT_MS, o as DEFAULT_STT_SAMPLE_RATE, p as MAX_VALUE_SIZE, r as DEFAULT_MAX_HISTORY, s as DEFAULT_TTS_SAMPLE_RATE, t as AGENT_CSP, u as MAX_MESSAGE_BUFFER_SIZE, v as WS_OPEN } from "./constants-BL3nvg4I.js";
 import { i as ToolChoiceSchema, n as DEFAULT_GREETING, r as DEFAULT_SYSTEM_PROMPT, t as BuiltinToolSchema } from "./types-Cfx_4QDK.js";
 import { i as toolError, n as errorDetail, r as errorMessage, t as parseWsUpgradeParams } from "./ws-upgrade-BeOQ7fXL.js";
 //#region sdk/allowed-hosts.ts
@@ -137,6 +137,11 @@ function tool(def) {
 * });
 * ```
 *
+* @remarks
+* Pipeline mode: pass `stt`, `llm`, and `tts` together to switch from the
+* default AssemblyAI Streaming Speech-to-Speech path to a pluggable
+* STT → LLM → TTS pipeline. All three must be set (or all left unset).
+*
 * @public
 */
 function agent(def) {
@@ -149,4 +154,4 @@ function agent(def) {
 	};
 }
 //#endregion
-export { AGENT_CSP, BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_MAX_HISTORY, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_SYSTEM_PROMPT, DEFAULT_TTS_SAMPLE_RATE, FETCH_TIMEOUT_MS, MAX_HTML_BYTES, MAX_MESSAGE_BUFFER_SIZE, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, MAX_WS_PAYLOAD_BYTES, RUN_CODE_TIMEOUT_MS, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, WS_OPEN, agent, errorDetail, errorMessage, matchesAllowedHost, parseWsUpgradeParams, tool, toolError, validateAllowedHostPattern };
+export { AGENT_CSP, BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_MAX_HISTORY, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_SYSTEM_PROMPT, DEFAULT_TTS_SAMPLE_RATE, FETCH_TIMEOUT_MS, MAX_HTML_BYTES, MAX_MESSAGE_BUFFER_SIZE, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, MAX_WS_PAYLOAD_BYTES, PIPELINE_FLUSH_TIMEOUT_MS, RUN_CODE_TIMEOUT_MS, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, WS_OPEN, agent, errorDetail, errorMessage, matchesAllowedHost, parseWsUpgradeParams, tool, toolError, validateAllowedHostPattern };

package/dist/sdk/_internal-types.d.ts

@@ -7,13 +7,27 @@ import type { JSONSchema7 } from "json-schema";
 import { z } from "zod";
 import type { Message } from "./types.ts";
 import { type ToolDef } from "./types.ts";
+/**
+ * Options forwarded to an {@link ExecuteTool} invocation.
+ *
+ * Primarily used by the pipeline orchestrator (streamText tool loop) to
+ * thread an {@link AbortSignal} into tool execution. The S2S voice path
+ * does not pass these options today — recipients must treat the whole
+ * bag as optional.
+ */
+export interface ExecuteToolOptions {
+    /** Abort signal bound to the enclosing LLM turn / request. */
+    signal?: AbortSignal;
+    /** Vercel AI SDK tool-call ID for this invocation. Useful for tracing and correlation. */
+    toolCallId?: string;
+}
 /**
  * Function signature for executing a tool by name.
  *
  * Used by session.ts to invoke tools, by direct-executor.ts and
  * harness-runtime.ts to implement the execution.
  */
-export type ExecuteTool = (name: string, args: Readonly<Record<string, unknown>>, sessionId?: string, messages?: readonly Message[]) => Promise<string>;
+export type ExecuteTool = (name: string, args: Readonly<Record<string, unknown>>, sessionId?: string, messages?: readonly Message[], opts?: ExecuteToolOptions) => Promise<string>;
 /**
  * Zod schema for serializable agent configuration sent over the wire.
  *

package/dist/sdk/constants.d.ts

@@ -20,6 +20,13 @@ export declare const FETCH_TIMEOUT_MS = 15000;
 export declare const RUN_CODE_TIMEOUT_MS = 5000;
 /** Maximum time to wait for sessions to stop during graceful shutdown. */
 export declare const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30000;
+/**
+ * Maximum time to wait for a pipeline-mode TTS drain after `flush()` before
+ * forcing the turn to complete. Prevents a stuck TTS provider from wedging
+ * the session. Short relative to `DEFAULT_SHUTDOWN_TIMEOUT_MS` so stop()
+ * can still reclaim the socket cleanly.
+ */
+export declare const PIPELINE_FLUSH_TIMEOUT_MS = 10000;
 /** Maximum length for tool result strings sent to clients. */
 export declare const MAX_TOOL_RESULT_CHARS = 4000;
 /** Maximum chars for webpage text after HTML-to-text conversion. */

package/dist/sdk/define.d.ts

@@ -2,6 +2,7 @@
  * Helper functions for defining agents and tools with full type inference.
  */
 import type { z } from "zod";
+import type { LlmProvider, SttProvider, TtsProvider } from "./providers.ts";
 import { type AgentDef, type BuiltinTool, type ToolChoice, type ToolContext, type ToolDef } from "./types.ts";
 /**
  * Define a tool with typed parameters and execute function.
@@ -51,6 +52,11 @@ export declare function tool<P extends z.ZodObject<z.ZodRawShape>>(def: {
  * });
  * ```
  *
+ * @remarks
+ * Pipeline mode: pass `stt`, `llm`, and `tts` together to switch from the
+ * default AssemblyAI Streaming Speech-to-Speech path to a pluggable
+ * STT → LLM → TTS pipeline. All three must be set (or all left unset).
+ *
  * @public
  */
 export declare function agent(def: {
@@ -63,4 +69,19 @@ export declare function agent(def: {
     toolChoice?: ToolChoice;
     sttPrompt?: string;
     idleTimeoutMs?: number;
+    /**
+     * Pluggable STT provider. Must be set together with `llm` and `tts` to
+     * enable pipeline mode; leave all three unset for S2S mode.
+     */
+    stt?: SttProvider;
+    /**
+     * Pluggable LLM provider (Vercel AI SDK `LanguageModel`). Must be set
+     * together with `stt` and `tts` to enable pipeline mode.
+     */
+    llm?: LlmProvider;
+    /**
+     * Pluggable TTS provider. Must be set together with `stt` and `llm` to
+     * enable pipeline mode.
+     */
+    tts?: TtsProvider;
 }): AgentDef;

package/dist/sdk/manifest.d.ts

@@ -4,6 +4,7 @@
  * Flows from build → host → sdk. Validated via Zod at the boundary,
  * then used as a plain typed object throughout the runtime.
  */
+import type { LlmProvider, SttProvider, TtsProvider } from "./providers.ts";
 /**
  * Tool definition as it appears in the serialized manifest JSON.
  *
@@ -39,6 +40,27 @@ export type Manifest = {
     tools: Record<string, ToolManifest>;
     /** Hostnames the agent is allowed to fetch. Empty = no fetch access. */
     allowedHosts: string[];
+    /**
+     * Pluggable STT provider. Must be set together with `llm` and `tts` to
+     * enable pipeline mode, or all three left unset for s2s mode.
+     */
+    stt?: SttProvider | undefined;
+    /**
+     * Pluggable LLM provider (Vercel AI SDK `LanguageModel`). Must be set
+     * together with `stt` and `tts` to enable pipeline mode.
+     */
+    llm?: LlmProvider | undefined;
+    /**
+     * Pluggable TTS provider. Must be set together with `stt` and `llm` to
+     * enable pipeline mode.
+     */
+    tts?: TtsProvider | undefined;
+    /**
+     * Session mode derived from provider fields:
+     * - `"s2s"` (default): AssemblyAI Streaming Speech-to-Speech path (no stt/llm/tts set).
+     * - `"pipeline"`: pluggable STT → LLM → TTS path (stt + llm + tts all set).
+     */
+    mode: "s2s" | "pipeline";
 };
 /**
  * Parse and normalize a raw agent manifest, applying defaults for all

package/dist/sdk/protocol.d.ts

@@ -61,13 +61,13 @@ export type KvRequest = z.infer<typeof KvRequestSchema>;
  */
 export declare const SessionErrorCodeSchema: z.ZodEnum<{
     internal: "internal";
+    audio: "audio";
     tool: "tool";
     connection: "connection";
     stt: "stt";
     llm: "llm";
     tts: "tts";
     protocol: "protocol";
-    audio: "audio";
 }>;
 /**
  * Error codes for categorizing session errors on the wire.
@@ -108,13 +108,13 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"error">;
     code: z.ZodEnum<{
         internal: "internal";
+        audio: "audio";
         tool: "tool";
         connection: "connection";
         stt: "stt";
         llm: "llm";
         tts: "tts";
         protocol: "protocol";
-        audio: "audio";
     }>;
     message: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -190,13 +190,13 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"error">;
     code: z.ZodEnum<{
         internal: "internal";
+        audio: "audio";
         tool: "tool";
         connection: "connection";
         stt: "stt";
         llm: "llm";
         tts: "tts";
         protocol: "protocol";
-        audio: "audio";
     }>;
     message: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{

package/dist/sdk/protocol.js

@@ -1,4 +1,4 @@
-import { f as MAX_TOOL_RESULT_CHARS } from "../constants-VTFoymJ-.js";
+import { f as MAX_TOOL_RESULT_CHARS } from "../constants-BL3nvg4I.js";
 import { z } from "zod";
 //#region sdk/protocol.ts
 /**

package/dist/sdk/providers.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Pluggable provider interfaces — normalized seams over streaming STT / TTS
+ * SDKs, plus the LLM provider type.
+ *
+ * These are zero-runtime **type** declarations with no Node.js dependencies,
+ * so they live in `sdk/` alongside the `Manifest` type that references them.
+ * Concrete adapters (e.g. AssemblyAI STT, Cartesia TTS) live under
+ * `host/providers/` because they depend on Node-only SDKs.
+ */
+import type { LanguageModel } from "ai";
+/** Unsubscribe callback returned by `.on()` event subscriptions. */
+export type Unsubscribe = () => void;
+export interface SttError extends Error {
+    readonly code: "stt_connect_failed" | "stt_auth_failed" | "stt_stream_error";
+}
+export type SttEvents = {
+    /** Interim transcript; drives barge-in detection. */
+    partial: (text: string) => void;
+    /** End-of-turn final transcript; cue to run the LLM. */
+    final: (text: string) => void;
+    /** Terminal error. The session is expected to end after this fires. */
+    error: (err: SttError) => void;
+};
+export interface SttSession {
+    sendAudio(pcm: Int16Array): void;
+    on<E extends keyof SttEvents>(event: E, fn: SttEvents[E]): Unsubscribe;
+    close(): Promise<void>;
+}
+export interface SttOpenOptions {
+    sampleRate: number;
+    apiKey: string;
+    sttPrompt?: string | undefined;
+    signal: AbortSignal;
+}
+export interface SttProvider {
+    readonly name: string;
+    open(opts: SttOpenOptions): Promise<SttSession>;
+}
+export interface TtsError extends Error {
+    readonly code: "tts_connect_failed" | "tts_auth_failed" | "tts_stream_error";
+}
+export type TtsEvents = {
+    /** One PCM16 audio chunk. Orchestrator forwards to the client. */
+    audio: (pcm: Int16Array) => void;
+    /** Synthesis drained after flush() or cancel(). Emitted exactly once per turn. */
+    done: () => void;
+    /** Terminal error. The session is expected to end after this fires. */
+    error: (err: TtsError) => void;
+};
+export interface TtsSession {
+    /** Push text deltas from the LLM. Provider may synthesize as chunks arrive. */
+    sendText(text: string): void;
+    /** Signal "no more text this turn". Emits `done` when fully synthesized. */
+    flush(): void;
+    /** Interrupt immediately (barge-in). Emits `done` synchronously. */
+    cancel(): void;
+    on<E extends keyof TtsEvents>(event: E, fn: TtsEvents[E]): Unsubscribe;
+    close(): Promise<void>;
+}
+export interface TtsOpenOptions {
+    sampleRate: number;
+    apiKey: string;
+    signal: AbortSignal;
+}
+export interface TtsProvider {
+    readonly name: string;
+    open(opts: TtsOpenOptions): Promise<TtsSession>;
+}
+/** LLM provider — Vercel AI SDK's `LanguageModel`; no wrapping. */
+export type LlmProvider = LanguageModel;

package/dist/sdk/types.d.ts

@@ -3,6 +3,7 @@
  */
 import { z } from "zod";
 import type { Kv } from "./kv.ts";
+import type { LlmProvider, SttProvider, TtsProvider } from "./providers.ts";
 /**
  * Identifier for a built-in server-side tool.
  *
@@ -188,6 +189,21 @@ export type AgentDef<S = Record<string, unknown>> = {
     tools: Readonly<Record<string, ToolDef<z.ZodObject<z.ZodRawShape>, S>>>;
     state?: () => S;
     idleTimeoutMs?: number;
+    /**
+     * Pluggable STT provider. Set together with `llm` and `tts` to enable
+     * pipeline mode; all three unset means S2S mode.
+     */
+    stt?: SttProvider;
+    /**
+     * Pluggable LLM provider (Vercel AI SDK `LanguageModel`). Set together
+     * with `stt` and `tts` for pipeline mode.
+     */
+    llm?: LlmProvider;
+    /**
+     * Pluggable TTS provider. Set together with `stt` and `llm` for
+     * pipeline mode.
+     */
+    tts?: TtsProvider;
 };
 /** @internal Zod schema for {@link BuiltinTool}. Exported for reuse in internal schemas. */
 export declare const BuiltinToolSchema: z.ZodEnum<{

package/exports-no-dev-deps.test.ts

@@ -1,30 +1,46 @@
 // Copyright 2025 the AAI authors. MIT license.
 /**
- * Regression guard: the published bundle must not import any devDependency.
+ * Regression guard: the published bundle must not import any devDependency
+ * that isn't also a (peer) dependency.
  *
  * `tsdown` is configured with `deps.neverBundle: [/^[^./]/]`, meaning every
  * bare npm specifier survives as an `import` in the built output. If a
- * devDependency (e.g. `vitest`) is reachable from any public export, the
- * production server — which only installs `dependencies` — crashes at
- * startup with `ERR_MODULE_NOT_FOUND`.
+ * pure devDependency (e.g. `vitest`) is reachable from any public export,
+ * the production server — which only installs `dependencies` +
+ * `peerDependencies` — crashes at startup with `ERR_MODULE_NOT_FOUND`.
+ *
+ * Optional peer dependencies (e.g. `ai`, `assemblyai`,
+ * `@cartesia/cartesia-js`) are legitimately listed in both
+ * `devDependencies` (so our own tests resolve them) and
+ * `peerDependencies` (so consumers supply their own pin). Those are
+ * allowed — only specifiers that are `devDependencies`-only count as
+ * leaks.
  *
  * This test reads the built `dist/` files for each public export and fails
- * if any bare import specifier is a devDependency.
+ * if any bare import specifier is exclusively a devDependency.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { describe, expect, test } from "vitest";
+import { beforeAll, describe, expect, test } from "vitest";
 
 const PKG_DIR = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(resolve(PKG_DIR, "package.json"), "utf-8")) as {
   exports: Record<string, { "@dev/source"?: string; import?: string }>;
   devDependencies?: Record<string, string>;
   dependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
 };
 
-const devDeps = new Set(Object.keys(pkg.devDependencies ?? {}));
+const peerDeps = new Set(Object.keys(pkg.peerDependencies ?? {}));
+// "leak" means: listed in devDependencies but NOT also a peer dep. Pure
+// devDeps (like `vitest`, `tsdown`) are leaks; optional peer SDKs that
+// happen to double as a devDep for our own tests are not.
+const devDeps = new Set(
+  Object.keys(pkg.devDependencies ?? {}).filter((name) => !peerDeps.has(name)),
+);
 
 // Extract bare module specifiers from an ESM source string. Covers:
 //   import ... from "x"      export ... from "x"      import("x")
@@ -36,18 +52,25 @@ function rootSpecifier(spec: string): string {
   return spec.split("/")[0] ?? spec;
 }
 
-describe("built exports do not import devDependencies", () => {
+describe("built exports do not import devDependency-only packages", () => {
   const entries = Object.entries(pkg.exports)
     .map(([subpath, val]) => ({ subpath, dist: val.import }))
     .filter((e): e is { subpath: string; dist: string } => typeof e.dist === "string");
 
+  // Self-heal so this test works from a clean checkout without a manual
+  // build step — otherwise `pnpm test` on a fresh worktree fails opaquely.
+  beforeAll(() => {
+    const missing = entries.some(({ dist }) => !existsSync(resolve(PKG_DIR, dist)));
+    if (missing) {
+      execFileSync("pnpm", ["--filter", "@alexkroman1/aai", "build"], {
+        cwd: resolve(PKG_DIR, "../.."),
+        stdio: "inherit",
+      });
+    }
+  }, 60_000);
+
   test.each(entries)("$subpath bundle has no devDependency import", ({ dist }) => {
     const file = resolve(PKG_DIR, dist);
-    if (!existsSync(file)) {
-      throw new Error(
-        `Built artifact missing: ${file}. Run \`pnpm --filter @alexkroman1/aai build\` first.`,
-      );
-    }
     const src = readFileSync(file, "utf-8");
     const leaks = new Set<string>();
     for (const match of src.matchAll(IMPORT_RE)) {
@@ -57,6 +80,8 @@ describe("built exports do not import devDependencies", () => {
       const root = rootSpecifier(spec);
       if (devDeps.has(root)) leaks.add(root);
     }
-    expect([...leaks], `devDependency imports in ${dist}: ${[...leaks].join(", ")}`).toEqual([]);
+    expect([...leaks], `devDependency-only imports in ${dist}: ${[...leaks].join(", ")}`).toEqual(
+      [],
+    );
   });
 });