@dex-ai/sdk 0.1.30

package/src/tool-dispatch.ts

@@ -0,0 +1,166 @@
+/** Dispatch one tool call: validate input → execute → return result. */
+
+import type {
+	AnyTool,
+	Extension,
+	GenerateContext,
+	ToolCall,
+	ToolResult,
+	ToolOutput,
+	ExecuteResult,
+	ErrorSource,
+} from "./index";
+import { validateWithSchema } from "./util";
+import { cacheIfLarge, type ResolvedCacheConfig } from "./tool-result-cache";
+
+const MAX_TOOL_OUTPUT_LINES = 1000;
+const MAX_TOOL_OUTPUT_CHARS = 40_000;
+
+/**
+ * Truncate tool output text to fit within limits.
+ * Keeps the tail (most recent output) and prepends a truncation notice.
+ */
+function truncateText(text: string): string {
+	const lines = text.split("\n");
+	let result = text;
+	let truncated = false;
+
+	if (lines.length > MAX_TOOL_OUTPUT_LINES) {
+		result = lines.slice(-MAX_TOOL_OUTPUT_LINES).join("\n");
+		truncated = true;
+	}
+
+	if (result.length > MAX_TOOL_OUTPUT_CHARS) {
+		result = result.slice(-MAX_TOOL_OUTPUT_CHARS);
+		truncated = true;
+	}
+
+	if (truncated) {
+		return (
+			"[OUTPUT TRUNCATED — showing last portion only. " +
+			"Use more targeted commands to reduce output if needed.]\n" +
+			result
+		);
+	}
+	return text;
+}
+
+/** Truncate a ToolOutput if it exceeds size limits. */
+function truncateToolOutput(output: ToolOutput): ToolOutput {
+	switch (output.type) {
+		case "text":
+			return { type: "text", value: truncateText(output.value) };
+		case "error-text":
+			return { type: "error-text", value: truncateText(output.value) };
+		case "json": {
+			const serialized = JSON.stringify(output.value, null, 2);
+			const truncatedStr = truncateText(serialized);
+			if (truncatedStr !== serialized) {
+				// Truncated JSON is no longer valid JSON — return as text
+				return { type: "text", value: truncatedStr };
+			}
+			return output;
+		}
+		case "content": {
+			const parts = output.value.map((part) => {
+				if (part.type === "text") {
+					return { ...part, text: truncateText(part.text) };
+				}
+				return part;
+			});
+			return { type: "content", value: parts };
+		}
+		default:
+			return output;
+	}
+}
+
+/** Wrap an execute() return value into a ToolOutput tagged variant. */
+export function toToolOutput(result: ExecuteResult<unknown>): ToolOutput {
+	if (typeof result === "object" && result !== null && "type" in result) {
+		const t = (result as { type: string }).type;
+		if (
+			t === "content" ||
+			t === "json" ||
+			t === "text" ||
+			t === "error-text" ||
+			t === "error-json"
+		) {
+			return result as ToolOutput;
+		}
+	}
+	return { type: "json", value: result };
+}
+
+export interface DispatchOptions {
+	readonly call: ToolCall;
+	readonly tool: AnyTool;
+	readonly extensions: ReadonlyArray<Extension>;
+	readonly gctx: GenerateContext;
+	readonly reportError: (err: unknown, source: ErrorSource) => Promise<void>;
+	readonly cacheConfig?: ResolvedCacheConfig;
+}
+
+export interface DispatchOutcome {
+	result: ToolResult;
+	shortCircuited: boolean;
+	executeError?: unknown;
+}
+
+/**
+ * Validate and execute a tool call. Tool-start/tool-stop events are handled
+ * by the generate loop — this function only does validation + execution.
+ */
+export async function dispatchTool(
+	opts: DispatchOptions,
+): Promise<DispatchOutcome> {
+	const { call, tool, gctx, reportError } = opts;
+
+	// 1. Validate input against tool.parameters.
+	const validated = await validateWithSchema(tool.parameters, call.input);
+	if ("issues" in validated) {
+		const msg = validated.issues
+			.map((i) => (i.path?.length ? i.path.join(".") + ": " : "") + i.message)
+			.join("; ");
+		return {
+			result: {
+				toolCallId: call.toolCallId,
+				toolName: call.toolName,
+				output: { type: "error-text", value: "Invalid tool input: " + msg },
+			},
+			shortCircuited: false,
+		};
+	}
+
+	// 2. Execute.
+	let executeError: unknown | undefined;
+	let result: ToolResult;
+	try {
+		const raw = await tool.execute(validated.value as any, gctx);
+		let output = toToolOutput(raw);
+		// Cache large results before truncation — agent can explore via `read`
+		if (opts.cacheConfig) {
+			output = await cacheIfLarge(
+				output,
+				call.toolName,
+				call.toolCallId,
+				opts.cacheConfig,
+			);
+		}
+		output = truncateToolOutput(output);
+		result = { toolCallId: call.toolCallId, toolName: call.toolName, output };
+	} catch (err) {
+		executeError = err;
+		await reportError(err, { kind: "tool", call });
+		result = {
+			toolCallId: call.toolCallId,
+			toolName: call.toolName,
+			output: {
+				type: "error-text",
+				value: err instanceof Error ? err.message : String(err),
+			},
+		};
+	}
+
+	return { result, shortCircuited: false, executeError };
+}

