@ai-agent-forge/agent-forge 0.85.0

package/dist/core/tools/render-utils.d.ts

@@ -0,0 +1,24 @@
+import type { ImageContent, TextContent } from "@agent-forge/ai";
+import type { Theme } from "../../modes/interactive/theme/theme.ts";
+export declare function shortenPath(path: unknown): string;
+export declare function linkPath(styledText: string, rawPath: string, cwd: string): string;
+export declare function str(value: unknown): string | null;
+export declare function replaceTabs(text: string): string;
+export declare function normalizeDisplayText(text: string): string;
+export declare function getTextOutput(result: {
+    content: Array<{
+        type: string;
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+} | undefined, showImages: boolean): string;
+export type ToolRenderResultLike<TDetails> = {
+    content: (TextContent | ImageContent)[];
+    details: TDetails;
+};
+export declare function invalidArgText(theme: Theme): string;
+export declare function renderToolPath(rawPath: string | null, theme: Theme, cwd: string, options?: {
+    emptyFallback?: string;
+}): string;
+//# sourceMappingURL=render-utils.d.ts.map

package/dist/core/tools/render-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-utils.d.ts","sourceRoot":"","sources":["../../../src/core/tools/render-utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEjE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wCAAwC,CAAC;AAKpE,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAOjD;AAED,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIjF;AAED,wBAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAIjD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,aAAa,CAC5B,MAAM,EAAE;IAAE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,SAAS,EACzG,UAAU,EAAE,OAAO,GACjB,MAAM,CAsBR;AAED,MAAM,MAAM,oBAAoB,CAAC,QAAQ,IAAI;IAC5C,OAAO,EAAE,CAAC,WAAW,GAAG,YAAY,CAAC,EAAE,CAAC;IACxC,OAAO,EAAE,QAAQ,CAAC;CAClB,CAAC;AAEF,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAEnD;AAED,wBAAgB,cAAc,CAC7B,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC,MAAM,CAKR","sourcesContent":["import * as os from \"node:os\";\nimport { pathToFileURL } from \"node:url\";\nimport type { ImageContent, TextContent } from \"@agent-forge/ai\";\nimport { getCapabilities, getImageDimensions, hyperlink, imageFallback } from \"@agent-forge/tui\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport { stripAnsi } from \"../../utils/ansi.ts\";\nimport { resolvePath } from \"../../utils/paths.ts\";\nimport { sanitizeBinaryOutput } from \"../../utils/shell.ts\";\n\nexport function shortenPath(path: unknown): string {\n\tif (typeof path !== \"string\") return \"\";\n\tconst home = os.homedir();\n\tif (path.startsWith(home)) {\n\t\treturn `~${path.slice(home.length)}`;\n\t}\n\treturn path;\n}\n\nexport function linkPath(styledText: string, rawPath: string, cwd: string): string {\n\tif (!getCapabilities().hyperlinks) return styledText;\n\tconst absolutePath = resolvePath(rawPath, cwd);\n\treturn hyperlink(styledText, pathToFileURL(absolutePath).href);\n}\n\nexport function str(value: unknown): string | null {\n\tif (typeof value === \"string\") return value;\n\tif (value == null) return \"\";\n\treturn null;\n}\n\nexport function replaceTabs(text: string): string {\n\treturn text.replace(/\\t/g, \"   \");\n}\n\nexport function normalizeDisplayText(text: string): string {\n\treturn text.replace(/\\r/g, \"\");\n}\n\nexport function getTextOutput(\n\tresult: { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> } | undefined,\n\tshowImages: boolean,\n): string {\n\tif (!result) return \"\";\n\n\tconst textBlocks = result.content.filter((c) => c.type === \"text\");\n\tconst imageBlocks = result.content.filter((c) => c.type === \"image\");\n\n\tlet output = textBlocks.map((c) => sanitizeBinaryOutput(stripAnsi(c.text || \"\")).replace(/\\r/g, \"\")).join(\"\\n\");\n\n\tconst caps = getCapabilities();\n\tif (imageBlocks.length > 0 && (!caps.images || !showImages)) {\n\t\tconst imageIndicators = imageBlocks\n\t\t\t.map((img) => {\n\t\t\t\tconst mimeType = img.mimeType ?? \"image/unknown\";\n\t\t\t\tconst dims =\n\t\t\t\t\timg.data && img.mimeType ? (getImageDimensions(img.data, img.mimeType) ?? undefined) : undefined;\n\t\t\t\treturn imageFallback(mimeType, dims);\n\t\t\t})\n\t\t\t.join(\"\\n\");\n\t\toutput = output ? `${output}\\n${imageIndicators}` : imageIndicators;\n\t}\n\n\treturn output;\n}\n\nexport type ToolRenderResultLike<TDetails> = {\n\tcontent: (TextContent | ImageContent)[];\n\tdetails: TDetails;\n};\n\nexport function invalidArgText(theme: Theme): string {\n\treturn theme.fg(\"error\", \"[invalid arg]\");\n}\n\nexport function renderToolPath(\n\trawPath: string | null,\n\ttheme: Theme,\n\tcwd: string,\n\toptions?: { emptyFallback?: string },\n): string {\n\tif (rawPath === null) return invalidArgText(theme);\n\tconst value = rawPath || options?.emptyFallback;\n\tif (!value) return theme.fg(\"toolOutput\", \"...\");\n\treturn linkPath(theme.fg(\"accent\", shortenPath(value)), value, cwd);\n}\n"]}

package/dist/core/tools/render-utils.js

@@ -0,0 +1,65 @@
+import * as os from "node:os";
+import { pathToFileURL } from "node:url";
+import { getCapabilities, getImageDimensions, hyperlink, imageFallback } from "@agent-forge/tui";
+import { stripAnsi } from "../../utils/ansi.js";
+import { resolvePath } from "../../utils/paths.js";
+import { sanitizeBinaryOutput } from "../../utils/shell.js";
+export function shortenPath(path) {
+    if (typeof path !== "string")
+        return "";
+    const home = os.homedir();
+    if (path.startsWith(home)) {
+        return `~${path.slice(home.length)}`;
+    }
+    return path;
+}
+export function linkPath(styledText, rawPath, cwd) {
+    if (!getCapabilities().hyperlinks)
+        return styledText;
+    const absolutePath = resolvePath(rawPath, cwd);
+    return hyperlink(styledText, pathToFileURL(absolutePath).href);
+}
+export function str(value) {
+    if (typeof value === "string")
+        return value;
+    if (value == null)
+        return "";
+    return null;
+}
+export function replaceTabs(text) {
+    return text.replace(/\t/g, "   ");
+}
+export function normalizeDisplayText(text) {
+    return text.replace(/\r/g, "");
+}
+export function getTextOutput(result, showImages) {
+    if (!result)
+        return "";
+    const textBlocks = result.content.filter((c) => c.type === "text");
+    const imageBlocks = result.content.filter((c) => c.type === "image");
+    let output = textBlocks.map((c) => sanitizeBinaryOutput(stripAnsi(c.text || "")).replace(/\r/g, "")).join("\n");
+    const caps = getCapabilities();
+    if (imageBlocks.length > 0 && (!caps.images || !showImages)) {
+        const imageIndicators = imageBlocks
+            .map((img) => {
+            const mimeType = img.mimeType ?? "image/unknown";
+            const dims = img.data && img.mimeType ? (getImageDimensions(img.data, img.mimeType) ?? undefined) : undefined;
+            return imageFallback(mimeType, dims);
+        })
+            .join("\n");
+        output = output ? `${output}\n${imageIndicators}` : imageIndicators;
+    }
+    return output;
+}
+export function invalidArgText(theme) {
+    return theme.fg("error", "[invalid arg]");
+}
+export function renderToolPath(rawPath, theme, cwd, options) {
+    if (rawPath === null)
+        return invalidArgText(theme);
+    const value = rawPath || options?.emptyFallback;
+    if (!value)
+        return theme.fg("toolOutput", "...");
+    return linkPath(theme.fg("accent", shortenPath(value)), value, cwd);
+}
+//# sourceMappingURL=render-utils.js.map

