@alexkroman1/aai 0.12.2 → 1.0.2

package/host/fixtures/session-updated.json

@@ -0,0 +1,45 @@
+[
+  {
+    "type": "session.updated",
+    "timestamp": 1774669383.6972675,
+    "config": {
+      "system_prompt": "You are a helpful assistant. Keep responses very short, under 10 words.",
+      "tools": [],
+      "greeting": "Hello! How can I help you today?"
+    }
+  },
+  {
+    "type": "session.updated",
+    "timestamp": 1774669390.5091305,
+    "config": {
+      "system_prompt": "You are a helpful assistant. Keep responses to one short sentence.",
+      "tools": [],
+      "greeting": "Hi!"
+    }
+  },
+  {
+    "type": "session.updated",
+    "timestamp": 1774669401.4762232,
+    "config": {
+      "system_prompt": "You are a weather assistant. Always use the get_weather tool for weather questions. After getting the result, tell the user the weather in one sentence.",
+      "tools": [
+        {
+          "type": "function",
+          "name": "get_weather",
+          "description": "Get the current weather for a city",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "city": {
+                "type": "string",
+                "description": "City name"
+              }
+            },
+            "required": ["city"]
+          }
+        }
+      ],
+      "greeting": "Ask me about the weather!"
+    }
+  }
+]

package/host/fixtures/simple-question-sequence.json

@@ -0,0 +1,73 @@
+[
+  {
+    "type": "session.updated",
+    "timestamp": 1774669390.5091305,
+    "config": {
+      "system_prompt": "You are a helpful assistant. Keep responses to one short sentence.",
+      "tools": [],
+      "greeting": "Hi!"
+    }
+  },
+  {
+    "type": "session.ready",
+    "timestamp": 1774669390.5586526,
+    "session_id": "sess_2246ce7e2eb146e08e62c9476278fbef",
+    "config": {
+      "system_prompt": "You are a helpful assistant. Keep responses to one short sentence.",
+      "tools": [],
+      "greeting": "Hi!"
+    }
+  },
+  {
+    "type": "reply.started",
+    "timestamp": 1774669390.5646203,
+    "reply_id": "resp_b202d16235bf47c39e9704df37c45e1c"
+  },
+  {
+    "type": "transcript.agent",
+    "timestamp": 1774669391.9406674,
+    "reply_id": "resp_b202d16235bf47c39e9704df37c45e1c",
+    "item_id": "msg_8c5ec0e896704aaf99db0aaa564ce98f",
+    "text": "Hi!",
+    "interrupted": false
+  },
+  {
+    "type": "reply.done",
+    "timestamp": 1774669392.302396,
+    "reply_id": "resp_b202d16235bf47c39e9704df37c45e1c",
+    "status": "completed"
+  },
+  {
+    "type": "input.speech.started",
+    "timestamp": 1774669393.0812206
+  },
+  {
+    "type": "reply.started",
+    "timestamp": 1774669393.4352796,
+    "reply_id": "resp_a3b4fed4e6d9413bbf51fd55324a5a0a"
+  },
+  {
+    "type": "input.speech.stopped",
+    "timestamp": 1774669394.1324704
+  },
+  {
+    "type": "transcript.user",
+    "timestamp": 1774669394.2344203,
+    "item_id": "msg_8ee3b8ef00ec4354ae5c084bebfc5361",
+    "text": "Tell me a fun fact about space."
+  },
+  {
+    "type": "transcript.agent",
+    "timestamp": 1774669397.911438,
+    "reply_id": "resp_a3b4fed4e6d9413bbf51fd55324a5a0a",
+    "item_id": "msg_54b36b413ce94b62a66926dbd4475508",
+    "text": "A day on Venus is longer than its year.",
+    "interrupted": false
+  },
+  {
+    "type": "reply.done",
+    "timestamp": 1774669398.1820145,
+    "reply_id": "resp_a3b4fed4e6d9413bbf51fd55324a5a0a",
+    "status": "completed"
+  }
+]

package/host/fixtures/tool-call-sequence.json

