@akon-labs/nexus-cli 0.1.0

package/dist/core/tools/tool-definition-wrapper.js

@@ -0,0 +1,36 @@
+/** Wrap a ToolDefinition into an AgentTool for the core runtime. */
+export function wrapToolDefinition(definition, ctxFactory) {
+    return {
+        name: definition.name,
+        label: definition.label,
+        description: definition.description,
+        parameters: definition.parameters,
+        constrainedSampling: definition.constrainedSampling,
+        prepareArguments: definition.prepareArguments,
+        executionMode: definition.executionMode,
+        execute: (toolCallId, params, signal, onUpdate, ctx) => definition.execute(toolCallId, params, signal, onUpdate, ctx ?? ctxFactory?.()),
+    };
+}
+/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */
+export function wrapToolDefinitions(definitions, ctxFactory) {
+    return definitions.map((definition) => wrapToolDefinition(definition, ctxFactory));
+}
+/**
+ * Synthesize a minimal ToolDefinition from an AgentTool.
+ *
+ * This keeps AgentSession's internal registry definition-first even when a caller
+ * provides plain AgentTool overrides that do not include prompt metadata or renderers.
+ */
+export function createToolDefinitionFromAgentTool(tool) {
+    return {
+        name: tool.name,
+        label: tool.label,
+        description: tool.description,
+        parameters: tool.parameters,
+        constrainedSampling: tool.constrainedSampling,
+        prepareArguments: tool.prepareArguments,
+        executionMode: tool.executionMode,
+        execute: async (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),
+    };
+}
+//# sourceMappingURL=tool-definition-wrapper.js.map

package/dist/core/tools/tool-definition-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-definition-wrapper.js","sourceRoot":"","sources":["../../../src/core/tools/tool-definition-wrapper.ts"],"names":[],"mappings":"AAGA,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CACjC,UAAyC,EACzC,UAAmC,EACR;IAC3B,OAAO;QACN,IAAI,EAAE,UAAU,CAAC,IAAI;QACrB,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,WAAW,EAAE,UAAU,CAAC,WAAW;QACnC,UAAU,EAAE,UAAU,CAAC,UAAU;QACjC,mBAAmB,EAAE,UAAU,CAAC,mBAAmB;QACnD,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;QAC7C,aAAa,EAAE,UAAU,CAAC,aAAa;QACvC,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAsB,EAAE,EAAE,CACzE,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAK,UAAU,EAAE,EAAuB,CAAC;KACtG,CAAC;AAAA,CACF;AAED,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CAClC,WAAuC,EACvC,UAAmC,EAChB;IACnB,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,kBAAkB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC;AAAA,CACnF;AAED;;;;;GAKG;AACH,MAAM,UAAU,iCAAiC,CAAC,IAAoB,EAAgC;IACrG,OAAO;QACN,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAiB;QAClC,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;QAC7C,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC;KAC3G,CAAC;AAAA,CACF","sourcesContent":["import type { AgentTool } from \"@earendil-works/pi-agent-core\";\nimport type { ExtensionContext, ToolDefinition } from \"../extensions/types.ts\";\n\n/** Wrap a ToolDefinition into an AgentTool for the core runtime. */\nexport function wrapToolDefinition<TDetails = unknown>(\n\tdefinition: ToolDefinition<any, TDetails>,\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<any, TDetails> {\n\treturn {\n\t\tname: definition.name,\n\t\tlabel: definition.label,\n\t\tdescription: definition.description,\n\t\tparameters: definition.parameters,\n\t\tconstrainedSampling: definition.constrainedSampling,\n\t\tprepareArguments: definition.prepareArguments,\n\t\texecutionMode: definition.executionMode,\n\t\texecute: (toolCallId, params, signal, onUpdate, ctx?: ExtensionContext) =>\n\t\t\tdefinition.execute(toolCallId, params, signal, onUpdate, ctx ?? (ctxFactory?.() as ExtensionContext)),\n\t};\n}\n\n/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */\nexport function wrapToolDefinitions(\n\tdefinitions: ToolDefinition<any, any>[],\n\tctxFactory?: () => ExtensionContext,\n): AgentTool<any>[] {\n\treturn definitions.map((definition) => wrapToolDefinition(definition, ctxFactory));\n}\n\n/**\n * Synthesize a minimal ToolDefinition from an AgentTool.\n *\n * This keeps AgentSession's internal registry definition-first even when a caller\n * provides plain AgentTool overrides that do not include prompt metadata or renderers.\n */\nexport function createToolDefinitionFromAgentTool(tool: AgentTool<any>): ToolDefinition<any, unknown> {\n\treturn {\n\t\tname: tool.name,\n\t\tlabel: tool.label,\n\t\tdescription: tool.description,\n\t\tparameters: tool.parameters as any,\n\t\tconstrainedSampling: tool.constrainedSampling,\n\t\tprepareArguments: tool.prepareArguments,\n\t\texecutionMode: tool.executionMode,\n\t\texecute: async (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),\n\t};\n}\n"]}

package/dist/core/tools/truncate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines (except bash tail truncation edge case).
+ */
+export declare const DEFAULT_MAX_LINES = 2000;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const GREP_MAX_LINE_LENGTH = 500;
+export interface TruncationResult {
+    /** The truncated content */
+    content: string;
+    /** Whether truncation occurred */
+    truncated: boolean;
+    /** Which limit was hit: "lines", "bytes", or null if not truncated */
+    truncatedBy: "lines" | "bytes" | null;
+    /** Total number of lines in the original content */
+    totalLines: number;
+    /** Total number of bytes in the original content */
+    totalBytes: number;
+    /** Number of complete lines in the truncated output */
+    outputLines: number;
+    /** Number of bytes in the truncated output */
+    outputBytes: number;
+    /** Whether the last line was partially truncated (only for tail truncation edge case) */
+    lastLinePartial: boolean;
+    /** Whether the first line exceeded the byte limit (for head truncation) */
+    firstLineExceedsLimit: boolean;
+    /** The max lines limit that was applied */
+    maxLines: number;
+    /** The max bytes limit that was applied */
+    maxBytes: number;
+}
+export interface TruncationOptions {
+    /** Maximum number of lines (default: 2000) */
+    maxLines?: number;
+    /** Maximum number of bytes (default: 50KB) */
+    maxBytes?: number;
+}
+/**
+ * Format bytes as human-readable size.
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * Suitable for bash output where you want to see the end (errors, final results).
+ *
+ * May return partial first line if the last line of original content exceeds byte limit.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+/**
+ * Truncate a single line to max characters, adding [truncated] suffix.
+ * Used for grep match lines.
+ */
+export declare function truncateLine(line: string, maxChars?: number): {
+    text: string;
+    wasTruncated: boolean;
+};
+//# sourceMappingURL=truncate.d.ts.map

