@alexkroman1/aai 1.3.1 → 1.4.0

package/.turbo/turbo-build.log

@@ -1,22 +1,26 @@
 
-> @alexkroman1/aai@1.3.1 build /home/runner/work/agent/agent/packages/aai
+> @alexkroman1/aai@1.4.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, host/providers/stt-barrel.ts, host/providers/tts-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
 ℹ target: node22
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ dist/host/runtime-barrel.js        63.51 kB │ gzip: 19.17 kB
-ℹ dist/index.js                       6.67 kB │ gzip:  2.65 kB
-ℹ dist/host/providers/tts-barrel.js   5.52 kB │ gzip:  2.12 kB
-ℹ dist/sdk/protocol.js                4.75 kB │ gzip:  1.76 kB
-ℹ dist/host/providers/stt-barrel.js   3.08 kB │ gzip:  1.26 kB
-ℹ dist/sdk/manifest-barrel.js         0.26 kB │ gzip:  0.17 kB
-ℹ dist/constants-BL3nvg4I.js          3.10 kB │ gzip:  1.38 kB
-ℹ dist/_internal-types-CoDTiBd1.js    2.33 kB │ gzip:  0.99 kB
-ℹ dist/types-Cfx_4QDK.js              1.74 kB │ gzip:  0.93 kB
-ℹ dist/ws-upgrade-BeOQ7fXL.js         1.14 kB │ gzip:  0.54 kB
-ℹ 10 files, total: 92.10 kB
-✔ Build complete in 43ms
+ℹ dist/host/runtime-barrel.js       74.18 kB │ gzip: 22.09 kB
+ℹ dist/sdk/protocol.js               4.75 kB │ gzip:  1.76 kB
+ℹ dist/index.js                      2.88 kB │ gzip:  1.24 kB
+ℹ dist/sdk/manifest-barrel.js        0.36 kB │ gzip:  0.20 kB
+ℹ dist/sdk/providers/stt-barrel.js   0.13 kB │ gzip:  0.11 kB
+ℹ dist/sdk/providers/llm-barrel.js   0.12 kB │ gzip:  0.11 kB
+ℹ dist/sdk/providers/tts-barrel.js   0.12 kB │ gzip:  0.10 kB
+ℹ dist/types-KUgezM6u.js             5.64 kB │ gzip:  2.39 kB
+ℹ dist/_internal-types-3p3OJZPb.js   5.61 kB │ gzip:  2.07 kB
+ℹ dist/constants-C2nirZUI.js         3.10 kB │ gzip:  1.38 kB
+ℹ dist/ws-upgrade-BeOQ7fXL.js        1.14 kB │ gzip:  0.54 kB
+ℹ dist/assemblyai-Cxg9eobY.js        0.53 kB │ gzip:  0.35 kB
+ℹ dist/anthropic-BrUCPKUc.js         0.23 kB │ gzip:  0.18 kB
+ℹ dist/cartesia-DwDk2tEu.js          0.22 kB │ gzip:  0.17 kB
+ℹ 14 files, total: 99.00 kB
+✔ Build complete in 39ms

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @alexkroman1/aai
 
+## 1.4.0
+
+## 1.3.2
+
 ## 1.3.1
 
 ### Patch Changes

package/dist/_internal-types-3p3OJZPb.js