package/src/tool-result-cache.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Tests for tool-result-cache.ts
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdtemp, readFile, rm, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+	cacheIfLarge,
+	cleanCacheDir,
+	resolveConfig,
+	type ResolvedCacheConfig,
+} from "./tool-result-cache";
+import type { ToolOutput } from "./message";
+
+describe("resolveConfig", () => {
+	test("fills defaults when no config provided", () => {
+		const config = resolveConfig();
+		expect(config.threshold).toBe(10_000);
+		expect(config.cacheDir).toContain(".dex");
+		expect(config.ttlMs).toBe(86_400_000);
+		expect(config.excludedTools).toEqual(["read"]);
+	});
+
+	test("respects provided values", () => {
+		const config = resolveConfig({
+			threshold: 5000,
+			cacheDir: "/tmp/test-cache",
+			ttlMs: 1000,
+			excludedTools: ["read", "search"],
+		});
+		expect(config.threshold).toBe(5000);
+		expect(config.cacheDir).toBe("/tmp/test-cache");
+		expect(config.ttlMs).toBe(1000);
+		expect(config.excludedTools).toEqual(["read", "search"]);
+	});
+});
+
+describe("cacheIfLarge", () => {
+	let cacheDir: string;
+	let config: ResolvedCacheConfig;
+
+	beforeEach(async () => {
+		cacheDir = await mkdtemp(join(tmpdir(), "dex-cache-test-"));
+		config = {
+			threshold: 100,
+			cacheDir,
+			ttlMs: 86_400_000,
+			excludedTools: ["read"],
+		};
+	});
+
+	afterEach(async () => {
+		await rm(cacheDir, { recursive: true, force: true });
+	});
+
+	test("passes through small text output unchanged", async () => {
+		const output: ToolOutput = { type: "text", value: "hello world" };
+		const result = await cacheIfLarge(output, "bash", "call_1", config);
+		expect(result).toBe(output);
+	});
+
+	test("passes through excluded tools unchanged", async () => {
+		const bigText = "x".repeat(200);
+		const output: ToolOutput = { type: "text", value: bigText };
+		const result = await cacheIfLarge(output, "read", "call_2", config);
+		expect(result).toBe(output); // unchanged — read is excluded
+	});
+
+	test("caches large text output and returns tail with header", async () => {
+		const bigText = "a".repeat(50) + "b".repeat(150);
+		const output: ToolOutput = { type: "text", value: bigText };
+		const result = await cacheIfLarge(output, "bash", "call_3", config);
+
+		// Should be transformed
+		expect(result.type).toBe("text");
+		const value = (result as { type: "text"; value: string }).value;
+		expect(value).toContain("[Tool output cached");
+		expect(value).toContain("call_3");
+		expect(value).toContain("200"); // total length
+
+		// Tail should be last 100 chars
+		expect(value).toEndWith("b".repeat(100));
+
+		// File should exist on disk with full content
+		const cached = await readFile(join(cacheDir, "call_3"), "utf-8");
+		expect(cached).toBe(bigText);
+	});
+
+	test("caches large JSON output", async () => {
+		const bigObj = { data: "x".repeat(200) };
+		const output: ToolOutput = { type: "json", value: bigObj };
+		const result = await cacheIfLarge(output, "search", "call_4", config);
+
+		expect(result.type).toBe("text"); // JSON is serialized to text
+		const value = (result as { type: "text"; value: string }).value;
+		expect(value).toContain("[Tool output cached");
+
+		// Full JSON should be on disk
+		const cached = await readFile(join(cacheDir, "call_4"), "utf-8");
+		expect(cached).toBe(JSON.stringify(bigObj, null, 2));
+	});
+
+	test("preserves error-text type for large error outputs", async () => {
+		const bigError = "Error: " + "x".repeat(200);
+		const output: ToolOutput = { type: "error-text", value: bigError };
+		const result = await cacheIfLarge(output, "bash", "call_5", config);
+
+		expect(result.type).toBe("error-text");
+	});
+
+	test("handles content type with text parts", async () => {
+		const output: ToolOutput = {
+			type: "content",
+			value: [{ type: "text", text: "y".repeat(200) }],
+		};
+		const result = await cacheIfLarge(output, "bash", "call_6", config);
+
+		expect(result.type).toBe("text");
+		const value = (result as { type: "text"; value: string }).value;
+		expect(value).toContain("[Tool output cached");
+	});
+
+	test("returns unchanged if content has no text parts", async () => {
+		const output: ToolOutput = {
+			type: "content",
+			value: [
+				{
+					type: "image",
+					image: "base64data",
+					mediaType: "image/png",
+				},
+			],
+		};
+		const result = await cacheIfLarge(output, "bash", "call_7", config);
+		expect(result).toBe(output);
+	});
+});
+
+describe("cleanCacheDir", () => {
+	let cacheDir: string;
+
+	beforeEach(async () => {
+		cacheDir = await mkdtemp(join(tmpdir(), "dex-cache-clean-test-"));
+	});
+
+	afterEach(async () => {
+		await rm(cacheDir, { recursive: true, force: true });
+	});
+
+	test("creates cache directory if it doesn't exist", async () => {
+		const newDir = join(cacheDir, "subdir", "cache");
+		const config: ResolvedCacheConfig = {
+			threshold: 10_000,
+			cacheDir: newDir,
+			ttlMs: 86_400_000,
+			excludedTools: ["read"],
+		};
+		await cleanCacheDir(config);
+
+		const entries = await readdir(newDir);
+		expect(entries).toEqual([]);
+	});
+
+	test("wipes existing cache files on clean", async () => {
+		// Write a file to the cache
+		const { writeFile } = await import("node:fs/promises");
+		await writeFile(join(cacheDir, "old_call"), "old content");
+
+		const config: ResolvedCacheConfig = {
+			threshold: 10_000,
+			cacheDir,
+			ttlMs: 86_400_000,
+			excludedTools: ["read"],
+		};
+		await cleanCacheDir(config);
+
+		// Directory should exist but be empty
+		const entries = await readdir(cacheDir);
+		expect(entries).toEqual([]);
+	});
+});