@@ -0,0 +1,114 @@
+[
+  {
+    "type": "session.updated",
+    "timestamp": 1774669401.4762232,
+    "config": {
+      "system_prompt": "You are a weather assistant. Always use the get_weather tool for weather questions. After getting the result, tell the user the weather in one sentence.",
+      "tools": [
+        {
+          "type": "function",
+          "name": "get_weather",
+          "description": "Get the current weather for a city",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "city": {
+                "type": "string",
+                "description": "City name"
+              }
+            },
+            "required": ["city"]
+          }
+        }
+      ],
+      "greeting": "Ask me about the weather!"
+    }
+  },
+  {
+    "type": "session.ready",
+    "timestamp": 1774669401.5069516,
+    "session_id": "sess_b01d5d5f1865418b955dc30b00b3d52b",
+    "config": {
+      "system_prompt": "You are a weather assistant. Always use the get_weather tool for weather questions. After getting the result, tell the user the weather in one sentence.",
+      "tools": [
+        {
+          "type": "function",
+          "name": "get_weather",
+          "description": "Get the current weather for a city",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "city": {
+                "type": "string",
+                "description": "City name"
+              }
+            },
+            "required": ["city"]
+          }
+        }
+      ],
+      "greeting": "Ask me about the weather!"
+    }
+  },
+  {
+    "type": "reply.started",
+    "timestamp": 1774669401.5081005,
+    "reply_id": "resp_0c5069c8a284417696b0fb94121b5302"
+  },
+  {
+    "type": "transcript.agent",
+    "timestamp": 1774669403.61195,
+    "reply_id": "resp_0c5069c8a284417696b0fb94121b5302",
+    "item_id": "msg_f3a8a53d8cce4ad6b92607ea38131f7d",
+    "text": "Ask me about the weather!",
+    "interrupted": false
+  },
+  {
+    "type": "reply.done",
+    "timestamp": 1774669403.9528494,
+    "reply_id": "resp_0c5069c8a284417696b0fb94121b5302",
+    "status": "completed"
+  },
+  {
+    "type": "input.speech.started",
+    "timestamp": 1774669404.8296304
+  },
+  {
+    "type": "reply.started",
+    "timestamp": 1774669405.0349832,
+    "reply_id": "resp_c8b83fbfde1d4dbc8cb39318c3012981"
+  },
+  {
+    "type": "input.speech.stopped",
+    "timestamp": 1774669406.0299
+  },
+  {
+    "type": "transcript.user",
+    "timestamp": 1774669406.184384,
+    "item_id": "msg_2ff13ff4b77b46e19d2b7f20ad88d822",
+    "text": "What is the weather like in San Francisco?"
+  },
+  {
+    "type": "tool.call",
+    "timestamp": 1774669406.466613,
+    "call_id": "chatcmpl-tool-9793a062159342bb8e221cbab79229e3",
+    "name": "get_weather",
+    "args": {
+      "city": "San Francisco"
+    }
+  },
+  {
+    "type": "transcript.agent",
+    "timestamp": 1774669417.728002,
+    "reply_id": "resp_c8b83fbfde1d4dbc8cb39318c3012981",
+    "item_id": "msg_8421a07d995e4f25b07983ce420b7eca",
+    "text": "The weather in San Francisco is sunny with a temperature of 72 degrees Fahrenheit, 45 percent humidity, and winds at 8 miles per hour from the northwest.",
+    "interrupted": false
+  },
+  {
+    "type": "reply.done",
+    "timestamp": 1774669417.9831085,
+    "reply_id": "resp_c8b83fbfde1d4dbc8cb39318c3012981",
+    "status": "completed"
+  }
+]

package/host/fixtures/tool-calls.json

@@ -0,0 +1,11 @@
+[
+  {
+    "type": "tool.call",
+    "timestamp": 1774669406.466613,
+    "call_id": "chatcmpl-tool-9793a062159342bb8e221cbab79229e3",
+    "name": "get_weather",
+    "args": {
+      "city": "San Francisco"
+    }
+  }
+]

package/host/fixtures/tool-config-session-sequence.json

@@ -0,0 +1,51 @@
+[
+  {
+    "type": "session.updated",
+    "timestamp": 1774668542.389923,
+    "config": {
+      "system_prompt": "You are a weather assistant. Always use the get_weather tool when asked about weather. Keep responses under 10 words.",
+      "tools": [
+        {
+          "type": "function",
+          "name": "get_weather",
+          "description": "Get the current weather for a city",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "city": {
+                "type": "string",
+                "description": "City name"
+              }
+            },
+            "required": ["city"]
+          }
+        }
+      ]
+    }
+  },
+  {
+    "type": "session.ready",
+    "timestamp": 1774668542.4018698,
+    "session_id": "sess_d0b0b408c00944c49183bb2d6f18feb9",
+    "config": {
+      "system_prompt": "You are a weather assistant. Always use the get_weather tool when asked about weather. Keep responses under 10 words.",
+      "tools": [
+        {
+          "type": "function",
+          "name": "get_weather",
+          "description": "Get the current weather for a city",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "city": {
+                "type": "string",
+                "description": "City name"
+              }
+            },
+            "required": ["city"]
+          }
+        }
+      ]
+    }
+  }
+]

package/host/fixtures/user-speech-recognition.json

