@alexkroman1/aai 1.5.0 → 1.6.0

package/host/transports/s2s-transport.test.ts

@@ -1,5 +1,7 @@
-import { describe, expect, test, vi } from "vitest";
-import { createS2sTransport } from "./s2s-transport.ts";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { makeMockHandle, silentLogger } from "../_test-utils.ts";
+import type { S2sCallbacks, S2sHandle } from "../s2s.ts";
+import { _internals, createS2sTransport } from "./s2s-transport.ts";
 import type { TransportCallbacks } from "./types.ts";
 
 function makeCallbacks(): TransportCallbacks {
@@ -15,6 +17,7 @@ function makeCallbacks(): TransportCallbacks {
     onError: vi.fn(),
     onSpeechStarted: vi.fn(),
     onSpeechStopped: vi.fn(),
+    onSessionReady: vi.fn(),
   };
 }
 
@@ -54,3 +57,220 @@ describe("S2sTransport", () => {
     expect(close).toHaveBeenCalled();
   });
 });
+
+// ─── Reconnect tests ────────────────────────────────────────────────────────
+
+/** Capture the S2sCallbacks that the transport hands to connectS2s. */
+function setupSpiedTransport(): {
+  callbacks: TransportCallbacks;
+  handles: S2sHandle[];
+  capturedCallbacks: S2sCallbacks[];
+  spy: ReturnType<typeof vi.spyOn>;
+} {
+  const handles: S2sHandle[] = [];
+  const capturedCallbacks: S2sCallbacks[] = [];
+  const spy = vi
+    .spyOn(_internals, "connectS2s")
+    .mockImplementation(async (opts: import("../s2s.ts").ConnectS2sOptions) => {
+      capturedCallbacks.push(opts.callbacks);
+      const h = makeMockHandle();
+      handles.push(h);
+      return h;
+    });
+  return {
+    callbacks: makeCallbacks(),
+    handles,
+    capturedCallbacks,
+    spy,
+  };
+}
+
+describe("S2sTransport reconnect", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("attempts session.resume on transient close (1005) inside the resume window", async () => {
+    const { callbacks, handles, capturedCallbacks } = setupSpiedTransport();
+
+    const t = createS2sTransport({
+      apiKey: "k",
+      s2sConfig: { wssUrl: "wss://fake", inputSampleRate: 16_000, outputSampleRate: 24_000 },
+      sessionConfig: { systemPrompt: "test", tools: [] },
+      toolSchemas: [],
+      callbacks,
+      sid: "sid-1",
+      agent: "a",
+      logger: silentLogger,
+    });
+    await t.start();
+
+    // Establish session, start a reply, then drop the socket.
+    const cb1 = capturedCallbacks[0];
+    if (!cb1) throw new Error("expected first callbacks");
+    cb1.onSessionReady("sess_abc");
+    cb1.onReplyStarted("rep_1");
+    cb1.onClose(1005, "");
+
+    // Wait for the async resume() to fire connectS2s a second time.
+    await vi.waitFor(() => {
+      expect(handles.length).toBe(2);
+    });
+
+    // The new handle should have received resumeSession with the prior id.
+    const newHandle = handles[1];
+    if (!newHandle) throw new Error("expected new handle");
+    expect(newHandle.resumeSession).toHaveBeenCalledWith("sess_abc");
+
+    // The in-flight reply was unblocked via onCancelled, NOT a fatal error.
+    expect(callbacks.onCancelled).toHaveBeenCalledOnce();
+    expect(callbacks.onError).not.toHaveBeenCalled();
+  });
+
+  test("does NOT reconnect on fatal close codes (1008 unauthorized)", async () => {
+    const { callbacks, handles, capturedCallbacks } = setupSpiedTransport();
+
+    const t = createS2sTransport({
+      apiKey: "k",
+      s2sConfig: { wssUrl: "wss://fake", inputSampleRate: 16_000, outputSampleRate: 24_000 },
+      sessionConfig: { systemPrompt: "test", tools: [] },
+      toolSchemas: [],
+      callbacks,
+      sid: "sid-1",
+      agent: "a",
+      logger: silentLogger,
+    });
+    await t.start();
+
+    const cb1 = capturedCallbacks[0];
+    if (!cb1) throw new Error("expected first callbacks");
+    cb1.onSessionReady("sess_abc");
+    cb1.onReplyStarted("rep_1");
+    cb1.onClose(1008, "unauthorized");
+
+    // No reconnect — only one connectS2s call total.
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(handles.length).toBe(1);
+    // Fatal error surfaces, since a reply was in flight.
+    expect(callbacks.onError).toHaveBeenCalledWith(
+      "connection",
+      expect.stringContaining("S2S closed mid-reply"),
+    );
+  });
+
+  test("does NOT reconnect when stop() was called", async () => {
+    const { callbacks, handles, capturedCallbacks } = setupSpiedTransport();
+
+    const t = createS2sTransport({
+      apiKey: "k",
+      s2sConfig: { wssUrl: "wss://fake", inputSampleRate: 16_000, outputSampleRate: 24_000 },
+      sessionConfig: { systemPrompt: "test", tools: [] },
+      toolSchemas: [],
+      callbacks,
+      sid: "sid-1",
+      agent: "a",
+      logger: silentLogger,
+    });
+    await t.start();
+
+    const cb1 = capturedCallbacks[0];
+    if (!cb1) throw new Error("expected first callbacks");
+    cb1.onSessionReady("sess_abc");
+    await t.stop();
+
+    // Simulate the upstream's close arriving after stop() — it should be
+    // treated as a clean shutdown, not a transient drop worth resuming.
+    cb1.onClose(1005, "");
+
+    await new Promise((resolve) => setTimeout(resolve, 5));
+    expect(handles.length).toBe(1);
+    expect(callbacks.onError).not.toHaveBeenCalled();
+  });
+
+  test("surfaces resume failure when the resumed socket also closes", async () => {
+    const { callbacks, handles, capturedCallbacks } = setupSpiedTransport();
+
+    const t = createS2sTransport({
+      apiKey: "k",
+      s2sConfig: { wssUrl: "wss://fake", inputSampleRate: 16_000, outputSampleRate: 24_000 },
+      sessionConfig: { systemPrompt: "test", tools: [] },
+      toolSchemas: [],
+      callbacks,
+      sid: "sid-1",
+      agent: "a",
+      logger: silentLogger,
+    });
+    await t.start();
+
+    capturedCallbacks[0]?.onSessionReady("sess_abc");
+    capturedCallbacks[0]?.onReplyStarted("rep_1");
+    capturedCallbacks[0]?.onClose(1005, "");
+
+    await vi.waitFor(() => expect(handles.length).toBe(2));
+
+    // The resume socket also drops before its session.ready arrives.
+    const cb2 = capturedCallbacks[1];
+    if (!cb2) throw new Error("expected resume callbacks");
+    cb2.onClose(1006, "");
+
+    expect(callbacks.onError).toHaveBeenCalledWith(
+      "connection",
+      expect.stringContaining("resume failed"),
+    );
+  });
+
+  test("surfaces resume failure when server reports session_not_found", async () => {
+    const { callbacks, handles, capturedCallbacks } = setupSpiedTransport();
+
+    const t = createS2sTransport({
+      apiKey: "k",
+      s2sConfig: { wssUrl: "wss://fake", inputSampleRate: 16_000, outputSampleRate: 24_000 },
+      sessionConfig: { systemPrompt: "test", tools: [] },
+      toolSchemas: [],
+      callbacks,
+      sid: "sid-1",
+      agent: "a",
+      logger: silentLogger,
+    });
+    await t.start();
+
+    capturedCallbacks[0]?.onSessionReady("sess_abc");
+    capturedCallbacks[0]?.onClose(1005, "");
+
+    await vi.waitFor(() => expect(handles.length).toBe(2));
+
+    capturedCallbacks[1]?.onSessionExpired();
+
+    expect(callbacks.onError).toHaveBeenCalledWith(
+      "connection",
+      expect.stringContaining("session expired"),
+    );
+  });
+
+  test("after a successful resume, a later transient drop also resumes", async () => {
+    const { callbacks, handles, capturedCallbacks } = setupSpiedTransport();
+
+    const t = createS2sTransport({
+      apiKey: "k",
+      s2sConfig: { wssUrl: "wss://fake", inputSampleRate: 16_000, outputSampleRate: 24_000 },
+      sessionConfig: { systemPrompt: "test", tools: [] },
+      toolSchemas: [],
+      callbacks,
+      sid: "sid-1",
+      agent: "a",
+      logger: silentLogger,
+    });
+    await t.start();
+
+    // First connection establishes, drops, resumes, becomes ready again.
+    capturedCallbacks[0]?.onSessionReady("sess_abc");
+    capturedCallbacks[0]?.onClose(1005, "");
+    await vi.waitFor(() => expect(handles.length).toBe(2));
+    capturedCallbacks[1]?.onSessionReady("sess_abc");
+
+    // Second drop — should trigger another resume attempt.
+    capturedCallbacks[1]?.onClose(1006, "");
+    await vi.waitFor(() => expect(handles.length).toBe(3));
+    expect(handles[2]?.resumeSession).toHaveBeenCalledWith("sess_abc");
+  });
+});

