@alexkroman1/aai 1.7.1 → 1.8.0

package/.turbo/turbo-build.log

@@ -1,14 +1,14 @@
 
-> @alexkroman1/aai@1.7.1 build /home/runner/work/agent/agent/packages/aai
+> @alexkroman1/aai@1.8.0 build /home/runner/work/agent/agent/packages/aai
 > tsdown && tsc -p tsconfig.build.json
 
 ℹ tsdown v0.21.7 powered by rolldown v1.0.0-rc.12
 ℹ config file: /home/runner/work/agent/agent/packages/aai/tsdown.config.ts 
-ℹ entry: index.ts, sdk/protocol.ts, host/runtime-barrel.ts, sdk/manifest-barrel.ts, sdk/providers/stt-barrel.ts, sdk/providers/tts-barrel.ts, sdk/providers/llm-barrel.ts, sdk/providers/vector-barrel.ts, sdk/providers/kv-barrel.ts
+ℹ entry: index.ts, sdk/protocol.ts, host/runtime-barrel.ts, sdk/manifest-barrel.ts, sdk/providers/stt-barrel.ts, sdk/providers/tts-barrel.ts, sdk/providers/llm-barrel.ts, sdk/providers/vector-barrel.ts, sdk/providers/kv-barrel.ts, sdk/providers/s2s-barrel.ts
 ℹ target: node22
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ dist/host/runtime-barrel.js          113.03 kB │ gzip: 32.35 kB
+ℹ dist/host/runtime-barrel.js          108.22 kB │ gzip: 29.84 kB
 ℹ dist/sdk/protocol.js                   5.70 kB │ gzip:  1.92 kB
 ℹ dist/index.js                          2.88 kB │ gzip:  1.24 kB
 ℹ dist/sdk/manifest-barrel.js            0.36 kB │ gzip:  0.20 kB
@@ -17,14 +17,16 @@
 ℹ dist/sdk/providers/kv-barrel.js        0.26 kB │ gzip:  0.17 kB
 ℹ dist/sdk/providers/tts-barrel.js       0.25 kB │ gzip:  0.16 kB
 ℹ dist/sdk/providers/vector-barrel.js    0.22 kB │ gzip:  0.15 kB
-ℹ dist/_internal-types-CrnTi9Ew.js       5.93 kB │ gzip:  2.13 kB
-ℹ dist/types-KUgezM6u.js                 5.64 kB │ gzip:  2.39 kB
-ℹ dist/constants-C2nirZUI.js             3.10 kB │ gzip:  1.38 kB
+ℹ dist/sdk/providers/s2s-barrel.js       0.15 kB │ gzip:  0.12 kB
+ℹ dist/_internal-types-CfOAbK6V.js       5.45 kB │ gzip:  1.87 kB
+ℹ dist/types-DOWVZhb9.js                 5.39 kB │ gzip:  2.27 kB
 ℹ dist/soniox-BQdL0mB5.js                2.03 kB │ gzip:  0.54 kB
+ℹ dist/constants-y68COEGj.js             1.70 kB │ gzip:  0.76 kB
 ℹ dist/xai-BDI61Y2M.js                   1.18 kB │ gzip:  0.35 kB
-ℹ dist/ws-upgrade-BeOQ7fXL.js            1.14 kB │ gzip:  0.54 kB
 ℹ dist/rime-58p9mDR8.js                  1.08 kB │ gzip:  0.51 kB
+ℹ dist/ws-upgrade-CG8-by1n.js            1.08 kB │ gzip:  0.52 kB
 ℹ dist/s3-BtCMvCod.js                    0.76 kB │ gzip:  0.29 kB
 ℹ dist/pinecone-CeJ69aRs.js              0.48 kB │ gzip:  0.24 kB
-ℹ 18 files, total: 144.72 kB
-✔ Build complete in 54ms
+ℹ dist/openai-realtime-cjPAHMMx.js       0.27 kB │ gzip:  0.19 kB
+ℹ 20 files, total: 138.16 kB
+✔ Build complete in 48ms

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @alexkroman1/aai
 
