@alexkroman1/aai 1.6.0 → 1.7.0

package/dist/host/runtime.d.ts

@@ -12,6 +12,7 @@ import type { ClientSink } from "../sdk/protocol.ts";
 import { type ReadyConfig } from "../sdk/protocol.ts";
 import { type LlmProvider, type SttOpener, type SttProvider, type TtsOpener, type TtsProvider } from "../sdk/providers.ts";
 import type { AgentDef } from "../sdk/types.ts";
+import type { Vector } from "../sdk/vector.ts";
 import type { Logger, S2SConfig } from "./runtime-config.ts";
 import type { CreateS2sWebSocket } from "./s2s.ts";
 import { type SessionCore } from "./session-core.ts";
@@ -50,6 +51,11 @@ export type RuntimeOptions = {
     agent: AgentDef<any>;
     env: Record<string, string>;
     kv?: Kv | undefined;
+    /**
+     * Vector store. If omitted, an in-memory store is created. The
+     * runtime overrides this with `agent.vector` if set.
+     */
+    vector?: Vector | undefined;
     /** Custom WebSocket factory for the S2S connection (useful for testing). */
     createWebSocket?: CreateS2sWebSocket | undefined;
     logger?: Logger | undefined;

package/dist/host/server.d.ts

@@ -8,6 +8,7 @@
  * Import via `aai/host`.
  */
 import type { Kv } from "../sdk/kv.ts";
+import type { Vector } from "../sdk/vector.ts";
 import type { Runtime } from "./runtime.ts";
 import type { Logger } from "./runtime-config.ts";
 export { createRuntime, type Runtime, type RuntimeOptions } from "./runtime.ts";
@@ -19,6 +20,7 @@ type ServerOptions = {
     runtime: Runtime;
     name?: string;
     kv?: Kv;
+    vector?: Vector;
     clientHtml?: string;
     clientDir?: string;
     logger?: Logger;

package/dist/host/tool-executor.d.ts

@@ -6,6 +6,7 @@
  */
 import type { Kv } from "../sdk/kv.ts";
 import type { Message, ToolDef } from "../sdk/types.ts";
+import type { Vector } from "../sdk/vector.ts";
 import type { Logger } from "./runtime-config.ts";
 export type { ExecuteTool } from "../sdk/_internal-types.ts";
 export type ExecuteToolCallOptions = {
@@ -14,6 +15,7 @@ export type ExecuteToolCallOptions = {
     state?: Record<string, unknown>;
     sessionId?: string | undefined;
     kv?: Kv | undefined;
+    vector?: Vector | undefined;
     messages?: readonly Message[] | undefined;
     logger?: Logger | undefined;
     send?: ((event: string, data: unknown) => void) | undefined;

package/dist/pinecone-CeJ69aRs.js

@@ -0,0 +1,19 @@
+//#region sdk/providers/vector/in-memory.ts
+const IN_MEMORY_VECTOR_KIND = "in-memory";
+function inMemoryVector() {
+	return {
+		kind: IN_MEMORY_VECTOR_KIND,
+		options: {}
+	};
+}
+//#endregion
+//#region sdk/providers/vector/pinecone.ts
+const PINECONE_VECTOR_KIND = "pinecone";
+function pinecone(opts) {
+	return {
+		kind: PINECONE_VECTOR_KIND,
+		options: { ...opts }
+	};
+}
+//#endregion
+export { inMemoryVector as i, pinecone as n, IN_MEMORY_VECTOR_KIND as r, PINECONE_VECTOR_KIND as t };

package/dist/{cartesia-BfQPOQ7Y.js → rime-58p9mDR8.js}

@@ -1,21 +1,3 @@
-//#region sdk/providers/tts/rime.ts
-const RIME_KIND = "rime";
-/**
-* Default Rime speaker used when callers invoke `rime()` with no `voice`.
-* `cove` is a `mistv2` speaker, matching the default model below — so a
-* bare `rime()` works out of the box for new agents.
-*/
-const RIME_DEFAULT_VOICE = "cove";
-function rime(opts = {}) {
-	return {
-		kind: RIME_KIND,
-		options: {
-			...opts,
-			voice: opts.voice ?? "cove"
-		}
-	};
-}
-//#endregion
 //#region sdk/providers/tts/cartesia.ts
 const CARTESIA_KIND = "cartesia";
 /**
@@ -34,4 +16,22 @@ function cartesia(opts = {}) {
 	};
 }
 //#endregion
-export { RIME_KIND as a, RIME_DEFAULT_VOICE as i, CARTESIA_KIND as n, rime as o, cartesia as r, CARTESIA_DEFAULT_VOICE as t };
+//#region sdk/providers/tts/rime.ts
+const RIME_KIND = "rime";
+/**
+* Default Rime speaker used when callers invoke `rime()` with no `voice`.
+* `cove` is a `mistv2` speaker, matching the default model below — so a
+* bare `rime()` works out of the box for new agents.
+*/
+const RIME_DEFAULT_VOICE = "cove";
+function rime(opts = {}) {
+	return {
+		kind: RIME_KIND,
+		options: {
+			...opts,
+			voice: opts.voice ?? "cove"
+		}
+	};
+}
+//#endregion
+export { CARTESIA_KIND as a, CARTESIA_DEFAULT_VOICE as i, RIME_KIND as n, cartesia as o, rime as r, RIME_DEFAULT_VOICE as t };

package/dist/s3-BtCMvCod.js

@@ -0,0 +1,37 @@
+//#region sdk/providers/kv/fs.ts
+const FS_KV_KIND = "fs";
+function fsKv(opts) {
+	return {
+		kind: "fs",
+		options: { ...opts }
+	};
+}
+//#endregion
+//#region sdk/providers/kv/memory.ts
+const MEMORY_KV_KIND = "memory";
+function memoryKv() {
+	return {
+		kind: MEMORY_KV_KIND,
+		options: {}
+	};
+}
+//#endregion
+//#region sdk/providers/kv/redis.ts
+const REDIS_KV_KIND = "redis";
+function redisKv(opts = {}) {
+	return {
+		kind: REDIS_KV_KIND,
+		options: { ...opts }
+	};
+}
+//#endregion
+//#region sdk/providers/kv/s3.ts
+const S3_KV_KIND = "s3";
+function s3Kv(opts) {
+	return {
+		kind: "s3",
+		options: { ...opts }
+	};
+}
+//#endregion
+export { MEMORY_KV_KIND as a, fsKv as c, redisKv as i, s3Kv as n, memoryKv as o, REDIS_KV_KIND as r, FS_KV_KIND as s, S3_KV_KIND as t };

package/dist/sdk/_internal-types.d.ts

@@ -5,7 +5,7 @@
  */
 import type { JSONSchema7 } from "json-schema";
 import { z } from "zod";
-import { type LlmProvider, type SttProvider, type TtsProvider } from "./providers.ts";
+import { type KvProvider, type LlmProvider, type SttProvider, type TtsProvider, type VectorProvider } from "./providers.ts";
 import type { Message } from "./types.ts";
 import { type ToolDef } from "./types.ts";
 /**
@@ -68,6 +68,14 @@ export declare const AgentConfigSchema: z.ZodObject<{
         s2s: "s2s";
         pipeline: "pipeline";
     }>>;
+    kv: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+    vector: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        options: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Serializable agent configuration — derived from {@link AgentConfigSchema}. */
 export type AgentConfig = z.infer<typeof AgentConfigSchema>;
@@ -88,6 +96,8 @@ export interface AgentConfigSource {
     stt?: SttProvider | undefined;
     llm?: LlmProvider | undefined;
     tts?: TtsProvider | undefined;
+    kv?: KvProvider | undefined;
+    vector?: VectorProvider | undefined;
 }
 /**
  * Extract the serializable {@link AgentConfig} subset from a source object.

package/dist/sdk/define.d.ts

@@ -2,7 +2,7 @@
  * Helper functions for defining agents and tools with full type inference.
  */
 import type { z } from "zod";
-import type { LlmProvider, SttProvider, TtsProvider } from "./providers.ts";
+import type { KvProvider, LlmProvider, SttProvider, TtsProvider, VectorProvider } from "./providers.ts";
 import { type AgentDef, type BuiltinTool, type ToolChoice, type ToolContext, type ToolDef } from "./types.ts";
 /**
  * Define a tool with typed parameters and execute function.
@@ -84,4 +84,8 @@ export declare function agent(def: {
      * enable pipeline mode.
      */
     tts?: TtsProvider;
+    /** Pluggable KV backend. Falls back to platform default when omitted. */
+    kv?: KvProvider;
+    /** Pluggable Vector backend. Falls back to platform default when omitted. */
+    vector?: VectorProvider;
 }): AgentDef;

package/dist/sdk/manifest-barrel.js

@@ -1,2 +1,2 @@
-import { a as toAgentConfig, i as agentToolsToSchemas, n as EMPTY_PARAMS, o as ProviderDescriptorSchema, r as ToolSchemaSchema, s as assertProviderTriple, t as AgentConfigSchema } from "../_internal-types-DFL07G3f.js";
+import { a as toAgentConfig, i as agentToolsToSchemas, n as EMPTY_PARAMS, o as ProviderDescriptorSchema, r as ToolSchemaSchema, s as assertProviderTriple, t as AgentConfigSchema } from "../_internal-types-CrnTi9Ew.js";
 export { AgentConfigSchema, EMPTY_PARAMS, ProviderDescriptorSchema, ToolSchemaSchema, agentToolsToSchemas, assertProviderTriple, toAgentConfig };

package/dist/sdk/manifest.d.ts

@@ -5,7 +5,7 @@
  * then used as a plain typed object throughout the runtime.
  */
 import { z } from "zod";
-import { type LlmProvider, type SessionMode, type SttProvider, type TtsProvider } from "./providers.ts";
+import { type KvProvider, type LlmProvider, type SessionMode, type SttProvider, type TtsProvider, type VectorProvider } from "./providers.ts";
 /**
  * Tool definition as it appears in the serialized manifest JSON.
  *
@@ -56,6 +56,10 @@ export type Manifest = {
      * enable pipeline mode.
      */
     tts?: TtsProvider | undefined;
+    /** Pluggable KV backend descriptor. Falls back to platform default when omitted. */
+    kv?: KvProvider | undefined;
+    /** Pluggable Vector backend descriptor. Falls back to platform default when omitted. */
+    vector?: VectorProvider | undefined;
     /**
      * Session mode derived from provider fields:
      * - `"s2s"` (default): AssemblyAI Streaming Speech-to-Speech path (no stt/llm/tts set).

package/dist/sdk/protocol.d.ts

@@ -55,6 +55,42 @@ export declare const KvRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "op">;
 /** KV operation request — discriminated union on the `op` field. */
 export type KvRequest = z.infer<typeof KvRequestSchema>;
+/** Zod schema for the Vector "upsert" operation. */
+export declare const VectorUpsertSchema: z.ZodObject<{
+    op: z.ZodLiteral<"upsert">;
+    id: z.ZodString;
+    text: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** Zod schema for the Vector "query" operation. */
+export declare const VectorQuerySchema: z.ZodObject<{
+    op: z.ZodLiteral<"query">;
+    text: z.ZodString;
+    topK: z.ZodOptional<z.ZodNumber>;
+    filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/** Zod schema for the Vector "delete" operation. */
+export declare const VectorDeleteSchema: z.ZodObject<{
+    op: z.ZodLiteral<"delete">;
+    ids: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+}, z.core.$strip>;
+/** Zod schema for Vector operation requests from the worker to the host. */
+export declare const VectorRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"upsert">;
+    id: z.ZodString;
+    text: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"query">;
+    text: z.ZodString;
+    topK: z.ZodOptional<z.ZodNumber>;
+    filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"delete">;
+    ids: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+}, z.core.$strip>], "op">;
+/** Vector operation request — discriminated union on the `op` field. */
+export type VectorRequest = z.infer<typeof VectorRequestSchema>;
 /**
  * Zod schema for session error codes.
  * @public

package/dist/sdk/protocol.js

@@ -67,6 +67,31 @@ const KvRequestSchema = z.discriminatedUnion("op", [
 	KvSetSchema,
 	KvDelSchema
 ]);
+/** Zod schema for the Vector "upsert" operation. */
+const VectorUpsertSchema = z.object({
+	op: z.literal("upsert"),
+	id: z.string().min(1),
+	text: z.string().min(1),
+	metadata: z.record(z.string(), z.unknown()).optional()
+});
+/** Zod schema for the Vector "query" operation. */
+const VectorQuerySchema = z.object({
+	op: z.literal("query"),
+	text: z.string().min(1),
+	topK: z.number().int().positive().max(100).optional(),
+	filter: z.record(z.string(), z.unknown()).optional()
+});
+/** Zod schema for the Vector "delete" operation. */
+const VectorDeleteSchema = z.object({
+	op: z.literal("delete"),
+	ids: z.union([z.string().min(1), z.array(z.string().min(1)).max(1e3)])
+});
+/** Zod schema for Vector operation requests from the worker to the host. */
+const VectorRequestSchema = z.discriminatedUnion("op", [
+	VectorUpsertSchema,
+	VectorQuerySchema,
+	VectorDeleteSchema
+]);
 /**
 * Zod schema for session error codes.
 * @public
@@ -163,4 +188,4 @@ function buildReadyConfig(s2sConfig) {
 	};
 }
 //#endregion
-export { ClientEventSchema, ClientMessageSchema, KvDelSchema, KvGetSchema, KvRequestSchema, KvSetSchema, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, buildReadyConfig, lenientParse };
+export { ClientEventSchema, ClientMessageSchema, KvDelSchema, KvGetSchema, KvRequestSchema, KvSetSchema, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, VectorDeleteSchema, VectorQuerySchema, VectorRequestSchema, VectorUpsertSchema, buildReadyConfig, lenientParse };

package/dist/sdk/providers/kv/fs.d.ts

@@ -0,0 +1,12 @@
+/** Filesystem KV descriptor — unstorage `fs` driver. */
+import type { KvProvider } from "../../providers.ts";
+export declare const FS_KV_KIND: "fs";
+export interface FsKvOptions {
+    /** Directory to store key files under. Created on first write. */
+    base: string;
+}
+export type FsKvProvider = KvProvider & {
+    readonly kind: typeof FS_KV_KIND;
+    readonly options: FsKvOptions;
+};
+export declare function fsKv(opts: FsKvOptions): FsKvProvider;

package/dist/sdk/providers/kv/memory.d.ts

@@ -0,0 +1,9 @@
+/** In-memory KV descriptor — unstorage default driver. */
+import type { KvProvider } from "../../providers.ts";
+export declare const MEMORY_KV_KIND: "memory";
+export type MemoryKvOptions = Record<string, never>;
+export type MemoryKvProvider = KvProvider & {
+    readonly kind: typeof MEMORY_KV_KIND;
+    readonly options: MemoryKvOptions;
+};
+export declare function memoryKv(): MemoryKvProvider;

package/dist/sdk/providers/kv/redis.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Redis KV descriptor.
+ *
+ * Resolves to unstorage's `redis` driver. Connection URL is pulled
+ * from the agent env (`REDIS_URL`) at session start.
+ */
+import type { KvProvider } from "../../providers.ts";
+export declare const REDIS_KV_KIND: "redis";
+export interface RedisKvOptions {
+    /** Force TLS. Defaults to inferring from `rediss://` URL scheme. */
+    tls?: boolean;
+}
+export type RedisKvProvider = KvProvider & {
+    readonly kind: typeof REDIS_KV_KIND;
+    readonly options: RedisKvOptions;
+};
+export declare function redisKv(opts?: RedisKvOptions): RedisKvProvider;

package/dist/sdk/providers/kv/s3.d.ts

@@ -0,0 +1,25 @@
+/**
+ * S3-compatible KV descriptor.
+ *
+ * Resolves to unstorage's `s3` driver — works with AWS S3, Tigris,
+ * Cloudflare R2, and other S3-protocol stores. Credentials are
+ * pulled from the agent env at session start (the descriptor stays
+ * secret-free).
+ *
+ * Required agent env: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`.
+ * Optional: `AWS_SESSION_TOKEN` (for temporary credentials).
+ */
+import type { KvProvider } from "../../providers.ts";
+export declare const S3_KV_KIND: "s3";
+export interface S3KvOptions {
+    bucket: string;
+    /** Custom endpoint URL — required for non-AWS providers (Tigris, R2). */
+    endpoint?: string;
+    /** Region. Defaults to `"auto"`. */
+    region?: string;
+}
+export type S3KvProvider = KvProvider & {
+    readonly kind: typeof S3_KV_KIND;
+    readonly options: S3KvOptions;
+};
+export declare function s3Kv(opts: S3KvOptions): S3KvProvider;

package/dist/sdk/providers/kv-barrel.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@alexkroman1/aai/kv` subpath barrel.
+ *
+ * Re-exports KV descriptor factories. Importing this barrel does
+ * not pull in any unstorage driver — the host resolver handles that
+ * at session start.
+ */
+export type { Kv } from "../kv.ts";
+export type { KvProvider } from "../providers.ts";
+export * from "./kv/fs.ts";
+export * from "./kv/memory.ts";
+export * from "./kv/redis.ts";
+export * from "./kv/s3.ts";

package/dist/sdk/providers/kv-barrel.js

@@ -0,0 +1,2 @@
+import { a as MEMORY_KV_KIND, c as fsKv, i as redisKv, n as s3Kv, o as memoryKv, r as REDIS_KV_KIND, s as FS_KV_KIND, t as S3_KV_KIND } from "../../s3-BtCMvCod.js";
+export { FS_KV_KIND, MEMORY_KV_KIND, REDIS_KV_KIND, S3_KV_KIND, fsKv, memoryKv, redisKv, s3Kv };

package/dist/sdk/providers/llm-barrel.js

@@ -1,2 +1,2 @@
-import { a as MISTRAL_KIND, c as groq, d as ANTHROPIC_KIND, f as anthropic, i as openai, l as GOOGLE_KIND, n as xai, o as mistral, r as OPENAI_KIND, s as GROQ_KIND, t as XAI_KIND, u as google } from "../../xai-jfQsxxPZ.js";
+import { a as MISTRAL_KIND, c as groq, d as ANTHROPIC_KIND, f as anthropic, i as openai, l as GOOGLE_KIND, n as xai, o as mistral, r as OPENAI_KIND, s as GROQ_KIND, t as XAI_KIND, u as google } from "../../xai-BDI61Y2M.js";
 export { ANTHROPIC_KIND, GOOGLE_KIND, GROQ_KIND, MISTRAL_KIND, OPENAI_KIND, XAI_KIND, anthropic, google, groq, mistral, openai, xai };

package/dist/sdk/providers/stt-barrel.js

@@ -1,2 +1,2 @@
-import { a as ASSEMBLYAI_KIND, c as deepgram, i as elevenlabs, n as soniox, o as assemblyAI, r as ELEVENLABS_KIND, s as DEEPGRAM_KIND, t as SONIOX_KIND } from "../../soniox-DCQ3GqJq.js";
+import { a as DEEPGRAM_KIND, c as assemblyAI, i as elevenlabs, n as soniox, o as deepgram, r as ELEVENLABS_KIND, s as ASSEMBLYAI_KIND, t as SONIOX_KIND } from "../../soniox-BQdL0mB5.js";
 export { ASSEMBLYAI_KIND, DEEPGRAM_KIND, ELEVENLABS_KIND, SONIOX_KIND, assemblyAI, deepgram, elevenlabs, soniox };

package/dist/sdk/providers/tts-barrel.js

@@ -1,2 +1,2 @@
-import { a as RIME_KIND, i as RIME_DEFAULT_VOICE, n as CARTESIA_KIND, o as rime, r as cartesia, t as CARTESIA_DEFAULT_VOICE } from "../../cartesia-BfQPOQ7Y.js";
+import { a as CARTESIA_KIND, i as CARTESIA_DEFAULT_VOICE, n as RIME_KIND, o as cartesia, r as rime, t as RIME_DEFAULT_VOICE } from "../../rime-58p9mDR8.js";
 export { CARTESIA_DEFAULT_VOICE, CARTESIA_KIND, RIME_DEFAULT_VOICE, RIME_KIND, cartesia, rime };

package/dist/sdk/providers/vector/in-memory.d.ts

@@ -0,0 +1,15 @@
+/**
+ * In-memory Vector descriptor.
+ *
+ * Resolves to a process-local store with deterministic hash-based
+ * pseudo-embeddings. Quality is intentionally bad — the purpose is
+ * proving tool wiring during `aai dev`, not retrieval ranking.
+ */
+import type { VectorProvider } from "../../providers.ts";
+export declare const IN_MEMORY_VECTOR_KIND: "in-memory";
+export type InMemoryVectorOptions = Record<string, never>;
+export type InMemoryVectorProvider = VectorProvider & {
+    readonly kind: typeof IN_MEMORY_VECTOR_KIND;
+    readonly options: InMemoryVectorOptions;
+};
+export declare function inMemoryVector(): InMemoryVectorProvider;

package/dist/sdk/providers/vector/pinecone.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pinecone Vector descriptor.
+ *
+ * The descriptor flows through bundle → server → runtime without
+ * importing `@pinecone-database/pinecone`. The host-side resolver in
+ * `host/providers/resolve-vector.ts` constructs a real client during
+ * `createRuntime`, using `PINECONE_API_KEY` from the agent's env.
+ */
+import type { VectorProvider } from "../../providers.ts";
+export declare const PINECONE_VECTOR_KIND: "pinecone";
+export interface PineconeOptions {
+    /** Pinecone index name. The index must be created with integrated-inference embed config. */
+    index: string;
+}
+export type PineconeProvider = VectorProvider & {
+    readonly kind: typeof PINECONE_VECTOR_KIND;
+    readonly options: PineconeOptions;
+};
+export declare function pinecone(opts: PineconeOptions): PineconeProvider;

package/dist/sdk/providers/vector-barrel.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@alexkroman1/aai/vector` subpath barrel.
+ *
+ * Re-exports descriptor factories. Importing this barrel does not
+ * pull in `@pinecone-database/pinecone` — the host resolver handles
+ * that at session start.
+ */
+export type { VectorProvider } from "../providers.ts";
+export type { Vector, VectorMatch, VectorQueryOptions } from "../vector.ts";
+export * from "./vector/in-memory.ts";
+export * from "./vector/pinecone.ts";

package/dist/sdk/providers/vector-barrel.js

@@ -0,0 +1,2 @@
+import { i as inMemoryVector, n as pinecone, r as IN_MEMORY_VECTOR_KIND, t as PINECONE_VECTOR_KIND } from "../../pinecone-CeJ69aRs.js";
+export { IN_MEMORY_VECTOR_KIND, PINECONE_VECTOR_KIND, inMemoryVector, pinecone };

package/dist/sdk/providers.d.ts

@@ -39,6 +39,10 @@ export type SttProvider = ProviderDescriptor<string, Record<string, unknown>>;
 export type LlmProvider = ProviderDescriptor<string, Record<string, unknown>>;
 /** Descriptor for a TTS provider. Returned by factories like `cartesia(...)`. */
 export type TtsProvider = ProviderDescriptor<string, Record<string, unknown>>;
+/** Descriptor for a KV backend. Returned by factories like `redisKv()`. */
+export type KvProvider = ProviderDescriptor<string, Record<string, unknown>>;
+/** Descriptor for a Vector backend. Returned by factories like `pinecone(...)`. */
+export type VectorProvider = ProviderDescriptor<string, Record<string, unknown>>;
 /**
  * Session mode derived from which provider triple is set.
  *

package/dist/sdk/types.d.ts

@@ -3,7 +3,8 @@
  */
 import { z } from "zod";
 import type { Kv } from "./kv.ts";
-import type { LlmProvider, SttProvider, TtsProvider } from "./providers.ts";
+import type { KvProvider, LlmProvider, SttProvider, TtsProvider, VectorProvider } from "./providers.ts";
+import type { Vector } from "./vector.ts";
 /**
  * Identifier for a built-in server-side tool.
  *
@@ -74,6 +75,8 @@ export type ToolContext<S = Record<string, unknown>> = {
     state: S;
     /** Key-value store scoped to this agent deployment. */
     kv: Kv;
+    /** Vector store scoped to this agent deployment. */
+    vector: Vector;
     /** Read-only snapshot of conversation messages so far. */
     messages: readonly Message[];
     /** Unique identifier for the current session. Useful for correlating logs across concurrent sessions. */
@@ -204,6 +207,10 @@ export type AgentDef<S = Record<string, unknown>> = {
      * pipeline mode.
      */
     tts?: TtsProvider;
+    /** Pluggable KV backend. Falls back to platform default when omitted. */
+    kv?: KvProvider;
+    /** Pluggable Vector backend. Falls back to platform default when omitted. */
+    vector?: VectorProvider;
 };
 /** @internal Zod schema for {@link BuiltinTool}. Exported for reuse in internal schemas. */
 export declare const BuiltinToolSchema: z.ZodEnum<{

package/dist/sdk/vector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Vector storage interface used by agents.
+ *
+ * Agents access the store via `ctx.vector`. Backends embed text on
+ * write and run similarity search on read; the interface is text-in,
+ * matches-out so users never deal with embedding vectors directly.
+ *
+ * @public
+ */
+export type VectorMatch = {
+    id: string;
+    score: number;
+    text: string;
+    metadata?: Record<string, unknown>;
+};
+/** @public */
+export type VectorQueryOptions = {
+    /** Number of results to return. Default 5, max 100. */
+    topK?: number;
+    /** Backend-specific filter (Pinecone uses MongoDB-like operators). */
+    filter?: Record<string, unknown>;
+};
+/** @public */
+export type Vector = {
+    upsert(id: string, text: string, metadata?: Record<string, unknown>): Promise<void>;
+    query(text: string, opts?: VectorQueryOptions): Promise<VectorMatch[]>;
+    delete(ids: string | string[]): Promise<void>;
+    close?(): void;
+};

package/dist/{soniox-DCQ3GqJq.js → soniox-BQdL0mB5.js}

@@ -1,33 +1,33 @@
-//#region sdk/providers/stt/deepgram.ts
+//#region sdk/providers/stt/assemblyai.ts
 /** Kind tag recognised by the host-side resolver. */
-const DEEPGRAM_KIND = "deepgram";
+const ASSEMBLYAI_KIND = "assemblyai";
 /**
-* Build a Deepgram STT descriptor.
+* Build an AssemblyAI STT descriptor.
 *
 * The API key is resolved host-side from the agent's env
-* (`DEEPGRAM_API_KEY`); there is no factory-time key parameter, so the
+* (`ASSEMBLYAI_API_KEY`); there is no factory-time key parameter, so the
 * descriptor stays free of secrets and safe to serialize.
 */
-function deepgram(opts = {}) {
+function assemblyAI(opts = {}) {
 	return {
-		kind: DEEPGRAM_KIND,
+		kind: ASSEMBLYAI_KIND,
 		options: { ...opts }
 	};
 }
 //#endregion
-//#region sdk/providers/stt/assemblyai.ts
+//#region sdk/providers/stt/deepgram.ts
 /** Kind tag recognised by the host-side resolver. */
-const ASSEMBLYAI_KIND = "assemblyai";
+const DEEPGRAM_KIND = "deepgram";
 /**
-* Build an AssemblyAI STT descriptor.
+* Build a Deepgram 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
+* (`DEEPGRAM_API_KEY`); there is no factory-time key parameter, so the
 * descriptor stays free of secrets and safe to serialize.
 */
-function assemblyAI(opts = {}) {
+function deepgram(opts = {}) {
 	return {
-		kind: ASSEMBLYAI_KIND,
+		kind: DEEPGRAM_KIND,
 		options: { ...opts }
 	};
 }
@@ -66,4 +66,4 @@ function soniox(opts = {}) {
 	};
 }
 //#endregion
-export { ASSEMBLYAI_KIND as a, deepgram as c, elevenlabs as i, soniox as n, assemblyAI as o, ELEVENLABS_KIND as r, DEEPGRAM_KIND as s, SONIOX_KIND as t };
+export { DEEPGRAM_KIND as a, assemblyAI as c, elevenlabs as i, soniox as n, deepgram as o, ELEVENLABS_KIND as r, ASSEMBLYAI_KIND as s, SONIOX_KIND as t };

package/host/_runtime-conformance.ts

@@ -83,6 +83,16 @@ export const CONFORMANCE_AGENT: AgentDef = {
         return `stored:${JSON.stringify(result)}`;
       },
     },
+    vector_roundtrip: {
+      description: "Test Vector roundtrip via tool execution",
+      parameters: z.object({ text: z.string() }),
+      execute: async ({ text }: { text: string }, ctx) => {
+        await ctx.vector.upsert("conformance-doc", text);
+        const matches = await ctx.vector.query(text, { topK: 1 });
+        await ctx.vector.delete("conformance-doc");
+        return matches[0]?.text ?? "(none)";
+      },
+    },
   },
 };
 
@@ -130,6 +140,17 @@ export function testRuntime(label: string, getContext: () => RuntimeTestContext)
       expect(result).toBe('stored:"abc"');
     });
 
+    test("Vector round-trip through tool context", async () => {
+      const { executeTool } = getContext();
+      const vectorResult = await executeTool(
+        "vector_roundtrip",
+        { text: "conformance-input" },
+        "s1",
+        [],
+      );
+      expect(vectorResult).toBe("conformance-input");
+    });
+
     // ── Session state ────────────────────────────────────────────────
 
     test("session state is initialized from factory", async () => {

package/host/_test-utils.ts

@@ -22,6 +22,7 @@ export function createMockToolContext(overrides?: Partial<ToolContext>): ToolCon
     env: {},
     state: {},
     kv: {} as never,
+    vector: {} as never,
     messages: [],
     sessionId: "test-session",
     send: vi.fn(),