package/host/transports/s2s-transport.ts

@@ -7,6 +7,7 @@ import {
   type CreateS2sWebSocket,
   connectS2s,
   defaultCreateS2sWebSocket,
+  type S2sCallbacks,
   type S2sHandle,
   type S2sSessionConfig,
   type S2sToolSchema,
@@ -28,11 +29,184 @@ export type S2sTransportOptions = {
   logger?: Logger;
 };
 
+/**
+ * Close codes worth attempting `session.resume` on. These are network/server
+ * blips, not protocol or auth violations. Per AssemblyAI's docs, sessions are
+ * preserved for 30 s after disconnect, so resume is bounded by the window in
+ * `RESUME_WINDOW_MS` below.
+ */
+const TRANSIENT_CLOSE_CODES = new Set<number>([
+  1005, // No Status Received (abnormal close, no frame)
+  1006, // Abnormal Closure (no close frame at all)
+  1011, // Internal Server Error
+  3005, // Session Cancelled (unknown server error)
+]);
+
+/**
+ * AssemblyAI keeps the session alive for 30 s after disconnect; we leave a
+ * little headroom so the resume request still fits inside that window after
+ * the new WebSocket finishes opening.
+ */
+const RESUME_WINDOW_MS = 25_000;
+
 export function createS2sTransport(opts: S2sTransportOptions): Transport {
   const log = opts.logger ?? consoleLogger;
   const createWs = opts.createWebSocket ?? defaultCreateS2sWebSocket;
   let handle: S2sHandle | null = null;
   let currentReplyId: string | null = null;
+  /** Most recent `session.ready` ID — present once the upstream session is established. */
+  let providerSessionId: string | null = null;
+  /** When the current session became ready; bounds the resume window. */
+  let sessionReadyAt = 0;
+  /** Set by `stop()` so a deliberate close doesn't trigger a reconnect. */
+  let closing = false;
+  /**
+   * True while a `session.resume` round-trip is in flight (between sending
+   * resume and the next `session.ready`). Used to distinguish a resume failure
+   * (close before ready) from a normal close.
+   */
+  let reconnecting = false;
+  /**
+   * Set when a reconnect attempt is kicked off, cleared once the resumed
+   * session's `session.ready` arrives. Prevents back-to-back reconnect loops
+   * when the freshly-resumed socket also drops before fully recovering.
+   */
+  let reconnectInFlight = false;
+
+  function buildCallbacks(): S2sCallbacks {
+    return {
+      onSessionReady: (id) => {
+        providerSessionId = id;
+        sessionReadyAt = Date.now();
+        if (reconnecting) {
+          reconnecting = false;
+          reconnectInFlight = false;
+          log.info("S2S resumed", { sid: opts.sid, sessionId: id });
+        }
+        opts.callbacks.onSessionReady?.(id);
+      },
+      onReplyStarted: (replyId) => {
+        currentReplyId = replyId;
+        opts.callbacks.onReplyStarted(replyId);
+      },
+      onReplyDone: () => {
+        currentReplyId = null;
+        opts.callbacks.onReplyDone();
+      },
+      onCancelled: () => {
+        currentReplyId = null;
+        opts.callbacks.onCancelled();
+      },
+      onAudio: (bytes) => opts.callbacks.onAudioChunk(bytes),
+      onUserTranscript: opts.callbacks.onUserTranscript,
+      onAgentTranscript: opts.callbacks.onAgentTranscript,
+      onToolCall: opts.callbacks.onToolCall,
+      onSpeechStarted: opts.callbacks.onSpeechStarted,
+      onSpeechStopped: opts.callbacks.onSpeechStopped,
+      onSessionExpired: () => {
+        // The server told us the session no longer exists (most likely
+        // session_not_found in response to our resume). Surface as fatal
+        // rather than retrying — there's nothing left to resume.
+        if (reconnecting) {
+          reconnecting = false;
+          reconnectInFlight = false;
+          log.warn("S2S resume rejected: session expired", { sid: opts.sid });
+          opts.callbacks.onError("connection", "S2S resume failed: session expired");
+          return;
+        }
+        log.info("S2S session expired", { sid: opts.sid });
+        handle?.close();
+      },
+      onError: (err) => opts.callbacks.onError("internal", err.message),
+      onClose: (code, reason) => handleClose(code, reason),
+    };
+  }
+
+  function canResumeAfter(code: number): boolean {
+    if (!TRANSIENT_CLOSE_CODES.has(code)) return false;
+    if (providerSessionId === null) return false;
+    if (reconnectInFlight) return false;
+    return sessionReadyAt > 0 && Date.now() - sessionReadyAt < RESUME_WINDOW_MS;
+  }
+
+  function emitFatalClose(code: number, reason: string, wasReconnecting: boolean): void {
+    if (wasReconnecting) {
+      // Fresh resume socket closed before session.ready — resume failed.
+      reconnecting = false;
+      reconnectInFlight = false;
+      opts.callbacks.onError("connection", `S2S resume failed (code=${code})`);
+      return;
+    }
+    if (currentReplyId !== null) {
+      log.warn("S2S closed with active reply", {
+        sid: opts.sid,
+        agent: opts.agent,
+        activeReplyId: currentReplyId,
+        code,
+        reason,
+      });
+      opts.callbacks.onError("connection", `S2S closed mid-reply (code=${code})`);
+      return;
+    }
+    log.info("S2S closed", { code, reason });
+  }
+
+  function startResume(prevId: string, code: number, reason: string): void {
+    reconnectInFlight = true;
+    reconnecting = true;
+    log.warn("S2S unexpected close — attempting resume", {
+      sid: opts.sid,
+      agent: opts.agent,
+      code,
+      reason,
+      prevSessionId: prevId,
+    });
+    // The in-flight reply is gone; unblock SessionCore's turn promise.
+    if (currentReplyId !== null) {
+      currentReplyId = null;
+      opts.callbacks.onCancelled();
+    }
+    void resume(prevId).catch((err: unknown) => {
+      reconnecting = false;
+      reconnectInFlight = false;
+      const msg = err instanceof Error ? err.message : String(err);
+      log.warn("S2S resume failed", { sid: opts.sid, error: msg });
+      opts.callbacks.onError("connection", `S2S resume failed: ${msg}`);
+    });
+  }
+
+  function handleClose(code: number, reason: string): void {
+    if (closing) {
+      log.info("S2S closed", { code, reason });
+      return;
+    }
+    const wasReconnecting = reconnecting;
+    if (!canResumeAfter(code)) {
+      emitFatalClose(code, reason, wasReconnecting);
+      return;
+    }
+    // canResumeAfter ensures providerSessionId !== null; capture as const.
+    const prevId = providerSessionId;
+    if (prevId === null) return;
+    startResume(prevId, code, reason);
+  }
+
+  async function resume(prevSessionId: string): Promise<void> {
+    const newHandle = await _internals.connectS2s({
+      apiKey: opts.apiKey,
+      config: opts.s2sConfig,
+      createWebSocket: createWs,
+      logger: log,
+      ...(opts.sid !== undefined ? { sid: opts.sid } : {}),
+      callbacks: buildCallbacks(),
+    });
+    if (closing) {
+      newHandle.close();
+      return;
+    }
+    handle = newHandle;
+    newHandle.resumeSession(prevSessionId);
+  }
 
   async function start(): Promise<void> {
     handle = await _internals.connectS2s({
@@ -41,51 +215,13 @@ export function createS2sTransport(opts: S2sTransportOptions): Transport {
       createWebSocket: createWs,
       logger: log,
       sid: opts.sid,
-      callbacks: {
-        onSessionReady: (providerSessionId) => opts.callbacks.onSessionReady?.(providerSessionId),
-        onReplyStarted: (replyId) => {
-          currentReplyId = replyId;
-          opts.callbacks.onReplyStarted(replyId);
-        },
-        onReplyDone: () => {
-          currentReplyId = null;
-          opts.callbacks.onReplyDone();
-        },
-        onCancelled: () => {
-          currentReplyId = null;
-          opts.callbacks.onCancelled();
-        },
-        onAudio: (bytes) => opts.callbacks.onAudioChunk(bytes),
-        onUserTranscript: opts.callbacks.onUserTranscript,
-        onAgentTranscript: opts.callbacks.onAgentTranscript,
-        onToolCall: opts.callbacks.onToolCall,
-        onSpeechStarted: opts.callbacks.onSpeechStarted,
-        onSpeechStopped: opts.callbacks.onSpeechStopped,
-        onSessionExpired: () => {
-          log.info("S2S session expired", { sid: opts.sid });
-          handle?.close();
-        },
-        onError: (err) => opts.callbacks.onError("internal", err.message),
-        onClose: (code, reason) => {
-          if (currentReplyId !== null) {
-            log.warn("S2S closed with active reply", {
-              sid: opts.sid,
-              agent: opts.agent,
-              activeReplyId: currentReplyId,
-              code,
-              reason,
-            });
-            opts.callbacks.onError("connection", `S2S closed mid-reply (code=${code})`);
-          } else {
-            log.info("S2S closed", { code, reason });
-          }
-        },
-      },
+      callbacks: buildCallbacks(),
     });
     handle.updateSession(opts.sessionConfig);
   }
 
   async function stop(): Promise<void> {
+    closing = true;
     handle?.close();
     handle = null;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "exports": {
     ".": {
@@ -40,9 +40,9 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "^3.0.0",
     "@cartesia/cartesia-js": "^3.0.0",
     "@deepgram/sdk": "^5.0.0",
+    "@elevenlabs/elevenlabs-js": "^2.43.0",
     "ai": "^6.0.161",
     "assemblyai": "^4.30.0",
     "escape-html": "^1.0.3",
@@ -54,8 +54,41 @@
     "ws": "^8.20.0",
     "zod": "^4.3.6"
   },
+  "peerDependencies": {
+    "@ai-sdk/anthropic": "^3.0.0",
+    "@ai-sdk/google": "^3.0.0",
+    "@ai-sdk/groq": "^3.0.0",
+    "@ai-sdk/mistral": "^3.0.0",
+    "@ai-sdk/openai": "^3.0.0",
+    "@ai-sdk/xai": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/google": {
+      "optional": true
+    },
+    "@ai-sdk/groq": {
+      "optional": true
+    },
+    "@ai-sdk/mistral": {
+      "optional": true
+    },
+    "@ai-sdk/openai": {
+      "optional": true
+    },
+    "@ai-sdk/xai": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@ai-sdk/anthropic": "^3.0.0",
+    "@ai-sdk/google": "^3.0.0",
+    "@ai-sdk/groq": "^3.0.0",
+    "@ai-sdk/mistral": "^3.0.0",
     "@ai-sdk/openai": "^3.0.0",
+    "@ai-sdk/xai": "^3.0.0",
     "@types/escape-html": "^1.0.4",
     "@types/html-to-text": "^9.0.4",
     "@types/json-schema": "^7.0.15",

package/sdk/__snapshots__/schema-shapes.test.ts.snap

@@ -22,6 +22,7 @@ exports[`manifest schema shapes > ToolSchemaSchema shape 1`] = `
   "description",
   "name",
   "parameters",
+  "type",
 ]
 `;
 

package/sdk/_internal-types.ts

@@ -128,6 +128,7 @@ export function toAgentConfig(src: AgentConfigSource): AgentConfig {
  * etc.) — the Vercel AI SDK wraps it via `jsonSchema()`.
  */
 export 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()),
@@ -135,6 +136,7 @@ export const ToolSchemaSchema = z.object({
 
 /** Serialized tool schema — derived from {@link ToolSchemaSchema}. */
 export type ToolSchema = {
+  type: "function";
   name: string;
   description: string;
   parameters: JSONSchema7;
@@ -151,6 +153,7 @@ export const EMPTY_PARAMS = z.object({});
  */
 export function agentToolsToSchemas(tools: Readonly<Record<string, ToolDef>>): ToolSchema[] {
   return Object.entries(tools).map(([name, def]) => ({
+    type: "function",
     name,
     description: def.description,
     parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS) as JSONSchema7,

package/sdk/providers/llm/google.ts

@@ -0,0 +1,30 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Google (Gemini) LLM factory — returns a pure descriptor.
+ *
+ * Users call this in place of importing from `@ai-sdk/google` directly,
+ * so agent bundles don't drag the Google SDK into the guest sandbox.
+ *
+ * The host-side resolver in `host/providers/resolve.ts` builds a real
+ * Vercel AI SDK `LanguageModel` from this descriptor during
+ * `createRuntime`, using `GOOGLE_GENERATIVE_AI_API_KEY` from the
+ * agent's env.
+ */
+
+import type { LlmProvider } from "../../providers.ts";
+
+export const GOOGLE_KIND = "google" as const;
+
+export interface GoogleOptions {
+  /** Google Gemini model id, e.g. `"gemini-2.0-flash"`. */
+  model: string;
+}
+
+export type GoogleProvider = LlmProvider & {
+  readonly kind: typeof GOOGLE_KIND;
+  readonly options: GoogleOptions;
+};
+
+export function google(opts: GoogleOptions): GoogleProvider {
+  return { kind: GOOGLE_KIND, options: { ...opts } };
+}

package/sdk/providers/llm/groq.ts

@@ -0,0 +1,29 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Groq LLM factory — returns a pure descriptor.
+ *
+ * Users call this in place of importing from `@ai-sdk/groq` directly,
+ * so agent bundles don't drag the Groq SDK into the guest sandbox.
+ *
+ * The host-side resolver in `host/providers/resolve.ts` builds a real
+ * Vercel AI SDK `LanguageModel` from this descriptor during
+ * `createRuntime`, using `GROQ_API_KEY` from the agent's env.
+ */
+
+import type { LlmProvider } from "../../providers.ts";
+
+export const GROQ_KIND = "groq" as const;
+
+export interface GroqOptions {
+  /** Groq model id, e.g. `"llama-3.3-70b-versatile"`. */
+  model: string;
+}
+
+export type GroqProvider = LlmProvider & {
+  readonly kind: typeof GROQ_KIND;
+  readonly options: GroqOptions;
+};
+
+export function groq(opts: GroqOptions): GroqProvider {
+  return { kind: GROQ_KIND, options: { ...opts } };
+}

package/sdk/providers/llm/mistral.ts

@@ -0,0 +1,29 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Mistral LLM factory — returns a pure descriptor.
+ *
+ * Users call this in place of importing from `@ai-sdk/mistral` directly,
+ * so agent bundles don't drag the Mistral SDK into the guest sandbox.
+ *
+ * The host-side resolver in `host/providers/resolve.ts` builds a real
+ * Vercel AI SDK `LanguageModel` from this descriptor during
+ * `createRuntime`, using `MISTRAL_API_KEY` from the agent's env.
+ */
+
+import type { LlmProvider } from "../../providers.ts";
+
+export const MISTRAL_KIND = "mistral" as const;
+
+export interface MistralOptions {
+  /** Mistral model id, e.g. `"mistral-large-latest"`. */
+  model: string;
+}
+
+export type MistralProvider = LlmProvider & {
+  readonly kind: typeof MISTRAL_KIND;
+  readonly options: MistralOptions;
+};
+
+export function mistral(opts: MistralOptions): MistralProvider {
+  return { kind: MISTRAL_KIND, options: { ...opts } };
+}

package/sdk/providers/llm/openai.ts

@@ -0,0 +1,29 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * OpenAI LLM factory — returns a pure descriptor.
+ *
+ * Users call this in place of importing from `@ai-sdk/openai` directly,
+ * so agent bundles don't drag the OpenAI SDK into the guest sandbox.
+ *
+ * The host-side resolver in `host/providers/resolve.ts` builds a real
+ * Vercel AI SDK `LanguageModel` from this descriptor during
+ * `createRuntime`, using `OPENAI_API_KEY` from the agent's env.
+ */
+
+import type { LlmProvider } from "../../providers.ts";
+
+export const OPENAI_KIND = "openai" as const;
+
+export interface OpenAIOptions {
+  /** OpenAI model id, e.g. `"gpt-4o"`, `"gpt-4o-mini"`. */
+  model: string;
+}
+
+export type OpenAIProvider = LlmProvider & {
+  readonly kind: typeof OPENAI_KIND;
+  readonly options: OpenAIOptions;
+};
+
+export function openai(opts: OpenAIOptions): OpenAIProvider {
+  return { kind: OPENAI_KIND, options: { ...opts } };
+}