package/dist/core/tools/truncate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../../src/core/tools/truncate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAC3C,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAChC,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,WAAW,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;IACtC,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,eAAe,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,qBAAqB,EAAE,OAAO,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAaD;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAkF/F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAyE/F;AAuBD;;;GAGG;AACH,wBAAgB,YAAY,CAC3B,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAA6B,GACrC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAKzC","sourcesContent":["/**\n * Shared truncation utilities for tool outputs.\n *\n * Truncation is based on two independent limits - whichever is hit first wins:\n * - Line limit (default: 2000 lines)\n * - Byte limit (default: 50KB)\n *\n * Never returns partial lines (except bash tail truncation edge case).\n */\n\nexport const DEFAULT_MAX_LINES = 2000;\nexport const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB\nexport const GREP_MAX_LINE_LENGTH = 500; // Max chars per grep match line\n\nexport interface TruncationResult {\n\t/** The truncated content */\n\tcontent: string;\n\t/** Whether truncation occurred */\n\ttruncated: boolean;\n\t/** Which limit was hit: \"lines\", \"bytes\", or null if not truncated */\n\ttruncatedBy: \"lines\" | \"bytes\" | null;\n\t/** Total number of lines in the original content */\n\ttotalLines: number;\n\t/** Total number of bytes in the original content */\n\ttotalBytes: number;\n\t/** Number of complete lines in the truncated output */\n\toutputLines: number;\n\t/** Number of bytes in the truncated output */\n\toutputBytes: number;\n\t/** Whether the last line was partially truncated (only for tail truncation edge case) */\n\tlastLinePartial: boolean;\n\t/** Whether the first line exceeded the byte limit (for head truncation) */\n\tfirstLineExceedsLimit: boolean;\n\t/** The max lines limit that was applied */\n\tmaxLines: number;\n\t/** The max bytes limit that was applied */\n\tmaxBytes: number;\n}\n\nexport interface TruncationOptions {\n\t/** Maximum number of lines (default: 2000) */\n\tmaxLines?: number;\n\t/** Maximum number of bytes (default: 50KB) */\n\tmaxBytes?: number;\n}\n\nfunction splitLinesForCounting(content: string): string[] {\n\tif (content.length === 0) {\n\t\treturn [];\n\t}\n\tconst lines = content.split(\"\\n\");\n\tif (content.endsWith(\"\\n\")) {\n\t\tlines.pop();\n\t}\n\treturn lines;\n}\n\n/**\n * Format bytes as human-readable size.\n */\nexport function formatSize(bytes: number): string {\n\tif (bytes < 1024) {\n\t\treturn `${bytes}B`;\n\t} else if (bytes < 1024 * 1024) {\n\t\treturn `${(bytes / 1024).toFixed(1)}KB`;\n\t} else {\n\t\treturn `${(bytes / (1024 * 1024)).toFixed(1)}MB`;\n\t}\n}\n\n/**\n * Truncate content from the head (keep first N lines/bytes).\n * Suitable for file reads where you want to see the beginning.\n *\n * Never returns partial lines. If first line exceeds byte limit,\n * returns empty content with firstLineExceedsLimit=true.\n */\nexport function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {\n\tconst maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n\tconst maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\n\tconst totalBytes = Buffer.byteLength(content, \"utf-8\");\n\tconst lines = splitLinesForCounting(content);\n\tconst totalLines = lines.length;\n\n\t// Check if no truncation needed\n\tif (totalLines <= maxLines && totalBytes <= maxBytes) {\n\t\treturn {\n\t\t\tcontent,\n\t\t\ttruncated: false,\n\t\t\ttruncatedBy: null,\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: totalLines,\n\t\t\toutputBytes: totalBytes,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: false,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Check if first line alone exceeds byte limit\n\tconst firstLineBytes = Buffer.byteLength(lines[0], \"utf-8\");\n\tif (firstLineBytes > maxBytes) {\n\t\treturn {\n\t\t\tcontent: \"\",\n\t\t\ttruncated: true,\n\t\t\ttruncatedBy: \"bytes\",\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: 0,\n\t\t\toutputBytes: 0,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: true,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Collect complete lines that fit\n\tconst outputLinesArr: string[] = [];\n\tlet outputBytesCount = 0;\n\tlet truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n\n\tfor (let i = 0; i < lines.length && i < maxLines; i++) {\n\t\tconst line = lines[i];\n\t\tconst lineBytes = Buffer.byteLength(line, \"utf-8\") + (i > 0 ? 1 : 0); // +1 for newline\n\n\t\tif (outputBytesCount + lineBytes > maxBytes) {\n\t\t\ttruncatedBy = \"bytes\";\n\t\t\tbreak;\n\t\t}\n\n\t\toutputLinesArr.push(line);\n\t\toutputBytesCount += lineBytes;\n\t}\n\n\t// If we exited due to line limit\n\tif (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {\n\t\ttruncatedBy = \"lines\";\n\t}\n\n\tconst outputContent = outputLinesArr.join(\"\\n\");\n\tconst finalOutputBytes = Buffer.byteLength(outputContent, \"utf-8\");\n\n\treturn {\n\t\tcontent: outputContent,\n\t\ttruncated: true,\n\t\ttruncatedBy,\n\t\ttotalLines,\n\t\ttotalBytes,\n\t\toutputLines: outputLinesArr.length,\n\t\toutputBytes: finalOutputBytes,\n\t\tlastLinePartial: false,\n\t\tfirstLineExceedsLimit: false,\n\t\tmaxLines,\n\t\tmaxBytes,\n\t};\n}\n\n/**\n * Truncate content from the tail (keep last N lines/bytes).\n * Suitable for bash output where you want to see the end (errors, final results).\n *\n * May return partial first line if the last line of original content exceeds byte limit.\n */\nexport function truncateTail(content: string, options: TruncationOptions = {}): TruncationResult {\n\tconst maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n\tconst maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\n\tconst totalBytes = Buffer.byteLength(content, \"utf-8\");\n\tconst lines = splitLinesForCounting(content);\n\tconst totalLines = lines.length;\n\n\t// Check if no truncation needed\n\tif (totalLines <= maxLines && totalBytes <= maxBytes) {\n\t\treturn {\n\t\t\tcontent,\n\t\t\ttruncated: false,\n\t\t\ttruncatedBy: null,\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: totalLines,\n\t\t\toutputBytes: totalBytes,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: false,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Work backwards from the end\n\tconst outputLinesArr: string[] = [];\n\tlet outputBytesCount = 0;\n\tlet truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n\tlet lastLinePartial = false;\n\n\tfor (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {\n\t\tconst line = lines[i];\n\t\tconst lineBytes = Buffer.byteLength(line, \"utf-8\") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline\n\n\t\tif (outputBytesCount + lineBytes > maxBytes) {\n\t\t\ttruncatedBy = \"bytes\";\n\t\t\t// Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,\n\t\t\t// take the end of the line (partial)\n\t\t\tif (outputLinesArr.length === 0) {\n\t\t\t\tconst truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);\n\t\t\t\toutputLinesArr.unshift(truncatedLine);\n\t\t\t\toutputBytesCount = Buffer.byteLength(truncatedLine, \"utf-8\");\n\t\t\t\tlastLinePartial = true;\n\t\t\t}\n\t\t\tbreak;\n\t\t}\n\n\t\toutputLinesArr.unshift(line);\n\t\toutputBytesCount += lineBytes;\n\t}\n\n\t// If we exited due to line limit\n\tif (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {\n\t\ttruncatedBy = \"lines\";\n\t}\n\n\tconst outputContent = outputLinesArr.join(\"\\n\");\n\tconst finalOutputBytes = Buffer.byteLength(outputContent, \"utf-8\");\n\n\treturn {\n\t\tcontent: outputContent,\n\t\ttruncated: true,\n\t\ttruncatedBy,\n\t\ttotalLines,\n\t\ttotalBytes,\n\t\toutputLines: outputLinesArr.length,\n\t\toutputBytes: finalOutputBytes,\n\t\tlastLinePartial,\n\t\tfirstLineExceedsLimit: false,\n\t\tmaxLines,\n\t\tmaxBytes,\n\t};\n}\n\n/**\n * Truncate a string to fit within a byte limit (from the end).\n * Handles multi-byte UTF-8 characters correctly.\n */\nfunction truncateStringToBytesFromEnd(str: string, maxBytes: number): string {\n\tconst buf = Buffer.from(str, \"utf-8\");\n\tif (buf.length <= maxBytes) {\n\t\treturn str;\n\t}\n\n\t// Start from the end, skip maxBytes back\n\tlet start = buf.length - maxBytes;\n\n\t// Find a valid UTF-8 boundary (start of a character)\n\twhile (start < buf.length && (buf[start] & 0xc0) === 0x80) {\n\t\tstart++;\n\t}\n\n\treturn buf.slice(start).toString(\"utf-8\");\n}\n\n/**\n * Truncate a single line to max characters, adding [truncated] suffix.\n * Used for grep match lines.\n */\nexport function truncateLine(\n\tline: string,\n\tmaxChars: number = GREP_MAX_LINE_LENGTH,\n): { text: string; wasTruncated: boolean } {\n\tif (line.length <= maxChars) {\n\t\treturn { text: line, wasTruncated: false };\n\t}\n\treturn { text: `${line.slice(0, maxChars)}... [truncated]`, wasTruncated: true };\n}\n"]}