@@ -0,0 +1,145 @@
+import { i as ToolChoiceSchema, o as validateAllowedHostPattern, t as BuiltinToolSchema } from "./types-KUgezM6u.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.
+*/
+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";
+}
+/** Build an {@link SttError} with a typed `code`. Zero-dep helper so both sdk/ and host/ can use it. */
+function makeSttError(code, message) {
+	return Object.assign(new Error(message), { code });
+}
+/** Build a {@link TtsError} with a typed `code`. Mirror of {@link makeSttError}. */
+function makeTtsError(code, message) {
+	return Object.assign(new Error(message), { code });
+}
+//#endregion
+//#region sdk/manifest.ts
+/**
+* Canonical manifest format for directory-based agents.
+*
+* Flows from build → host → sdk. Validated via Zod at the boundary,
+* then used as a plain typed object throughout the runtime.
+*/
+const ToolManifestSchema = z.object({
+	description: z.string(),
+	parameters: z.record(z.string(), z.unknown()).optional()
+});
+/**
+* Provider descriptor — a `{ kind, options }` pair produced by factories
+* like `assemblyAI(...)` / `anthropic(...)` / `cartesia(...)`. Kept
+* deliberately generic at the schema layer: kind-specific validation lives
+* in the host-side resolver, which knows what each adapter expects.
+*/
+const ProviderDescriptorSchema = z.object({
+	kind: z.string().min(1),
+	options: z.record(z.string(), z.unknown())
+});
+z.object({
+	name: z.string().min(1),
+	systemPrompt: z.string().optional(),
+	greeting: z.string().optional(),
+	sttPrompt: z.string().optional(),
+	builtinTools: z.array(BuiltinToolSchema).optional(),
+	maxSteps: z.number().int().positive().optional(),
+	toolChoice: z.enum(["auto", "required"]).optional(),
+	idleTimeoutMs: z.number().int().positive().optional(),
+	theme: z.record(z.string(), z.string()).optional(),
+	tools: z.record(z.string(), ToolManifestSchema).optional(),
+	allowedHosts: z.array(z.string()).optional().superRefine((hosts, ctx) => {
+		if (!hosts) return;
+		for (const h of hosts) {
+			const result = validateAllowedHostPattern(h);
+			if (!result.valid) ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: `Invalid allowedHosts pattern "${h}": ${result.reason}`
+			});
+		}
+	}),
+	stt: ProviderDescriptorSchema.optional(),
+	llm: ProviderDescriptorSchema.optional(),
+	tts: 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(),
+	greeting: z.string(),
+	sttPrompt: z.string().optional(),
+	maxSteps: z.number().int().positive().optional(),
+	toolChoice: ToolChoiceSchema.optional(),
+	builtinTools: z.array(BuiltinToolSchema).readonly().optional(),
+	idleTimeoutMs: z.number().nonnegative().optional(),
+	stt: ProviderDescriptorSchema.optional(),
+	llm: ProviderDescriptorSchema.optional(),
+	tts: ProviderDescriptorSchema.optional(),
+	mode: z.enum(["s2s", "pipeline"]).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 config = {
+		name: src.name,
+		systemPrompt: src.systemPrompt,
+		greeting: src.greeting
+	};
+	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") {
+		config.stt = src.stt;
+		config.llm = src.llm;
+		config.tts = src.tts;
+	}
+	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({
+	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]) => ({
+		name,
+		description: def.description,
+		parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS)
+	}));
+}
+//#endregion
+export { toAgentConfig as a, makeSttError as c, agentToolsToSchemas as i, makeTtsError as l, EMPTY_PARAMS as n, ProviderDescriptorSchema as o, ToolSchemaSchema as r, assertProviderTriple as s, AgentConfigSchema as t };

package/dist/anthropic-BrUCPKUc.js

@@ -0,0 +1,10 @@
+//#region sdk/providers/llm/anthropic.ts
+const ANTHROPIC_KIND = "anthropic";
+function anthropic(opts) {
+	return {
+		kind: ANTHROPIC_KIND,
+		options: { ...opts }
+	};
+}
+//#endregion
+export { anthropic as n, ANTHROPIC_KIND as t };

package/dist/assemblyai-Cxg9eobY.js

@@ -0,0 +1,18 @@
+//#region sdk/providers/stt/assemblyai.ts
+/** Kind tag recognised by the host-side resolver. */
+const ASSEMBLYAI_KIND = "assemblyai";
+/**
+* Build an AssemblyAI STT descriptor.
+*
+* The API key is resolved host-side from the agent's env
+* (`ASSEMBLYAI_API_KEY`); there is no factory-time key parameter, so the
+* descriptor stays free of secrets and safe to serialize.
+*/
+function assemblyAI(opts = {}) {
+	return {
+		kind: ASSEMBLYAI_KIND,
+		options: { ...opts }
+	};
+}
+//#endregion
+export { assemblyAI as n, ASSEMBLYAI_KIND as t };

package/dist/cartesia-DwDk2tEu.js

@@ -0,0 +1,10 @@
+//#region sdk/providers/tts/cartesia.ts
+const CARTESIA_KIND = "cartesia";
+function cartesia(opts) {
+	return {
+		kind: CARTESIA_KIND,
+		options: { ...opts }
+	};
+}
+//#endregion
+export { cartesia as n, CARTESIA_KIND as t };

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

@@ -15,7 +15,7 @@
 import type { LanguageModel } from "ai";
 import { type Emitter } from "nanoevents";
 import { vi } from "vitest";