package/dist/core/tools/render-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-utils.js","sourceRoot":"","sources":["../../../src/core/tools/render-utils.ts"],"names":[],"mappings":"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","sourcesContent":["import * as os from \"node:os\";\nimport { pathToFileURL } from \"node:url\";\nimport type { ImageContent, TextContent } from \"@agent-forge/ai\";\nimport { getCapabilities, getImageDimensions, hyperlink, imageFallback } from \"@agent-forge/tui\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport { stripAnsi } from \"../../utils/ansi.ts\";\nimport { resolvePath } from \"../../utils/paths.ts\";\nimport { sanitizeBinaryOutput } from \"../../utils/shell.ts\";\n\nexport function shortenPath(path: unknown): string {\n\tif (typeof path !== \"string\") return \"\";\n\tconst home = os.homedir();\n\tif (path.startsWith(home)) {\n\t\treturn `~${path.slice(home.length)}`;\n\t}\n\treturn path;\n}\n\nexport function linkPath(styledText: string, rawPath: string, cwd: string): string {\n\tif (!getCapabilities().hyperlinks) return styledText;\n\tconst absolutePath = resolvePath(rawPath, cwd);\n\treturn hyperlink(styledText, pathToFileURL(absolutePath).href);\n}\n\nexport function str(value: unknown): string | null {\n\tif (typeof value === \"string\") return value;\n\tif (value == null) return \"\";\n\treturn null;\n}\n\nexport function replaceTabs(text: string): string {\n\treturn text.replace(/\\t/g, \"   \");\n}\n\nexport function normalizeDisplayText(text: string): string {\n\treturn text.replace(/\\r/g, \"\");\n}\n\nexport function getTextOutput(\n\tresult: { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> } | undefined,\n\tshowImages: boolean,\n): string {\n\tif (!result) return \"\";\n\n\tconst textBlocks = result.content.filter((c) => c.type === \"text\");\n\tconst imageBlocks = result.content.filter((c) => c.type === \"image\");\n\n\tlet output = textBlocks.map((c) => sanitizeBinaryOutput(stripAnsi(c.text || \"\")).replace(/\\r/g, \"\")).join(\"\\n\");\n\n\tconst caps = getCapabilities();\n\tif (imageBlocks.length > 0 && (!caps.images || !showImages)) {\n\t\tconst imageIndicators = imageBlocks\n\t\t\t.map((img) => {\n\t\t\t\tconst mimeType = img.mimeType ?? \"image/unknown\";\n\t\t\t\tconst dims =\n\t\t\t\t\timg.data && img.mimeType ? (getImageDimensions(img.data, img.mimeType) ?? undefined) : undefined;\n\t\t\t\treturn imageFallback(mimeType, dims);\n\t\t\t})\n\t\t\t.join(\"\\n\");\n\t\toutput = output ? `${output}\\n${imageIndicators}` : imageIndicators;\n\t}\n\n\treturn output;\n}\n\nexport type ToolRenderResultLike<TDetails> = {\n\tcontent: (TextContent | ImageContent)[];\n\tdetails: TDetails;\n};\n\nexport function invalidArgText(theme: Theme): string {\n\treturn theme.fg(\"error\", \"[invalid arg]\");\n}\n\nexport function renderToolPath(\n\trawPath: string | null,\n\ttheme: Theme,\n\tcwd: string,\n\toptions?: { emptyFallback?: string },\n): string {\n\tif (rawPath === null) return invalidArgText(theme);\n\tconst value = rawPath || options?.emptyFallback;\n\tif (!value) return theme.fg(\"toolOutput\", \"...\");\n\treturn linkPath(theme.fg(\"accent\", shortenPath(value)), value, cwd);\n}\n"]}

package/dist/core/tools/tool-definition-wrapper.d.ts