package/dist/core/tools/truncate.js

@@ -0,0 +1,215 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines (except bash tail truncation edge case).
+ */
+export const DEFAULT_MAX_LINES = 2000;
+export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
+export const GREP_MAX_LINE_LENGTH = 500; // Max chars per grep match line
+function splitLinesForCounting(content) {
+    if (content.length === 0) {
+        return [];
+    }
+    const lines = content.split("\n");
+    if (content.endsWith("\n")) {
+        lines.pop();
+    }
+    return lines;
+}
+/**
+ * Format bytes as human-readable size.
+ */
+export function formatSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes}B`;
+    }
+    else if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    }
+    else {
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    }
+}
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export function truncateHead(content, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const totalBytes = Buffer.byteLength(content, "utf-8");
+    const lines = splitLinesForCounting(content);
+    const totalLines = lines.length;
+    // Check if no truncation needed
+    if (totalLines <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content,
+            truncated: false,
+            truncatedBy: null,
+            totalLines,
+            totalBytes,
+            outputLines: totalLines,
+            outputBytes: totalBytes,
+            lastLinePartial: false,
+            firstLineExceedsLimit: false,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Check if first line alone exceeds byte limit
+    const firstLineBytes = Buffer.byteLength(lines[0], "utf-8");
+    if (firstLineBytes > maxBytes) {
+        return {
+            content: "",
+            truncated: true,
+            truncatedBy: "bytes",
+            totalLines,
+            totalBytes,
+            outputLines: 0,
+            outputBytes: 0,
+            lastLinePartial: false,
+            firstLineExceedsLimit: true,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Collect complete lines that fit
+    const outputLinesArr = [];
+    let outputBytesCount = 0;
+    let truncatedBy = "lines";
+    for (let i = 0; i < lines.length && i < maxLines; i++) {
+        const line = lines[i];
+        const lineBytes = Buffer.byteLength(line, "utf-8") + (i > 0 ? 1 : 0); // +1 for newline
+        if (outputBytesCount + lineBytes > maxBytes) {
+            truncatedBy = "bytes";
+            break;
+        }
+        outputLinesArr.push(line);
+        outputBytesCount += lineBytes;
+    }
+    // If we exited due to line limit
+    if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+        truncatedBy = "lines";
+    }
+    const outputContent = outputLinesArr.join("\n");
+    const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+    return {
+        content: outputContent,
+        truncated: true,
+        truncatedBy,
+        totalLines,
+        totalBytes,
+        outputLines: outputLinesArr.length,
+        outputBytes: finalOutputBytes,
+        lastLinePartial: false,
+        firstLineExceedsLimit: false,
+        maxLines,
+        maxBytes,
+    };
+}
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * Suitable for bash output where you want to see the end (errors, final results).
+ *
+ * May return partial first line if the last line of original content exceeds byte limit.
+ */
+export function truncateTail(content, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const totalBytes = Buffer.byteLength(content, "utf-8");
+    const lines = splitLinesForCounting(content);
+    const totalLines = lines.length;
+    // Check if no truncation needed
+    if (totalLines <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content,
+            truncated: false,
+            truncatedBy: null,
+            totalLines,
+            totalBytes,
+            outputLines: totalLines,
+            outputBytes: totalBytes,
+            lastLinePartial: false,
+            firstLineExceedsLimit: false,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Work backwards from the end
+    const outputLinesArr = [];
+    let outputBytesCount = 0;
+    let truncatedBy = "lines";
+    let lastLinePartial = false;
+    for (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {
+        const line = lines[i];
+        const lineBytes = Buffer.byteLength(line, "utf-8") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline
+        if (outputBytesCount + lineBytes > maxBytes) {
+            truncatedBy = "bytes";
+            // Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,
+            // take the end of the line (partial)
+            if (outputLinesArr.length === 0) {
+                const truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);
+                outputLinesArr.unshift(truncatedLine);
+                outputBytesCount = Buffer.byteLength(truncatedLine, "utf-8");
+                lastLinePartial = true;
+            }
+            break;
+        }
+        outputLinesArr.unshift(line);
+        outputBytesCount += lineBytes;
+    }
+    // If we exited due to line limit
+    if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+        truncatedBy = "lines";
+    }
+    const outputContent = outputLinesArr.join("\n");
+    const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+    return {
+        content: outputContent,
+        truncated: true,
+        truncatedBy,
+        totalLines,
+        totalBytes,
+        outputLines: outputLinesArr.length,
+        outputBytes: finalOutputBytes,
+        lastLinePartial,
+        firstLineExceedsLimit: false,
+        maxLines,
+        maxBytes,
+    };
+}
+/**
+ * Truncate a string to fit within a byte limit (from the end).
+ * Handles multi-byte UTF-8 characters correctly.
+ */
+function truncateStringToBytesFromEnd(str, maxBytes) {
+    const buf = Buffer.from(str, "utf-8");
+    if (buf.length <= maxBytes) {
+        return str;
+    }
+    // Start from the end, skip maxBytes back
+    let start = buf.length - maxBytes;
+    // Find a valid UTF-8 boundary (start of a character)
+    while (start < buf.length && (buf[start] & 0xc0) === 0x80) {
+        start++;
+    }
+    return buf.slice(start).toString("utf-8");
+}
+/**
+ * Truncate a single line to max characters, adding [truncated] suffix.
+ * Used for grep match lines.
+ */
+export function truncateLine(line, maxChars = GREP_MAX_LINE_LENGTH) {
+    if (line.length <= maxChars) {
+        return { text: line, wasTruncated: false };
+    }
+    return { text: `${line.slice(0, maxChars)}... [truncated]`, wasTruncated: true };
+}
+//# sourceMappingURL=truncate.js.map

package/dist/core/tools/truncate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../../src/core/tools/truncate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared truncation utilities for tool outputs.\n *\n * Truncation is based on two independent limits - whichever is hit first wins:\n * - Line limit (default: 2000 lines)\n * - Byte limit (default: 50KB)\n *\n * Never returns partial lines (except bash tail truncation edge case).\n */\n\nexport const DEFAULT_MAX_LINES = 2000;\nexport const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB\nexport const GREP_MAX_LINE_LENGTH = 500; // Max chars per grep match line\n\nexport interface TruncationResult {\n\t/** The truncated content */\n\tcontent: string;\n\t/** Whether truncation occurred */\n\ttruncated: boolean;\n\t/** Which limit was hit: \"lines\", \"bytes\", or null if not truncated */\n\ttruncatedBy: \"lines\" | \"bytes\" | null;\n\t/** Total number of lines in the original content */\n\ttotalLines: number;\n\t/** Total number of bytes in the original content */\n\ttotalBytes: number;\n\t/** Number of complete lines in the truncated output */\n\toutputLines: number;\n\t/** Number of bytes in the truncated output */\n\toutputBytes: number;\n\t/** Whether the last line was partially truncated (only for tail truncation edge case) */\n\tlastLinePartial: boolean;\n\t/** Whether the first line exceeded the byte limit (for head truncation) */\n\tfirstLineExceedsLimit: boolean;\n\t/** The max lines limit that was applied */\n\tmaxLines: number;\n\t/** The max bytes limit that was applied */\n\tmaxBytes: number;\n}\n\nexport interface TruncationOptions {\n\t/** Maximum number of lines (default: 2000) */\n\tmaxLines?: number;\n\t/** Maximum number of bytes (default: 50KB) */\n\tmaxBytes?: number;\n}\n\nfunction splitLinesForCounting(content: string): string[] {\n\tif (content.length === 0) {\n\t\treturn [];\n\t}\n\tconst lines = content.split(\"\\n\");\n\tif (content.endsWith(\"\\n\")) {\n\t\tlines.pop();\n\t}\n\treturn lines;\n}\n\n/**\n * Format bytes as human-readable size.\n */\nexport function formatSize(bytes: number): string {\n\tif (bytes < 1024) {\n\t\treturn `${bytes}B`;\n\t} else if (bytes < 1024 * 1024) {\n\t\treturn `${(bytes / 1024).toFixed(1)}KB`;\n\t} else {\n\t\treturn `${(bytes / (1024 * 1024)).toFixed(1)}MB`;\n\t}\n}\n\n/**\n * Truncate content from the head (keep first N lines/bytes).\n * Suitable for file reads where you want to see the beginning.\n *\n * Never returns partial lines. If first line exceeds byte limit,\n * returns empty content with firstLineExceedsLimit=true.\n */\nexport function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {\n\tconst maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n\tconst maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\n\tconst totalBytes = Buffer.byteLength(content, \"utf-8\");\n\tconst lines = splitLinesForCounting(content);\n\tconst totalLines = lines.length;\n\n\t// Check if no truncation needed\n\tif (totalLines <= maxLines && totalBytes <= maxBytes) {\n\t\treturn {\n\t\t\tcontent,\n\t\t\ttruncated: false,\n\t\t\ttruncatedBy: null,\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: totalLines,\n\t\t\toutputBytes: totalBytes,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: false,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Check if first line alone exceeds byte limit\n\tconst firstLineBytes = Buffer.byteLength(lines[0], \"utf-8\");\n\tif (firstLineBytes > maxBytes) {\n\t\treturn {\n\t\t\tcontent: \"\",\n\t\t\ttruncated: true,\n\t\t\ttruncatedBy: \"bytes\",\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: 0,\n\t\t\toutputBytes: 0,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: true,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Collect complete lines that fit\n\tconst outputLinesArr: string[] = [];\n\tlet outputBytesCount = 0;\n\tlet truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n\n\tfor (let i = 0; i < lines.length && i < maxLines; i++) {\n\t\tconst line = lines[i];\n\t\tconst lineBytes = Buffer.byteLength(line, \"utf-8\") + (i > 0 ? 1 : 0); // +1 for newline\n\n\t\tif (outputBytesCount + lineBytes > maxBytes) {\n\t\t\ttruncatedBy = \"bytes\";\n\t\t\tbreak;\n\t\t}\n\n\t\toutputLinesArr.push(line);\n\t\toutputBytesCount += lineBytes;\n\t}\n\n\t// If we exited due to line limit\n\tif (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {\n\t\ttruncatedBy = \"lines\";\n\t}\n\n\tconst outputContent = outputLinesArr.join(\"\\n\");\n\tconst finalOutputBytes = Buffer.byteLength(outputContent, \"utf-8\");\n\n\treturn {\n\t\tcontent: outputContent,\n\t\ttruncated: true,\n\t\ttruncatedBy,\n\t\ttotalLines,\n\t\ttotalBytes,\n\t\toutputLines: outputLinesArr.length,\n\t\toutputBytes: finalOutputBytes,\n\t\tlastLinePartial: false,\n\t\tfirstLineExceedsLimit: false,\n\t\tmaxLines,\n\t\tmaxBytes,\n\t};\n}\n\n/**\n * Truncate content from the tail (keep last N lines/bytes).\n * Suitable for bash output where you want to see the end (errors, final results).\n *\n * May return partial first line if the last line of original content exceeds byte limit.\n */\nexport function truncateTail(content: string, options: TruncationOptions = {}): TruncationResult {\n\tconst maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n\tconst maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\n\tconst totalBytes = Buffer.byteLength(content, \"utf-8\");\n\tconst lines = splitLinesForCounting(content);\n\tconst totalLines = lines.length;\n\n\t// Check if no truncation needed\n\tif (totalLines <= maxLines && totalBytes <= maxBytes) {\n\t\treturn {\n\t\t\tcontent,\n\t\t\ttruncated: false,\n\t\t\ttruncatedBy: null,\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: totalLines,\n\t\t\toutputBytes: totalBytes,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: false,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Work backwards from the end\n\tconst outputLinesArr: string[] = [];\n\tlet outputBytesCount = 0;\n\tlet truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n\tlet lastLinePartial = false;\n\n\tfor (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {\n\t\tconst line = lines[i];\n\t\tconst lineBytes = Buffer.byteLength(line, \"utf-8\") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline\n\n\t\tif (outputBytesCount + lineBytes > maxBytes) {\n\t\t\ttruncatedBy = \"bytes\";\n\t\t\t// Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,\n\t\t\t// take the end of the line (partial)\n\t\t\tif (outputLinesArr.length === 0) {\n\t\t\t\tconst truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);\n\t\t\t\toutputLinesArr.unshift(truncatedLine);\n\t\t\t\toutputBytesCount = Buffer.byteLength(truncatedLine, \"utf-8\");\n\t\t\t\tlastLinePartial = true;\n\t\t\t}\n\t\t\tbreak;\n\t\t}\n\n\t\toutputLinesArr.unshift(line);\n\t\toutputBytesCount += lineBytes;\n\t}\n\n\t// If we exited due to line limit\n\tif (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {\n\t\ttruncatedBy = \"lines\";\n\t}\n\n\tconst outputContent = outputLinesArr.join(\"\\n\");\n\tconst finalOutputBytes = Buffer.byteLength(outputContent, \"utf-8\");\n\n\treturn {\n\t\tcontent: outputContent,\n\t\ttruncated: true,\n\t\ttruncatedBy,\n\t\ttotalLines,\n\t\ttotalBytes,\n\t\toutputLines: outputLinesArr.length,\n\t\toutputBytes: finalOutputBytes,\n\t\tlastLinePartial,\n\t\tfirstLineExceedsLimit: false,\n\t\tmaxLines,\n\t\tmaxBytes,\n\t};\n}\n\n/**\n * Truncate a string to fit within a byte limit (from the end).\n * Handles multi-byte UTF-8 characters correctly.\n */\nfunction truncateStringToBytesFromEnd(str: string, maxBytes: number): string {\n\tconst buf = Buffer.from(str, \"utf-8\");\n\tif (buf.length <= maxBytes) {\n\t\treturn str;\n\t}\n\n\t// Start from the end, skip maxBytes back\n\tlet start = buf.length - maxBytes;\n\n\t// Find a valid UTF-8 boundary (start of a character)\n\twhile (start < buf.length && (buf[start] & 0xc0) === 0x80) {\n\t\tstart++;\n\t}\n\n\treturn buf.slice(start).toString(\"utf-8\");\n}\n\n/**\n * Truncate a single line to max characters, adding [truncated] suffix.\n * Used for grep match lines.\n */\nexport function truncateLine(\n\tline: string,\n\tmaxChars: number = GREP_MAX_LINE_LENGTH,\n): { text: string; wasTruncated: boolean } {\n\tif (line.length <= maxChars) {\n\t\treturn { text: line, wasTruncated: false };\n\t}\n\treturn { text: `${line.slice(0, maxChars)}... [truncated]`, wasTruncated: true };\n}\n"]}

package/dist/core/tools/websearch.d.ts

@@ -0,0 +1,29 @@
+import { type Static, Type } from "typebox";
+import type { ToolDefinition } from "../extensions/types.ts";
+declare const websearchSchema: Type.TObject<{
+    query: Type.TString;
+    numResults: Type.TOptional<Type.TNumber>;
+}>;
+export type WebSearchToolInput = Static<typeof websearchSchema>;
+export interface WebSearchToolDetails {
+    query: string;
+    /** True when a key was used, so the UI can explain a rate limit accurately. */
+    authenticated: boolean;
+}
+export interface WebSearchToolOptions {
+    /** Overridable so tests never reach the network. */
+    fetchImpl?: typeof fetch;
+    apiKey?: string | undefined;
+}
+/**
+ * The endpoint answers `application/json` or an SSE stream depending on how it
+ * feels; both carry the same JSON-RPC envelope, so pull the payload out of
+ * whichever arrived.
+ */
+export declare function parseMcpPayload(body: string): unknown;
+/** Flatten the MCP tool result into the text the model reads. */
+export declare function extractResultText(payload: unknown): string;
+export declare function createWebSearchToolDefinition(options?: WebSearchToolOptions): ToolDefinition<typeof websearchSchema, WebSearchToolDetails | undefined>;
+export declare const createWebSearchTool: (options?: WebSearchToolOptions | undefined) => import("@earendil-works/pi-agent-core").AgentTool<any, WebSearchToolDetails | undefined>;
+export {};
+//# sourceMappingURL=websearch.d.ts.map

package/dist/core/tools/websearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websearch.d.ts","sourceRoot":"","sources":["../../../src/core/tools/websearch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,wBAAwB,CAAC;AAsBtF,QAAA,MAAM,eAAe;;;EAKnB,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAEhE,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,aAAa,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACpC,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAOD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAcrD;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAoB1D;AAED,wBAAgB,6BAA6B,CAC5C,OAAO,CAAC,EAAE,oBAAoB,GAC5B,cAAc,CAAC,OAAO,eAAe,EAAE,oBAAoB,GAAG,SAAS,CAAC,CA6E1E;AAED,eAAO,MAAM,mBAAmB,0IAC2B,CAAC","sourcesContent":["import { Text } from \"@earendil-works/pi-tui\";\nimport { type Static, Type } from \"typebox\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport type { ToolDefinition, ToolRenderResultOptions } from \"../extensions/types.ts\";\nimport { getTextOutput, str } from \"./render-utils.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\n/**\n * Web search through Exa's hosted MCP endpoint.\n *\n * The endpoint answers unauthenticated requests on a free plan, so search works\n * with no configuration at all. EXA_API_KEY lifts the rate limit and is what a\n * deployment should use — Exa's own guidance is to authenticate for sustained\n * use, and the anonymous pool is shared with every other unauthenticated caller\n * on the internet.\n *\n * Only the transport is spoken here rather than pulling in an MCP client: this\n * is one JSON-RPC method against one known endpoint, and the response is a\n * text block either way.\n */\n\nconst EXA_MCP_URL = \"https://mcp.exa.ai/mcp\";\nconst DEFAULT_RESULTS = 8;\nconst REQUEST_TIMEOUT_MS = 25_000;\n\nconst websearchSchema = Type.Object({\n\tquery: Type.String({ description: \"What to search the web for\" }),\n\tnumResults: Type.Optional(\n\t\tType.Number({ description: `Maximum number of results to return (default: ${DEFAULT_RESULTS})` }),\n\t),\n});\n\nexport type WebSearchToolInput = Static<typeof websearchSchema>;\n\nexport interface WebSearchToolDetails {\n\tquery: string;\n\t/** True when a key was used, so the UI can explain a rate limit accurately. */\n\tauthenticated: boolean;\n}\n\nexport interface WebSearchToolOptions {\n\t/** Overridable so tests never reach the network. */\n\tfetchImpl?: typeof fetch;\n\tapiKey?: string | undefined;\n}\n\n/** Exa reads the key from a query parameter on the hosted endpoint. */\nfunction endpointFor(apiKey: string | undefined): string {\n\treturn apiKey ? `${EXA_MCP_URL}?exaApiKey=${encodeURIComponent(apiKey)}` : EXA_MCP_URL;\n}\n\n/**\n * The endpoint answers `application/json` or an SSE stream depending on how it\n * feels; both carry the same JSON-RPC envelope, so pull the payload out of\n * whichever arrived.\n */\nexport function parseMcpPayload(body: string): unknown {\n\tconst trimmed = body.trim();\n\tif (!trimmed) throw new Error(\"Search returned an empty response\");\n\n\tif (trimmed.startsWith(\"{\")) return JSON.parse(trimmed);\n\n\t// SSE: one or more `data:` lines, last one wins.\n\tconst dataLines = trimmed\n\t\t.split(\"\\n\")\n\t\t.filter((line) => line.startsWith(\"data:\"))\n\t\t.map((line) => line.slice(5).trim());\n\tconst last = dataLines.at(-1);\n\tif (!last) throw new Error(\"Search returned an unrecognized response\");\n\treturn JSON.parse(last);\n}\n\n/** Flatten the MCP tool result into the text the model reads. */\nexport function extractResultText(payload: unknown): string {\n\tconst envelope = payload as {\n\t\terror?: { message?: string };\n\t\tresult?: { content?: Array<{ type?: string; text?: string }>; isError?: boolean };\n\t};\n\n\tif (envelope?.error?.message) throw new Error(envelope.error.message);\n\n\tconst content = envelope?.result?.content;\n\tif (!Array.isArray(content)) throw new Error(\"Search returned no results\");\n\n\tconst text = content\n\t\t.filter((part) => part?.type === \"text\" && typeof part.text === \"string\")\n\t\t.map((part) => part.text)\n\t\t.join(\"\\n\")\n\t\t.trim();\n\n\tif (!text) throw new Error(\"Search returned no results\");\n\tif (envelope.result?.isError) throw new Error(text);\n\treturn text;\n}\n\nexport function createWebSearchToolDefinition(\n\toptions?: WebSearchToolOptions,\n): ToolDefinition<typeof websearchSchema, WebSearchToolDetails | undefined> {\n\treturn {\n\t\tname: \"websearch\",\n\t\tlabel: \"websearch\",\n\t\tdescription:\n\t\t\t\"Search the web and return ranked results with excerpts. Use for current information, documentation, error messages, and anything outside the repository.\",\n\t\tpromptSnippet: \"Search the web for current information\",\n\t\tpromptGuidelines: [\"Use websearch for anything outside the repository; do not guess at current facts.\"],\n\t\tparameters: websearchSchema,\n\t\tasync execute(_toolCallId, { query, numResults }, signal?: AbortSignal) {\n\t\t\tconst doFetch = options?.fetchImpl ?? fetch;\n\t\t\tconst apiKey = options?.apiKey ?? process.env.EXA_API_KEY;\n\n\t\t\t// Bound the request ourselves and honour an outer abort, so a hung\n\t\t\t// endpoint cannot wedge the turn.\n\t\t\tconst controller = new AbortController();\n\t\t\tconst timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);\n\t\t\tconst onAbort = () => controller.abort();\n\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\n\t\t\tlet response: Response;\n\t\t\ttry {\n\t\t\t\tresponse = await doFetch(endpointFor(apiKey), {\n\t\t\t\t\tmethod: \"POST\",\n\t\t\t\t\theaders: { \"content-type\": \"application/json\", accept: \"application/json, text/event-stream\" },\n\t\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\t\tjsonrpc: \"2.0\",\n\t\t\t\t\t\tid: 1,\n\t\t\t\t\t\tmethod: \"tools/call\",\n\t\t\t\t\t\tparams: {\n\t\t\t\t\t\t\tname: \"web_search_exa\",\n\t\t\t\t\t\t\targuments: { query, numResults: numResults ?? DEFAULT_RESULTS, type: \"auto\" },\n\t\t\t\t\t\t},\n\t\t\t\t\t}),\n\t\t\t\t\tsignal: controller.signal,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t\t\t\tif (controller.signal.aborted) throw new Error(`Search timed out after ${REQUEST_TIMEOUT_MS / 1000}s`);\n\t\t\t\tthrow new Error(`Search request failed: ${error instanceof Error ? error.message : String(error)}`);\n\t\t\t} finally {\n\t\t\t\tclearTimeout(timer);\n\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t}\n\n\t\t\t// A rate limit is the one failure worth naming: it is expected on the\n\t\t\t// free plan, and the fix is specific rather than \"try again\".\n\t\t\tif (response.status === 429) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\tapiKey\n\t\t\t\t\t\t? \"Search rate limit reached for this Exa API key.\"\n\t\t\t\t\t\t: \"Search rate limit reached on Exa's free plan. Set EXA_API_KEY to raise it.\",\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (!response.ok) {\n\t\t\t\tthrow new Error(`Search failed with HTTP ${response.status}`);\n\t\t\t}\n\n\t\t\tconst text = extractResultText(parseMcpPayload(await response.text()));\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text }],\n\t\t\t\tdetails: { query, authenticated: apiKey !== undefined },\n\t\t\t};\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\tconst query = str(args?.query);\n\t\t\ttext.setText(query ? theme.fg(\"muted\", query) : \"\");\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, _options: ToolRenderResultOptions, theme: Theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\t// Results are text only; images never appear in a search payload.\n\t\t\ttext.setText(theme.fg(\"muted\", getTextOutput(result as never, false)));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport const createWebSearchTool = (options?: WebSearchToolOptions) =>\n\twrapToolDefinition(createWebSearchToolDefinition(options));\n"]}

package/dist/core/tools/websearch.js

@@ -0,0 +1,145 @@
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { getTextOutput, str } from "./render-utils.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+/**
+ * Web search through Exa's hosted MCP endpoint.
+ *
+ * The endpoint answers unauthenticated requests on a free plan, so search works
+ * with no configuration at all. EXA_API_KEY lifts the rate limit and is what a
+ * deployment should use — Exa's own guidance is to authenticate for sustained
+ * use, and the anonymous pool is shared with every other unauthenticated caller
+ * on the internet.
+ *
+ * Only the transport is spoken here rather than pulling in an MCP client: this
+ * is one JSON-RPC method against one known endpoint, and the response is a
+ * text block either way.
+ */
+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+const DEFAULT_RESULTS = 8;
+const REQUEST_TIMEOUT_MS = 25_000;
+const websearchSchema = Type.Object({
+    query: Type.String({ description: "What to search the web for" }),
+    numResults: Type.Optional(Type.Number({ description: `Maximum number of results to return (default: ${DEFAULT_RESULTS})` })),
+});
+/** Exa reads the key from a query parameter on the hosted endpoint. */
+function endpointFor(apiKey) {
+    return apiKey ? `${EXA_MCP_URL}?exaApiKey=${encodeURIComponent(apiKey)}` : EXA_MCP_URL;
+}
+/**
+ * The endpoint answers `application/json` or an SSE stream depending on how it
+ * feels; both carry the same JSON-RPC envelope, so pull the payload out of
+ * whichever arrived.
+ */
+export function parseMcpPayload(body) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        throw new Error("Search returned an empty response");
+    if (trimmed.startsWith("{"))
+        return JSON.parse(trimmed);
+    // SSE: one or more `data:` lines, last one wins.
+    const dataLines = trimmed
+        .split("\n")
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice(5).trim());
+    const last = dataLines.at(-1);
+    if (!last)
+        throw new Error("Search returned an unrecognized response");
+    return JSON.parse(last);
+}
+/** Flatten the MCP tool result into the text the model reads. */
+export function extractResultText(payload) {
+    const envelope = payload;
+    if (envelope?.error?.message)
+        throw new Error(envelope.error.message);
+    const content = envelope?.result?.content;
+    if (!Array.isArray(content))
+        throw new Error("Search returned no results");
+    const text = content
+        .filter((part) => part?.type === "text" && typeof part.text === "string")
+        .map((part) => part.text)
+        .join("\n")
+        .trim();
+    if (!text)
+        throw new Error("Search returned no results");
+    if (envelope.result?.isError)
+        throw new Error(text);
+    return text;
+}
+export function createWebSearchToolDefinition(options) {
+    return {
+        name: "websearch",
+        label: "websearch",
+        description: "Search the web and return ranked results with excerpts. Use for current information, documentation, error messages, and anything outside the repository.",
+        promptSnippet: "Search the web for current information",
+        promptGuidelines: ["Use websearch for anything outside the repository; do not guess at current facts."],
+        parameters: websearchSchema,
+        async execute(_toolCallId, { query, numResults }, signal) {
+            const doFetch = options?.fetchImpl ?? fetch;
+            const apiKey = options?.apiKey ?? process.env.EXA_API_KEY;
+            // Bound the request ourselves and honour an outer abort, so a hung
+            // endpoint cannot wedge the turn.
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+            const onAbort = () => controller.abort();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            let response;
+            try {
+                response = await doFetch(endpointFor(apiKey), {
+                    method: "POST",
+                    headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+                    body: JSON.stringify({
+                        jsonrpc: "2.0",
+                        id: 1,
+                        method: "tools/call",
+                        params: {
+                            name: "web_search_exa",
+                            arguments: { query, numResults: numResults ?? DEFAULT_RESULTS, type: "auto" },
+                        },
+                    }),
+                    signal: controller.signal,
+                });
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw new Error("Operation aborted");
+                if (controller.signal.aborted)
+                    throw new Error(`Search timed out after ${REQUEST_TIMEOUT_MS / 1000}s`);
+                throw new Error(`Search request failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            finally {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+            }
+            // A rate limit is the one failure worth naming: it is expected on the
+            // free plan, and the fix is specific rather than "try again".
+            if (response.status === 429) {
+                throw new Error(apiKey
+                    ? "Search rate limit reached for this Exa API key."
+                    : "Search rate limit reached on Exa's free plan. Set EXA_API_KEY to raise it.");
+            }
+            if (!response.ok) {
+                throw new Error(`Search failed with HTTP ${response.status}`);
+            }
+            const text = extractResultText(parseMcpPayload(await response.text()));
+            return {
+                content: [{ type: "text", text }],
+                details: { query, authenticated: apiKey !== undefined },
+            };
+        },
+        renderCall(args, theme, context) {
+            const text = context.lastComponent ?? new Text("", 0, 0);
+            const query = str(args?.query);
+            text.setText(query ? theme.fg("muted", query) : "");
+            return text;
+        },
+        renderResult(result, _options, theme, context) {
+            const text = context.lastComponent ?? new Text("", 0, 0);
+            // Results are text only; images never appear in a search payload.
+            text.setText(theme.fg("muted", getTextOutput(result, false)));
+            return text;
+        },
+    };
+}
+export const createWebSearchTool = (options) => wrapToolDefinition(createWebSearchToolDefinition(options));
+//# sourceMappingURL=websearch.js.map

