@alexkroman1/aai 1.6.0 → 1.7.0

package/host/memory-vector.test.ts

@@ -0,0 +1,87 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { afterEach, describe, expect, it } from "vitest";
+import { _resetMemoryVectorForTests, createMemoryVector } from "./memory-vector.ts";
+
+afterEach(() => _resetMemoryVectorForTests());
+
+describe("createMemoryVector", () => {
+  it("returns empty array when querying an empty namespace", async () => {
+    const v = createMemoryVector({ namespace: "ns1" });
+    expect(await v.query("anything")).toEqual([]);
+  });
+
+  it("upsert + query returns the upserted record", async () => {
+    const v = createMemoryVector({ namespace: "ns1" });
+    await v.upsert("doc-1", "the quick brown fox", { tag: "anim" });
+    const matches = await v.query("the quick brown fox");
+    expect(matches).toHaveLength(1);
+    expect(matches[0]).toMatchObject({
+      id: "doc-1",
+      text: "the quick brown fox",
+      metadata: { tag: "anim" },
+    });
+    expect(matches[0]?.score).toBeGreaterThan(0.9);
+  });
+
+  it("ranks more similar text higher than less similar text", async () => {
+    const v = createMemoryVector({ namespace: "ns1" });
+    await v.upsert("a", "exact match string");
+    await v.upsert("b", "completely different content");
+    const matches = await v.query("exact match string", { topK: 2 });
+    expect(matches[0]?.id).toBe("a");
+  });
+
+  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}`);
+    expect(await v.query("text", { topK: 3 })).toHaveLength(3);
+  });
+
+  it("idempotent: same id overwrites text and metadata", async () => {
+    const v = createMemoryVector({ namespace: "ns1" });
+    await v.upsert("doc", "v1", { tag: "old" });
+    await v.upsert("doc", "v2", { tag: "new" });
+    const matches = await v.query("v2");
+    expect(matches[0]?.text).toBe("v2");
+    expect(matches[0]?.metadata).toEqual({ tag: "new" });
+  });
+
+  it("delete removes by id", async () => {
+    const v = createMemoryVector({ namespace: "ns1" });
+    await v.upsert("a", "one");
+    await v.upsert("b", "two");
+    await v.delete("a");
+    const ids = (await v.query("one")).map((m) => m.id);
+    expect(ids).not.toContain("a");
+  });
+
+  it("delete accepts an array of ids", async () => {
+    const v = createMemoryVector({ namespace: "ns1" });
+    await v.upsert("a", "one");
+    await v.upsert("b", "two");
+    await v.delete(["a", "b"]);
+    expect(await v.query("anything")).toEqual([]);
+  });
+
+  it("isolates namespaces", async () => {
+    const a = createMemoryVector({ namespace: "ns1" });
+    const b = createMemoryVector({ namespace: "ns2" });
+    await a.upsert("doc", "in ns1");
+    expect(await b.query("in ns1")).toEqual([]);
+    expect((await a.query("in ns1"))[0]?.id).toBe("doc");
+  });
+
+  it("filter applies top-level exact-match", async () => {
+    const v = createMemoryVector({ namespace: "ns1" });
+    await v.upsert("a", "one", { kind: "x" });
+    await v.upsert("b", "two", { kind: "y" });
+    const matches = await v.query("one", { filter: { kind: "x" } });
+    expect(matches.map((m) => m.id)).toEqual(["a"]);
+  });
+
+  it("rejects unsupported filter operators", async () => {
+    const v = createMemoryVector({ namespace: "ns1" });
+    await v.upsert("a", "one");
+    await expect(v.query("one", { filter: { kind: { $in: ["x"] } } })).rejects.toThrow(/operator/i);
+  });
+});

package/host/memory-vector.ts

@@ -0,0 +1,108 @@
+// 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";
+
+export type MemoryVectorOptions = {
+  namespace: string;
+};
+
+type Record_ = {
+  text: string;
+  metadata: Record<string, unknown> | undefined;
+  vec: Float32Array;
+};
+
+const stores = new Map<string, Map<string, Record_>>();
+
+function getStore(ns: string): Map<string, Record_> {
+  let store = stores.get(ns);
+  if (!store) {
+    store = new Map();
+    stores.set(ns, store);
+  }
+  return store;
+}
+
+const DIM = 64;
+
+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;
+  let norm = 0;
+  for (let i = 0; i < DIM; i++) norm += (out[i] as number) * (out[i] as number);
+  norm = Math.sqrt(norm) || 1;
+  for (let i = 0; i < DIM; i++) out[i] = (out[i] as number) / norm;
+  return out;
+}
+
+function cosine(a: Float32Array, b: Float32Array): number {
+  let dot = 0;
+  for (let i = 0; i < DIM; i++) dot += (a[i] as number) * (b[i] as number);
+  return dot;
+}
+
+function matches(
+  metadata: Record<string, unknown> | undefined,
+  filter: Record<string, unknown>,
+): boolean {
+  for (const [key, want] of Object.entries(filter)) {
+    if (want !== null && typeof want === "object") {
+      throw new Error(
+        `In-memory Vector: filter operator unsupported (${key}). Only top-level exact-match is supported.`,
+      );
+    }
+    if (metadata?.[key] !== want) return false;
+  }
+  return true;
+}
+
+export function createMemoryVector(opts: MemoryVectorOptions): Vector {
+  const ns = opts.namespace;
+
+  return {
+    async upsert(id, text, metadata) {
+      getStore(ns).set(id, { text, metadata, vec: pseudoEmbed(text) });
+    },
+    async query(text, queryOpts?: VectorQueryOptions) {
+      const topK = queryOpts?.topK ?? 5;
+      const filter = queryOpts?.filter;
+      const probe = pseudoEmbed(text);
+      const scored: VectorMatch[] = [];
+      for (const [id, rec] of getStore(ns)) {
+        if (filter && !matches(rec.metadata, filter)) continue;
+        scored.push({
+          id,
+          score: cosine(probe, rec.vec),
+          text: rec.text,
+          ...(rec.metadata !== undefined ? { metadata: rec.metadata } : {}),
+        });
+      }
+      scored.sort((a, b) => b.score - a.score);
+      return scored.slice(0, topK);
+    },
+    async delete(ids) {
+      const store = getStore(ns);
+      const list = Array.isArray(ids) ? ids : [ids];
+      for (const id of list) store.delete(id);
+    },
+  };
+}
+
+/** Test-only: clear all in-memory state. Not exported from the package. */
+export function _resetMemoryVectorForTests(): void {
+  stores.clear();
+}

package/host/pinecone-vector.test.ts

@@ -0,0 +1,79 @@
+// 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 {
+    ...original,
+    createRequire:
+      () =>
+      (id: string): unknown => {
+        if (id === "@pinecone-database/pinecone") {
+          return { Pinecone: PineconeFake };
+        }
+        return original.createRequire(import.meta.url)(id);
+      },
+  };
+});
+
+// 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
+var PineconeFake = vi.fn(function (this: unknown) {
+  // eslint-disable-line no-var
+  return { index };
+});
+
+import { createPineconeVector } from "./pinecone-vector.ts";
+
+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" });
+    await v.upsert("doc-1", "hello", { tag: "x" });
+    expect(index).toHaveBeenCalledWith("ix");
+    expect(namespace).toHaveBeenCalledWith("ns");
+    expect(upsertRecords).toHaveBeenCalledWith([{ _id: "doc-1", text: "hello", tag: "x" }]);
+  });
+
+  it("calls searchRecords on query", async () => {
+    searchRecords.mockResolvedValueOnce({
+      result: {
+        hits: [{ _id: "doc-1", _score: 0.9, fields: { text: "hello", tag: "x" } }],
+      },
+    });
+    const v = createPineconeVector({ apiKey: "k", index: "ix", namespace: "ns" });
+    const matches = await v.query("hello", { topK: 3, filter: { tag: "x" } });
+    expect(searchRecords).toHaveBeenCalledWith({
+      query: { inputs: { text: "hello" }, topK: 3, filter: { tag: "x" } },
+      fields: ["*"],
+    });
+    expect(matches).toEqual([{ id: "doc-1", score: 0.9, text: "hello", metadata: { tag: "x" } }]);
+  });
+
+  it("delete with single id", async () => {
+    const v = createPineconeVector({ apiKey: "k", index: "ix", namespace: "ns" });
+    await v.delete("doc-1");
+    expect(deleteMany).toHaveBeenCalledWith(["doc-1"]);
+  });
+
+  it("delete with array", async () => {
+    const v = createPineconeVector({ apiKey: "k", index: "ix", namespace: "ns" });
+    await v.delete(["a", "b"]);
+    expect(deleteMany).toHaveBeenCalledWith(["a", "b"]);
+  });
+});

package/host/pinecone-vector.ts

@@ -0,0 +1,79 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Pinecone Vector implementation using integrated inference.
+ *
+ * The Pinecone index must be created with an embed config (e.g.
+ * `multilingual-e5-large`); we never see the embedding vectors.
+ *
+ * `@pinecone-database/pinecone` is loaded lazily via `createRequire`
+ * so the package becomes a true *optional* peer dependency: if a
+ * deployment doesn't use Pinecone, the missing package is never
+ * imported.
+ */
+
+import type { Vector, VectorMatch, VectorQueryOptions } from "../sdk/vector.ts";
+import { loadProviderPackage } from "./providers/resolve.ts";
+
+export type PineconeVectorOptions = {
+  apiKey: string;
+  index: string;
+  /** Per-tenant namespace — set by the server to the agent slug. */
+  namespace: string;
+};
+
+type PineconeNs = {
+  upsertRecords: (records: Record<string, unknown>[]) => Promise<unknown>;
+  searchRecords: (req: {
+    query: { inputs: { text: string }; topK: number; filter?: Record<string, unknown> };
+    fields: string[];
+  }) => Promise<{
+    result: { hits: Array<{ _id: string; _score: number; fields: Record<string, unknown> }> };
+  }>;
+  deleteMany: (ids: string[]) => Promise<unknown>;
+};
+
+type PineconeClient = {
+  index: (name: string) => { namespace: (ns: string) => PineconeNs };
+};
+
+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);
+
+  return {
+    async upsert(id, text, metadata) {
+      const record: Record<string, unknown> = { _id: id, text, ...(metadata ?? {}) };
+      await ns().upsertRecords([record]);
+    },
+    async query(text, queryOpts?: VectorQueryOptions) {
+      const topK = queryOpts?.topK ?? 5;
+      const req = {
+        query: {
+          inputs: { text },
+          topK,
+          ...(queryOpts?.filter !== undefined ? { filter: queryOpts.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 {
+          id: hit._id,
+          score: hit._score,
+          text: typeof hitText === "string" ? hitText : "",
+          ...(metadata !== undefined ? { metadata } : {}),
+        };
+      });
+    },
+    async delete(ids) {
+      const list = Array.isArray(ids) ? ids : [ids];
+      await ns().deleteMany(list);
+    },
+  };
+}

package/host/providers/resolve-kv.test.ts

@@ -0,0 +1,48 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { describe, expect, it } from "vitest";
+import { fsKv } from "../../sdk/providers/kv/fs.ts";
+import { memoryKv } from "../../sdk/providers/kv/memory.ts";
+import { redisKv } from "../../sdk/providers/kv/redis.ts";
+import { s3Kv } from "../../sdk/providers/kv/s3.ts";
+import { resolveKv } from "./resolve-kv.ts";
+
+describe("resolveKv", () => {
+  it("resolves memoryKv to a working in-memory KV", async () => {
+    const kv = resolveKv(memoryKv(), {}, "p");
+    await kv.set("k", "v");
+    expect(await kv.get("k")).toBe("v");
+  });
+
+  it("resolves fsKv with explicit base", () => {
+    expect(() => resolveKv(fsKv({ base: "/tmp/aai-test" }), {}, "p")).not.toThrow();
+  });
+
+  it("resolves s3Kv when AWS creds are present", () => {
+    expect(() =>
+      resolveKv(
+        s3Kv({ bucket: "b", endpoint: "https://e", region: "auto" }),
+        {
+          AWS_ACCESS_KEY_ID: "k",
+          AWS_SECRET_ACCESS_KEY: "s",
+        },
+        "p",
+      ),
+    ).not.toThrow();
+  });
+
+  it("throws when s3Kv has no AWS creds", () => {
+    expect(() => resolveKv(s3Kv({ bucket: "b" }), {}, "p")).toThrow(/AWS_ACCESS_KEY_ID/);
+  });
+
+  it("resolves redisKv when REDIS_URL is present", () => {
+    expect(() => resolveKv(redisKv(), { REDIS_URL: "redis://localhost:6379" }, "p")).not.toThrow();
+  });
+
+  it("throws when redisKv has no REDIS_URL", () => {
+    expect(() => resolveKv(redisKv(), {}, "p")).toThrow(/REDIS_URL/);
+  });
+
+  it("throws on unknown kind", () => {
+    expect(() => resolveKv({ kind: "nope", options: {} }, {}, "p")).toThrow(/Unknown KV provider/);
+  });
+});

package/host/providers/resolve-kv.ts

@@ -0,0 +1,128 @@
+// 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";
+import { FS_KV_KIND, type FsKvOptions } from "../../sdk/providers/kv/fs.ts";
+import { MEMORY_KV_KIND } from "../../sdk/providers/kv/memory.ts";
+import { REDIS_KV_KIND, type RedisKvOptions } from "../../sdk/providers/kv/redis.ts";
+import { S3_KV_KIND, type S3KvOptions } from "../../sdk/providers/kv/s3.ts";
+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`);
+}
+
+/**
+ * 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.
+ */
+function makeLazyDriver(modulePath: string, label: string, opts: Record<string, unknown>): Driver {
+  let resolved: Driver | null = null;
+  const get = (): Driver => {
+    if (!resolved) {
+      const factory = loadDriver<(o: Record<string, unknown>) => Driver>(modulePath, label);
+      resolved = factory(opts);
+    }
+    return resolved;
+  };
+  return {
+    name: label.toLowerCase(),
+    hasItem: (key, txOpts) => get().hasItem(key, txOpts),
+    getItem: (key, txOpts) => get().getItem(key, txOpts),
+    getItemRaw: (key, txOpts) => get().getItemRaw?.(key, txOpts) ?? null,
+    setItem: (key, value, txOpts) => get().setItem?.(key, value, txOpts),
+    setItemRaw: (key, value, txOpts) => get().setItemRaw?.(key, value, txOpts),
+    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),
+  };
+}
+
+/** 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: {
+      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");
+      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);
+      const secretAccessKey = resolveApiKey("AWS_SECRET_ACCESS_KEY", env);
+      if (!(accessKeyId && secretAccessKey)) {
+        throw new Error(
+          "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");
+      return createUnstorageKv({
+        storage: createStorage({
+          driver: s3Driver({
+            bucket: opts.bucket,
+            ...(opts.endpoint !== undefined ? { endpoint: opts.endpoint } : {}),
+            region: opts.region ?? "auto",
+            accessKeyId,
+            secretAccessKey,
+          }),
+        }),
+        prefix,
+      });
+    }
+    case REDIS_KV_KIND: {
+      const opts = descriptor.options as unknown as RedisKvOptions;
+      const url = resolveApiKey("REDIS_URL", env);
+      if (!url) {
+        throw new Error("Redis KV: missing connection URL. Set REDIS_URL in the agent env.");
+      }
+      return createUnstorageKv({
+        storage: createStorage({
+          driver: makeLazyDriver("unstorage/drivers/redis", "Redis", {
+            url,
+            ...(opts.tls !== undefined ? { tls: opts.tls } : {}),
+          }),
+        }),
+        prefix,
+      });
+    }
+    default:
+      throw new Error(
+        `Unknown KV provider kind: "${descriptor.kind}". ` +
+          `Supported: ${MEMORY_KV_KIND}, ${FS_KV_KIND}, ${S3_KV_KIND}, ${REDIS_KV_KIND}.`,
+      );
+  }
+}

package/host/providers/resolve-vector.test.ts

@@ -0,0 +1,26 @@
+// Copyright 2025 the AAI authors. MIT license.
+import { afterEach, describe, expect, it } from "vitest";
+import { inMemoryVector } from "../../sdk/providers/vector/in-memory.ts";
+import { pinecone } from "../../sdk/providers/vector/pinecone.ts";
+import { _resetMemoryVectorForTests } from "../memory-vector.ts";
+import { resolveVector } from "./resolve-vector.ts";
+
+afterEach(() => _resetMemoryVectorForTests());
+
+describe("resolveVector", () => {
+  it("resolves inMemoryVector descriptor to a working store", async () => {
+    const v = resolveVector(inMemoryVector(), {}, "ns1");
+    await v.upsert("doc", "hello");
+    expect((await v.query("hello"))[0]?.id).toBe("doc");
+  });
+
+  it("throws clear error when PINECONE_API_KEY is missing", () => {
+    expect(() => resolveVector(pinecone({ index: "ix" }), {}, "ns")).toThrow(/PINECONE_API_KEY/);
+  });
+
+  it("throws on unknown kind", () => {
+    expect(() => resolveVector({ kind: "nope", options: {} }, {}, "ns")).toThrow(
+      /Unknown Vector provider/,
+    );
+  });
+});

package/host/providers/resolve-vector.ts

@@ -0,0 +1,42 @@
+// 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";
+import type { VectorProvider } from "../../sdk/providers.ts";
+import type { Vector } from "../../sdk/vector.ts";
+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: {
+      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 });
+    }
+    default:
+      throw new Error(
+        `Unknown Vector provider kind: "${descriptor.kind}". ` +
+          `Supported: ${IN_MEMORY_VECTOR_KIND}, ${PINECONE_VECTOR_KIND}.`,
+      );
+  }
+}