@alexkroman1/aai 1.7.1 → 1.8.1

package/host/integration/pipeline-reference.integration.test.ts

@@ -34,19 +34,13 @@ const here = dirname(fileURLToPath(import.meta.url));
 const fixturePath = join(here, "fixtures/hello-how-are-you.pcm16");
 
 async function fixtureExists(): Promise<boolean> {
-  try {
-    const s = await stat(fixturePath);
-    return s.isFile() && s.size > 0;
-  } catch {
-    return false;
-  }
+  const s = await stat(fixturePath).catch(() => null);
+  return s !== null && s.isFile() && s.size > 0;
 }
 
+const { ASSEMBLYAI_API_KEY, OPENAI_API_KEY, CARTESIA_API_KEY, VITEST_PROFILE } = process.env;
 const envReady = Boolean(
-  process.env.VITEST_PROFILE === "integration" &&
-    process.env.ASSEMBLYAI_API_KEY &&
-    process.env.OPENAI_API_KEY &&
-    process.env.CARTESIA_API_KEY,
+  VITEST_PROFILE === "integration" && ASSEMBLYAI_API_KEY && OPENAI_API_KEY && CARTESIA_API_KEY,
 );
 
 describe.skipIf(!envReady)("pipeline integration — reference stack", () => {
@@ -66,12 +60,14 @@ describe.skipIf(!envReady)("pipeline integration — reference stack", () => {
       open: true,
       event: (e) => {
         if (e.type === "user_transcript") userTranscripts.push(e.text);
-        if (e.type === "reply_done") replyDone = true;
+        else if (e.type === "reply_done") replyDone = true;
       },
       playAudioChunk: (chunk) => {
         audioOut.push(chunk);
       },
-      playAudioDone: () => undefined,
+      playAudioDone: () => {
+        /* no-op */
+      },
     };
 
     const runtime = createRuntime({
@@ -84,9 +80,9 @@ describe.skipIf(!envReady)("pipeline integration — reference stack", () => {
       },
       env: {
         // biome-ignore lint/style/noNonNullAssertion: envReady guard ensures presence
-        ASSEMBLYAI_API_KEY: process.env.ASSEMBLYAI_API_KEY!,
+        ASSEMBLYAI_API_KEY: ASSEMBLYAI_API_KEY!,
         // biome-ignore lint/style/noNonNullAssertion: envReady guard ensures presence
-        CARTESIA_API_KEY: process.env.CARTESIA_API_KEY!,
+        CARTESIA_API_KEY: CARTESIA_API_KEY!,
       },
       stt: openAssemblyAI({ model: "u3pro-rt" }),
       llm: openai("gpt-4o-mini"),
@@ -103,11 +99,10 @@ describe.skipIf(!envReady)("pipeline integration — reference stack", () => {
     await session.start();
     session.onAudioReady();
 
-    // Stream the PCM fixture in ~100ms chunks (16 kHz PCM16 → 3200 bytes/100ms).
+    // 16 kHz PCM16 → 3200 bytes per 100ms.
     const chunkBytes = 3200;
     for (let i = 0; i < pcm.length; i += chunkBytes) {
-      const chunk = pcm.subarray(i, Math.min(i + chunkBytes, pcm.length));
-      session.onAudio(new Uint8Array(chunk));
+      session.onAudio(new Uint8Array(pcm.subarray(i, i + chunkBytes)));
       await new Promise((r) => setTimeout(r, 100));
     }
     await session.stop();

package/host/integration.test.ts

@@ -108,7 +108,6 @@ describe("SDK integration: AgentDef → tool execution", () => {
     const exec = createRuntime({ agent, env: {} });
     expect(await exec.executeTool("increment", {}, "session-a", [])).toBe("1");
     expect(await exec.executeTool("increment", {}, "session-a", [])).toBe("2");
-    // Different session starts fresh
     expect(await exec.executeTool("increment", {}, "session-b", [])).toBe("1");
   });
 
@@ -141,9 +140,7 @@ describe("SDK integration: AgentDef → tool execution", () => {
     };
 
     const exec = createRuntime({ agent, env: {} });
-    // Valid input
     expect(await exec.executeTool("typed", { count: 5 }, "s1", [])).toBe("10");
-    // Invalid input
     const err = await exec.executeTool("typed", { count: "not a number" }, "s1", []);
     expect(err).toContain("error");
   });
@@ -160,7 +157,6 @@ describe("SDK integration: AgentDef → tool execution", () => {
     };
 
     const config = toAgentConfig(agent);
-    // Should survive JSON round-trip
     const parsed = JSON.parse(JSON.stringify(config));
     expect(parsed.name).toBe("config-test");
     expect(parsed.systemPrompt).toBe("Custom instructions");
@@ -182,9 +178,7 @@ describe("SDK integration: AgentDef → tool execution", () => {
     };
 
     const exec = createRuntime({ agent, env: {} });
-    // Custom tool works
     expect(await exec.executeTool("custom", {}, "s1", [])).toBe("custom result");
-    // Builtin tool works
     const codeResult = await exec.executeTool(
       "run_code",
       { code: 'console.log("from builtin")' },
@@ -192,7 +186,6 @@ describe("SDK integration: AgentDef → tool execution", () => {
       [],
     );
     expect(codeResult).toBe("from builtin");
-    // Tool schemas include both
     const names = exec.toolSchemas.map((s) => s.name);
     expect(names).toContain("custom");
     expect(names).toContain("run_code");

package/host/memory-vector.test.ts

@@ -33,7 +33,9 @@ describe("createMemoryVector", () => {
 
   it("topK caps the number of results", async () => {
     const v = createMemoryVector({ namespace: "ns1" });
-    for (let i = 0; i < 10; i++) await v.upsert(`id-${i}`, `text ${i}`);
+    for (let i = 0; i < 10; i++) {
+      await v.upsert(`id-${i}`, `text ${i}`);
+    }
     expect(await v.query("text", { topK: 3 })).toHaveLength(3);
   });
 

package/host/memory-vector.ts

@@ -1,14 +1,4 @@
 // Copyright 2025 the AAI authors. MIT license.
-/**
- * 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 { createHash } from "node:crypto";
 import type { Vector, VectorMatch, VectorQueryOptions } from "../sdk/vector.ts";
@@ -17,15 +7,16 @@ export type MemoryVectorOptions = {
   namespace: string;
 };
 
-type Record_ = {
+type StoredRecord = {
   text: string;
   metadata: Record<string, unknown> | undefined;
   vec: Float32Array;
 };
 
-const stores = new Map<string, Map<string, Record_>>();
+const DIM = 64;
+const stores = new Map<string, Map<string, StoredRecord>>();
 
-function getStore(ns: string): Map<string, Record_> {
+function getStore(ns: string): Map<string, StoredRecord> {
   let store = stores.get(ns);
   if (!store) {
     store = new Map();
@@ -34,14 +25,18 @@ function getStore(ns: string): Map<string, Record_> {
   return store;
 }
 
-const DIM = 64;
-
+// Pseudo-embedding: hash text → 64-dim unit vector. Both stored and probe
+// vectors are unit-length, so cosine similarity reduces to a dot product.
+// Intentionally low-quality — this is for `aai dev` and tests only, where
+// the goal is proving tool wiring rather than retrieval ranking.
 function pseudoEmbed(text: string): Float32Array {
   const out = new Float32Array(DIM);
   const h1 = createHash("sha256").update(text).digest();
   const h2 = createHash("sha256").update(h1).digest();
-  for (let i = 0; i < 32; i++) out[i] = ((h1[i] as number) - 128) / 128;
-  for (let i = 0; i < 32; i++) out[i + 32] = ((h2[i] as number) - 128) / 128;
+  for (let i = 0; i < 32; i++) {
+    out[i] = ((h1[i] as number) - 128) / 128;
+    out[i + 32] = ((h2[i] as number) - 128) / 128;
+  }
   let norm = 0;
   for (let i = 0; i < DIM; i++) norm += (out[i] as number) * (out[i] as number);
   norm = Math.sqrt(norm) || 1;
@@ -84,12 +79,13 @@ export function createMemoryVector(opts: MemoryVectorOptions): Vector {
       const scored: VectorMatch[] = [];
       for (const [id, rec] of getStore(ns)) {
         if (filter && !matches(rec.metadata, filter)) continue;
-        scored.push({
+        const match: VectorMatch = {
           id,
           score: cosine(probe, rec.vec),
           text: rec.text,
-          ...(rec.metadata !== undefined ? { metadata: rec.metadata } : {}),
-        });
+        };
+        if (rec.metadata !== undefined) match.metadata = rec.metadata;
+        scored.push(match);
       }
       scored.sort((a, b) => b.score - a.score);
       return scored.slice(0, topK);
@@ -102,7 +98,6 @@ export function createMemoryVector(opts: MemoryVectorOptions): Vector {
   };
 }
 
-/** Test-only: clear all in-memory state. Not exported from the package. */
 export function _resetMemoryVectorForTests(): void {
   stores.clear();
 }

package/host/pinecone-vector.test.ts

@@ -1,8 +1,6 @@
 // Copyright 2025 the AAI authors. MIT license.
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
-// Intercept createRequire from node:module so that require("@pinecone-database/pinecone")
-// returns a controlled fake — works even when the package is not installed.
 vi.mock("node:module", async (importOriginal) => {
   const original = await importOriginal<typeof import("node:module")>();
   return {
@@ -20,30 +18,29 @@ vi.mock("node:module", async (importOriginal) => {
 
 // Must use var (not const/let) to avoid TDZ when the vi.mock factory above
 // is hoisted — the variables are referenced inside the factory closure.
-var upsertRecords = vi.fn(); // eslint-disable-line no-var
-var searchRecords = vi.fn(); // eslint-disable-line no-var
-var deleteMany = vi.fn(); // eslint-disable-line no-var
-var namespace = vi.fn(() => ({ upsertRecords, searchRecords, deleteMany })); // eslint-disable-line no-var
-var index = vi.fn(() => ({ namespace })); // eslint-disable-line no-var
+/* eslint-disable no-var */
+var upsertRecords = vi.fn();
+var searchRecords = vi.fn();
+var deleteMany = vi.fn();
+var namespace = vi.fn(() => ({ upsertRecords, searchRecords, deleteMany }));
+var index = vi.fn(() => ({ namespace }));
 var PineconeFake = vi.fn(function (this: unknown) {
-  // eslint-disable-line no-var
   return { index };
 });
 
+/* eslint-enable no-var */
+
 import { createPineconeVector } from "./pinecone-vector.ts";
 
+const config = { apiKey: "k", index: "ix", namespace: "ns" };
+
 beforeEach(() => {
   vi.clearAllMocks();
-  PineconeFake.mockImplementation(function (this: unknown) {
-    return { index };
-  });
-  index.mockImplementation(() => ({ namespace }));
-  namespace.mockImplementation(() => ({ upsertRecords, searchRecords, deleteMany }));
 });
 
 describe("createPineconeVector", () => {
   it("threads namespace and index on upsert", async () => {
-    const v = createPineconeVector({ apiKey: "k", index: "ix", namespace: "ns" });
+    const v = createPineconeVector(config);
     await v.upsert("doc-1", "hello", { tag: "x" });
     expect(index).toHaveBeenCalledWith("ix");
     expect(namespace).toHaveBeenCalledWith("ns");
@@ -56,7 +53,7 @@ describe("createPineconeVector", () => {
         hits: [{ _id: "doc-1", _score: 0.9, fields: { text: "hello", tag: "x" } }],
       },
     });
-    const v = createPineconeVector({ apiKey: "k", index: "ix", namespace: "ns" });
+    const v = createPineconeVector(config);
     const matches = await v.query("hello", { topK: 3, filter: { tag: "x" } });
     expect(searchRecords).toHaveBeenCalledWith({
       query: { inputs: { text: "hello" }, topK: 3, filter: { tag: "x" } },
@@ -66,13 +63,13 @@ describe("createPineconeVector", () => {
   });
 
   it("delete with single id", async () => {
-    const v = createPineconeVector({ apiKey: "k", index: "ix", namespace: "ns" });
+    const v = createPineconeVector(config);
     await v.delete("doc-1");
     expect(deleteMany).toHaveBeenCalledWith(["doc-1"]);
   });
 
   it("delete with array", async () => {
-    const v = createPineconeVector({ apiKey: "k", index: "ix", namespace: "ns" });
+    const v = createPineconeVector(config);
     await v.delete(["a", "b"]);
     expect(deleteMany).toHaveBeenCalledWith(["a", "b"]);
   });

package/host/pinecone-vector.ts

@@ -37,43 +37,34 @@ type PineconeClient = {
 };
 
 export function createPineconeVector(opts: PineconeVectorOptions): Vector {
-  // Lazy-load via loadProviderPackage so the package is a true optional peer dep.
   const { Pinecone } = loadProviderPackage<{
     Pinecone: new (opts: { apiKey: string }) => PineconeClient;
   }>("@pinecone-database/pinecone", "Pinecone Vector");
-  const client = new Pinecone({ apiKey: opts.apiKey });
-  const ns = (): PineconeNs => client.index(opts.index).namespace(opts.namespace);
+  const ns = new Pinecone({ apiKey: opts.apiKey }).index(opts.index).namespace(opts.namespace);
 
   return {
     async upsert(id, text, metadata) {
-      const record: Record<string, unknown> = { _id: id, text, ...(metadata ?? {}) };
-      await ns().upsertRecords([record]);
+      await ns.upsertRecords([{ _id: id, text, ...(metadata ?? {}) }]);
     },
     async query(text, queryOpts?: VectorQueryOptions) {
-      const topK = queryOpts?.topK ?? 5;
-      const req = {
-        query: {
-          inputs: { text },
-          topK,
-          ...(queryOpts?.filter !== undefined ? { filter: queryOpts.filter } : {}),
-        },
+      const { topK = 5, filter } = queryOpts ?? {};
+      const resp = await ns.searchRecords({
+        query: { inputs: { text }, topK, ...(filter !== undefined ? { filter } : {}) },
         fields: ["*"],
-      };
-      const resp = await ns().searchRecords(req);
+      });
       return resp.result.hits.map((hit): VectorMatch => {
         const { text: hitText, ...rest } = hit.fields;
-        const metadata = Object.keys(rest).length > 0 ? rest : undefined;
-        return {
+        const match: VectorMatch = {
           id: hit._id,
           score: hit._score,
           text: typeof hitText === "string" ? hitText : "",
-          ...(metadata !== undefined ? { metadata } : {}),
         };
+        if (Object.keys(rest).length > 0) match.metadata = rest;
+        return match;
       });
     },
     async delete(ids) {
-      const list = Array.isArray(ids) ? ids : [ids];
-      await ns().deleteMany(list);
+      await ns.deleteMany(Array.isArray(ids) ? ids : [ids]);
     },
   };
 }

package/host/providers/providers.test-d.ts

@@ -12,10 +12,12 @@ import type {
   Unsubscribe,
 } from "../../sdk/providers.ts";
 
+type Descriptor = { kind: string; options: Record<string, unknown> };
+
 test("Descriptors are { kind, options } data", () => {
-  expectTypeOf<SttProvider>().toMatchTypeOf<{ kind: string; options: Record<string, unknown> }>();
-  expectTypeOf<LlmProvider>().toMatchTypeOf<{ kind: string; options: Record<string, unknown> }>();
-  expectTypeOf<TtsProvider>().toMatchTypeOf<{ kind: string; options: Record<string, unknown> }>();
+  expectTypeOf<SttProvider>().toMatchTypeOf<Descriptor>();
+  expectTypeOf<LlmProvider>().toMatchTypeOf<Descriptor>();
+  expectTypeOf<TtsProvider>().toMatchTypeOf<Descriptor>();
 });
 
 test("SttOpener.open returns Promise<SttSession>", () => {

package/host/providers/resolve-kv.ts

@@ -1,10 +1,4 @@
 // Copyright 2025 the AAI authors. MIT license.
-/**
- * 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 { createStorage, type Driver } from "unstorage";
 import type { Kv } from "../../sdk/kv.ts";
@@ -16,34 +10,22 @@ import type { KvProvider } from "../../sdk/providers.ts";
 import { createUnstorageKv } from "../unstorage-kv.ts";
 import { loadProviderPackage, resolveApiKey } from "./resolve.ts";
 
-/**
- * Load a CJS unstorage driver factory. The CJS variants use
- * `module.exports = defineDriver(...)` so the require result is the
- * factory itself (not an object with `.default`).
- *
- * Delegates to loadProviderPackage (lazy-load via createRequire so the
- * driver is a true optional peer dep).
- */
-function loadDriver<T>(modulePath: string, label: string): T {
-  return loadProviderPackage<T>(modulePath, `${label} KV: driver`);
+type DriverFactory<O> = (opts: O) => Driver;
+
+function loadDriver<O>(modulePath: string, label: string): DriverFactory<O> {
+  return loadProviderPackage<DriverFactory<O>>(modulePath, `${label} KV: driver`);
 }
 
-/**
- * Build a lazy unstorage Driver that defers loading the real driver
- * factory until the first I/O operation. This is necessary for drivers
- * whose peer dependencies (e.g. `ioredis`) may not be installed on the
- * host at startup — the missing package will only surface when the agent
- * actually performs KV operations, not at session creation time.
- */
+// Defers driver factory loading until first I/O so missing optional peer
+// deps (e.g. `ioredis`) surface at use-time rather than session start.
 function makeLazyDriver(modulePath: string, label: string, opts: Record<string, unknown>): Driver {
   let resolved: Driver | null = null;
-  const get = (): Driver => {
+  function get(): Driver {
     if (!resolved) {
-      const factory = loadDriver<(o: Record<string, unknown>) => Driver>(modulePath, label);
-      resolved = factory(opts);
+      resolved = loadDriver<Record<string, unknown>>(modulePath, label)(opts);
     }
     return resolved;
-  };
+  }
   return {
     name: label.toLowerCase(),
     hasItem: (key, txOpts) => get().hasItem(key, txOpts),
@@ -54,24 +36,24 @@ function makeLazyDriver(modulePath: string, label: string, opts: Record<string,
     removeItem: (key, txOpts) => get().removeItem?.(key, txOpts),
     getKeys: (base, txOpts) => get().getKeys(base, txOpts),
     clear: (base, txOpts) => get().clear?.(base, txOpts),
-    dispose: () => (resolved ? resolved.dispose?.() : undefined),
+    dispose: () => resolved?.dispose?.(),
   };
 }
 
-/** Resolve a {@link KvProvider} descriptor into a {@link Kv}. */
 export function resolveKv(descriptor: KvProvider, env: Record<string, string>, prefix: string): Kv {
   switch (descriptor.kind) {
-    case MEMORY_KV_KIND: {
+    case MEMORY_KV_KIND:
       return createUnstorageKv({ storage: createStorage(), prefix });
-    }
+
     case FS_KV_KIND: {
       const opts = descriptor.options as unknown as FsKvOptions;
-      const fsDriver = loadDriver<(o: { base: string }) => Driver>("unstorage/drivers/fs", "fs");
+      const fsDriver = loadDriver<{ base: string }>("unstorage/drivers/fs", "fs");
       return createUnstorageKv({
         storage: createStorage({ driver: fsDriver({ base: opts.base }) }),
         prefix,
       });
     }
+
     case S3_KV_KIND: {
       const opts = descriptor.options as unknown as S3KvOptions;
       const accessKeyId = resolveApiKey("AWS_ACCESS_KEY_ID", env);
@@ -81,15 +63,13 @@ export function resolveKv(descriptor: KvProvider, env: Record<string, string>, p
           "S3 KV: missing AWS credentials. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the agent env.",
         );
       }
-      const s3Driver = loadDriver<
-        (o: {
-          bucket: string;
-          endpoint?: string;
-          region: string;
-          accessKeyId: string;
-          secretAccessKey: string;
-        }) => Driver
-      >("unstorage/drivers/s3", "S3");
+      const s3Driver = loadDriver<{
+        bucket: string;
+        endpoint?: string;
+        region: string;
+        accessKeyId: string;
+        secretAccessKey: string;
+      }>("unstorage/drivers/s3", "S3");
       return createUnstorageKv({
         storage: createStorage({
           driver: s3Driver({
@@ -103,6 +83,7 @@ export function resolveKv(descriptor: KvProvider, env: Record<string, string>, p
         prefix,
       });
     }
+
     case REDIS_KV_KIND: {
       const opts = descriptor.options as unknown as RedisKvOptions;
       const url = resolveApiKey("REDIS_URL", env);
@@ -119,6 +100,7 @@ export function resolveKv(descriptor: KvProvider, env: Record<string, string>, p
         prefix,
       });
     }
+
     default:
       throw new Error(
         `Unknown KV provider kind: "${descriptor.kind}". ` +

package/host/providers/resolve-vector.ts

@@ -1,11 +1,4 @@
 // Copyright 2025 the AAI authors. MIT license.
-/**
- * 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 { IN_MEMORY_VECTOR_KIND } from "../../sdk/providers/vector/in-memory.ts";
 import { PINECONE_VECTOR_KIND, type PineconeOptions } from "../../sdk/providers/vector/pinecone.ts";
@@ -15,23 +8,21 @@ import { createMemoryVector } from "../memory-vector.ts";
 import { createPineconeVector } from "../pinecone-vector.ts";
 import { resolveApiKey } from "./resolve.ts";
 
-/** Resolve a {@link VectorProvider} descriptor into a {@link Vector}. */
 export function resolveVector(
   descriptor: VectorProvider,
   env: Record<string, string>,
   namespace: string,
 ): Vector {
   switch (descriptor.kind) {
-    case IN_MEMORY_VECTOR_KIND: {
+    case IN_MEMORY_VECTOR_KIND:
       return createMemoryVector({ namespace });
-    }
     case PINECONE_VECTOR_KIND: {
       const apiKey = resolveApiKey("PINECONE_API_KEY", env);
       if (!apiKey) {
         throw new Error("Pinecone Vector: missing API key. Set PINECONE_API_KEY in the agent env.");
       }
-      const opts = descriptor.options as unknown as PineconeOptions;
-      return createPineconeVector({ apiKey, index: opts.index, namespace });
+      const { index } = descriptor.options as unknown as PineconeOptions;
+      return createPineconeVector({ apiKey, index, namespace });
     }
     default:
       throw new Error(

package/host/providers/resolve.test.ts

@@ -9,17 +9,16 @@
  */
 
 import { describe, expect, it } from "vitest";
-import { ANTHROPIC_KIND, type AnthropicProvider } from "../../sdk/providers/llm/anthropic.ts";
-import { GOOGLE_KIND, type GoogleProvider } from "../../sdk/providers/llm/google.ts";
-import { GROQ_KIND, type GroqProvider } from "../../sdk/providers/llm/groq.ts";
-import { MISTRAL_KIND, type MistralProvider } from "../../sdk/providers/llm/mistral.ts";
-import { OPENAI_KIND, type OpenAIProvider } from "../../sdk/providers/llm/openai.ts";
-import { XAI_KIND, type XaiProvider } from "../../sdk/providers/llm/xai.ts";
+import { ANTHROPIC_KIND } from "../../sdk/providers/llm/anthropic.ts";
+import { GOOGLE_KIND } from "../../sdk/providers/llm/google.ts";
+import { GROQ_KIND } from "../../sdk/providers/llm/groq.ts";
+import { MISTRAL_KIND } from "../../sdk/providers/llm/mistral.ts";
+import { OPENAI_KIND } from "../../sdk/providers/llm/openai.ts";
+import { XAI_KIND } from "../../sdk/providers/llm/xai.ts";
 import type { LlmProvider } from "../../sdk/providers.ts";
 import { resolveLlm } from "./resolve.ts";
 
 type ProviderCase = {
-  kind: string;
   provider: LlmProvider;
   envVar: string;
   label: string;
@@ -27,41 +26,32 @@ type ProviderCase = {
 
 const cases: ProviderCase[] = [
   {
-    kind: ANTHROPIC_KIND,
-    provider: { kind: ANTHROPIC_KIND, options: { model: "claude-haiku-4-5" } } as AnthropicProvider,
+    provider: { kind: ANTHROPIC_KIND, options: { model: "claude-haiku-4-5" } },
     envVar: "ANTHROPIC_API_KEY",
     label: "Anthropic",
   },
   {
-    kind: OPENAI_KIND,
-    provider: { kind: OPENAI_KIND, options: { model: "gpt-4o" } } as OpenAIProvider,
+    provider: { kind: OPENAI_KIND, options: { model: "gpt-4o" } },
     envVar: "OPENAI_API_KEY",
     label: "OpenAI",
   },
   {
-    kind: GOOGLE_KIND,
-    provider: { kind: GOOGLE_KIND, options: { model: "gemini-2.0-flash" } } as GoogleProvider,
+    provider: { kind: GOOGLE_KIND, options: { model: "gemini-2.0-flash" } },
     envVar: "GOOGLE_GENERATIVE_AI_API_KEY",
     label: "Google",
   },
   {
-    kind: MISTRAL_KIND,
-    provider: {
-      kind: MISTRAL_KIND,
-      options: { model: "mistral-large-latest" },
-    } as MistralProvider,
+    provider: { kind: MISTRAL_KIND, options: { model: "mistral-large-latest" } },
     envVar: "MISTRAL_API_KEY",
     label: "Mistral",
   },
   {
-    kind: XAI_KIND,
-    provider: { kind: XAI_KIND, options: { model: "grok-2-1212" } } as XaiProvider,
+    provider: { kind: XAI_KIND, options: { model: "grok-2-1212" } },
     envVar: "XAI_API_KEY",
     label: "xAI",
   },
   {
-    kind: GROQ_KIND,
-    provider: { kind: GROQ_KIND, options: { model: "llama-3.3-70b-versatile" } } as GroqProvider,
+    provider: { kind: GROQ_KIND, options: { model: "llama-3.3-70b-versatile" } },
     envVar: "GROQ_API_KEY",
     label: "Groq",
   },
@@ -72,10 +62,8 @@ describe("resolveLlm", () => {
     describe(tc.label, () => {
       it("returns a LanguageModel when the API key is present", () => {
         const model = resolveLlm(tc.provider, { [tc.envVar]: "fake-key" });
-        // Vercel AI SDK LanguageModels are objects with a
-        // `specificationVersion` property; this is the cheapest stable
-        // handle to confirm resolve dispatched to the right factory and
-        // returned a real model.
+        // `specificationVersion` is the cheapest stable handle on a Vercel AI SDK
+        // LanguageModel — confirms resolve dispatched to the right factory.
         expect(model).toBeTypeOf("object");
         expect(model).toHaveProperty("specificationVersion");
       });
@@ -94,13 +82,12 @@ describe("resolveLlm", () => {
   }
 
   it("throws a useful error for an unknown kind, listing supported kinds", () => {
-    const bogus = { kind: "claude-direct", options: {} } as LlmProvider;
+    const bogus = { kind: "claude-direct", options: {} } as unknown as LlmProvider;
     expect(() => resolveLlm(bogus, {})).toThrow(/Unknown LLM provider kind: "claude-direct"/);
     expect(() => resolveLlm(bogus, {})).toThrow(/anthropic.*openai.*google.*mistral.*xai.*groq/);
   });
 });
 
-/** Temporarily delete a process.env var, returning a restore function. */
 function stripEnv(name: string): () => void {
   const prev = process.env[name];
   delete process.env[name];