package/src/tool-result-cache.ts

@@ -0,0 +1,164 @@
+/**
+ * Large Tool Result Caching
+ *
+ * When a tool result exceeds a character threshold, the full output is cached
+ * to disk and only the tail is sent to the model — with a header noting where
+ * the full output can be read.
+ *
+ * This reduces context consumption while allowing the agent to explore
+ * cached results via the existing `read` tool.
+ */
+
+import { writeFile, mkdir, readdir, stat, unlink, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { ToolOutput } from "./message";
+
+/* ------------------------------------------------------------------ */
+/* Configuration                                                       */
+/* ------------------------------------------------------------------ */
+
+export interface ToolResultCacheConfig {
+	/** Character threshold above which results are cached. Default: 10_000 */
+	readonly threshold?: number;
+	/** Cache directory. Default: ~/.dex/cache */
+	readonly cacheDir?: string;
+	/** TTL in milliseconds for stale file cleanup. Default: 86_400_000 (24h) */
+	readonly ttlMs?: number;
+	/** Tool names excluded from caching. Default: ['read'] */
+	readonly excludedTools?: ReadonlyArray<string>;
+}
+
+/** Internal state key used to store the resolved config in AgentContext.state */
+export const TOOL_RESULT_CACHE_KEY = "__toolResultCache";
+
+/* ------------------------------------------------------------------ */
+/* Defaults                                                            */
+/* ------------------------------------------------------------------ */
+
+const DEFAULT_THRESHOLD = 10_000;
+const DEFAULT_CACHE_DIR = join(homedir(), ".dex", "cache");
+const DEFAULT_TTL_MS = 86_400_000; // 24 hours
+const DEFAULT_EXCLUDED_TOOLS: ReadonlyArray<string> = ["read"];
+
+export interface ResolvedCacheConfig {
+	readonly threshold: number;
+	readonly cacheDir: string;
+	readonly ttlMs: number;
+	readonly excludedTools: ReadonlyArray<string>;
+}
+
+export function resolveConfig(
+	config?: ToolResultCacheConfig,
+): ResolvedCacheConfig {
+	return {
+		threshold: config?.threshold ?? DEFAULT_THRESHOLD,
+		cacheDir: config?.cacheDir ?? DEFAULT_CACHE_DIR,
+		ttlMs: config?.ttlMs ?? DEFAULT_TTL_MS,
+		excludedTools: config?.excludedTools ?? DEFAULT_EXCLUDED_TOOLS,
+	};
+}
+
+/* ------------------------------------------------------------------ */
+/* Text extraction                                                     */
+/* ------------------------------------------------------------------ */
+
+/** Extract the text content from a ToolOutput, or null if non-textual. */
+function extractText(output: ToolOutput): string | null {
+	switch (output.type) {
+		case "text":
+		case "error-text":
+			return output.value;
+		case "json":
+			return JSON.stringify(output.value, null, 2);
+		case "content": {
+			const texts = output.value
+				.filter((p) => p.type === "text")
+				.map((p) => (p as { type: "text"; text: string }).text);
+			return texts.length > 0 ? texts.join("\n") : null;
+		}
+		default:
+			return null;
+	}
+}
+
+/* ------------------------------------------------------------------ */
+/* Core: cacheIfLarge                                                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * If the tool output exceeds the threshold, cache the full result to disk
+ * and return a truncated version with a header pointing to the cache file.
+ *
+ * Returns the original output unchanged if below threshold or excluded.
+ */
+export async function cacheIfLarge(
+	output: ToolOutput,
+	toolName: string,
+	toolCallId: string,
+	config: ResolvedCacheConfig,
+): Promise<ToolOutput> {
+	// Skip excluded tools
+	if (config.excludedTools.includes(toolName)) return output;
+
+	// Extract text content
+	const text = extractText(output);
+	if (!text || text.length <= config.threshold) return output;
+
+	// Write full output to cache
+	const cachePath = join(config.cacheDir, toolCallId);
+	try {
+		await mkdir(config.cacheDir, { recursive: true });
+		await writeFile(cachePath, text, "utf-8");
+	} catch {
+		// If caching fails (disk full, permissions), fall through to existing truncation
+		return output;
+	}
+
+	// Return tail with header
+	const tail = text.slice(-config.threshold);
+	const header =
+		`[Tool output cached — showing last ${config.threshold.toLocaleString()} of ${text.length.toLocaleString()} chars. ` +
+		`Full output: ${cachePath}]\n`;
+
+	// Preserve the output type for error results
+	if (output.type === "error-text") {
+		return { type: "error-text", value: header + tail };
+	}
+	return { type: "text", value: header + tail };
+}
+
+/* ------------------------------------------------------------------ */
+/* Cleanup                                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Remove stale cache files older than TTL, then wipe the directory.
+ * Called on session start to ensure a clean slate.
+ */
+export async function cleanCacheDir(
+	config: ResolvedCacheConfig,
+): Promise<void> {
+	const { cacheDir, ttlMs } = config;
+
+	try {
+		// First pass: remove stale files (safety net for orphaned files from crashed sessions)
+		const entries = await readdir(cacheDir).catch(() => [] as string[]);
+		const now = Date.now();
+		for (const entry of entries) {
+			const filePath = join(cacheDir, entry);
+			const fileStat = await stat(filePath).catch(() => null);
+			if (fileStat && now - fileStat.mtimeMs > ttlMs) {
+				await unlink(filePath).catch(() => {});
+			}
+		}
+
+		// Wipe the directory for a clean session start
+		await rm(cacheDir, { recursive: true, force: true });
+	} catch {
+		// Non-fatal — directory may not exist yet
+	}
+
+	// Ensure directory exists for this session
+	await mkdir(cacheDir, { recursive: true });
+}

package/src/tool.ts

@@ -0,0 +1,110 @@
+/**
+ * Tool — an action a Provider may invoke.
+ *
+ * ai-sdk aligned:
+ *   - parameters: Standard Schema for the input
+ *   - execute:    ({input}, gctx) => ToolOutput | value
+ *   - outputSchema: optional Standard Schema for the output value
+ *
+ * Approval is NOT a first-class tool field. Use the onToolCall hook
+ * (see extension.ts) — a short-circuit-capable reducer. An approver
+ * extension returns a ToolResult to reject, a rewritten ToolCall to
+ * modify, or void to pass through. A rejection is data for the LLM:
+ * the tool-result message goes into history and the model decides to
+ * retry, call a different tool, or stop.
+ */
+
+import type { StandardSchemaV1, InferInput } from "./schema";
+import type { ToolOutput } from "./message";
+import type { GenerateContext } from "./context";
+
+/** A pending tool invocation parsed from the model. */
+export interface ToolCall<Input = unknown> {
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly input: Input;
+}
+
+/**
+ * The outcome of a tool invocation. Wraps a tagged ToolOutput so tools
+ * can return rich content, structured JSON, plain text, or errors
+ * uniformly.
+ */
+export interface ToolResult {
+	readonly toolCallId: string;
+	readonly toolName: string;
+	readonly output: ToolOutput;
+}
+
+/**
+ * An execute function may return either:
+ *   - a raw Output value (wrapped by the loop into a ToolOutput.json), or
+ *   - a ToolOutput directly (for rich content / explicit error shapes).
+ */
+export type ExecuteResult<Output> = Output | ToolOutput;
+
+export interface Tool<Input = unknown, Output = unknown> {
+	readonly name: string;
+	readonly description?: string;
+	readonly parameters: StandardSchemaV1<Input>;
+	readonly outputSchema?: StandardSchemaV1<Output>;
+	/**
+	 * Access level hint for permission systems.
+	 *   - 'read': tool only reads/queries data (no side effects)
+	 *   - 'write': tool modifies state (files, memory, shell, etc.)
+	 *
+	 * If omitted, defaults to 'write' (conservative — requires approval).
+	 */
+	readonly access?: "read" | "write";
+	/**
+	 * Human-friendly name for UI display.
+	 * Falls back to `name` when omitted.
+	 * Examples: "Read", "Update", "Search", "Remember"
+	 */
+	readonly displayName?: string;
+	/**
+	 * Whether the tool invocation should be rendered in the UI message stream.
+	 * Defaults to `true`. Set to `false` for tools that have dedicated UI
+	 * (e.g. task panel) or whose invocations aren't useful to show inline.
+	 */
+	readonly visible?: boolean;
+	execute(
+		input: Input,
+		gctx: GenerateContext,
+	): Promise<ExecuteResult<Output>> | ExecuteResult<Output>;
+	/**
+	 * Streaming alternative to execute. Yields Parts (tool-progress + tool-result).
+	 * If present, the loop prefers stream() over execute().
+	 * The loop stamps toolCallId on emitted parts.
+	 */
+	stream?(input: Input, gctx: GenerateContext): AsyncIterable<ToolStreamPart>;
+}
+
+/** Parts a streaming tool can yield. */
+export type ToolStreamPart =
+	| { readonly type: "tool-progress"; readonly text: string }
+	| { readonly type: "tool-result"; readonly output: ToolOutput };
+
+export type AnyTool = Tool<any, any>;
+
+/**
+ * Tool namespace — identity-typed declaration helper.
+ *
+ * Use `Tool.define({...})` at author-time to get full contextual typing
+ * (tool input/output inference from the Standard Schema `parameters`).
+ * Runtime behavior: returns the argument unchanged.
+ */
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export const Tool = {
+	define<ParamsSchema extends StandardSchemaV1<any, any>, Output>(
+		tool: Omit<
+			Tool<InferInput<ParamsSchema>, Output>,
+			"parameters" | "outputSchema"
+		> & {
+			readonly parameters: ParamsSchema;
+			readonly outputSchema?: StandardSchemaV1<Output>;
+		},
+	): Tool<InferInput<ParamsSchema>, Output> {
+		return tool as Tool<InferInput<ParamsSchema>, Output>;
+	},
+};