@@ -0,0 +1,30 @@
+[
+  {
+    "type": "input.speech.started",
+    "timestamp": 1774669393.0812206
+  },
+  {
+    "type": "input.speech.stopped",
+    "timestamp": 1774669394.1324704
+  },
+  {
+    "type": "transcript.user",
+    "timestamp": 1774669394.2344203,
+    "item_id": "msg_8ee3b8ef00ec4354ae5c084bebfc5361",
+    "text": "Tell me a fun fact about space."
+  },
+  {
+    "type": "input.speech.started",
+    "timestamp": 1774669404.8296304
+  },
+  {
+    "type": "input.speech.stopped",
+    "timestamp": 1774669406.0299
+  },
+  {
+    "type": "transcript.user",
+    "timestamp": 1774669406.184384,
+    "item_id": "msg_2ff13ff4b77b46e19d2b7f20ad88d822",
+    "text": "What is the weather like in San Francisco?"
+  }
+]

package/host/fixtures/web-search-sequence.json

@@ -0,0 +1,122 @@
+[
+  {
+    "type": "session.updated",
+    "timestamp": 1774669501.4762232,
+    "config": {
+      "system_prompt": "You are a research assistant. Use the web_search tool to find current information.",
+      "tools": [
+        {
+          "type": "function",
+          "name": "web_search",
+          "description": "Search the web for current information, facts, news, or answers to questions. Returns a list of results with title, URL, and description. Use this when the user asks about something you don't know, need up-to-date information, or want to verify facts.",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "query": {
+                "type": "string",
+                "description": "The search query"
+              },
+              "max_results": {
+                "type": "number",
+                "description": "Maximum number of results to return (default 5)"
+              }
+            },
+            "required": ["query"]
+          }
+        }
+      ],
+      "greeting": "Hi! I can search the web for you."
+    }
+  },
+  {
+    "type": "session.ready",
+    "timestamp": 1774669501.5069516,
+    "session_id": "sess_a12c3d4e5f6789ab0cde12345f678901",
+    "config": {
+      "system_prompt": "You are a research assistant. Use the web_search tool to find current information.",
+      "tools": [
+        {
+          "type": "function",
+          "name": "web_search",
+          "description": "Search the web for current information, facts, news, or answers to questions. Returns a list of results with title, URL, and description. Use this when the user asks about something you don't know, need up-to-date information, or want to verify facts.",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "query": {
+                "type": "string",
+                "description": "The search query"
+              },
+              "max_results": {
+                "type": "number",
+                "description": "Maximum number of results to return (default 5)"
+              }
+            },
+            "required": ["query"]
+          }
+        }
+      ],
+      "greeting": "Hi! I can search the web for you."
+    }
+  },
+  {
+    "type": "reply.started",
+    "timestamp": 1774669501.5081005,
+    "reply_id": "resp_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
+  },
+  {
+    "type": "transcript.agent",
+    "timestamp": 1774669503.61195,
+    "reply_id": "resp_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
+    "item_id": "msg_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
+    "text": "Hi! I can search the web for you.",
+    "interrupted": false
+  },
+  {
+    "type": "reply.done",
+    "timestamp": 1774669503.9528494,
+    "reply_id": "resp_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
+    "status": "completed"
+  },
+  {
+    "type": "input.speech.started",
+    "timestamp": 1774669504.8296304
+  },
+  {
+    "type": "reply.started",
+    "timestamp": 1774669505.0349832,
+    "reply_id": "resp_2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d"
+  },
+  {
+    "type": "input.speech.stopped",
+    "timestamp": 1774669506.0299
+  },
+  {
+    "type": "transcript.user",
+    "timestamp": 1774669506.184384,
+    "item_id": "msg_b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
+    "text": "Search for the latest Mars rover findings"
+  },
+  {
+    "type": "tool.call",
+    "timestamp": 1774669506.466613,
+    "call_id": "chatcmpl-tool-8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d",
+    "name": "web_search",
+    "args": {
+      "query": "latest Mars rover findings"
+    }
+  },
+  {
+    "type": "transcript.agent",
+    "timestamp": 1774669517.728002,
+    "reply_id": "resp_2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d",
+    "item_id": "msg_c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8",
+    "text": "Based on my search, NASA's Perseverance rover has discovered organic molecules in Jezero Crater.",
+    "interrupted": false
+  },
+  {
+    "type": "reply.done",
+    "timestamp": 1774669517.9831085,
+    "reply_id": "resp_2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d",
+    "status": "completed"
+  }
+]

package/host/integration.test.ts