@@ -0,0 +1,15 @@
+import type { AgentTool } from "@agent-forge/agent-core";
+import type { TSchema } from "typebox";
+import type { ToolDefinition, ToolExecuteContext } from "./tool-definition.ts";
+/** Wrap a ToolDefinition into an AgentTool for the core runtime. */
+export declare function wrapToolDefinition<TParams extends TSchema, TDetails = unknown>(definition: ToolDefinition<TParams, TDetails>, ctxFactory?: () => ToolExecuteContext): AgentTool<TParams, TDetails>;
+/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */
+export declare function wrapToolDefinitions<TParams extends TSchema, TDetails = unknown>(definitions: ToolDefinition<TParams, TDetails>[], ctxFactory?: () => ToolExecuteContext): AgentTool<TParams, TDetails>[];
+/**
+ * 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 declare function createToolDefinitionFromAgentTool<TParameters extends TSchema>(tool: AgentTool<TParameters>): ToolDefinition<TParameters, unknown>;
+//# sourceMappingURL=tool-definition-wrapper.d.ts.map

package/dist/core/tools/tool-definition-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-definition-wrapper.d.ts","sourceRoot":"","sources":["../../../src/core/tools/tool-definition-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/E,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,OAAO,EAAE,QAAQ,GAAG,OAAO,EAC7E,UAAU,EAAE,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,EAC7C,UAAU,CAAC,EAAE,MAAM,kBAAkB,GACnC,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,CAY9B;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,OAAO,SAAS,OAAO,EAAE,QAAQ,GAAG,OAAO,EAC9E,WAAW,EAAE,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,EAChD,UAAU,CAAC,EAAE,MAAM,kBAAkB,GACnC,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,CAEhC;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,WAAW,SAAS,OAAO,EAC5E,IAAI,EAAE,SAAS,CAAC,WAAW,CAAC,GAC1B,cAAc,CAAC,WAAW,EAAE,OAAO,CAAC,CAWtC","sourcesContent":["import type { AgentTool } from \"@agent-forge/agent-core\";\nimport type { TSchema } from \"typebox\";\nimport type { ToolDefinition, ToolExecuteContext } from \"./tool-definition.ts\";\n\n/** Wrap a ToolDefinition into an AgentTool for the core runtime. */\nexport function wrapToolDefinition<TParams extends TSchema, TDetails = unknown>(\n\tdefinition: ToolDefinition<TParams, TDetails>,\n\tctxFactory?: () => ToolExecuteContext,\n): AgentTool<TParams, 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?: ToolExecuteContext) =>\n\t\t\tdefinition.execute(toolCallId, params, signal, onUpdate, ctx ?? (ctxFactory?.() as ToolExecuteContext)),\n\t};\n}\n\n/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */\nexport function wrapToolDefinitions<TParams extends TSchema, TDetails = unknown>(\n\tdefinitions: ToolDefinition<TParams, TDetails>[],\n\tctxFactory?: () => ToolExecuteContext,\n): AgentTool<TParams, TDetails>[] {\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<TParameters extends TSchema>(\n\ttool: AgentTool<TParameters>,\n): ToolDefinition<TParameters, unknown> {\n\treturn {\n\t\tname: tool.name,\n\t\tlabel: tool.label,\n\t\tdescription: tool.description,\n\t\tparameters: tool.parameters,\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/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":"AAIA,oEAAoE;AACpE,MAAM,UAAU,kBAAkB,CACjC,UAA6C,EAC7C,UAAqC,EACN;IAC/B,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,GAAwB,EAAE,EAAE,CAC3E,UAAU,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAK,UAAU,EAAE,EAAyB,CAAC;KACxG,CAAC;AAAA,CACF;AAED,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CAClC,WAAgD,EAChD,UAAqC,EACJ;IACjC,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,CAChD,IAA4B,EACW;IACvC,OAAO;QACN,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,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 \"@agent-forge/agent-core\";\nimport type { TSchema } from \"typebox\";\nimport type { ToolDefinition, ToolExecuteContext } from \"./tool-definition.ts\";\n\n/** Wrap a ToolDefinition into an AgentTool for the core runtime. */\nexport function wrapToolDefinition<TParams extends TSchema, TDetails = unknown>(\n\tdefinition: ToolDefinition<TParams, TDetails>,\n\tctxFactory?: () => ToolExecuteContext,\n): AgentTool<TParams, 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?: ToolExecuteContext) =>\n\t\t\tdefinition.execute(toolCallId, params, signal, onUpdate, ctx ?? (ctxFactory?.() as ToolExecuteContext)),\n\t};\n}\n\n/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */\nexport function wrapToolDefinitions<TParams extends TSchema, TDetails = unknown>(\n\tdefinitions: ToolDefinition<TParams, TDetails>[],\n\tctxFactory?: () => ToolExecuteContext,\n): AgentTool<TParams, TDetails>[] {\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<TParameters extends TSchema>(\n\ttool: AgentTool<TParameters>,\n): ToolDefinition<TParameters, unknown> {\n\treturn {\n\t\tname: tool.name,\n\t\tlabel: tool.label,\n\t\tdescription: tool.description,\n\t\tparameters: tool.parameters,\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/tool-definition.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Tool definition types shared by the built-in coding tools, SDK custom tools,
+ * and the capability tool registry projection.
+ *
+ * This is the tool domain's own type home (D-052 sibling ruling: these types
+ * describe product tools, not any host UI). The render types are consumed by
+ * the TUI tool components but defined here because the definition carries the
+ * renderer contract.
+ */
+import type { AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "@agent-forge/agent-core";
+import type { Api, ConstrainedSamplingConfig, Model } from "@agent-forge/ai";
+import type { Component } from "@agent-forge/tui";
+import type { Static, TSchema } from "typebox";
+import type { Theme } from "../../modes/interactive/theme/theme.ts";
+import type { SourceInfo } from "../source-info.ts";
+/** Session-scoped facts handed to a tool's execute. The session resolves the values at call time. */
+export interface ToolExecuteContext {
+    /** Current working directory. */
+    cwd: string;
+    /** Current model (may be undefined). */
+    model: Model<Api> | undefined;
+    /** Session identity for env exposure and logging. */
+    sessionManager: {
+        getSessionId(): string;
+        getSessionFile(): string | undefined;
+    };
+    /** Current thinking level, when provided by the session runtime. */
+    thinkingLevel: ThinkingLevel | undefined;
+}
+/** Rendering options for tool results */
+export interface ToolRenderResultOptions {
+    /** Whether the result view is expanded */
+    expanded: boolean;
+    /** Whether this is a partial/streaming result */
+    isPartial: boolean;
+}
+/** Context passed to tool renderers. */
+export interface ToolRenderContext<TState = unknown, TArgs = unknown> {
+    /** Current tool call arguments. Shared across call/result renders for the same tool call. */
+    args: TArgs;
+    /** Unique id for this tool execution. Stable across call/result renders for the same tool call. */
+    toolCallId: string;
+    /** Invalidate just this tool execution component for redraw. */
+    invalidate: () => void;
+    /** Previously returned component for this render slot, if any. */
+    lastComponent: Component | undefined;
+    /** Shared renderer state for this tool row. Initialized by tool-execution.ts. */
+    state: TState;
+    /** Working directory for this tool execution. */
+    cwd: string;
+    /** Whether the tool execution has started. */
+    executionStarted: boolean;
+    /** Whether the tool call arguments are complete. */
+    argsComplete: boolean;
+    /** Whether the tool result is partial/streaming. */
+    isPartial: boolean;
+    /** Whether the result view is expanded. */
+    expanded: boolean;
+    /** Whether inline images are currently shown in the TUI. */
+    showImages: boolean;
+    /** Whether the current result is an error. */
+    isError: boolean;
+}
+/**
+ * Tool definition for the session tool registry (built-in tools, SDK custom
+ * tools, and the capability runtime's tool projection).
+ */
+export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = unknown> {
+    /** Tool name (used in LLM tool calls) */
+    name: string;
+    /** Human-readable label for UI */
+    label: string;
+    /** Description for LLM */
+    description: string;
+    /** Optional one-line snippet for the Available tools section in the default system prompt. Custom tools are omitted from that section when this is not provided. */
+    promptSnippet?: string;
+    /** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
+    promptGuidelines?: string[];
+    /** Parameter schema (TypeBox) */
+    parameters: TParams;
+    /** Optional provider-side constrained sampling request for this tool. Set false to explicitly disable it, equivalent to leaving it undefined. */
+    constrainedSampling?: false | ConstrainedSamplingConfig;
+    /** Controls whether ToolExecutionComponent renders the standard colored shell or the tool renders its own framing. */
+    renderShell?: "default" | "self";
+    /** Optional compatibility shim to prepare raw tool call arguments before schema validation. Must return an object conforming to TParams. */
+    prepareArguments?: (args: unknown) => Static<TParams>;
+    /**
+     * Per-tool execution mode override.
+     * - "sequential": this tool must execute one at a time with other tool calls.
+     * - "parallel": this tool can execute concurrently with other tool calls.
+     *
+     * If omitted, the default execution mode applies.
+     */
+    executionMode?: ToolExecutionMode;
+    /**
+     * Owning-plugin declaration (宪法 §6): this tool is explicitly safe for the
+     * `readonly` capability mode. In readonly sessions the kernel keeps only
+     * first-party (`agent-forge.builtin.*`) tools that declare it on the active
+     * face; tools from external plugins keep their own semantics regardless.
+     */
+    readonlySafe?: boolean;
+    /** Execute the tool. */
+    execute(toolCallId: string, params: Static<TParams>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: ToolExecuteContext): Promise<AgentToolResult<TDetails>>;
+    /** Custom rendering for tool call display. Method syntax keeps renderer assignability bivariant in TState. */
+    renderCall?(args: Static<TParams>, theme: Theme, context: ToolRenderContext<TState, Static<TParams>>): Component;
+    /** Custom rendering for tool result display. Method syntax keeps renderer assignability bivariant in TState/TDetails. */
+    renderResult?(result: AgentToolResult<TDetails>, options: ToolRenderResultOptions, theme: Theme, context: ToolRenderContext<TState, Static<TParams>>): Component;
+}
+/** Tool info with name, description, parameter schema, prompt guidelines, and source metadata. */
+export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters" | "promptGuidelines"> & {
+    sourceInfo: SourceInfo;
+};
+type AnyToolDefinition = ToolDefinition;
+/**
+ * Preserve parameter inference for standalone tool definitions.
+ *
+ * Use this when assigning a tool to a variable or passing it through arrays such
+ * as `customTools`, where contextual typing would otherwise widen params to
+ * `unknown`.
+ */
+export declare function defineTool<TParams extends TSchema, TDetails = unknown, TState = unknown>(tool: ToolDefinition<TParams, TDetails, TState>): ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition;
+export {};
+//# sourceMappingURL=tool-definition.d.ts.map

package/dist/core/tools/tool-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-definition.d.ts","sourceRoot":"","sources":["../../../src/core/tools/tool-definition.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Tool definition types shared by the built-in coding tools, SDK custom tools,\n * and the capability tool registry projection.\n *\n * This is the tool domain's own type home (D-052 sibling ruling: these types\n * describe product tools, not any host UI). The render types are consumed by\n * the TUI tool components but defined here because the definition carries the\n * renderer contract.\n */\n\nimport type {\n\tAgentToolResult,\n\tAgentToolUpdateCallback,\n\tThinkingLevel,\n\tToolExecutionMode,\n} from \"@agent-forge/agent-core\";\nimport type { Api, ConstrainedSamplingConfig, Model } from \"@agent-forge/ai\";\nimport type { Component } from \"@agent-forge/tui\";\nimport type { Static, TSchema } from \"typebox\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport type { SourceInfo } from \"../source-info.ts\";\n\n/** Session-scoped facts handed to a tool's execute. The session resolves the values at call time. */\nexport interface ToolExecuteContext {\n\t/** Current working directory. */\n\tcwd: string;\n\t/** Current model (may be undefined). */\n\tmodel: Model<Api> | undefined;\n\t/** Session identity for env exposure and logging. */\n\tsessionManager: {\n\t\tgetSessionId(): string;\n\t\tgetSessionFile(): string | undefined;\n\t};\n\t/** Current thinking level, when provided by the session runtime. */\n\tthinkingLevel: ThinkingLevel | undefined;\n}\n\n/** Rendering options for tool results */\nexport interface ToolRenderResultOptions {\n\t/** Whether the result view is expanded */\n\texpanded: boolean;\n\t/** Whether this is a partial/streaming result */\n\tisPartial: boolean;\n}\n\n/** Context passed to tool renderers. */\nexport interface ToolRenderContext<TState = unknown, TArgs = unknown> {\n\t/** Current tool call arguments. Shared across call/result renders for the same tool call. */\n\targs: TArgs;\n\t/** Unique id for this tool execution. Stable across call/result renders for the same tool call. */\n\ttoolCallId: string;\n\t/** Invalidate just this tool execution component for redraw. */\n\tinvalidate: () => void;\n\t/** Previously returned component for this render slot, if any. */\n\tlastComponent: Component | undefined;\n\t/** Shared renderer state for this tool row. Initialized by tool-execution.ts. */\n\tstate: TState;\n\t/** Working directory for this tool execution. */\n\tcwd: string;\n\t/** Whether the tool execution has started. */\n\texecutionStarted: boolean;\n\t/** Whether the tool call arguments are complete. */\n\targsComplete: boolean;\n\t/** Whether the tool result is partial/streaming. */\n\tisPartial: boolean;\n\t/** Whether the result view is expanded. */\n\texpanded: boolean;\n\t/** Whether inline images are currently shown in the TUI. */\n\tshowImages: boolean;\n\t/** Whether the current result is an error. */\n\tisError: boolean;\n}\n\n/**\n * Tool definition for the session tool registry (built-in tools, SDK custom\n * tools, and the capability runtime's tool projection).\n */\nexport interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = unknown> {\n\t/** Tool name (used in LLM tool calls) */\n\tname: string;\n\t/** Human-readable label for UI */\n\tlabel: string;\n\t/** Description for LLM */\n\tdescription: string;\n\t/** Optional one-line snippet for the Available tools section in the default system prompt. Custom tools are omitted from that section when this is not provided. */\n\tpromptSnippet?: string;\n\t/** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */\n\tpromptGuidelines?: string[];\n\t/** Parameter schema (TypeBox) */\n\tparameters: TParams;\n\t/** Optional provider-side constrained sampling request for this tool. Set false to explicitly disable it, equivalent to leaving it undefined. */\n\tconstrainedSampling?: false | ConstrainedSamplingConfig;\n\t/** Controls whether ToolExecutionComponent renders the standard colored shell or the tool renders its own framing. */\n\trenderShell?: \"default\" | \"self\";\n\n\t/** Optional compatibility shim to prepare raw tool call arguments before schema validation. Must return an object conforming to TParams. */\n\tprepareArguments?: (args: unknown) => Static<TParams>;\n\n\t/**\n\t * Per-tool execution mode override.\n\t * - \"sequential\": this tool must execute one at a time with other tool calls.\n\t * - \"parallel\": this tool can execute concurrently with other tool calls.\n\t *\n\t * If omitted, the default execution mode applies.\n\t */\n\texecutionMode?: ToolExecutionMode;\n\n\t/**\n\t * Owning-plugin declaration (宪法 §6): this tool is explicitly safe for the\n\t * `readonly` capability mode. In readonly sessions the kernel keeps only\n\t * first-party (`agent-forge.builtin.*`) tools that declare it on the active\n\t * face; tools from external plugins keep their own semantics regardless.\n\t */\n\treadonlySafe?: boolean;\n\n\t/** Execute the tool. */\n\texecute(\n\t\ttoolCallId: string,\n\t\tparams: Static<TParams>,\n\t\tsignal: AbortSignal | undefined,\n\t\tonUpdate: AgentToolUpdateCallback<TDetails> | undefined,\n\t\tctx: ToolExecuteContext,\n\t): Promise<AgentToolResult<TDetails>>;\n\n\t/** Custom rendering for tool call display. Method syntax keeps renderer assignability bivariant in TState. */\n\trenderCall?(args: Static<TParams>, theme: Theme, context: ToolRenderContext<TState, Static<TParams>>): Component;\n\n\t/** Custom rendering for tool result display. Method syntax keeps renderer assignability bivariant in TState/TDetails. */\n\trenderResult?(\n\t\tresult: AgentToolResult<TDetails>,\n\t\toptions: ToolRenderResultOptions,\n\t\ttheme: Theme,\n\t\tcontext: ToolRenderContext<TState, Static<TParams>>,\n\t): Component;\n}\n\n/** Tool info with name, description, parameter schema, prompt guidelines, and source metadata. */\nexport type ToolInfo = Pick<ToolDefinition, \"name\" | \"description\" | \"parameters\" | \"promptGuidelines\"> & {\n\tsourceInfo: SourceInfo;\n};\n\ntype AnyToolDefinition = ToolDefinition;\n\n/**\n * Preserve parameter inference for standalone tool definitions.\n *\n * Use this when assigning a tool to a variable or passing it through arrays such\n * as `customTools`, where contextual typing would otherwise widen params to\n * `unknown`.\n */\nexport function defineTool<TParams extends TSchema, TDetails = unknown, TState = unknown>(\n\ttool: ToolDefinition<TParams, TDetails, TState>,\n): ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition {\n\treturn tool as ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition;\n}\n"]}

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

@@ -0,0 +1,20 @@
+/**
+ * Tool definition types shared by the built-in coding tools, SDK custom tools,
+ * and the capability tool registry projection.
+ *
+ * This is the tool domain's own type home (D-052 sibling ruling: these types
+ * describe product tools, not any host UI). The render types are consumed by
+ * the TUI tool components but defined here because the definition carries the
+ * renderer contract.
+ */
+/**
+ * Preserve parameter inference for standalone tool definitions.
+ *
+ * Use this when assigning a tool to a variable or passing it through arrays such
+ * as `customTools`, where contextual typing would otherwise widen params to
+ * `unknown`.
+ */
+export function defineTool(tool) {
+    return tool;
+}
+//# sourceMappingURL=tool-definition.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-definition.js","sourceRoot":"","sources":["../../../src/core/tools/tool-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuIH;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACzB,IAA+C,EACiB;IAChE,OAAO,IAAqE,CAAC;AAAA,CAC7E","sourcesContent":["/**\n * Tool definition types shared by the built-in coding tools, SDK custom tools,\n * and the capability tool registry projection.\n *\n * This is the tool domain's own type home (D-052 sibling ruling: these types\n * describe product tools, not any host UI). The render types are consumed by\n * the TUI tool components but defined here because the definition carries the\n * renderer contract.\n */\n\nimport type {\n\tAgentToolResult,\n\tAgentToolUpdateCallback,\n\tThinkingLevel,\n\tToolExecutionMode,\n} from \"@agent-forge/agent-core\";\nimport type { Api, ConstrainedSamplingConfig, Model } from \"@agent-forge/ai\";\nimport type { Component } from \"@agent-forge/tui\";\nimport type { Static, TSchema } from \"typebox\";\nimport type { Theme } from \"../../modes/interactive/theme/theme.ts\";\nimport type { SourceInfo } from \"../source-info.ts\";\n\n/** Session-scoped facts handed to a tool's execute. The session resolves the values at call time. */\nexport interface ToolExecuteContext {\n\t/** Current working directory. */\n\tcwd: string;\n\t/** Current model (may be undefined). */\n\tmodel: Model<Api> | undefined;\n\t/** Session identity for env exposure and logging. */\n\tsessionManager: {\n\t\tgetSessionId(): string;\n\t\tgetSessionFile(): string | undefined;\n\t};\n\t/** Current thinking level, when provided by the session runtime. */\n\tthinkingLevel: ThinkingLevel | undefined;\n}\n\n/** Rendering options for tool results */\nexport interface ToolRenderResultOptions {\n\t/** Whether the result view is expanded */\n\texpanded: boolean;\n\t/** Whether this is a partial/streaming result */\n\tisPartial: boolean;\n}\n\n/** Context passed to tool renderers. */\nexport interface ToolRenderContext<TState = unknown, TArgs = unknown> {\n\t/** Current tool call arguments. Shared across call/result renders for the same tool call. */\n\targs: TArgs;\n\t/** Unique id for this tool execution. Stable across call/result renders for the same tool call. */\n\ttoolCallId: string;\n\t/** Invalidate just this tool execution component for redraw. */\n\tinvalidate: () => void;\n\t/** Previously returned component for this render slot, if any. */\n\tlastComponent: Component | undefined;\n\t/** Shared renderer state for this tool row. Initialized by tool-execution.ts. */\n\tstate: TState;\n\t/** Working directory for this tool execution. */\n\tcwd: string;\n\t/** Whether the tool execution has started. */\n\texecutionStarted: boolean;\n\t/** Whether the tool call arguments are complete. */\n\targsComplete: boolean;\n\t/** Whether the tool result is partial/streaming. */\n\tisPartial: boolean;\n\t/** Whether the result view is expanded. */\n\texpanded: boolean;\n\t/** Whether inline images are currently shown in the TUI. */\n\tshowImages: boolean;\n\t/** Whether the current result is an error. */\n\tisError: boolean;\n}\n\n/**\n * Tool definition for the session tool registry (built-in tools, SDK custom\n * tools, and the capability runtime's tool projection).\n */\nexport interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = unknown> {\n\t/** Tool name (used in LLM tool calls) */\n\tname: string;\n\t/** Human-readable label for UI */\n\tlabel: string;\n\t/** Description for LLM */\n\tdescription: string;\n\t/** Optional one-line snippet for the Available tools section in the default system prompt. Custom tools are omitted from that section when this is not provided. */\n\tpromptSnippet?: string;\n\t/** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */\n\tpromptGuidelines?: string[];\n\t/** Parameter schema (TypeBox) */\n\tparameters: TParams;\n\t/** Optional provider-side constrained sampling request for this tool. Set false to explicitly disable it, equivalent to leaving it undefined. */\n\tconstrainedSampling?: false | ConstrainedSamplingConfig;\n\t/** Controls whether ToolExecutionComponent renders the standard colored shell or the tool renders its own framing. */\n\trenderShell?: \"default\" | \"self\";\n\n\t/** Optional compatibility shim to prepare raw tool call arguments before schema validation. Must return an object conforming to TParams. */\n\tprepareArguments?: (args: unknown) => Static<TParams>;\n\n\t/**\n\t * Per-tool execution mode override.\n\t * - \"sequential\": this tool must execute one at a time with other tool calls.\n\t * - \"parallel\": this tool can execute concurrently with other tool calls.\n\t *\n\t * If omitted, the default execution mode applies.\n\t */\n\texecutionMode?: ToolExecutionMode;\n\n\t/**\n\t * Owning-plugin declaration (宪法 §6): this tool is explicitly safe for the\n\t * `readonly` capability mode. In readonly sessions the kernel keeps only\n\t * first-party (`agent-forge.builtin.*`) tools that declare it on the active\n\t * face; tools from external plugins keep their own semantics regardless.\n\t */\n\treadonlySafe?: boolean;\n\n\t/** Execute the tool. */\n\texecute(\n\t\ttoolCallId: string,\n\t\tparams: Static<TParams>,\n\t\tsignal: AbortSignal | undefined,\n\t\tonUpdate: AgentToolUpdateCallback<TDetails> | undefined,\n\t\tctx: ToolExecuteContext,\n\t): Promise<AgentToolResult<TDetails>>;\n\n\t/** Custom rendering for tool call display. Method syntax keeps renderer assignability bivariant in TState. */\n\trenderCall?(args: Static<TParams>, theme: Theme, context: ToolRenderContext<TState, Static<TParams>>): Component;\n\n\t/** Custom rendering for tool result display. Method syntax keeps renderer assignability bivariant in TState/TDetails. */\n\trenderResult?(\n\t\tresult: AgentToolResult<TDetails>,\n\t\toptions: ToolRenderResultOptions,\n\t\ttheme: Theme,\n\t\tcontext: ToolRenderContext<TState, Static<TParams>>,\n\t): Component;\n}\n\n/** Tool info with name, description, parameter schema, prompt guidelines, and source metadata. */\nexport type ToolInfo = Pick<ToolDefinition, \"name\" | \"description\" | \"parameters\" | \"promptGuidelines\"> & {\n\tsourceInfo: SourceInfo;\n};\n\ntype AnyToolDefinition = ToolDefinition;\n\n/**\n * Preserve parameter inference for standalone tool definitions.\n *\n * Use this when assigning a tool to a variable or passing it through arrays such\n * as `customTools`, where contextual typing would otherwise widen params to\n * `unknown`.\n */\nexport function defineTool<TParams extends TSchema, TDetails = unknown, TState = unknown>(\n\ttool: ToolDefinition<TParams, TDetails, TState>,\n): ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition {\n\treturn tool as ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition;\n}\n"]}

package/dist/core/tools/tool-search.d.ts

@@ -0,0 +1,30 @@
+/**
+ * First-party tool_search tool for deferred MCP tool discovery.
+ *
+ * When MCP servers are configured with `deferredTools: true`, their tools are
+ * registered in the session tool registry but excluded from the default active
+ * (prompt-visible) set. This tool lets the model discover them by lexical
+ * query and activate the matches; the resulting activation diff is recorded in
+ * the toolResult's `addedToolNames` by the extension wrapper, which provider
+ * deferred-tools paths replay.
+ */
+import { Type } from "typebox";
+import type { ToolDefinition } from "./tool-definition.ts";
+export interface ToolSearchDeps {
+    /** All tool names in the registry, including currently inactive tools. */
+    listAllToolNames(): readonly string[];
+    /** Display metadata for a tool name; undefined when the name left the registry. */
+    getToolInfo(name: string): {
+        name: string;
+        description: string;
+    } | undefined;
+    getActiveToolNames(): readonly string[];
+    setActiveToolsByName(toolNames: string[]): void;
+}
+declare const toolSearchParameters: Type.TObject<{
+    query: Type.TString;
+    limit: Type.TOptional<Type.TNumber>;
+}>;
+export declare function createToolSearchTool(deps: ToolSearchDeps): ToolDefinition<typeof toolSearchParameters>;
+export {};
+//# sourceMappingURL=tool-search.d.ts.map

package/dist/core/tools/tool-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-search.d.ts","sourceRoot":"","sources":["../../../src/core/tools/tool-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAe,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC9B,0EAA0E;IAC1E,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAAC;IACtC,mFAAmF;IACnF,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IAC7E,kBAAkB,IAAI,SAAS,MAAM,EAAE,CAAC;IACxC,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAChD;AAED,QAAA,MAAM,oBAAoB;;;EAKxB,CAAC;AA+BH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAAC,OAAO,oBAAoB,CAAC,CAyDtG","sourcesContent":["/**\n * First-party tool_search tool for deferred MCP tool discovery.\n *\n * When MCP servers are configured with `deferredTools: true`, their tools are\n * registered in the session tool registry but excluded from the default active\n * (prompt-visible) set. This tool lets the model discover them by lexical\n * query and activate the matches; the resulting activation diff is recorded in\n * the toolResult's `addedToolNames` by the extension wrapper, which provider\n * deferred-tools paths replay.\n */\n\nimport { type Static, Type } from \"typebox\";\nimport type { ToolDefinition } from \"./tool-definition.ts\";\n\nexport interface ToolSearchDeps {\n\t/** All tool names in the registry, including currently inactive tools. */\n\tlistAllToolNames(): readonly string[];\n\t/** Display metadata for a tool name; undefined when the name left the registry. */\n\tgetToolInfo(name: string): { name: string; description: string } | undefined;\n\tgetActiveToolNames(): readonly string[];\n\tsetActiveToolsByName(toolNames: string[]): void;\n}\n\nconst toolSearchParameters = Type.Object({\n\tquery: Type.String({ description: \"Search text matched against tool names and descriptions.\" }),\n\tlimit: Type.Optional(\n\t\tType.Number({ description: \"Maximum number of matches to activate. Defaults to 5.\", minimum: 1, maximum: 20 }),\n\t),\n});\n\ninterface ScoredMatch {\n\tname: string;\n\tscore: number;\n}\n\n/**\n * Lexical score for one tool against the query terms. Name hits outweigh\n * description hits; exact and prefix matches outweigh substring hits. Returns\n * undefined when the tool matches no term at all.\n */\nfunction scoreTool(name: string, description: string, terms: readonly string[]): number | undefined {\n\tconst lowerName = name.toLowerCase();\n\tconst lowerDescription = description.toLowerCase();\n\tlet score = 0;\n\tfor (const term of terms) {\n\t\tif (lowerName === term) {\n\t\t\tscore += 8;\n\t\t} else if (lowerName.startsWith(term)) {\n\t\t\tscore += 4;\n\t\t} else if (lowerName.includes(term)) {\n\t\t\tscore += 2;\n\t\t}\n\t\tif (lowerDescription.includes(term)) {\n\t\t\tscore += 1;\n\t\t}\n\t}\n\treturn score > 0 ? score : undefined;\n}\n\nexport function createToolSearchTool(deps: ToolSearchDeps): ToolDefinition<typeof toolSearchParameters> {\n\tconst definition: ToolDefinition<typeof toolSearchParameters> = {\n\t\tname: \"tool_search\",\n\t\tlabel: \"Tool search\",\n\t\tdescription:\n\t\t\t\"Search for available tools by name or description and activate the matches so they can be called. \" +\n\t\t\t\"Use this when a capability you need is not in the current tool list.\",\n\t\tpromptSnippet: \"Search and activate deferred tools (used when a needed capability is not currently available)\",\n\t\tparameters: toolSearchParameters,\n\t\texecute: async (_toolCallId, params: Static<typeof toolSearchParameters>) => {\n\t\t\tconst query = params.query.trim();\n\t\t\tif (query.length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text: \"Provide a non-empty query.\" }],\n\t\t\t\t\tdetails: { activated: [] },\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst terms = query\n\t\t\t\t.toLowerCase()\n\t\t\t\t.split(/\\s+/)\n\t\t\t\t.filter((term) => term.length > 0);\n\t\t\tconst activeNames = new Set(deps.getActiveToolNames());\n\t\t\tconst matches: ScoredMatch[] = [];\n\t\t\tfor (const name of deps.listAllToolNames()) {\n\t\t\t\tconst info = deps.getToolInfo(name);\n\t\t\t\tif (!info || activeNames.has(name)) continue;\n\t\t\t\tconst score = scoreTool(name, info.description, terms);\n\t\t\t\tif (score !== undefined) {\n\t\t\t\t\tmatches.push({ name, score });\n\t\t\t\t}\n\t\t\t}\n\t\t\tmatches.sort((left, right) => right.score - left.score || left.name.localeCompare(right.name));\n\t\t\tconst limit = params.limit ?? 5;\n\t\t\tconst activated = matches.slice(0, limit).map((match) => match.name);\n\t\t\tif (activated.length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text: `No inactive tools match \"${query}\".` }],\n\t\t\t\t\tdetails: { activated: [] },\n\t\t\t\t};\n\t\t\t}\n\t\t\tdeps.setActiveToolsByName([...deps.getActiveToolNames(), ...activated]);\n\t\t\tconst lines = activated.map((name) => {\n\t\t\t\tconst info = deps.getToolInfo(name);\n\t\t\t\treturn `- ${name}: ${info?.description ?? \"\"}`;\n\t\t\t});\n\t\t\treturn {\n\t\t\t\tcontent: [\n\t\t\t\t\t{\n\t\t\t\t\t\ttype: \"text\",\n\t\t\t\t\t\ttext: `Activated ${activated.length} tool(s). They are now available for tool calls:\\n${lines.join(\"\\n\")}`,\n\t\t\t\t\t},\n\t\t\t\t],\n\t\t\t\tdetails: { activated },\n\t\t\t};\n\t\t},\n\t};\n\treturn definition;\n}\n"]}