-import type { SttEvents, SttOpenOptions, SttProvider, SttSession, TtsEvents, TtsOpenOptions, TtsProvider, TtsSession } from "../sdk/providers.ts";
+import type { SttEvents, SttOpener, SttOpenOptions, SttSession, TtsEvents, TtsOpener, TtsOpenOptions, TtsSession } from "../sdk/providers.ts";
 export type FakeSttSession = SttSession & {
     readonly emitter: Emitter<SttEvents>;
     readonly opts: SttOpenOptions;
@@ -27,7 +27,7 @@ export type FakeSttSession = SttSession & {
     fireFinal(text: string): void;
     fireError(code: "stt_stream_error" | "stt_connect_failed" | "stt_auth_failed", message: string): void;
 };
-export type FakeSttProvider = SttProvider & {
+export type FakeSttProvider = SttOpener & {
     /** The most recently opened session, or undefined if `open()` hasn't been called. */
     last(): FakeSttSession | undefined;
     readonly sessions: FakeSttSession[];
@@ -46,7 +46,7 @@ export type FakeTtsSession = TtsSession & {
     fireAudio(pcm: Int16Array): void;
     fireError(code: "tts_stream_error" | "tts_connect_failed" | "tts_auth_failed", message: string): void;
 };
-export type FakeTtsProvider = TtsProvider & {
+export type FakeTtsProvider = TtsOpener & {
     /** The most recently opened session, or undefined if `open()` hasn't been called. */
     last(): FakeTtsSession | undefined;
     readonly sessions: FakeTtsSession[];
@@ -63,12 +63,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): SttProvider;
+export declare function createFailingSttProvider(code: "stt_connect_failed" | "stt_auth_failed" | "stt_stream_error", 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): TtsProvider;
+export declare function createFailingTtsProvider(code: "tts_connect_failed" | "tts_auth_failed" | "tts_stream_error", 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

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

@@ -8,7 +8,7 @@
 import type { LanguageModel } from "ai";
 import type { AgentConfig, ExecuteTool, ToolSchema } from "../sdk/_internal-types.ts";
 import type { ClientSink } from "../sdk/protocol.ts";
-import type { SttProvider, TtsProvider } from "../sdk/providers.ts";
+import type { SttOpener, TtsOpener } from "../sdk/providers.ts";
 import { type Logger } from "./runtime-config.ts";
 import type { Session } from "./session.ts";
 /** Configuration options for {@link createPipelineSession}. */
@@ -27,12 +27,12 @@ export interface PipelineSessionOptions {
     toolGuidance?: readonly string[] | undefined;
     /** Function to invoke tools by name. */
     executeTool: ExecuteTool;
-    /** STT provider (injected via manifest in pipeline mode). */
-    stt: SttProvider;
+    /** STT opener (resolved from an {@link SttProvider} descriptor). */
+    stt: SttOpener;
     /** LLM provider (Vercel AI SDK `LanguageModel`). */
     llm: LanguageModel;
-    /** TTS provider (injected via manifest in pipeline mode). */
-    tts: TtsProvider;
+    /** TTS opener (resolved from a {@link TtsProvider} descriptor). */
+    tts: TtsOpener;
     /** STT API key. */
     sttApiKey: string;
     /** TTS API key. */

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

@@ -0,0 +1,34 @@
+/**
+ * Descriptor → concrete-provider resolution (host-only).
+ *
+ * User code (and the server, after extracting config from a bundled agent)
+ * holds `SttProvider` / `LlmProvider` / `TtsProvider` **descriptors** —
+ * plain `{ kind, options }` data. At session start the runtime calls the
+ * resolvers here to turn each descriptor into its openable / callable
+ * host-side counterpart, importing the third-party SDK only at that point.
+ *
+ * The guest sandbox never imports these functions, which is how the agent
+ * bundle stays free of `@ai-sdk/anthropic` / `assemblyai` /
+ * `@cartesia/cartesia-js`.
+ */
+import type { LanguageModel } from "ai";
+import type { LlmProvider, SttOpener, SttProvider, TtsOpener, TtsProvider } from "../../sdk/providers.ts";
+/**
+ * Look up a provider API key: agent env first (set via `aai secret put` or
+ * `.env`), then the host's `process.env` as a fallback for self-hosted mode.
+ * Returns `""` if neither has it — the caller decides whether that's fatal.
+ */
+export declare function resolveApiKey(envVar: string, env: Record<string, string>): string;
+/** Resolve an {@link SttProvider} descriptor into a host-side opener. */
+export declare function resolveStt(descriptor: SttProvider): SttOpener;
+/** Resolve a {@link TtsProvider} descriptor into a host-side opener. */
+export declare function resolveTts(descriptor: TtsProvider): TtsOpener;
+/**
+ * Resolve an {@link LlmProvider} descriptor into a Vercel AI SDK
+ * {@link LanguageModel}.
+ *
+ * The API key is pulled from the agent's env (e.g. `ANTHROPIC_API_KEY`).
+ * Missing keys throw here — the pipeline session would fail on first
+ * `streamText` call otherwise, and the error is clearer at construction.
+ */
+export declare function resolveLlm(descriptor: LlmProvider, env: Record<string, string>): LanguageModel;

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

@@ -1,31 +1,22 @@
 /**
- * AssemblyAI Universal-Streaming STT adapter.
+ * AssemblyAI Universal-Streaming STT opener (host-only).
  *
- * Wraps the `assemblyai` Node SDK's {@link StreamingTranscriber} and
- * normalizes its event surface onto the {@link SttProvider} /
- * {@link SttEvents} contract consumed by the pipeline orchestrator.
+ * 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 { SttProvider, SttSession } from "../../../sdk/providers.ts";
-export interface AssemblyAIOptions {
-    /**
-     * Streaming speech model. Defaults to `"u3pro-rt"` (Universal-3 Pro
-     * Real-Time). Arbitrary strings are forwarded to the SDK unchanged.
-     */
-    model?: "u3pro-rt" | string;
-    /**
-     * AssemblyAI API key. Falls back to `SttOpenOptions.apiKey`, then
-     * `process.env.ASSEMBLYAI_API_KEY`.
-     */
-    apiKey?: string;
-}
+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;
 }
-export declare function assemblyAI(opts?: AssemblyAIOptions): SttProvider;
+/** Build an {@link SttOpener} from resolved AssemblyAI descriptor options. */
+export declare function openAssemblyAI(opts?: AssemblyAIOptions): SttOpener;

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

@@ -1,9 +1,13 @@
 /**
- * Cartesia TTS adapter — streaming WebSocket with per-turn `context_id`.
+ * Cartesia TTS opener (host-only).
+ *
+ * The user-facing descriptor factory (`cartesia(...)`) lives in
+ * `sdk/providers/tts/cartesia.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.
  *
  * Wraps `@cartesia/cartesia-js`'s `TTSWS` / `TTSWSContext` and normalizes it
- * onto the {@link TtsProvider} / {@link TtsEvents} contract consumed by the
- * pipeline orchestrator.
+ * onto the {@link TtsEvents} contract consumed by the pipeline orchestrator.
  *
  * **Per-turn context lifecycle.** Each `sendText(...)` within the same turn
  * appends to the same Cartesia context. On `flush()` or `cancel()`, a new
@@ -15,20 +19,8 @@
  * conversion.
  */
 import type { TTSWS } from "@cartesia/cartesia-js/resources/tts";
-import type { TtsProvider, TtsSession } from "../../../sdk/providers.ts";
-export interface CartesiaOptions {
-    /** Cartesia voice ID. Required. */
-    voice: string;
-    /** Model ID. Defaults to `"sonic-2"`. */
-    model?: string;
-    /**
-     * Cartesia API key. Falls back to `TtsOpenOptions.apiKey`, then
-     * `process.env.CARTESIA_API_KEY`.
-     */
-    apiKey?: string;
-    /** Spoken language hint. Defaults to `"en"`. */
-    language?: string;
-}
+import type { CartesiaOptions } from "../../../sdk/providers/tts/cartesia.ts";
+import { type TtsOpener, type TtsSession } from "../../../sdk/providers.ts";
 /** Internal: TtsSession with a test-only handle to the raw SDK socket. */
 export interface CartesiaSession extends TtsSession {
     /** @internal Test-only: exposes the underlying SDK WebSocket wrapper. */
@@ -36,4 +28,5 @@ export interface CartesiaSession extends TtsSession {
     /** @internal Test-only: id of the currently-active context. */
     readonly _currentContextId: () => string;
 }
-export declare function cartesia(opts: CartesiaOptions): TtsProvider;
+/** Build a {@link TtsOpener} from resolved Cartesia descriptor options. */
+export declare function openCartesia(opts: CartesiaOptions): TtsOpener;