package/dist/core/tools/websearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websearch.js","sourceRoot":"","sources":["../../../src/core/tools/websearch.ts"],"names":[],"mappings":"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","sourcesContent":["import { Text } from \"@earendil-works/pi-tui\";\nimport { type Static, Type } from \"typebox\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport type { ToolDefinition, ToolRenderResultOptions } from \"../extensions/types.ts\";\nimport { getTextOutput, str } from \"./render-utils.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\n/**\n * Web search through Exa's hosted MCP endpoint.\n *\n * The endpoint answers unauthenticated requests on a free plan, so search works\n * with no configuration at all. EXA_API_KEY lifts the rate limit and is what a\n * deployment should use — Exa's own guidance is to authenticate for sustained\n * use, and the anonymous pool is shared with every other unauthenticated caller\n * on the internet.\n *\n * Only the transport is spoken here rather than pulling in an MCP client: this\n * is one JSON-RPC method against one known endpoint, and the response is a\n * text block either way.\n */\n\nconst EXA_MCP_URL = \"https://mcp.exa.ai/mcp\";\nconst DEFAULT_RESULTS = 8;\nconst REQUEST_TIMEOUT_MS = 25_000;\n\nconst websearchSchema = Type.Object({\n\tquery: Type.String({ description: \"What to search the web for\" }),\n\tnumResults: Type.Optional(\n\t\tType.Number({ description: `Maximum number of results to return (default: ${DEFAULT_RESULTS})` }),\n\t),\n});\n\nexport type WebSearchToolInput = Static<typeof websearchSchema>;\n\nexport interface WebSearchToolDetails {\n\tquery: string;\n\t/** True when a key was used, so the UI can explain a rate limit accurately. */\n\tauthenticated: boolean;\n}\n\nexport interface WebSearchToolOptions {\n\t/** Overridable so tests never reach the network. */\n\tfetchImpl?: typeof fetch;\n\tapiKey?: string | undefined;\n}\n\n/** Exa reads the key from a query parameter on the hosted endpoint. */\nfunction endpointFor(apiKey: string | undefined): string {\n\treturn apiKey ? `${EXA_MCP_URL}?exaApiKey=${encodeURIComponent(apiKey)}` : EXA_MCP_URL;\n}\n\n/**\n * The endpoint answers `application/json` or an SSE stream depending on how it\n * feels; both carry the same JSON-RPC envelope, so pull the payload out of\n * whichever arrived.\n */\nexport function parseMcpPayload(body: string): unknown {\n\tconst trimmed = body.trim();\n\tif (!trimmed) throw new Error(\"Search returned an empty response\");\n\n\tif (trimmed.startsWith(\"{\")) return JSON.parse(trimmed);\n\n\t// SSE: one or more `data:` lines, last one wins.\n\tconst dataLines = trimmed\n\t\t.split(\"\\n\")\n\t\t.filter((line) => line.startsWith(\"data:\"))\n\t\t.map((line) => line.slice(5).trim());\n\tconst last = dataLines.at(-1);\n\tif (!last) throw new Error(\"Search returned an unrecognized response\");\n\treturn JSON.parse(last);\n}\n\n/** Flatten the MCP tool result into the text the model reads. */\nexport function extractResultText(payload: unknown): string {\n\tconst envelope = payload as {\n\t\terror?: { message?: string };\n\t\tresult?: { content?: Array<{ type?: string; text?: string }>; isError?: boolean };\n\t};\n\n\tif (envelope?.error?.message) throw new Error(envelope.error.message);\n\n\tconst content = envelope?.result?.content;\n\tif (!Array.isArray(content)) throw new Error(\"Search returned no results\");\n\n\tconst text = content\n\t\t.filter((part) => part?.type === \"text\" && typeof part.text === \"string\")\n\t\t.map((part) => part.text)\n\t\t.join(\"\\n\")\n\t\t.trim();\n\n\tif (!text) throw new Error(\"Search returned no results\");\n\tif (envelope.result?.isError) throw new Error(text);\n\treturn text;\n}\n\nexport function createWebSearchToolDefinition(\n\toptions?: WebSearchToolOptions,\n): ToolDefinition<typeof websearchSchema, WebSearchToolDetails | undefined> {\n\treturn {\n\t\tname: \"websearch\",\n\t\tlabel: \"websearch\",\n\t\tdescription:\n\t\t\t\"Search the web and return ranked results with excerpts. Use for current information, documentation, error messages, and anything outside the repository.\",\n\t\tpromptSnippet: \"Search the web for current information\",\n\t\tpromptGuidelines: [\"Use websearch for anything outside the repository; do not guess at current facts.\"],\n\t\tparameters: websearchSchema,\n\t\tasync execute(_toolCallId, { query, numResults }, signal?: AbortSignal) {\n\t\t\tconst doFetch = options?.fetchImpl ?? fetch;\n\t\t\tconst apiKey = options?.apiKey ?? process.env.EXA_API_KEY;\n\n\t\t\t// Bound the request ourselves and honour an outer abort, so a hung\n\t\t\t// endpoint cannot wedge the turn.\n\t\t\tconst controller = new AbortController();\n\t\t\tconst timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);\n\t\t\tconst onAbort = () => controller.abort();\n\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\n\t\t\tlet response: Response;\n\t\t\ttry {\n\t\t\t\tresponse = await doFetch(endpointFor(apiKey), {\n\t\t\t\t\tmethod: \"POST\",\n\t\t\t\t\theaders: { \"content-type\": \"application/json\", accept: \"application/json, text/event-stream\" },\n\t\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\t\tjsonrpc: \"2.0\",\n\t\t\t\t\t\tid: 1,\n\t\t\t\t\t\tmethod: \"tools/call\",\n\t\t\t\t\t\tparams: {\n\t\t\t\t\t\t\tname: \"web_search_exa\",\n\t\t\t\t\t\t\targuments: { query, numResults: numResults ?? DEFAULT_RESULTS, type: \"auto\" },\n\t\t\t\t\t\t},\n\t\t\t\t\t}),\n\t\t\t\t\tsignal: controller.signal,\n\t\t\t\t});\n\t\t\t} catch (error) {\n\t\t\t\tif (signal?.aborted) throw new Error(\"Operation aborted\");\n\t\t\t\tif (controller.signal.aborted) throw new Error(`Search timed out after ${REQUEST_TIMEOUT_MS / 1000}s`);\n\t\t\t\tthrow new Error(`Search request failed: ${error instanceof Error ? error.message : String(error)}`);\n\t\t\t} finally {\n\t\t\t\tclearTimeout(timer);\n\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t}\n\n\t\t\t// A rate limit is the one failure worth naming: it is expected on the\n\t\t\t// free plan, and the fix is specific rather than \"try again\".\n\t\t\tif (response.status === 429) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\tapiKey\n\t\t\t\t\t\t? \"Search rate limit reached for this Exa API key.\"\n\t\t\t\t\t\t: \"Search rate limit reached on Exa's free plan. Set EXA_API_KEY to raise it.\",\n\t\t\t\t);\n\t\t\t}\n\t\t\tif (!response.ok) {\n\t\t\t\tthrow new Error(`Search failed with HTTP ${response.status}`);\n\t\t\t}\n\n\t\t\tconst text = extractResultText(parseMcpPayload(await response.text()));\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text }],\n\t\t\t\tdetails: { query, authenticated: apiKey !== undefined },\n\t\t\t};\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\tconst query = str(args?.query);\n\t\t\ttext.setText(query ? theme.fg(\"muted\", query) : \"\");\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, _options: ToolRenderResultOptions, theme: Theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\t// Results are text only; images never appear in a search payload.\n\t\t\ttext.setText(theme.fg(\"muted\", getTextOutput(result as never, false)));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport const createWebSearchTool = (options?: WebSearchToolOptions) =>\n\twrapToolDefinition(createWebSearchToolDefinition(options));\n"]}

package/dist/core/tools/write.d.ts

@@ -0,0 +1,26 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type Static, Type } from "typebox";
+import type { ToolDefinition } from "../extensions/types.ts";
+declare const writeSchema: Type.TObject<{
+    path: Type.TString;
+    content: Type.TString;
+}>;
+export type WriteToolInput = Static<typeof writeSchema>;
+/**
+ * Pluggable operations for the write tool.
+ * Override these to delegate file writing to remote systems (for example SSH).
+ */
+export interface WriteOperations {
+    /** Write content to a file */
+    writeFile: (absolutePath: string, content: string) => Promise<void>;
+    /** Create directory recursively */
+    mkdir: (dir: string) => Promise<void>;
+}
+export interface WriteToolOptions {
+    /** Custom operations for file writing. Default: local filesystem */
+    operations?: WriteOperations;
+}
+export declare function createWriteToolDefinition(cwd: string, options?: WriteToolOptions): ToolDefinition<typeof writeSchema, undefined>;
+export declare function createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool<typeof writeSchema>;
+export {};
+//# sourceMappingURL=write.d.ts.map