package/dist/core/tools/tool-search.js

@@ -0,0 +1,99 @@
+/**
+ * First-party tool_search tool for deferred MCP tool discovery.
+ *
+ * When MCP servers are configured with `deferredTools: true`, their tools are
+ * registered in the session tool registry but excluded from the default active
+ * (prompt-visible) set. This tool lets the model discover them by lexical
+ * query and activate the matches; the resulting activation diff is recorded in
+ * the toolResult's `addedToolNames` by the extension wrapper, which provider
+ * deferred-tools paths replay.
+ */
+import { Type } from "typebox";
+const toolSearchParameters = Type.Object({
+    query: Type.String({ description: "Search text matched against tool names and descriptions." }),
+    limit: Type.Optional(Type.Number({ description: "Maximum number of matches to activate. Defaults to 5.", minimum: 1, maximum: 20 })),
+});
+/**
+ * Lexical score for one tool against the query terms. Name hits outweigh
+ * description hits; exact and prefix matches outweigh substring hits. Returns
+ * undefined when the tool matches no term at all.
+ */
+function scoreTool(name, description, terms) {
+    const lowerName = name.toLowerCase();
+    const lowerDescription = description.toLowerCase();
+    let score = 0;
+    for (const term of terms) {
+        if (lowerName === term) {
+            score += 8;
+        }
+        else if (lowerName.startsWith(term)) {
+            score += 4;
+        }
+        else if (lowerName.includes(term)) {
+            score += 2;
+        }
+        if (lowerDescription.includes(term)) {
+            score += 1;
+        }
+    }
+    return score > 0 ? score : undefined;
+}
+export function createToolSearchTool(deps) {
+    const definition = {
+        name: "tool_search",
+        label: "Tool search",
+        description: "Search for available tools by name or description and activate the matches so they can be called. " +
+            "Use this when a capability you need is not in the current tool list.",
+        promptSnippet: "Search and activate deferred tools (used when a needed capability is not currently available)",
+        parameters: toolSearchParameters,
+        execute: async (_toolCallId, params) => {
+            const query = params.query.trim();
+            if (query.length === 0) {
+                return {
+                    content: [{ type: "text", text: "Provide a non-empty query." }],
+                    details: { activated: [] },
+                };
+            }
+            const terms = query
+                .toLowerCase()
+                .split(/\s+/)
+                .filter((term) => term.length > 0);
+            const activeNames = new Set(deps.getActiveToolNames());
+            const matches = [];
+            for (const name of deps.listAllToolNames()) {
+                const info = deps.getToolInfo(name);
+                if (!info || activeNames.has(name))
+                    continue;
+                const score = scoreTool(name, info.description, terms);
+                if (score !== undefined) {
+                    matches.push({ name, score });
+                }
+            }
+            matches.sort((left, right) => right.score - left.score || left.name.localeCompare(right.name));
+            const limit = params.limit ?? 5;
+            const activated = matches.slice(0, limit).map((match) => match.name);
+            if (activated.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No inactive tools match "${query}".` }],
+                    details: { activated: [] },
+                };
+            }
+            deps.setActiveToolsByName([...deps.getActiveToolNames(), ...activated]);
+            const lines = activated.map((name) => {
+                const info = deps.getToolInfo(name);
+                return `- ${name}: ${info?.description ?? ""}`;
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Activated ${activated.length} tool(s). They are now available for tool calls:\n${lines.join("\n")}`,
+                    },
+                ],
+                details: { activated },
+            };
+        },
+    };
+    return definition;
+}
+//# sourceMappingURL=tool-search.js.map

