@alexkroman1/aai 0.12.1 → 0.12.3

package/dist/{direct-executor-ZUU0Ke4j.js → direct-executor-DRRrZUp0.js}

@@ -1,11 +1,11 @@
-import { a as agentToolsToSchemas, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "./system-prompt-CVJSQJiA.js";
+import { a as agentToolsToSchemas, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "./system-prompt-DYAYFW99.js";
 import { errorDetail, errorMessage, toolError } from "./isolate/_utils.js";
 import { C as MAX_VALUE_SIZE, S as MAX_TOOL_RESULT_CHARS, T as TOOL_EXECUTION_TIMEOUT_MS, _ as FETCH_TIMEOUT_MS, b as MAX_HTML_BYTES, g as DEFAULT_TTS_SAMPLE_RATE, h as DEFAULT_STT_SAMPLE_RATE, l as buildReadyConfig, m as DEFAULT_SHUTDOWN_TIMEOUT_MS, r as ClientMessageSchema, v as HOOK_TIMEOUT_MS, w as RUN_CODE_TIMEOUT_MS, x as MAX_PAGE_CHARS, y as MAX_GLOB_PATTERN_LENGTH } from "./protocol-rcOrz7T3.js";
 import { callResolveTurnConfig, createAgentHooks } from "./isolate/hooks.js";
 import { z } from "zod";
+import vm from "node:vm";
 import pTimeout from "p-timeout";
 import { createStorage, prefixStorage } from "unstorage";
-import vm from "node:vm";
 import { createNanoEvents } from "nanoevents";
 import WsWebSocket from "ws";
 //#region host/_run-code.ts
@@ -29,6 +29,7 @@ const runCodeParams = z.object({ code: z.string().describe("JavaScript code to e
 */
 function createRunCode() {
 	return {
+		guidance: "You MUST use the run_code tool for ANY question involving math, counting, calculations, data processing, or code. NEVER do mental math or recite code verbally. run_code executes JavaScript (not Python). Always write JavaScript.",
 		description: "Execute JavaScript code in a sandbox and return the output. Use this for calculations, data transformations, string manipulation, or any task that benefits from running code. Output is captured from console.log(). No network or filesystem access.",
 		parameters: runCodeParams,
 		async execute(args) {
@@ -103,6 +104,7 @@ const BraveSearchResponseSchema = z.object({ web: z.object({ results: z.array(z.
 })) }).optional() });
 function createWebSearch(fetchFn = globalThis.fetch) {
 	return {
+		guidance: "Use web_search for factual questions, current events, or anything you are unsure about. Search first rather than guessing.",
 		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: webSearchParams,
 		async execute(args, ctx) {
@@ -132,6 +134,7 @@ function createWebSearch(fetchFn = globalThis.fetch) {
 const visitWebpageParams = z.object({ url: z.string().describe("The full URL to fetch (e.g., 'https://example.com/page')") });
 function createVisitWebpage(fetchFn = globalThis.fetch) {
 	return {
+		guidance: "Use visit_webpage to read the full content of a URL when search snippets are not detailed enough.",
 		description: "Fetch a webpage and return its content as clean text. Use this to read the full content of a URL found via web_search, or any link the user shares. Good for reading articles, documentation, blog posts, or product pages.",
 		parameters: visitWebpageParams,
 		async execute(args, _ctx) {
@@ -187,6 +190,7 @@ function sanitizeHeaders(raw) {
 }
 function createFetchJson(fetchFn = globalThis.fetch) {
 	return {
+		guidance: "Use fetch_json to call REST APIs and retrieve structured JSON data.",
 		description: "Call a REST API endpoint via HTTP GET and return the JSON response. Use this to fetch structured data from APIs — for example, weather data, stock prices, exchange rates, or any public JSON API. Supports custom headers for authenticated APIs.",
 		parameters: fetchJsonParams,
 		async execute(args, _ctx) {
@@ -230,6 +234,10 @@ function getBuiltinToolDefs(names, opts) {
 	for (const name of names) for (const [k, v] of resolveBuiltin(name, opts)) defs[k] = v;
 	return defs;
 }
+/** Returns system prompt guidance strings for the specified builtin tools. */
+function getBuiltinToolGuidance(names) {
+	return names.flatMap((name) => resolveBuiltin(name).map(([, def]) => def.guidance).filter((g) => Boolean(g)));
+}
 /** Returns JSON tool schemas for the specified builtin tools. */
 function getBuiltinToolSchemas(names) {
 	return names.flatMap((name) => resolveBuiltin(name).map(([toolName, def]) => ({
@@ -822,7 +830,8 @@ function createS2sSession(opts) {
 	} : opts.agentConfig;
 	const systemPrompt = buildSystemPrompt(agentConfig, {
 		hasTools: toolSchemas.length > 0 || (agentConfig.builtinTools?.length ?? 0) > 0,
-		voice: true
+		voice: true,
+		toolGuidance: opts.toolGuidance
 	});
 	const s2sTools = toolSchemas.map((ts) => ({
 		type: "function",
@@ -1278,10 +1287,12 @@ function createRuntime(opts) {
 	let executeTool;
 	let hooks;
 	let toolSchemas;
+	let toolGuidance = [];
 	if (opts.executeTool && opts.hooks && opts.toolSchemas) {
 		executeTool = opts.executeTool;
 		hooks = opts.hooks;
 		toolSchemas = opts.toolSchemas;
+		toolGuidance = opts.toolGuidance ?? [];
 	} else {
 		const allTools = {
 			...getBuiltinToolDefs(agent.builtinTools ?? []),
@@ -1290,6 +1301,7 @@ function createRuntime(opts) {
 		const customSchemas = agentToolsToSchemas(agent.tools ?? {});
 		const builtinSchemas = getBuiltinToolSchemas(agent.builtinTools ?? []);
 		toolSchemas = [...customSchemas, ...builtinSchemas];
+		toolGuidance = getBuiltinToolGuidance(agent.builtinTools ?? []);
 		const stateMap = /* @__PURE__ */ new Map();
 		const getState = (sid) => {
 			if (!stateMap.has(sid) && agent.state) stateMap.set(sid, agent.state());
@@ -1337,6 +1349,7 @@ function createRuntime(opts) {
 			client: sessionOpts.client,
 			agentConfig,
 			toolSchemas,
+			toolGuidance,
 			apiKey,
 			s2sConfig,
 			executeTool,
@@ -1397,4 +1410,4 @@ function createRuntime(opts) {
 	};
 }
 //#endregion
-export { _internals as a, connectS2s as c, consoleLogger as d, jsonLogger as f, createUnstorageKv as i, defaultCreateS2sWebSocket as l, executeToolCall as n, buildCtx as o, wireSessionSocket as r, createS2sSession as s, createRuntime as t, DEFAULT_S2S_CONFIG as u };
+export { _internals as a, connectS2s as c, consoleLogger as d, jsonLogger as f, executeInIsolate as g, getBuiltinToolSchemas as h, createUnstorageKv as i, defaultCreateS2sWebSocket as l, getBuiltinToolGuidance as m, executeToolCall as n, buildCtx as o, getBuiltinToolDefs as p, wireSessionSocket as r, createS2sSession as s, createRuntime as t, DEFAULT_S2S_CONFIG as u };

package/dist/host/_run-code.d.ts

@@ -20,7 +20,9 @@ declare const runCodeParams: z.ZodObject<{
  * The context is discarded after execution, so no state leaks between
  * invocations or across sessions.
  */
-export declare function createRunCode(): ToolDef<typeof runCodeParams>;
+export declare function createRunCode(): ToolDef<typeof runCodeParams> & {
+    guidance: string;
+};
 /**
  * Execute user code in a fresh `node:vm` context.
  *

package/dist/host/_test-utils.d.ts

@@ -30,12 +30,12 @@ export declare const silentLogger: {
     debug: (...args: unknown[]) => void;
 };
 export declare function makeSessionOpts(overrides?: Partial<S2sSessionOptions>): S2sSessionOptions;
-/** Load a JSON fixture from __fixtures__/. */
+/** Load a JSON fixture from fixtures/. */
 export declare function loadFixture<T = Record<string, unknown>[]>(name: string): T;
 /**
  * Replay recorded S2S API messages through a MockS2sHandle.
  *
- * Converts raw wire-format JSON (from __fixtures__/) into typed `_fire()` calls.
+ * Converts raw wire-format JSON (from fixtures/) into typed `_fire()` calls.
  * This is the inverse of `dispatchS2sMessage` in s2s.ts — it translates
  * snake_case API fields to camelCase event payloads.
  *

package/dist/host/builtin-tools.d.ts

@@ -20,5 +20,7 @@ type ToolDefRecord = Record<string, ToolDef<z.ZodObject<z.ZodRawShape>>>;
  * For runtime use.
  */
 export declare function getBuiltinToolDefs(names: readonly string[], opts?: BuiltinToolOptions): ToolDefRecord;
+/** Returns system prompt guidance strings for the specified builtin tools. */
+export declare function getBuiltinToolGuidance(names: readonly string[]): string[];
 /** Returns JSON tool schemas for the specified builtin tools. */
 export declare function getBuiltinToolSchemas(names: readonly string[]): ToolSchema[];

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

@@ -87,6 +87,8 @@ export type RuntimeOptions = {
      * is provided (the host doesn't have the tool definitions to derive schemas).
      */
     toolSchemas?: ToolSchema[] | undefined;
+    /** System prompt guidance for builtin tools. Passed through in sandbox mode. */
+    toolGuidance?: string[] | undefined;
 };
 /**
  * The agent runtime returned by {@link createRuntime}.

package/dist/host/index.d.ts

@@ -10,6 +10,7 @@
  */
 export * from "../isolate/index.ts";
 export * from "./_runtime-conformance.ts";
+export * from "./builtin-tools.ts";
 export * from "./direct-executor.ts";
 export * from "./runtime.ts";
 export * from "./s2s.ts";

package/dist/host/index.js

@@ -1,10 +1,10 @@
 import { BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, ToolChoiceSchema, defineAgent, defineTool, defineToolFactory } from "../isolate/types.js";
-import { a as agentToolsToSchemas, i as ToolSchemaSchema, n as AgentConfigSchema, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "../system-prompt-CVJSQJiA.js";
+import { a as agentToolsToSchemas, i as ToolSchemaSchema, n as AgentConfigSchema, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "../system-prompt-DYAYFW99.js";
 import { errorDetail, errorMessage, toolError } from "../isolate/_utils.js";
 import { C as MAX_VALUE_SIZE, S as MAX_TOOL_RESULT_CHARS, T as TOOL_EXECUTION_TIMEOUT_MS, _ as FETCH_TIMEOUT_MS, a as ReadyConfigSchema, b as MAX_HTML_BYTES, c as TurnConfigSchema, d as DEFAULT_IDLE_TIMEOUT_MS, f as DEFAULT_MAX_HISTORY, g as DEFAULT_TTS_SAMPLE_RATE, h as DEFAULT_STT_SAMPLE_RATE, i as KvRequestSchema, l as buildReadyConfig, m as DEFAULT_SHUTDOWN_TIMEOUT_MS, n as ClientEventSchema, o as ServerMessageSchema, p as DEFAULT_SESSION_START_TIMEOUT_MS, r as ClientMessageSchema, s as SessionErrorCodeSchema, t as AUDIO_FORMAT, u as AGENT_CSP, v as HOOK_TIMEOUT_MS, w as RUN_CODE_TIMEOUT_MS, x as MAX_PAGE_CHARS, y as MAX_GLOB_PATTERN_LENGTH } from "../protocol-rcOrz7T3.js";
 import { callResolveTurnConfig, createAgentHooks } from "../isolate/hooks.js";
 import "../isolate/index.js";
-import { a as _internals, c as connectS2s, d as consoleLogger, f as jsonLogger, i as createUnstorageKv, l as defaultCreateS2sWebSocket, n as executeToolCall, o as buildCtx, r as wireSessionSocket, s as createS2sSession, t as createRuntime, u as DEFAULT_S2S_CONFIG } from "../direct-executor-ZUU0Ke4j.js";
+import { a as _internals, c as connectS2s, d as consoleLogger, f as jsonLogger, g as executeInIsolate, h as getBuiltinToolSchemas, i as createUnstorageKv, l as defaultCreateS2sWebSocket, m as getBuiltinToolGuidance, n as executeToolCall, o as buildCtx, p as getBuiltinToolDefs, r as wireSessionSocket, s as createS2sSession, t as createRuntime, u as DEFAULT_S2S_CONFIG } from "../direct-executor-DRRrZUp0.js";
 import { z } from "zod";
 import { describe, expect, test } from "vitest";
 //#region host/_runtime-conformance.ts
@@ -162,4 +162,4 @@ function testRuntime(label, getContext) {
 	});
 }
 //#endregion
-export { AGENT_CSP, AUDIO_FORMAT, AgentConfigSchema, BuiltinToolSchema, CONFORMANCE_AGENT, ClientEventSchema, ClientMessageSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_INSTRUCTIONS, DEFAULT_MAX_HISTORY, DEFAULT_S2S_CONFIG, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_TTS_SAMPLE_RATE, EMPTY_PARAMS, FETCH_TIMEOUT_MS, HOOK_TIMEOUT_MS, KvRequestSchema, MAX_GLOB_PATTERN_LENGTH, MAX_HTML_BYTES, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, RUN_CODE_TIMEOUT_MS, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, ToolSchemaSchema, TurnConfigSchema, _internals, agentToolsToSchemas, buildCtx, buildReadyConfig, buildSystemPrompt, callResolveTurnConfig, connectS2s, consoleLogger, createAgentHooks, createRuntime, createS2sSession, createUnstorageKv, defaultCreateS2sWebSocket, defineAgent, defineTool, defineTool as tool, defineToolFactory, errorDetail, errorMessage, executeToolCall, jsonLogger, testRuntime, toAgentConfig, toolError, wireSessionSocket };
+export { AGENT_CSP, AUDIO_FORMAT, AgentConfigSchema, BuiltinToolSchema, CONFORMANCE_AGENT, ClientEventSchema, ClientMessageSchema, DEFAULT_GREETING, DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_INSTRUCTIONS, DEFAULT_MAX_HISTORY, DEFAULT_S2S_CONFIG, DEFAULT_SESSION_START_TIMEOUT_MS, DEFAULT_SHUTDOWN_TIMEOUT_MS, DEFAULT_STT_SAMPLE_RATE, DEFAULT_TTS_SAMPLE_RATE, EMPTY_PARAMS, FETCH_TIMEOUT_MS, HOOK_TIMEOUT_MS, KvRequestSchema, MAX_GLOB_PATTERN_LENGTH, MAX_HTML_BYTES, MAX_PAGE_CHARS, MAX_TOOL_RESULT_CHARS, MAX_VALUE_SIZE, RUN_CODE_TIMEOUT_MS, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, TOOL_EXECUTION_TIMEOUT_MS, ToolChoiceSchema, ToolSchemaSchema, TurnConfigSchema, _internals, agentToolsToSchemas, buildCtx, buildReadyConfig, buildSystemPrompt, callResolveTurnConfig, connectS2s, consoleLogger, createAgentHooks, createRuntime, createS2sSession, createUnstorageKv, defaultCreateS2sWebSocket, defineAgent, defineTool, defineTool as tool, defineToolFactory, errorDetail, errorMessage, executeInIsolate, executeToolCall, getBuiltinToolDefs, getBuiltinToolGuidance, getBuiltinToolSchemas, jsonLogger, testRuntime, toAgentConfig, toolError, wireSessionSocket };

package/dist/host/matchers.js

@@ -1,4 +1,4 @@
-import { n as TurnResult } from "../testing-Bb2B5Uob.js";
+import { n as TurnResult } from "../testing-BreLdpq-.js";
 import { expect } from "vitest";
 //#region host/matchers.ts
 /**

package/dist/host/server.js

@@ -1,5 +1,5 @@
 import { u as AGENT_CSP } from "../protocol-rcOrz7T3.js";
-import { d as consoleLogger, t as createRuntime } from "../direct-executor-ZUU0Ke4j.js";
+import { d as consoleLogger, t as createRuntime } from "../direct-executor-DRRrZUp0.js";
 import { WebSocketServer } from "ws";
 import fs from "node:fs";
 import http from "node:http";

package/dist/host/session.d.ts

@@ -94,6 +94,7 @@ export type S2sSessionOptions = {
     client: ClientSink;
     agentConfig: AgentConfig;
     toolSchemas: readonly ToolSchema[];
+    toolGuidance?: readonly string[];
     apiKey: string;
     s2sConfig: S2SConfig;
     executeTool: ExecuteTool;

package/dist/host/testing.js

@@ -1,2 +1,2 @@
-import { a as makeStubSession, i as flush, n as TurnResult, o as MockWebSocket, r as createTestHarness, s as installMockWebSocket, t as TestHarness } from "../testing-Bb2B5Uob.js";
+import { a as makeStubSession, i as flush, n as TurnResult, o as MockWebSocket, r as createTestHarness, s as installMockWebSocket, t as TestHarness } from "../testing-BreLdpq-.js";
 export { MockWebSocket, TestHarness, TurnResult, createTestHarness, flush, installMockWebSocket, makeStubSession };

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

@@ -11,7 +11,7 @@ import { type ToolDef } from "./types.ts";
  * Function signature for executing a tool by name.
  *
  * Used by session.ts to invoke tools, by direct-executor.ts and
- * _harness-runtime.ts to implement the execution.
+ * harness-runtime.ts to implement the execution.
  */
 export type ExecuteTool = (name: string, args: Readonly<Record<string, unknown>>, sessionId?: string, messages?: readonly Message[]) => Promise<string>;
 /**

package/dist/isolate/index.js

@@ -1,5 +1,5 @@
 import { BuiltinToolSchema, DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, ToolChoiceSchema, defineAgent, defineTool, defineToolFactory } from "./types.js";
-import { a as agentToolsToSchemas, i as ToolSchemaSchema, n as AgentConfigSchema, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "../system-prompt-CVJSQJiA.js";
+import { a as agentToolsToSchemas, i as ToolSchemaSchema, n as AgentConfigSchema, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "../system-prompt-DYAYFW99.js";
 import { errorDetail, errorMessage, toolError } from "./_utils.js";
 import { C as MAX_VALUE_SIZE, S as MAX_TOOL_RESULT_CHARS, T as TOOL_EXECUTION_TIMEOUT_MS, _ as FETCH_TIMEOUT_MS, a as ReadyConfigSchema, b as MAX_HTML_BYTES, c as TurnConfigSchema, d as DEFAULT_IDLE_TIMEOUT_MS, f as DEFAULT_MAX_HISTORY, g as DEFAULT_TTS_SAMPLE_RATE, h as DEFAULT_STT_SAMPLE_RATE, i as KvRequestSchema, l as buildReadyConfig, m as DEFAULT_SHUTDOWN_TIMEOUT_MS, n as ClientEventSchema, o as ServerMessageSchema, p as DEFAULT_SESSION_START_TIMEOUT_MS, r as ClientMessageSchema, s as SessionErrorCodeSchema, t as AUDIO_FORMAT, u as AGENT_CSP, v as HOOK_TIMEOUT_MS, w as RUN_CODE_TIMEOUT_MS, x as MAX_PAGE_CHARS, y as MAX_GLOB_PATTERN_LENGTH } from "../protocol-rcOrz7T3.js";
 import { callResolveTurnConfig, createAgentHooks } from "./hooks.js";

package/dist/isolate/system-prompt.d.ts

@@ -18,4 +18,5 @@ import type { AgentConfig } from "./_internal-types.ts";
 export declare function buildSystemPrompt(config: AgentConfig, opts: {
     hasTools: boolean;
     voice?: boolean;
+    toolGuidance?: readonly string[] | undefined;
 }): string;

package/dist/{system-prompt-CVJSQJiA.js → system-prompt-DYAYFW99.js}

@@ -85,7 +85,8 @@ function buildSystemPrompt(config, opts) {
 	const { hasTools } = opts;
 	const agentInstructions = config.instructions && config.instructions !== DEFAULT_INSTRUCTIONS ? `\n\nAgent-Specific Instructions:\n${config.instructions}` : "";
 	const toolPreamble = hasTools ? "\n\nWhen you decide to use a tool, ALWAYS say a brief natural phrase BEFORE the tool call (e.g. \"Let me look that up\" or \"One moment while I check\"). This fills silence while the tool executes. Keep preambles to one short sentence." : "";
-	return DEFAULT_INSTRUCTIONS + `\n\nToday's date is ${getFormattedDate()}.` + agentInstructions + toolPreamble + (opts.voice ? VOICE_RULES : "");
+	const guidance = opts.toolGuidance && opts.toolGuidance.length > 0 ? `\n\nBuilt-in Tool Usage:\n${opts.toolGuidance.join("\n")}` : "";
+	return DEFAULT_INSTRUCTIONS + `\n\nToday's date is ${getFormattedDate()}.` + agentInstructions + toolPreamble + guidance + (opts.voice ? VOICE_RULES : "");
 }
 //#endregion
 export { agentToolsToSchemas as a, ToolSchemaSchema as i, AgentConfigSchema as n, toAgentConfig as o, EMPTY_PARAMS as r, buildSystemPrompt as t };

package/dist/{testing-Bb2B5Uob.js → testing-BreLdpq-.js}

@@ -1,5 +1,5 @@
 import "./isolate/types.js";
-import { i as createUnstorageKv, t as createRuntime } from "./direct-executor-ZUU0Ke4j.js";
+import { i as createUnstorageKv, t as createRuntime } from "./direct-executor-DRRrZUp0.js";
 import { vi } from "vitest";
 import { createStorage } from "unstorage";
 import "nanoevents";
@@ -177,7 +177,7 @@ function makeStubSession(overrides) {
 	};
 }
 vi.fn(), vi.fn(), vi.fn(), vi.fn();
-resolve(import.meta.dirname, "__fixtures__");
+resolve(import.meta.dirname, "fixtures");
 //#endregion
 //#region host/testing.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "type": "module",
   "files": [
     "dist"
@@ -76,7 +76,7 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "vitest": "^4.1.1"
+    "vitest": "^4.1.2"
   },
   "peerDependenciesMeta": {
     "vitest": {
@@ -87,7 +87,7 @@
     "@types/json-schema": "^7.0.15",
     "@types/node": "^25.5.0",
     "@types/ws": "^8.18.1",
-    "tsdown": "^0.21.5",
+    "tsdown": "^0.21.7",
     "vite": "^8.0.3"
   },
   "engines": {
@@ -99,6 +99,10 @@
     "directory": "packages/aai"
   },
   "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "check:integration": "pnpm run test:integration",
     "build": "tsdown && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit && tsc -p isolate/tsconfig.json",
     "lint": "biome check .",