@@ -0,0 +1,222 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Integration tests for the SDK public API surface.
+ *
+ * These test the connected flow as a consumer would use it:
+ * AgentDef → tools → direct executor → KV in tool context.
+ */
+
+import { createStorage } from "unstorage";
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import { toAgentConfig } from "../sdk/_internal-types.ts";
+import type { AgentDef } from "../sdk/types.ts";
+import { createRuntime } from "./runtime.ts";
+import { createUnstorageKv } from "./unstorage-kv.ts";
+
+describe("SDK integration: AgentDef → tool execution", () => {
+  test("AgentDef + tools + executeToolCall round-trip", async () => {
+    const agent: AgentDef = {
+      name: "test-agent",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      tools: {
+        greet: {
+          description: "Greet by name",
+          parameters: z.object({ name: z.string() }),
+          execute: ({ name }: { name: string }) => `Hello, ${name}!`,
+        },
+      },
+    };
+
+    const exec = createRuntime({ agent, env: {} });
+    const result = await exec.executeTool("greet", { name: "Alice" }, "s1", []);
+    expect(result).toBe("Hello, Alice!");
+  });
+
+  test("tool with KV access works end-to-end", async () => {
+    const kv = createUnstorageKv({ storage: createStorage() });
+    const agent: AgentDef = {
+      name: "kv-agent",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      tools: {
+        save: {
+          description: "Save a value",
+          parameters: z.object({ key: z.string(), value: z.string() }),
+          execute: async ({ key, value }: { key: string; value: string }, ctx) => {
+            await ctx.kv.set(key, value);
+            return "saved";
+          },
+        },
+        load: {
+          description: "Load a value",
+          parameters: z.object({ key: z.string() }),
+          execute: async ({ key }: { key: string }, ctx) => {
+            const val = await ctx.kv.get<string>(key);
+            return val ?? "not found";
+          },
+        },
+      },
+    };
+
+    const exec = createRuntime({ agent, env: {}, kv });
+    await exec.executeTool("save", { key: "color", value: "blue" }, "s1", []);
+    const result = await exec.executeTool("load", { key: "color" }, "s1", []);
+    expect(result).toBe("blue");
+  });
+
+  test("env vars are passed to tool context", async () => {
+    const agent: AgentDef = {
+      name: "env-agent",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      tools: {
+        check_key: {
+          description: "Check API key",
+          execute: (_args, ctx) => ctx.env.API_KEY ?? "missing",
+        },
+      },
+    };
+
+    const exec = createRuntime({ agent, env: { API_KEY: "sk-test-123" } });
+    const result = await exec.executeTool("check_key", {}, "s1", []);
+    expect(result).toBe("sk-test-123");
+  });
+
+  test("per-session state isolation", async () => {
+    const agent: AgentDef<{ count: number }> = {
+      name: "state-agent",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      state: () => ({ count: 0 }),
+      tools: {
+        increment: {
+          description: "Increment counter",
+          execute: (_args, ctx) => {
+            ctx.state.count += 1;
+            return String(ctx.state.count);
+          },
+        },
+      },
+    };
+
+    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");
+  });
+
+  test("unknown tool returns error JSON", async () => {
+    const agent: AgentDef = {
+      name: "test",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      tools: {},
+    };
+    const exec = createRuntime({ agent, env: {} });
+    const result = await exec.executeTool("nonexistent", {}, "s1", []);
+    expect(JSON.parse(result)).toEqual({ error: "Unknown tool: nonexistent" });
+  });
+
+  test("tool parameter validation rejects bad input", async () => {
+    const agent: AgentDef = {
+      name: "validation-agent",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      tools: {
+        typed: {
+          description: "Typed tool",
+          parameters: z.object({ count: z.number() }),
+          execute: ({ count }: { count: number }) => String(count * 2),
+        },
+      },
+    };
+
+    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");
+  });
+
+  test("toAgentConfig produces serializable config", () => {
+    const agent: AgentDef = {
+      name: "config-test",
+      systemPrompt: "Custom instructions",
+      greeting: "Hello!",
+      maxSteps: 10,
+      tools: {},
+      builtinTools: ["web_search"],
+      toolChoice: "required",
+    };
+
+    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");
+    expect(parsed.builtinTools).toEqual(["web_search"]);
+    expect(parsed.maxSteps).toBe(10);
+    expect(parsed.toolChoice).toBe("required");
+  });
+
+  test("builtin tools are available alongside custom tools", async () => {
+    const agent: AgentDef = {
+      name: "mixed-tools",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      builtinTools: ["run_code"],
+      tools: {
+        custom: { description: "Custom tool", execute: () => "custom result" },
+      },
+    };
+
+    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")' },
+      "s1",
+      [],
+    );
+    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");
+  });
+
+  test("messages are passed through to tool context", async () => {
+    const agent: AgentDef = {
+      name: "messages-agent",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      tools: {
+        count_msgs: {
+          description: "Count messages",
+          execute: (_args, ctx) => String(ctx.messages.length),
+        },
+      },
+    };
+
+    const exec = createRuntime({ agent, env: {} });
+    const result = await exec.executeTool("count_msgs", {}, "s1", [
+      { role: "user", content: "hi" },
+      { role: "assistant", content: "hello" },
+    ]);
+    expect(result).toBe("2");
+  });
+});