package/dist/core/tools/tool-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-search.js","sourceRoot":"","sources":["../../../src/core/tools/tool-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAe,IAAI,EAAE,MAAM,SAAS,CAAC;AAY5C,MAAM,oBAAoB,GAAG,IAAI,CAAC,MAAM,CAAC;IACxC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,0DAA0D,EAAE,CAAC;IAC/F,KAAK,EAAE,IAAI,CAAC,QAAQ,CACnB,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,uDAAuD,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAC9G;CACD,CAAC,CAAC;AAOH;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAY,EAAE,WAAmB,EAAE,KAAwB,EAAsB;IACnG,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,gBAAgB,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;IACnD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACxB,KAAK,IAAI,CAAC,CAAC;QACZ,CAAC;aAAM,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,KAAK,IAAI,CAAC,CAAC;QACZ,CAAC;aAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,KAAK,IAAI,CAAC,CAAC;QACZ,CAAC;QACD,IAAI,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,KAAK,IAAI,CAAC,CAAC;QACZ,CAAC;IACF,CAAC;IACD,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAAA,CACrC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAoB,EAA+C;IACvG,MAAM,UAAU,GAAgD;QAC/D,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,aAAa;QACpB,WAAW,EACV,oGAAoG;YACpG,sEAAsE;QACvE,aAAa,EAAE,+FAA+F;QAC9G,UAAU,EAAE,oBAAoB;QAChC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAA2C,EAAE,EAAE,CAAC;YAC5E,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAClC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxB,OAAO;oBACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,4BAA4B,EAAE,CAAC;oBAC/D,OAAO,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;iBAC1B,CAAC;YACH,CAAC;YACD,MAAM,KAAK,GAAG,KAAK;iBACjB,WAAW,EAAE;iBACb,KAAK,CAAC,KAAK,CAAC;iBACZ,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACpC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC;YACvD,MAAM,OAAO,GAAkB,EAAE,CAAC;YAClC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,gBAAgB,EAAE,EAAE,CAAC;gBAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;gBACpC,IAAI,CAAC,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,SAAS;gBAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;gBACvD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACzB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;gBAC/B,CAAC;YACF,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;YAC/F,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;YAChC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACrE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC5B,OAAO;oBACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,4BAA4B,KAAK,IAAI,EAAE,CAAC;oBACxE,OAAO,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;iBAC1B,CAAC;YACH,CAAC;YACD,IAAI,CAAC,oBAAoB,CAAC,CAAC,GAAG,IAAI,CAAC,kBAAkB,EAAE,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC;YACxE,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;gBACrC,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;gBACpC,OAAO,KAAK,IAAI,KAAK,IAAI,EAAE,WAAW,IAAI,EAAE,EAAE,CAAC;YAAA,CAC/C,CAAC,CAAC;YACH,OAAO;gBACN,OAAO,EAAE;oBACR;wBACC,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,aAAa,SAAS,CAAC,MAAM,qDAAqD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;qBAC1G;iBACD;gBACD,OAAO,EAAE,EAAE,SAAS,EAAE;aACtB,CAAC;QAAA,CACF;KACD,CAAC;IACF,OAAO,UAAU,CAAC;AAAA,CAClB","sourcesContent":["/**\n * First-party tool_search tool for deferred MCP tool discovery.\n *\n * When MCP servers are configured with `deferredTools: true`, their tools are\n * registered in the session tool registry but excluded from the default active\n * (prompt-visible) set. This tool lets the model discover them by lexical\n * query and activate the matches; the resulting activation diff is recorded in\n * the toolResult's `addedToolNames` by the extension wrapper, which provider\n * deferred-tools paths replay.\n */\n\nimport { type Static, Type } from \"typebox\";\nimport type { ToolDefinition } from \"./tool-definition.ts\";\n\nexport interface ToolSearchDeps {\n\t/** All tool names in the registry, including currently inactive tools. */\n\tlistAllToolNames(): readonly string[];\n\t/** Display metadata for a tool name; undefined when the name left the registry. */\n\tgetToolInfo(name: string): { name: string; description: string } | undefined;\n\tgetActiveToolNames(): readonly string[];\n\tsetActiveToolsByName(toolNames: string[]): void;\n}\n\nconst toolSearchParameters = Type.Object({\n\tquery: Type.String({ description: \"Search text matched against tool names and descriptions.\" }),\n\tlimit: Type.Optional(\n\t\tType.Number({ description: \"Maximum number of matches to activate. Defaults to 5.\", minimum: 1, maximum: 20 }),\n\t),\n});\n\ninterface ScoredMatch {\n\tname: string;\n\tscore: number;\n}\n\n/**\n * Lexical score for one tool against the query terms. Name hits outweigh\n * description hits; exact and prefix matches outweigh substring hits. Returns\n * undefined when the tool matches no term at all.\n */\nfunction scoreTool(name: string, description: string, terms: readonly string[]): number | undefined {\n\tconst lowerName = name.toLowerCase();\n\tconst lowerDescription = description.toLowerCase();\n\tlet score = 0;\n\tfor (const term of terms) {\n\t\tif (lowerName === term) {\n\t\t\tscore += 8;\n\t\t} else if (lowerName.startsWith(term)) {\n\t\t\tscore += 4;\n\t\t} else if (lowerName.includes(term)) {\n\t\t\tscore += 2;\n\t\t}\n\t\tif (lowerDescription.includes(term)) {\n\t\t\tscore += 1;\n\t\t}\n\t}\n\treturn score > 0 ? score : undefined;\n}\n\nexport function createToolSearchTool(deps: ToolSearchDeps): ToolDefinition<typeof toolSearchParameters> {\n\tconst definition: ToolDefinition<typeof toolSearchParameters> = {\n\t\tname: \"tool_search\",\n\t\tlabel: \"Tool search\",\n\t\tdescription:\n\t\t\t\"Search for available tools by name or description and activate the matches so they can be called. \" +\n\t\t\t\"Use this when a capability you need is not in the current tool list.\",\n\t\tpromptSnippet: \"Search and activate deferred tools (used when a needed capability is not currently available)\",\n\t\tparameters: toolSearchParameters,\n\t\texecute: async (_toolCallId, params: Static<typeof toolSearchParameters>) => {\n\t\t\tconst query = params.query.trim();\n\t\t\tif (query.length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text: \"Provide a non-empty query.\" }],\n\t\t\t\t\tdetails: { activated: [] },\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst terms = query\n\t\t\t\t.toLowerCase()\n\t\t\t\t.split(/\\s+/)\n\t\t\t\t.filter((term) => term.length > 0);\n\t\t\tconst activeNames = new Set(deps.getActiveToolNames());\n\t\t\tconst matches: ScoredMatch[] = [];\n\t\t\tfor (const name of deps.listAllToolNames()) {\n\t\t\t\tconst info = deps.getToolInfo(name);\n\t\t\t\tif (!info || activeNames.has(name)) continue;\n\t\t\t\tconst score = scoreTool(name, info.description, terms);\n\t\t\t\tif (score !== undefined) {\n\t\t\t\t\tmatches.push({ name, score });\n\t\t\t\t}\n\t\t\t}\n\t\t\tmatches.sort((left, right) => right.score - left.score || left.name.localeCompare(right.name));\n\t\t\tconst limit = params.limit ?? 5;\n\t\t\tconst activated = matches.slice(0, limit).map((match) => match.name);\n\t\t\tif (activated.length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text: `No inactive tools match \"${query}\".` }],\n\t\t\t\t\tdetails: { activated: [] },\n\t\t\t\t};\n\t\t\t}\n\t\t\tdeps.setActiveToolsByName([...deps.getActiveToolNames(), ...activated]);\n\t\t\tconst lines = activated.map((name) => {\n\t\t\t\tconst info = deps.getToolInfo(name);\n\t\t\t\treturn `- ${name}: ${info?.description ?? \"\"}`;\n\t\t\t});\n\t\t\treturn {\n\t\t\t\tcontent: [\n\t\t\t\t\t{\n\t\t\t\t\t\ttype: \"text\",\n\t\t\t\t\t\ttext: `Activated ${activated.length} tool(s). They are now available for tool calls:\\n${lines.join(\"\\n\")}`,\n\t\t\t\t\t},\n\t\t\t\t],\n\t\t\t\tdetails: { activated },\n\t\t\t};\n\t\t},\n\t};\n\treturn definition;\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