@alexkroman1/aai 1.7.1 → 1.8.0

package/host/session-core.ts

@@ -58,12 +58,14 @@ export type SessionCore = {
 export function createSessionCore(opts: SessionCoreOptions): SessionCore {
   const log = opts.logger ?? consoleLogger;
   const maxHistory = opts.maxHistory ?? DEFAULT_MAX_HISTORY;
-  const idleMs = (() => {
-    const raw = opts.agentConfig.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
-    return raw === 0 || !Number.isFinite(raw) ? 0 : raw;
-  })();
+  const rawIdleMs = opts.agentConfig.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+  const idleMs = rawIdleMs === 0 || !Number.isFinite(rawIdleMs) ? 0 : rawIdleMs;
 
-  let reply: ReplyState = { currentReplyId: null, pendingTools: [], toolCallCount: 0 };
+  function emptyReply(): ReplyState {
+    return { currentReplyId: null, pendingTools: [], toolCallCount: 0 };
+  }
+
+  let reply: ReplyState = emptyReply();
   let history: Message[] = [];
   let turnPromise: Promise<void> | null = null;
   let idleTimer: NodeJS.Timeout | null = null;
@@ -90,12 +92,12 @@ export function createSessionCore(opts: SessionCoreOptions): SessionCore {
   }
 
   function beginReply(replyId: string): void {
-    reply = { currentReplyId: replyId, pendingTools: [], toolCallCount: 0 };
+    reply = { ...emptyReply(), currentReplyId: replyId };
     turnPromise = null;
   }
 
   function cancelReply(): void {
-    reply = { currentReplyId: null, pendingTools: [], toolCallCount: 0 };
+    reply = emptyReply();
   }
 
   function flushReply(startMs: number, hadTurnPromise: boolean): void {
@@ -209,12 +211,7 @@ export function createSessionCore(opts: SessionCoreOptions): SessionCore {
     },
 
     onToolCall(callId, name, args) {
-      emit({
-        type: "tool_call",
-        toolCallId: callId,
-        toolName: name,
-        args: args as Record<string, unknown>,
-      });
+      emit({ type: "tool_call", toolCallId: callId, toolName: name, args });
       if (reply.currentReplyId === null) {
         log.warn("tool_call with no active reply", { sid: opts.id, name });
         return;

package/host/session-prompt.test.ts

@@ -4,13 +4,9 @@ import { DEFAULT_SYSTEM_PROMPT } from "../sdk/types.ts";
 import { makeConfig } from "./_test-utils.ts";
 
 describe("buildSystemPrompt", () => {
-  test("starts with DEFAULT_SYSTEM_PROMPT when no custom instructions", () => {
+  test("uses DEFAULT_SYSTEM_PROMPT with no agent-specific section when no custom instructions", () => {
     const result = buildSystemPrompt(makeConfig(), { hasTools: false });
     expect(result.startsWith(DEFAULT_SYSTEM_PROMPT)).toBe(true);
-  });
-
-  test("does not include agent-specific instructions section for default instructions", () => {
-    const result = buildSystemPrompt(makeConfig(), { hasTools: false });
     expect(result).not.toContain("Agent-Specific Instructions:");
   });
 

package/host/to-vercel-tools.test.ts

@@ -1,6 +1,7 @@
 // Copyright 2025 the AAI authors. MIT license.
+import type { Tool, ToolExecutionOptions } from "ai";
 import { describe, expect, test, vi } from "vitest";
-import type { ExecuteTool, ToolSchema } from "../sdk/_internal-types.ts";
+import type { ExecuteTool, ExecuteToolOptions, ToolSchema } from "../sdk/_internal-types.ts";
 import type { Message } from "../sdk/types.ts";
 import { toVercelTools } from "./to-vercel-tools.ts";
 
@@ -17,6 +18,15 @@ const schemas: ToolSchema[] = [
   },
 ];
 
+function runTool(
+  tool: Tool | undefined,
+  args: Readonly<Record<string, unknown>>,
+  options: ToolExecutionOptions,
+): Promise<unknown> {
+  if (!tool?.execute) throw new Error("tool.execute missing");
+  return tool.execute(args, options);
+}
+
 describe("toVercelTools", () => {
   test("produces one Vercel AI SDK tool per schema, keyed by name", () => {
     const executeTool = vi.fn(async () => "sunny");
@@ -26,9 +36,7 @@ describe("toVercelTools", () => {
       messages: () => [],
     });
     expect(Object.keys(tools)).toEqual(["get_weather"]);
-    expect(tools.get_weather).toMatchObject({
-      description: "Look up the weather.",
-    });
+    expect(tools.get_weather).toMatchObject({ description: "Look up the weather." });
   });
 
   test("execute delegates to ctx.executeTool with (name, args, sessionId, messages)", async () => {
@@ -38,9 +46,13 @@ describe("toVercelTools", () => {
       sessionId: "sess-42",
       messages: () => [{ role: "user", content: "?" }],
     });
-    const result = await tools.get_weather?.execute?.(
+    const result = await runTool(
+      tools.get_weather,
       { city: "SF" },
-      { toolCallId: "tc-1", messages: [] },
+      {
+        toolCallId: "tc-1",
+        messages: [],
+      },
     );
     expect(executeTool).toHaveBeenCalledWith(
       "get_weather",
@@ -54,103 +66,77 @@ describe("toVercelTools", () => {
 
   test("execute passes through abort signal when provided", async () => {
     const controller = new AbortController();
-    const executeTool = vi.fn(
-      async (
-        _n: string,
-        _a: Readonly<Record<string, unknown>>,
-        _s?: string,
-        _m?: readonly unknown[],
-        opts?: { signal?: AbortSignal },
-      ) => {
-        expect(opts?.signal).toBe(controller.signal);
-        return "ok";
-      },
-    );
+    let received: ExecuteToolOptions | undefined;
+    const executeTool: ExecuteTool = async (_n, _a, _s, _m, opts) => {
+      received = opts;
+      return "ok";
+    };
     const tools = toVercelTools(schemas, {
       executeTool,
       sessionId: "s",
       messages: () => [],
       signal: controller.signal,
     });
-    await tools.get_weather?.execute?.({ city: "NY" }, { toolCallId: "tc-2", messages: [] });
-    expect(executeTool).toHaveBeenCalledTimes(1);
+    await runTool(tools.get_weather, { city: "NY" }, { toolCallId: "tc-2", messages: [] });
+    expect(received?.signal).toBe(controller.signal);
   });
 
   test("execute prefers options.abortSignal over ctx.signal", async () => {
     const ctxController = new AbortController();
     const callController = new AbortController();
-    let receivedSignal: AbortSignal | undefined;
-    const executeTool = vi.fn(
-      async (
-        _n: string,
-        _a: Readonly<Record<string, unknown>>,
-        _s?: string,
-        _m?: readonly unknown[],
-        opts?: { signal?: AbortSignal },
-      ) => {
-        receivedSignal = opts?.signal;
-        return "ok";
-      },
-    );
+    let received: ExecuteToolOptions | undefined;
+    const executeTool: ExecuteTool = async (_n, _a, _s, _m, opts) => {
+      received = opts;
+      return "ok";
+    };
     const tools = toVercelTools(schemas, {
       executeTool,
       sessionId: "s",
       messages: () => [],
       signal: ctxController.signal,
     });
-    await tools.get_weather?.execute?.(
+    await runTool(
+      tools.get_weather,
       { city: "NY" },
-      { toolCallId: "tc-1", messages: [], abortSignal: callController.signal },
+      {
+        toolCallId: "tc-1",
+        messages: [],
+        abortSignal: callController.signal,
+      },
     );
-    expect(receivedSignal).toBe(callController.signal);
+    expect(received?.signal).toBe(callController.signal);
   });
 
   test("execute falls back to ctx.signal when options.abortSignal is absent", async () => {
     const ctxController = new AbortController();
-    let receivedSignal: AbortSignal | undefined;
-    const executeTool = vi.fn(
-      async (
-        _n: string,
-        _a: Readonly<Record<string, unknown>>,
-        _s?: string,
-        _m?: readonly unknown[],
-        opts?: { signal?: AbortSignal },
-      ) => {
-        receivedSignal = opts?.signal;
-        return "ok";
-      },
-    );
+    let received: ExecuteToolOptions | undefined;
+    const executeTool: ExecuteTool = async (_n, _a, _s, _m, opts) => {
+      received = opts;
+      return "ok";
+    };
     const tools = toVercelTools(schemas, {
       executeTool,
       sessionId: "s",
       messages: () => [],
       signal: ctxController.signal,
     });
-    await tools.get_weather?.execute?.({ city: "NY" }, { toolCallId: "tc-2", messages: [] });
-    expect(receivedSignal).toBe(ctxController.signal);
+    await runTool(tools.get_weather, { city: "NY" }, { toolCallId: "tc-2", messages: [] });
+    expect(received?.signal).toBe(ctxController.signal);
   });
 
   test("execute propagates toolCallId from options", async () => {
-    let receivedCallId: string | undefined;
-    const executeTool = vi.fn(
-      async (
-        _n: string,
-        _a: Readonly<Record<string, unknown>>,
-        _s?: string,
-        _m?: readonly unknown[],
-        opts?: { toolCallId?: string },
-      ) => {
-        receivedCallId = opts?.toolCallId;
-        return "ok";
-      },
-    );
+    let received: ExecuteToolOptions | undefined;
+    const executeTool: ExecuteTool = async (_n, _a, _s, _m, opts) => {
+      received = opts;
+      return "ok";
+    };
     const tools = toVercelTools(schemas, {
       executeTool,
       sessionId: "s",
       messages: () => [],
     });
-    await tools.get_weather?.execute?.({ city: "NY" }, { toolCallId: "tc-3", messages: [] });
-    expect(receivedCallId).toBe("tc-3");
+    await runTool(tools.get_weather, { city: "NY" }, { toolCallId: "tc-3", messages: [] });
+    expect(received?.toolCallId).toBe("tc-3");
   });
 });
 
@@ -161,7 +147,6 @@ describe("toVercelTools — message snapshot isolation", () => {
 
     const executeTool: ExecuteTool = async (_name, _args, _sid, msgs) => {
       observedInsideExecute = msgs;
-      // Mutate the original array; the snapshot we captured must be unaffected.
       messagesBox.messages.push({ role: "user", content: "second" });
       return "ok";
     };
@@ -182,13 +167,9 @@ describe("toVercelTools — message snapshot isolation", () => {
       },
     );
 
-    const t = tools.t;
-    if (!t?.execute) throw new Error("tool.execute missing");
-    await t.execute({}, { toolCallId: "c1", messages: [] });
+    await runTool(tools.t, {}, { toolCallId: "c1", messages: [] });
 
-    // The caller-observable messages array has 2 entries after the push.
     expect(messagesBox.messages).toHaveLength(2);
-    // But the snapshot the tool executed against was frozen at length 1.
     expect(observedInsideExecute).toHaveLength(1);
     expect(observedInsideExecute?.[0]).toMatchObject({ content: "first" });
   });

package/host/to-vercel-tools.ts

@@ -1,18 +1,8 @@
 // Copyright 2025 the AAI authors. MIT license.
 /**
- * Converts agent {@link ToolSchema}[] to Vercel AI SDK tools with `execute`
- * delegation to the agent's {@link ExecuteTool} function.
- *
- * The pipeline orchestrator passes the output to `streamText({ tools })`.
- * Each produced tool's `execute` closure calls
- * `ctx.executeTool(name, args, sessionId, messages(), { signal, toolCallId })`,
- * so the existing agent tool infrastructure (argument validation, KV, hooks,
- * timeout) remains the single source of truth for tool behavior.
- *
- * Per-call `options.abortSignal` (forwarded by `streamText` when the
- * outer turn is aborted, e.g. barge-in) takes precedence over the
- * bag-level `ctx.signal` so individual invocations respect streamText
- * aborts.
+ * Converts agent {@link ToolSchema}[] to Vercel AI SDK tools, delegating
+ * `execute` to the agent's {@link ExecuteTool} so validation, KV, hooks,
+ * and timeouts remain the single source of truth for tool behavior.
  */
 
 import { jsonSchema, type Tool, type ToolExecutionOptions, tool } from "ai";
@@ -20,32 +10,12 @@ import type { ExecuteTool, ExecuteToolOptions, ToolSchema } from "../sdk/_intern
 import type { Message } from "../sdk/types.ts";
 
 export interface ToVercelToolsContext {
-  /** The agent's tool-execution function (from the runtime). */
   executeTool: ExecuteTool;
-  /** Session id threaded to {@link executeTool}. */
   sessionId: string;
-  /**
-   * Returns the current conversation history at call-time. The orchestrator
-   * calls this per invocation; `toVercelTools` snapshots the returned array
-   * before forwarding to `executeTool` so concurrent mutations cannot leak
-   * across tool calls.
-   */
   messages: () => readonly Message[];
-  /**
-   * Bag-level abort signal. Used as a fallback when the per-call
-   * `options.abortSignal` from Vercel's `ToolExecutionOptions` is absent.
-   */
   signal?: AbortSignal;
 }
 
-/**
- * Convert an array of {@link ToolSchema} to a Vercel AI SDK `ToolSet`
- * (record keyed by tool name).
- *
- * Uses the v6 `tool()` helper with `inputSchema: jsonSchema(...)` wrapping
- * the agent's JSON Schema `parameters`. Execution is delegated to
- * `ctx.executeTool` so validation, KV, timeouts, and hooks keep working.
- */
 export function toVercelTools(
   schemas: readonly ToolSchema[],
   ctx: ToVercelToolsContext,
@@ -57,16 +27,16 @@ export function toVercelTools(
       inputSchema: jsonSchema(schema.parameters),
       execute: async (args: unknown, options: ToolExecutionOptions) => {
         const input = (args ?? {}) as Readonly<Record<string, unknown>>;
-        // Prefer the per-call abortSignal forwarded by streamText over the
-        // bag-level ctx.signal so individual invocations respect aborts.
+        // Per-call abortSignal from streamText takes precedence over bag-level
+        // ctx.signal so individual invocations respect outer-turn aborts.
         const signal = options.abortSignal ?? ctx.signal;
         const opts: ExecuteToolOptions = {};
         if (signal !== undefined) opts.signal = signal;
         if (options.toolCallId !== undefined) opts.toolCallId = options.toolCallId;
-        // Snapshot the messages array so concurrent mutation (e.g. a new
-        // turn starting after this one was aborted) can't leak into this
-        // tool's view of history.
-        return ctx.executeTool(schema.name, input, ctx.sessionId, ctx.messages().slice(), opts);
+        // Snapshot history so concurrent mutation from a newer turn can't
+        // leak into this tool's view.
+        const history = ctx.messages().slice();
+        return ctx.executeTool(schema.name, input, ctx.sessionId, history, opts);
       },
     });
   }

package/host/tool-executor.test.ts

@@ -46,31 +46,21 @@ describe("executeToolCall", () => {
   });
 
   test("returns error when tool throws", async () => {
-    expect(
-      await run(
-        "fail",
-        {},
-        makeTool({
-          execute: () => {
-            throw new Error("boom");
-          },
-        }),
-      ),
-    ).toBe(JSON.stringify({ error: "boom" }));
+    const tool = makeTool({
+      execute: () => {
+        throw new Error("boom");
+      },
+    });
+    expect(await run("fail", {}, tool)).toBe(JSON.stringify({ error: "boom" }));
   });
 
   test("returns error string when tool throws", async () => {
-    expect(
-      await run(
-        "fail",
-        {},
-        makeTool({
-          execute: () => {
-            throw new Error("string error");
-          },
-        }),
-      ),
-    ).toBe(JSON.stringify({ error: "string error" }));
+    const tool = makeTool({
+      execute: () => {
+        throw new Error("string error");
+      },
+    });
+    expect(await run("fail", {}, tool)).toBe(JSON.stringify({ error: "string error" }));
   });
 
   test("passes env to tool context", async () => {
@@ -86,15 +76,11 @@ describe("executeToolCall", () => {
   test("kv throws when not provided", async () => {
     const tool = makeTool({
       execute: (_args, ctx) => {
-        try {
-          void ctx.kv;
-          return "no error";
-        } catch (e) {
-          return (e as Error).message;
-        }
+        void ctx.kv;
+        return "no error";
       },
     });
-    expect(await run("test", {}, tool)).toBe("KV not available");
+    expect(await run("test", {}, tool)).toBe(JSON.stringify({ error: "KV not available" }));
   });
 
   test("handles async tool execution", async () => {
@@ -111,50 +97,38 @@ describe("executeToolCall", () => {
     vi.useFakeTimers();
     const tool = makeTool({
       execute: () =>
-        new Promise(() => {
+        new Promise<never>(() => {
           /* never resolves */
         }),
     });
     const promise = run("slow", {}, tool);
     await vi.advanceTimersByTimeAsync(30_000);
-    const result = await promise;
-    expect(result).toBe(JSON.stringify({ error: 'Tool "slow" timed out after 30000ms' }));
+    expect(await promise).toBe(JSON.stringify({ error: 'Tool "slow" timed out after 30000ms' }));
     vi.useRealTimers();
   });
 
   test("ctx.send calls the send callback", async () => {
     const sends: Array<{ event: string; data: unknown }> = [];
-    const tool: ToolDef = {
-      description: "sends an event",
-      parameters: z.object({}),
+    const tool = makeTool({
       execute: (_args, ctx) => {
         ctx.send("game_state", { hp: 10 });
         return "ok";
       },
-    };
-    const result = await executeToolCall(
-      "sender",
-      {},
-      {
-        tool,
-        env: {},
-        send: (event, data) => sends.push({ event, data }),
-      },
-    );
+    });
+    const result = await run("sender", {}, tool, {
+      send: (event: string, data: unknown) => sends.push({ event, data }),
+    });
     expect(result).toBe("ok");
     expect(sends).toEqual([{ event: "game_state", data: { hp: 10 } }]);
   });
 
   test("ctx.send is a no-op when no send callback provided", async () => {
-    const tool: ToolDef = {
-      description: "sends an event",
-      parameters: z.object({}),
+    const tool = makeTool({
       execute: (_args, ctx) => {
         ctx.send("test", {});
         return "ok";
       },
-    };
-    const result = await executeToolCall("sender", {}, { tool, env: {} });
-    expect(result).toBe("ok");
+    });
+    expect(await run("sender", {}, tool)).toBe("ok");
   });
 });

package/host/tool-executor.ts

@@ -33,7 +33,7 @@ export type ExecuteToolCallOptions = {
 };
 
 function buildToolContext(opts: ExecuteToolCallOptions): ToolContext {
-  const { env, state, kv, vector, messages, sessionId } = opts;
+  const { env, state, kv, vector, messages, sessionId, send } = opts;
   return {
     env,
     state: state ?? {},
@@ -48,24 +48,32 @@ function buildToolContext(opts: ExecuteToolCallOptions): ToolContext {
     messages: messages ?? [],
     sessionId: sessionId ?? "",
     send(event: string, data: unknown): void {
-      opts.send?.(event, data);
+      send?.(event, data);
     },
   };
 }
 
+function formatZodIssues(error: z.ZodError | undefined): string {
+  return (error?.issues ?? [])
+    .map((i: z.ZodIssue) => `${i.path.map(String).join(".")}: ${i.message}`)
+    .join(", ");
+}
+
+function stringifyResult(result: unknown): string {
+  if (result == null) return "null";
+  return typeof result === "string" ? result : JSON.stringify(result);
+}
+
 export async function executeToolCall(
   name: string,
   args: Readonly<Record<string, unknown>>,
   options: ExecuteToolCallOptions,
 ): Promise<string> {
-  const { tool } = options;
+  const { tool, logger } = options;
   const schema = tool.parameters ?? EMPTY_PARAMS;
   const parsed = schema.safeParse(args);
   if (!parsed.success) {
-    const issues = (parsed.error?.issues ?? [])
-      .map((i: z.ZodIssue) => `${i.path.map(String).join(".")}: ${i.message}`)
-      .join(", ");
-    return toolError(`Invalid arguments for tool "${name}": ${issues}`);
+    return toolError(`Invalid arguments for tool "${name}": ${formatZodIssues(parsed.error)}`);
   }
 
   try {
@@ -76,12 +84,10 @@ export async function executeToolCall(
       message: `Tool "${name}" timed out after ${TOOL_EXECUTION_TIMEOUT_MS}ms`,
     });
     await yieldTick();
-    if (result == null) return "null";
-    return typeof result === "string" ? result : JSON.stringify(result);
+    return stringifyResult(result);
   } catch (err: unknown) {
-    const log = options.logger;
-    if (log) {
-      log.warn("Tool execution failed", { tool: name, error: errorDetail(err) });
+    if (logger) {
+      logger.warn("Tool execution failed", { tool: name, error: errorDetail(err) });
     } else {
       console.warn(`[tool-executor] Tool execution failed: ${name}`, err);
     }