+## 1.8.0
+
+### Minor Changes
+
+- a7384ad: Add OpenAI Realtime API as a pluggable s2s: provider via openaiRealtime() from @alexkroman1/aai/s2s
+
+### Patch Changes
+
+- cc013df: Log session.error code+message at warn level (was hidden — only the type was logged), capture session id from session.updated.config.id (the success-path message; session.ready is no longer sent there, leaving resume permanently disabled), and remove the broken time-since-session-ready check from canResumeAfter that prevented resume on any session older than 25s.
+
 ## 1.7.1
 
 ### Patch Changes

package/dist/{_internal-types-CrnTi9Ew.js → _internal-types-CfOAbK6V.js}

@@ -1,16 +1,25 @@
-import { i as ToolChoiceSchema, o as validateAllowedHostPattern, t as BuiltinToolSchema } from "./types-KUgezM6u.js";
+import { i as ToolChoiceSchema, o as validateAllowedHostPattern, t as BuiltinToolSchema } from "./types-DOWVZhb9.js";
 import { z } from "zod";
 //#region sdk/providers.ts
 /**
 * Enforce the all-or-nothing provider rule and return the derived mode.
 *
 * Pipeline mode requires STT, LLM, and TTS all set; S2S mode requires
-* none of them. Anything in-between is a configuration error.
+* none of them. Anything in-between is a configuration error. An optional
+* `s2s` descriptor selects a non-default S2S provider — it must not be
+* combined with any pipeline field.
 */
-function assertProviderTriple(stt, llm, tts) {
-	const count = (stt != null ? 1 : 0) + (llm != null ? 1 : 0) + (tts != null ? 1 : 0);
-	if (count !== 0 && count !== 3) throw new Error("stt, llm, and tts must be set together");
-	return count === 3 ? "pipeline" : "s2s";
+function assertProviderTriple(stt, llm, tts, s2s) {
+	const hasStt = stt != null;
+	const hasLlm = llm != null;
+	const hasTts = tts != null;
+	const hasS2s = s2s != null;
+	const anyPipeline = hasStt || hasLlm || hasTts;
+	const allSet = hasStt && hasLlm && hasTts;
+	const noneSetPipeline = !anyPipeline;
+	if (hasS2s && anyPipeline) throw new Error("s2s and the stt/llm/tts pipeline cannot be set together");
+	if (!(allSet || noneSetPipeline)) throw new Error("stt, llm, and tts must be set together");
+	return allSet ? "pipeline" : "s2s";
 }
 /** Build an {@link SttError} with a typed `code`. Zero-dep helper so both sdk/ and host/ can use it. */
 function makeSttError(code, message) {
@@ -66,17 +75,12 @@ z.object({
 	stt: ProviderDescriptorSchema.optional(),
 	llm: ProviderDescriptorSchema.optional(),
 	tts: ProviderDescriptorSchema.optional(),
+	s2s: ProviderDescriptorSchema.optional(),
 	kv: ProviderDescriptorSchema.optional(),
 	vector: ProviderDescriptorSchema.optional()
 });
 //#endregion
 //#region sdk/_internal-types.ts
-/**
-* Zod schema for serializable agent configuration sent over the wire.
-*
-* This is the JSON-safe subset of the agent definition that can be
-* transmitted between the worker and the host process via structured clone.
-*/
 const AgentConfigSchema = z.object({
 	name: z.string().min(1),
 	systemPrompt: z.string(),
@@ -89,58 +93,41 @@ const AgentConfigSchema = z.object({
 	stt: ProviderDescriptorSchema.optional(),
 	llm: ProviderDescriptorSchema.optional(),
 	tts: ProviderDescriptorSchema.optional(),
+	s2s: ProviderDescriptorSchema.optional(),
 	mode: z.enum(["s2s", "pipeline"]).optional(),
 	kv: ProviderDescriptorSchema.optional(),
 	vector: ProviderDescriptorSchema.optional()
 });
-/**
-* Extract the serializable {@link AgentConfig} subset from a source object.
-*
-* When `stt`, `llm`, and `tts` descriptors are present they are all three
-* required (or none) — enforced here so the server can trust the config.
-* `mode` is derived from their presence.
-*/
 function toAgentConfig(src) {
+	const mode = assertProviderTriple(src.stt, src.llm, src.tts, src.s2s);
 	const config = {
 		name: src.name,
 		systemPrompt: src.systemPrompt,
-		greeting: src.greeting
+		greeting: src.greeting,
+		mode
 	};
 	if (src.sttPrompt !== void 0) config.sttPrompt = src.sttPrompt;
 	if (src.maxSteps !== void 0) config.maxSteps = src.maxSteps;
 	if (src.toolChoice !== void 0) config.toolChoice = src.toolChoice;
 	if (src.builtinTools) config.builtinTools = [...src.builtinTools];
 	if (src.idleTimeoutMs !== void 0) config.idleTimeoutMs = src.idleTimeoutMs;
-	config.mode = assertProviderTriple(src.stt, src.llm, src.tts);
-	if (config.mode === "pipeline") {
+	if (mode === "pipeline") {
 		config.stt = src.stt;
 		config.llm = src.llm;
 		config.tts = src.tts;
 	}
+	if (src.s2s !== void 0) config.s2s = src.s2s;
 	if (src.kv !== void 0) config.kv = src.kv;
 	if (src.vector !== void 0) config.vector = src.vector;
 	return config;
 }
-/**
-* Zod schema for serialized tool definitions sent over the wire.
-*
-* `parameters` must be a valid JSON Schema object (with `type`, `properties`,
-* etc.) — the Vercel AI SDK wraps it via `jsonSchema()`.
-*/
 const ToolSchemaSchema = z.object({
 	type: z.literal("function"),
 	name: z.string().min(1),
 	description: z.string().min(1),
 	parameters: z.record(z.string(), z.unknown())
 });
-/** Empty Zod object schema used as default when tools have no parameters. */
 const EMPTY_PARAMS = z.object({});
-/**
-* Convert agent tool definitions to JSON Schema format for wire transport.
-*
-* Transforms the Zod-based `parameters` of each tool into a plain JSON Schema
-* object suitable for structured clone / JSON serialization.
-*/
 function agentToolsToSchemas(tools) {
 	return Object.entries(tools).map(([name, def]) => ({
 		type: "function",

package/dist/constants-y68COEGj.js

@@ -0,0 +1,29 @@
+//#region sdk/constants.ts
+const DEFAULT_STT_SAMPLE_RATE = 16e3;
+const DEFAULT_TTS_SAMPLE_RATE = 24e3;
+const TOOL_EXECUTION_TIMEOUT_MS = 3e4;
+const DEFAULT_SESSION_START_TIMEOUT_MS = 1e4;
+const DEFAULT_IDLE_TIMEOUT_MS = 3e5;
+const FETCH_TIMEOUT_MS = 15e3;
+const RUN_CODE_TIMEOUT_MS = 5e3;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 3e4;
+/**
+* Short relative to `DEFAULT_SHUTDOWN_TIMEOUT_MS` so a stuck TTS provider
+* can't wedge the session — stop() must still reclaim the socket cleanly.
+*/
+const PIPELINE_FLUSH_TIMEOUT_MS = 1e4;
+const MAX_TOOL_RESULT_CHARS = 4e3;
+const MAX_PAGE_CHARS = 1e4;
+const MAX_HTML_BYTES = 2e5;
+const MAX_VALUE_SIZE = 65536;
+const DEFAULT_MAX_HISTORY = 200;
+const MAX_WS_PAYLOAD_BYTES = 1 * 1024 * 1024;
+const MAX_MESSAGE_BUFFER_SIZE = 100;
+const WS_OPEN = 1;
+/**
+* Single source of truth — used by `secureHeaders` middleware and
+* per-response CSP headers across self-hosted and platform agent UIs.
+*/
+const AGENT_CSP = "default-src 'self'; script-src 'self' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; connect-src 'self' wss: ws:; img-src 'self' data:; font-src 'self' https://fonts.gstatic.com; object-src 'none'; base-uri 'self'";
+//#endregion
+export { TOOL_EXECUTION_TIMEOUT_MS as _, DEFAULT_SHUTDOWN_TIMEOUT_MS as a, FETCH_TIMEOUT_MS as c, MAX_PAGE_CHARS as d, MAX_TOOL_RESULT_CHARS as f, RUN_CODE_TIMEOUT_MS as g, PIPELINE_FLUSH_TIMEOUT_MS as h, DEFAULT_SESSION_START_TIMEOUT_MS as i, MAX_HTML_BYTES as l, MAX_WS_PAYLOAD_BYTES as m, DEFAULT_IDLE_TIMEOUT_MS as n, DEFAULT_STT_SAMPLE_RATE as o, MAX_VALUE_SIZE as p, DEFAULT_MAX_HISTORY as r, DEFAULT_TTS_SAMPLE_RATE as s, AGENT_CSP as t, MAX_MESSAGE_BUFFER_SIZE as u, WS_OPEN as v };

package/dist/host/_base64.d.ts

@@ -0,0 +1,2 @@
+export declare function uint8ToBase64(bytes: Uint8Array): string;
+export declare function base64ToUint8(base64: string): Uint8Array;

package/dist/host/_mock-ws.d.ts

@@ -1,19 +1,3 @@
-/**
- * A mock WebSocket implementation for testing.
- *
- * Extends `EventTarget` to simulate WebSocket behavior without a real
- * network connection. Records all sent messages in the {@link sent}
- * array and provides helper methods to simulate incoming messages,
- * connection events, and errors.
- *
- * @example
- * ```ts
- * const ws = new MockWebSocket("wss://example.com");
- * ws.send(JSON.stringify({ type: "ping" }));
- * ws.simulateMessage(JSON.stringify({ type: "pong" }));
- * assertEquals(ws.sentJson(), [{ type: "ping" }]);
- * ```
- */
 export declare class MockWebSocket extends EventTarget {
     static readonly CONNECTING = 0;
     static readonly OPEN = 1;
@@ -21,18 +5,8 @@ export declare class MockWebSocket extends EventTarget {
     static readonly CLOSED = 3;
     readyState: number;
     binaryType: string;
-    /** All messages passed to {@link send}, in order. */
     sent: (string | ArrayBuffer | Uint8Array)[];
     url: string;
-    /**
-     * Create a new MockWebSocket.
-     *
-     * Automatically transitions to `OPEN` state on the next microtask,
-     * dispatching an `"open"` event.
-     *
-     * @param url - The WebSocket URL.
-     * @param _protocols - Ignored; accepted for API compatibility.
-     */
     constructor(url: string | URL, _protocols?: string | string[] | Record<string, unknown>);
     addEventListener(type: "close" | "open", listener: () => void): void;
     addEventListener(type: "message", listener: (event: {
@@ -45,47 +19,12 @@ export declare class MockWebSocket extends EventTarget {
     addEventListener(type: "error", listener: (event: {
         message?: string;
     }) => void): void;
-    /**
-     * Record a sent message without transmitting it.
-     *
-     * @param data - The message data to record.
-     */
     send(data: string | ArrayBuffer | Uint8Array): void;
-    /**
-     * Transition to `CLOSED` state and dispatch a `"close"` event.
-     *
-     * @param code - The close code (defaults to 1000).
-     * @param _reason - Ignored; accepted for API compatibility.
-     */
     close(code?: number, _reason?: string): void;
-    /**
-     * Simulate receiving a message from the server.
-     *
-     * @param data - The message data (string or binary).
-     */
     simulateMessage(data: string | ArrayBuffer): void;
-    /** Transition to `OPEN` state and dispatch an `"open"` event. */
     open(): void;
-    /**
-     * Shorthand for {@link simulateMessage}.
-     *
-     * @param data - The message data to dispatch.
-     */
     msg(data: string | ArrayBuffer): void;
-    /**
-     * Simulate a connection close from the server.
-     *
-     * @param code - The close code (defaults to 1000).
-     */
     disconnect(code?: number): void;
-    /** Dispatch an `"error"` event on this socket. */
     error(): void;
-    /**
-     * Return all sent string messages parsed as JSON objects.
-     *
-     * Binary messages are filtered out.
-     *
-     * @returns An array of parsed JSON objects from sent string messages.
-     */
     sentJson(): Record<string, unknown>[];
 }

package/dist/host/_pipeline-test-fakes.d.ts

@@ -16,6 +16,7 @@ import type { LanguageModel } from "ai";
 import { type Emitter } from "nanoevents";
 import { vi } from "vitest";
 import type { SttEvents, SttOpener, SttOpenOptions, SttSession, TtsEvents, TtsOpener, TtsOpenOptions, TtsSession } from "../sdk/providers.ts";
+type SttErrorCode = "stt_stream_error" | "stt_connect_failed" | "stt_auth_failed";
 export type FakeSttSession = SttSession & {
     readonly emitter: Emitter<SttEvents>;
     readonly opts: SttOpenOptions;
@@ -25,7 +26,7 @@ export type FakeSttSession = SttSession & {
     };
     firePartial(text: string): void;
     fireFinal(text: string): void;
-    fireError(code: "stt_stream_error" | "stt_connect_failed" | "stt_auth_failed", message: string): void;
+    fireError(code: SttErrorCode, message: string): void;
 };
 export type FakeSttProvider = SttOpener & {
     /** The most recently opened session, or undefined if `open()` hasn't been called. */
@@ -33,6 +34,7 @@ export type FakeSttProvider = SttOpener & {
     readonly sessions: FakeSttSession[];
 };
 export declare function createFakeSttProvider(): FakeSttProvider;
+type TtsErrorCode = "tts_stream_error" | "tts_connect_failed" | "tts_auth_failed";
 export type FakeTtsSession = TtsSession & {
     readonly emitter: Emitter<TtsEvents>;
     readonly opts: TtsOpenOptions;
@@ -44,7 +46,7 @@ export type FakeTtsSession = TtsSession & {
     readonly flush: ReturnType<typeof vi.fn<() => void>>;
     readonly cancel: ReturnType<typeof vi.fn<() => void>>;
     fireAudio(pcm: Int16Array): void;
-    fireError(code: "tts_stream_error" | "tts_connect_failed" | "tts_auth_failed", message: string): void;
+    fireError(code: TtsErrorCode, message: string): void;
 };
 export type FakeTtsProvider = TtsOpener & {
     /** The most recently opened session, or undefined if `open()` hasn't been called. */
@@ -63,12 +65,12 @@ export declare function createFakeTtsProvider(options?: {
  * Fake STT provider that throws on `open()` with a given error code. Used to
  * test atomic provider open — TTS should not be opened at all when STT fails.
  */
-export declare function createFailingSttProvider(code: "stt_connect_failed" | "stt_auth_failed" | "stt_stream_error", message: string): SttOpener;
+export declare function createFailingSttProvider(code: SttErrorCode, message: string): SttOpener;
 /**
  * Fake TTS provider that throws on `open()` with a given error code. Used to
  * test atomic provider open — STT should be closed when TTS fails.
  */
-export declare function createFailingTtsProvider(code: "tts_connect_failed" | "tts_auth_failed" | "tts_stream_error", message: string): TtsOpener;
+export declare function createFailingTtsProvider(code: TtsErrorCode, message: string): TtsOpener;
 /**
  * A scripted stream part. `text` yields a `text-delta` in the LLM provider's
  * raw wire format; `tool-call` / `tool-result` emit the corresponding parts
@@ -117,3 +119,4 @@ export declare function createFakeLanguageModel(options: {
 }): LanguageModel & {
     readonly calls: readonly Record<string, unknown>[];
 };
+export {};

package/dist/host/_run-code.d.ts

@@ -1,36 +1,11 @@
-/**
- * run_code built-in tool — executes user JavaScript in a fresh `node:vm`
- * context with no network, filesystem, or process access.
- */
 import { z } from "zod";
 import type { ToolDef } from "../sdk/types.ts";
 declare const runCodeParams: z.ZodObject<{
     code: z.ZodString;
 }, z.core.$strip>;
-/**
- * Execute JavaScript code inside a fresh `node:vm` context.
- *
- * Each invocation creates a disposable VM context with:
- * - No filesystem access (`node:fs` and other built-ins unavailable)
- * - No network access (`fetch`, `http` unavailable)
- * - No child process spawning
- * - No environment variable access (`process` unavailable)
- * - Execution timeout (default 5 s)
- *
- * The context is discarded after execution, so no state leaks between
- * invocations or across sessions.
- */
 export declare function createRunCode(): ToolDef<typeof runCodeParams> & {
     guidance: string;
 };
-/**
- * Execute user code in a fresh `node:vm` context.
- *
- * @remarks
- * The VM context only exposes standard ECMAScript globals and a console
- * object that captures output. Node.js APIs (`process`, `require`,
- * `import()`) are not available inside the sandbox.
- */
 export declare function executeInIsolate(code: string): Promise<string | {
     error: string;
 }>;

package/dist/host/_runtime-conformance.d.ts

@@ -6,49 +6,18 @@
  * reusable test suite that can be wired to either runtime.
  *
  * Inspired by Nitro's `testNitro()` pattern: one test fixture, many runtimes.
- *
- * @example Direct executor (unit test)
- * ```ts
- * import { testRuntime } from "./_runtime-conformance.ts";
- *
- * testRuntime("direct", () => {
- *   const exec = createRuntime({ agent: CONFORMANCE_AGENT, env: { MY_VAR: "test-value" } });
- *   return { executeTool: exec.executeTool, hooks: exec.hooks };
- * });
- * ```
- *
- * @example Sandbox (integration test in aai-server)
- * ```ts
- * // Internal module — import the .ts source directly from this package.
- * import { testRuntime } from "../../aai/host/_runtime-conformance.ts";
- *
- * testRuntime("sandbox", async () => {
- *   // ... start isolate with a bundled agent
- *   return { executeTool: buildExecuteTool(...), hooks: buildHookInvoker(...) };
- * });
- * ```
  */
 import type { ExecuteTool } from "../sdk/_internal-types.ts";
 import type { AgentDef } from "../sdk/types.ts";
-/**
- * Minimal runtime surface needed for conformance tests.
- *
- * Both `Runtime` and `buildExecuteTool`/`buildHookInvoker` from the
- * sandbox produce objects that satisfy this interface.
- */
 export type RuntimeTestContext = {
     executeTool: ExecuteTool;
 };
-/** Agent definition used by the conformance suite (direct executor path). */
 export declare const CONFORMANCE_AGENT: AgentDef;
 /**
  * Run the runtime conformance test suite against a given runtime context.
  *
- * The `getContext` callback is invoked once per test to retrieve the
- * current {@link RuntimeTestContext}. This allows the caller to set up
- * the runtime in a `beforeAll` and return it lazily.
- *
- * All tests assume the runtime was created with {@link CONFORMANCE_AGENT}
- * (or its bundle equivalent) and `env: { MY_VAR: "test-value" }`.
+ * `getContext` is invoked once per test so callers can lazily set up the
+ * runtime in a `beforeAll`. All tests assume the runtime was created with
+ * {@link CONFORMANCE_AGENT} and `env: { MY_VAR: "test-value" }`.
  */
 export declare function testRuntime(label: string, getContext: () => RuntimeTestContext): void;

package/dist/host/memory-vector.d.ts

@@ -1,17 +1,6 @@
-/**
- * In-memory Vector implementation.
- *
- * INTENTIONALLY BAD QUALITY. Pseudo-embedding hashes the text into a
- * 64-dim Float32Array of values in [-1, ~0.99], then L2-normalizes
- * the result. Because both stored and probe vectors are unit-length,
- * cosine similarity reduces to a plain dot product — that's what
- * `cosine()` computes. Used only for `aai dev` and tests — the goal
- * is proving tool wiring, not retrieval ranking.
- */
 import type { Vector } from "../sdk/vector.ts";
 export type MemoryVectorOptions = {
     namespace: string;
 };
 export declare function createMemoryVector(opts: MemoryVectorOptions): Vector;
-/** Test-only: clear all in-memory state. Not exported from the package. */
 export declare function _resetMemoryVectorForTests(): void;

package/dist/host/providers/resolve-kv.d.ts

@@ -1,10 +1,3 @@
-/**
- * Descriptor → concrete `Kv` resolver. Mirror of `resolveLlm` /
- * `resolveVector`. Always wraps the produced unstorage Storage in
- * `createUnstorageKv` with the provided per-tenant prefix so namespace
- * isolation is enforced regardless of backend choice.
- */
 import type { Kv } from "../../sdk/kv.ts";
 import type { KvProvider } from "../../sdk/providers.ts";
-/** Resolve a {@link KvProvider} descriptor into a {@link Kv}. */
 export declare function resolveKv(descriptor: KvProvider, env: Record<string, string>, prefix: string): Kv;

package/dist/host/providers/resolve-vector.d.ts

@@ -1,11 +1,3 @@
-/**
- * Descriptor → concrete `Vector` resolver. Mirror of `resolveLlm`.
- *
- * Pulls API keys from the agent env so descriptors stay
- * secret-free. Lazy-loads provider SDKs via `createRequire` so
- * unused providers never enter the bundle.
- */
 import type { VectorProvider } from "../../sdk/providers.ts";
 import type { Vector } from "../../sdk/vector.ts";
-/** Resolve a {@link VectorProvider} descriptor into a {@link Vector}. */
 export declare function resolveVector(descriptor: VectorProvider, env: Record<string, string>, namespace: string): Vector;

package/dist/host/providers/stt/assemblyai.d.ts

@@ -1,22 +1,8 @@
-/**
- * AssemblyAI Universal-Streaming STT opener (host-only).
- *
- * The user-facing descriptor factory (`assemblyAI(...)`) lives in
- * `sdk/providers/stt/assemblyai.ts`. This module is the host-side
- * counterpart: it takes the descriptor options + an API key and
- * returns an {@link SttOpener} that the pipeline session drives.
- *
- * Default model: `"u3pro-rt"` (Universal-3 Pro Real-Time). The adapter
- * maps that to the SDK's `"u3-rt-pro"` `speechModel` value; any other
- * string is forwarded verbatim.
- */
 import { type StreamingTranscriber } from "assemblyai";
 import type { AssemblyAIOptions } from "../../../sdk/providers/stt/assemblyai.ts";
 import { type SttOpener, type SttSession } from "../../../sdk/providers.ts";
-/** Internal: SttSession with a test-only handle to the raw SDK transcriber. */
 export interface AssemblyAISession extends SttSession {
     /** @internal Test-only: exposes the underlying SDK transcriber for fixture replay. */
     readonly _transcriber: StreamingTranscriber;
 }
-/** Build an {@link SttOpener} from resolved AssemblyAI descriptor options. */
 export declare function openAssemblyAI(opts?: AssemblyAIOptions): SttOpener;

package/dist/host/providers/stt/deepgram.d.ts

@@ -1,28 +1,16 @@
 /**
  * Deepgram Nova streaming STT opener (host-only).
  *
- * The user-facing descriptor factory (`deepgram(...)`) lives in
- * `sdk/providers/stt/deepgram.ts`. This module is the host-side
- * counterpart: it takes the descriptor options + an API key and
- * returns an {@link SttOpener} that the pipeline session drives.
- *
- * Default model: `"nova-3"`. Any string is forwarded verbatim to the SDK.
- *
- * This adapter targets the Deepgram SDK v5 (`@deepgram/sdk@^5`). The v5
- * streaming API is:
- *   `client.listen.v1.connect(args)` → `Promise<V1Socket>`
- * followed by:
- *   `socket.connect()` + `socket.waitForOpen()` to establish the connection.
+ * Targets Deepgram SDK v5: `client.listen.v1.connect(args)` returns a
+ * socket; `socket.connect()` + `socket.waitForOpen()` establish it.
  */
 import { DeepgramClient } from "@deepgram/sdk";
 import type { DeepgramOptions } from "../../../sdk/providers/stt/deepgram.ts";
 import { type SttOpener, type SttSession } from "../../../sdk/providers.ts";
 type V1Socket = Awaited<ReturnType<InstanceType<typeof DeepgramClient>["listen"]["v1"]["connect"]>>;
-/** Internal: SttSession with a test-only handle to the raw SDK socket. */
 export interface DeepgramSession extends SttSession {
     /** @internal Test-only: exposes the underlying SDK socket for fixture replay. */
     readonly _connection: V1Socket;
 }
-/** Build an {@link SttOpener} from resolved Deepgram descriptor options. */
 export declare function openDeepgram(opts?: DeepgramOptions): SttOpener;
 export {};

package/dist/host/providers/stt/soniox.d.ts

@@ -1,25 +1,3 @@
-/**
- * Soniox real-time STT opener (host-only).
- *
- * The user-facing descriptor factory (`soniox(...)`) lives in
- * `sdk/providers/stt/soniox.ts`. This module is the host-side
- * counterpart: it takes the descriptor options + an API key and
- * returns an {@link SttOpener} that the pipeline session drives.
- *
- * Soniox's published JS client (`@soniox/speech-to-text-web`) is
- * browser-only — it depends on `MediaRecorder` and `getUserMedia`. For
- * server-side use we talk to the WebSocket directly:
- *   `wss://stt-rt.soniox.com/transcribe-websocket`
- *
- * Wire format:
- *   - First text frame: JSON config with api_key, model, audio_format,
- *     sample_rate, num_channels (and optional language hints).
- *   - Subsequent binary frames: 16-bit signed little-endian PCM audio.
- *   - Server replies: JSON `{ tokens: [{ text, is_final }] }` messages.
- *     Final tokens accumulate; non-final tokens are a rolling preview.
- *   - On error: `{ error_code, error_message }`.
- */
 import type { SonioxOptions } from "../../../sdk/providers/stt/soniox.ts";
 import { type SttOpener } from "../../../sdk/providers.ts";
-/** Build an {@link SttOpener} from resolved Soniox descriptor options. */
 export declare function openSoniox(opts?: SonioxOptions): SttOpener;

package/dist/host/providers/tts/rime.d.ts

@@ -1,44 +1,23 @@
 /**
  * Rime TTS opener (host-only).
  *
- * The user-facing descriptor factory (`rime(...)`) lives in
- * `sdk/providers/tts/rime.ts`. This module is the host-side
- * counterpart: it takes the descriptor options + an API key and
- * returns a {@link TtsOpener} that the pipeline session drives.
+ * Connects to Rime's `ws2` JSON WebSocket endpoint with one long-lived
+ * connection per session. Client → server: `{ text }` appends to the
+ * synthesis buffer, `{ operation: "clear" }` drops it (barge-in). We never
+ * send `eos` since it tears down the WS — `flush()` instead sends a
+ * trailing `"."` to force synthesis of any text buffered behind missing
+ * terminal punctuation while keeping the connection reusable.
  *
- * **Protocol.** Connects to Rime's `ws2` JSON WebSocket endpoint
- * (`wss://users-ws.rime.ai/ws2`). Client-to-server messages are JSON:
- *   - `{ "text": "..." }` — append text to the synthesis buffer
- *   - `{ "operation": "clear" }` — drop buffered text (barge-in)
- *   - `{ "operation": "eos" }` — drain buffer, close connection (NOT used
- *     during a session: it would tear down the WS, forcing reconnect per
- *     turn). We force end-of-turn synthesis with a trailing `"."` instead.
- * The server responds with JSON frames:
- *   - `{ type: "chunk", data: <base64 PCM16 LE>, contextId: string | null }`
- *   - `{ type: "timestamps", ... }` (ignored)
- *   - `{ type: "error", message: string }` (surfaced as `tts_stream_error`)
- *
- * **Single long-lived connection per session.** Rime buffers text until it
- * sees terminal punctuation (`.`, `?`, `!`), so we use one WebSocket per
- * `open()` call and reuse it across turns. `clear` resets the buffer
- * between cancellations.
- *
- * **Done detection.** After `flush()` sends a trailing `"."` to force the
- * server to synthesize any half-buffered text, we arm a quiescence timer
- * that fires 500 ms after the last received audio chunk. When it fires,
- * `done` is emitted.
- *
- * **Audio format.** The URL requests `audioFormat=pcm` at the negotiated
- * `sampleRate`, which returns raw PCM16 little-endian. We decode the base64
- * payload and construct a zero-copy `Int16Array` view over the decoded bytes.
+ * Server → client: `{ type: "chunk", data: <base64 PCM16 LE> }` carries
+ * audio; `timestamps` is ignored; `error` surfaces as `tts_stream_error`.
+ * The `audioFormat=pcm` query param at the negotiated `sampleRate` returns
+ * raw PCM16 LE that we view as a zero-copy `Int16Array`.
  */
 import WebSocket from "ws";
 import { type RimeOptions } from "../../../sdk/providers/tts/rime.ts";
 import { type TtsOpener, type TtsSession } from "../../../sdk/providers.ts";
-/** Internal: TtsSession with a test-only handle to the raw WebSocket. */
 export interface RimeSession extends TtsSession {
     /** @internal Test-only: exposes the underlying raw WebSocket. */
     readonly _ws: WebSocket;
 }
-/** Build a {@link TtsOpener} from resolved Rime descriptor options. */
 export declare function openRime(opts: RimeOptions): TtsOpener;