c0de-agent 0.0.0 → 1.0.0

package/dist/tools/executor.js

@@ -0,0 +1,54 @@
+import { getTool } from './registry.js';
+import { truncateOutput } from './truncate.js';
+import { validateInput } from './validate.js';
+/**
+ * Execute a tool by name with full pipeline:
+ * find tool → validate input → check permission → execute → truncate output.
+ *
+ * Returns the ToolResult. Never throws — all errors become { _tag: 'error' }.
+ */
+export async function executeTool(registry, name, input, ctx, permissionChecker) {
+    // 0. Check abort signal
+    if (ctx.abort.aborted) {
+        return { _tag: 'error', error: 'Operation aborted before execution' };
+    }
+    // 1. Find tool
+    const tool = getTool(registry, name, { config: {}, cwd: ctx.cwd });
+    if (!tool) {
+        return { _tag: 'error', error: `Tool not found: ${name}` };
+    }
+    // 2. Validate input against JSON Schema
+    const validation = validateInput(tool.parameters, input);
+    if (!validation.valid) {
+        return { _tag: 'error', error: `Invalid input for "${name}": ${validation.error}` };
+    }
+    // 3. Check permission
+    const permission = await permissionChecker.check(tool, input, ctx);
+    if (permission._tag === 'deny') {
+        return { _tag: 'error', error: `Permission denied: ${permission.reason}` };
+    }
+    if (permission._tag === 'ask') {
+        return { _tag: 'permission_required', reason: permission.reason };
+    }
+    // 4. Execute
+    try {
+        const result = await tool.execute(input, ctx);
+        // 5. Truncate large output
+        if (result._tag === 'success') {
+            const truncated = truncateOutput(result.output);
+            if (truncated.truncated) {
+                return {
+                    _tag: 'truncated',
+                    output: truncated.output,
+                    truncated: true,
+                    totalLines: truncated.totalLines,
+                };
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { _tag: 'error', error: `Tool "${name}" failed: ${message}` };
+    }
+}

package/dist/tools/hashline/index.d.ts

@@ -0,0 +1,2 @@
+export type { ApplyResult, ParsedPatch, PatchOp } from './patch.js';
+export { applyPatch, computeHash, parsePatch } from './patch.js';

package/dist/tools/hashline/index.js

@@ -0,0 +1,3 @@
+// hashline 补丁语言（spec §16）：内容哈希锚定的行级补丁。
+// BLK 语法块操作待 AST 工具后续迭代。
+export { applyPatch, computeHash, parsePatch } from './patch.js';

package/dist/tools/hashline/patch.d.ts

@@ -0,0 +1,48 @@
+type PatchOp = {
+    _tag: 'SWAP';
+    start: number;
+    end: number;
+    content: string;
+} | {
+    _tag: 'DEL';
+    start: number;
+    end: number;
+} | {
+    _tag: 'INS_PRE';
+    line: number;
+    content: string;
+} | {
+    _tag: 'INS_POST';
+    line: number;
+    content: string;
+} | {
+    _tag: 'INS_HEAD';
+    content: string;
+} | {
+    _tag: 'INS_TAIL';
+    content: string;
+};
+type ParsedPatch = {
+    path: string;
+    hash: string;
+    operations: PatchOp[];
+};
+type ApplyResult = {
+    _tag: 'success';
+    content: string;
+} | {
+    _tag: 'hash_mismatch';
+    expected: string;
+    actual: string;
+} | {
+    _tag: 'line_not_found';
+    operation: PatchOp;
+};
+/** 4 位 hex 内容哈希（sha256 取前 4 位）。与 session 快照哈希算法同源。 */
+declare function computeHash(content: string): string;
+/** 解析补丁文本为一个或多个 ParsedPatch（按 `[path#hash]` 头分块）。 */
+declare function parsePatch(input: string): ParsedPatch[];
+/** 应用一个补丁到文件内容。先校验哈希，再按锚点降序应用操作。 */
+declare function applyPatch(file: string, patch: ParsedPatch): ApplyResult;
+export type { ApplyResult, ParsedPatch, PatchOp };
+export { applyPatch, computeHash, parsePatch };

package/dist/tools/hashline/patch.js

@@ -0,0 +1,201 @@
+import { createHash } from 'node:crypto';
+// ── computeHash ──────────────────────────────────────────
+/** 4 位 hex 内容哈希（sha256 取前 4 位）。与 session 快照哈希算法同源。 */
+function computeHash(content) {
+    return createHash('sha256').update(content).digest('hex').slice(0, 4);
+}
+// ── parsePatch ───────────────────────────────────────────
+const HEADER_RE = /^\[(.+?)#([0-9a-fA-F]+)\]\s*$/;
+/** 解析一个 `[path#hash]` 块内的操作序列。lines 为该块头之后的行。 */
+function parseOps(lines) {
+    const ops = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line || line.trim() === '') {
+            i++;
+            continue;
+        }
+        const tokens = line.split(/\s+/);
+        const head = tokens[0];
+        if (!head)
+            throw new Error('hashline: empty operation line');
+        // 收集到下一个分隔符 `---`（或块尾）的内容行
+        const collectContent = () => {
+            const body = [];
+            let j = i + 1;
+            while (j < lines.length && lines[j] !== '---') {
+                body.push(lines[j] ?? '');
+                j++;
+            }
+            return { content: body.join('\n'), next: j + 1 };
+        };
+        // 无内容体（DEL）也吃掉到 `---`
+        const skipToSeparator = () => {
+            let j = i + 1;
+            while (j < lines.length && lines[j] !== '---')
+                j++;
+            return j + 1;
+        };
+        if (head === 'SWAP') {
+            const [s, e] = parseRange(tokens[1]);
+            const { content, next } = collectContent();
+            ops.push({ _tag: 'SWAP', start: s, end: e ?? s, content });
+            i = next;
+        }
+        else if (head === 'DEL') {
+            const [s, e] = parseRange(tokens[1]);
+            ops.push({ _tag: 'DEL', start: s, end: e ?? s });
+            i = skipToSeparator();
+        }
+        else if (head === 'INS.PRE') {
+            const { content, next } = collectContent();
+            ops.push({ _tag: 'INS_PRE', line: Number(tokens[1]), content });
+            i = next;
+        }
+        else if (head === 'INS.POST') {
+            const { content, next } = collectContent();
+            ops.push({ _tag: 'INS_POST', line: Number(tokens[1]), content });
+            i = next;
+        }
+        else if (head === 'INS.HEAD') {
+            const { content, next } = collectContent();
+            ops.push({ _tag: 'INS_HEAD', content });
+            i = next;
+        }
+        else if (head === 'INS.TAIL') {
+            const { content, next } = collectContent();
+            ops.push({ _tag: 'INS_TAIL', content });
+            i = next;
+        }
+        else {
+            throw new Error(`hashline: unknown operation "${head}"`);
+        }
+    }
+    return ops;
+}
+/** 解析 `start` 或 `start-end`，返回 [start, end?]（1-indexed）。 */
+function parseRange(spec) {
+    if (!spec)
+        throw new Error('hashline: missing line range');
+    if (spec.includes('-')) {
+        const [a, b] = spec.split('-');
+        return [Number(a), Number(b)];
+    }
+    return [Number(spec), undefined];
+}
+/** 解析补丁文本为一个或多个 ParsedPatch（按 `[path#hash]` 头分块）。 */
+function parsePatch(input) {
+    const lines = input.split('\n');
+    const patches = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line || line.trim() === '') {
+            i++;
+            continue;
+        }
+        const m = HEADER_RE.exec(line);
+        if (!m)
+            throw new Error(`hashline: malformed header "${line}"`);
+        const path = m[1] ?? '';
+        const hash = m[2] ?? '';
+        const block = lines.slice(i + 1);
+        const endIdx = block.indexOf(''); // 块以空行或文件尾分隔（其实下一头才分隔）
+        // 操作持续到下一个头或文件尾：找到下一个 HEADER_RE 匹配行
+        let nextHead = block.length;
+        for (let k = 0; k < block.length; k++) {
+            if (HEADER_RE.test((block[k] ?? '').trim())) {
+                nextHead = k;
+                break;
+            }
+        }
+        void endIdx;
+        const opsLines = block.slice(0, nextHead);
+        patches.push({ path, hash, operations: parseOps(opsLines) });
+        i = i + 1 + nextHead;
+    }
+    return patches;
+}
+// ── applyPatch ───────────────────────────────────────────
+/** 每个操作基于原文件的"锚点行号"，用于排序使从后往前应用。 */
+function anchor(op, lineCount) {
+    switch (op._tag) {
+        case 'SWAP':
+        case 'DEL':
+            return op.start;
+        case 'INS_PRE':
+            return op.line;
+        case 'INS_POST':
+            return op.line + 1;
+        case 'INS_HEAD':
+            return 1;
+        case 'INS_TAIL':
+            return lineCount + 1;
+    }
+}
+/** 校验操作的行号范围是否落在 [1, lineCount]。 */
+function inBounds(op, lineCount) {
+    switch (op._tag) {
+        case 'SWAP':
+        case 'DEL':
+            return op.start >= 1 && op.end <= lineCount && op.start <= op.end;
+        case 'INS_PRE':
+        case 'INS_POST':
+            return op.line >= 1 && op.line <= lineCount;
+        case 'INS_HEAD':
+        case 'INS_TAIL':
+            return true;
+    }
+}
+/** 应用一个补丁到文件内容。先校验哈希，再按锚点降序应用操作。 */
+function applyPatch(file, patch) {
+    const actual = computeHash(file);
+    if (actual !== patch.hash) {
+        return { _tag: 'hash_mismatch', expected: patch.hash, actual };
+    }
+    // 末尾换行保留策略：按 \n 拆分，末尾空串代表文件以换行结尾。
+    const hadTrailingNewline = file.endsWith('\n');
+    const src = hadTrailingNewline ? file.slice(0, -1) : file;
+    const lines = src.split('\n');
+    const lineCount = lines.length;
+    // 先全部校验范围，任一越界即 line_not_found（保持原文件不变）
+    for (const op of patch.operations) {
+        if (!inBounds(op, lineCount)) {
+            return { _tag: 'line_not_found', operation: op };
+        }
+    }
+    // 按锚点降序应用：高行号先改，低行号锚点不受影响
+    const ordered = [...patch.operations].sort((a, b) => {
+        const lineCountFinal = lineCount;
+        return anchor(b, lineCountFinal) - anchor(a, lineCountFinal);
+    });
+    for (const op of ordered) {
+        const contentLines = 'content' in op && op.content !== '' ? op.content.split('\n') : [];
+        switch (op._tag) {
+            case 'SWAP':
+                lines.splice(op.start - 1, op.end - op.start + 1, ...contentLines);
+                break;
+            case 'DEL':
+                lines.splice(op.start - 1, op.end - op.start + 1);
+                break;
+            case 'INS_PRE':
+                lines.splice(op.line - 1, 0, ...contentLines);
+                break;
+            case 'INS_POST':
+                lines.splice(op.line, 0, ...contentLines);
+                break;
+            case 'INS_HEAD':
+                lines.unshift(...contentLines);
+                break;
+            case 'INS_TAIL':
+                lines.push(...contentLines);
+                break;
+        }
+    }
+    let result = lines.join('\n');
+    if (hadTrailingNewline)
+        result += '\n';
+    return { _tag: 'success', content: result };
+}
+export { applyPatch, computeHash, parsePatch };

package/dist/tools/index.d.ts

@@ -0,0 +1,30 @@
+export type { JSONSchema } from '../shared/types/base.js';
+export type { ChatTool } from '../shared/types/llm.js';
+export type { ToolContext, ToolDef, ToolExecutor, ToolMode, ToolPermission, ToolResult, } from '../shared/types/tool.js';
+export { bashTool } from './builtin/bash.js';
+export { dapTools } from './builtin/dap.js';
+export { editTool } from './builtin/edit.js';
+export { globTool, globToRegex } from './builtin/glob.js';
+export { grepTool } from './builtin/grep.js';
+export { readTool } from './builtin/read.js';
+export { createDefaultURLRegistry, createFileResolver, createSkillResolver, } from './builtin/resolvers.js';
+export { taskTool } from './builtin/task.js';
+export { writeTool } from './builtin/write.js';
+export { yieldTool } from './builtin/yield.js';
+export { executeTool } from './executor.js';
+export { autoAllowChecker, createPermissionChecker } from './permission.js';
+export { createToolRegistry, getTool, getToolSchemas, listTools, registerTool, registerToolFactory, } from './registry.js';
+export { DEFAULT_TRUNCATE_OPTIONS, truncateOutput } from './truncate.js';
+export type { BashInput, EditInput, GlobInput, GrepInput, GrepMatch, PermissionChecker, PermissionResult, ReadInput, ToolFactory, ToolFactoryContext, ToolRegistry, TruncateOptions, TruncateResult, ValidationResult, WriteInput, } from './types.js';
+export { validateInput } from './validate.js';
+export { formatForLLM, resolveProvider, runWebSearch } from './websearch/index.js';
+export type { WebSearchProvider, WebSearchProviderId, WebSearchResponse, WebSearchSource, } from './websearch/types.js';
+export { createWebSearchTool } from './websearch/websearch.js';
+import type { Config } from '../shared/types/config.js';
+/**
+ * Create a registry pre-loaded with all builtin tools:
+ * read, write, edit, glob, grep, bash, task, websearch, and the debug_* set.
+ *
+ * @param config 可选配置；websearch 工具按 config.websearch 构造。省略时用 DEFAULT_CONFIG。
+ */
+export declare function createDefaultRegistry(config?: Config): import("./types.js").ToolRegistry;

package/dist/tools/index.js

@@ -0,0 +1,55 @@
+// Tools package: tool registry, executor, validation, truncation, and builtin tools.
+export { bashTool } from './builtin/bash.js';
+export { dapTools } from './builtin/dap.js';
+export { editTool } from './builtin/edit.js';
+export { globTool, globToRegex } from './builtin/glob.js';
+export { grepTool } from './builtin/grep.js';
+export { readTool } from './builtin/read.js';
+// ── Builtin tools ───────────────────────────────────────────
+export { createDefaultURLRegistry, createFileResolver, createSkillResolver, } from './builtin/resolvers.js';
+export { taskTool } from './builtin/task.js';
+export { writeTool } from './builtin/write.js';
+export { yieldTool } from './builtin/yield.js';
+export { executeTool } from './executor.js';
+export { autoAllowChecker, createPermissionChecker } from './permission.js';
+// ── Framework ───────────────────────────────────────────────
+export { createToolRegistry, getTool, getToolSchemas, listTools, registerTool, registerToolFactory, } from './registry.js';
+export { DEFAULT_TRUNCATE_OPTIONS, truncateOutput } from './truncate.js';
+export { validateInput } from './validate.js';
+// ── Websearch ───────────────────────────────────────────────
+export { formatForLLM, resolveProvider, runWebSearch } from './websearch/index.js';
+export { createWebSearchTool } from './websearch/websearch.js';
+// ── Default registry ────────────────────────────────────────
+import { DEFAULT_CONFIG } from '../core/config.js';
+import { bashTool } from './builtin/bash.js';
+import { dapTools } from './builtin/dap.js';
+import { editTool } from './builtin/edit.js';
+import { globTool } from './builtin/glob.js';
+import { grepTool } from './builtin/grep.js';
+import { readTool } from './builtin/read.js';
+import { taskTool } from './builtin/task.js';
+import { writeTool } from './builtin/write.js';
+import { yieldTool } from './builtin/yield.js';
+import { createToolRegistry, registerTool } from './registry.js';
+import { createWebSearchTool } from './websearch/websearch.js';
+/**
+ * Create a registry pre-loaded with all builtin tools:
+ * read, write, edit, glob, grep, bash, task, websearch, and the debug_* set.
+ *
+ * @param config 可选配置；websearch 工具按 config.websearch 构造。省略时用 DEFAULT_CONFIG。
+ */
+export function createDefaultRegistry(config = DEFAULT_CONFIG) {
+    const reg = createToolRegistry();
+    registerTool(reg, readTool);
+    registerTool(reg, writeTool);
+    registerTool(reg, editTool);
+    registerTool(reg, globTool);
+    registerTool(reg, grepTool);
+    registerTool(reg, bashTool);
+    registerTool(reg, taskTool);
+    registerTool(reg, yieldTool);
+    registerTool(reg, createWebSearchTool(config.websearch));
+    for (const tool of dapTools)
+        registerTool(reg, tool);
+    return reg;
+}

package/dist/tools/permission.d.ts

@@ -0,0 +1,13 @@
+import type { PermissionChecker } from './types.js';
+/** Permission checker configuration. */
+type PermissionConfig = {
+    /** Tool names that are always allowed, regardless of their declared permission. */
+    alwaysAllow?: string[];
+    /** Tool names that are always denied, regardless of their declared permission. */
+    alwaysDeny?: string[];
+};
+/** Default checker: allows auto, asks for ask, denies deny. No persistent state. */
+export declare const autoAllowChecker: PermissionChecker;
+/** Create a permission checker with configurable allow/deny lists. */
+export declare function createPermissionChecker(config: PermissionConfig): PermissionChecker;
+export {};

package/dist/tools/permission.js

@@ -0,0 +1,39 @@
+import { randomUUID } from 'node:crypto';
+function checkPermission(tool, _input) {
+    switch (tool.permission) {
+        case 'auto':
+            return { _tag: 'allow' };
+        case 'deny':
+            return { _tag: 'deny', reason: `Tool "${tool.name}" is disabled` };
+        case 'ask':
+            return {
+                _tag: 'ask',
+                reason: `Tool "${tool.name}" requires confirmation`,
+                toolCallId: randomUUID(),
+            };
+    }
+}
+/** Default checker: allows auto, asks for ask, denies deny. No persistent state. */
+export const autoAllowChecker = {
+    check: async (_tool, _input, _ctx) => {
+        return checkPermission(_tool, _input);
+    },
+    confirm: (_toolCallId, _approved) => { },
+};
+/** Create a permission checker with configurable allow/deny lists. */
+export function createPermissionChecker(config) {
+    const allowSet = new Set(config.alwaysAllow ?? []);
+    const denySet = new Set(config.alwaysDeny ?? []);
+    return {
+        check: async (tool, _input, _ctx) => {
+            if (denySet.has(tool.name)) {
+                return { _tag: 'deny', reason: `Tool "${tool.name}" is disabled by configuration` };
+            }
+            if (allowSet.has(tool.name)) {
+                return { _tag: 'allow' };
+            }
+            return checkPermission(tool, _input);
+        },
+        confirm: (_toolCallId, _approved) => { },
+    };
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,15 @@
+import type { ChatTool } from '../shared/types/llm.js';
+import type { ToolDef } from '../shared/types/tool.js';
+import type { ToolFactory, ToolFactoryContext, ToolRegistry } from './types.js';
+/** Create an empty tool registry. */
+export declare function createToolRegistry(): ToolRegistry;
+/** Register a fully-constructed tool definition (eager). */
+export declare function registerTool(registry: ToolRegistry, tool: ToolDef): void;
+/** Register a lazy factory that constructs the tool on first access. */
+export declare function registerToolFactory(registry: ToolRegistry, name: string, factory: ToolFactory): void;
+/** Get a tool by name. Triggers and caches lazy factories. Returns undefined if not found. */
+export declare function getTool(registry: ToolRegistry, name: string, ctx?: ToolFactoryContext): ToolDef | undefined;
+/** List all tools. Triggers and caches all lazy factories. */
+export declare function listTools(registry: ToolRegistry, ctx?: ToolFactoryContext): ToolDef[];
+/** Convert registered tools to ChatTool[] for sending to the LLM. */
+export declare function getToolSchemas(registry: ToolRegistry, ctx?: ToolFactoryContext): ChatTool[];

package/dist/tools/registry.js

@@ -0,0 +1,54 @@
+/** Create an empty tool registry. */
+export function createToolRegistry() {
+    return { tools: new Map(), factories: new Map() };
+}
+/** Register a fully-constructed tool definition (eager). */
+export function registerTool(registry, tool) {
+    registry.tools.set(tool.name, tool);
+}
+/** Register a lazy factory that constructs the tool on first access. */
+export function registerToolFactory(registry, name, factory) {
+    registry.factories.set(name, factory);
+}
+/** Get a tool by name. Triggers and caches lazy factories. Returns undefined if not found. */
+export function getTool(registry, name, ctx) {
+    // Check eager tools first
+    const eager = registry.tools.get(name);
+    if (eager)
+        return eager;
+    // Check lazy factories
+    const factory = registry.factories.get(name);
+    if (factory && ctx) {
+        const tool = factory(ctx);
+        if (tool) {
+            registry.tools.set(name, tool); // cache
+            registry.factories.delete(name);
+            return tool;
+        }
+        // Factory returned null → remove
+        registry.factories.delete(name);
+    }
+    return undefined;
+}
+/** List all tools. Triggers and caches all lazy factories. */
+export function listTools(registry, ctx) {
+    // Materialize factories if context is provided
+    if (ctx) {
+        for (const [name, factory] of registry.factories) {
+            const tool = factory(ctx);
+            if (tool) {
+                registry.tools.set(name, tool);
+            }
+            registry.factories.delete(name);
+        }
+    }
+    return Array.from(registry.tools.values());
+}
+/** Convert registered tools to ChatTool[] for sending to the LLM. */
+export function getToolSchemas(registry, ctx) {
+    return listTools(registry, ctx).map((t) => ({
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+    }));
+}

package/dist/tools/resolver.d.ts

@@ -0,0 +1,15 @@
+import type { ResolveResult, URLRegistry, URLResolveContext, URLResolver } from '../shared/types/tool.js';
+/** Create an empty URL resolver registry. */
+declare function createURLRegistry(): URLRegistry;
+/** Register a resolver for its scheme. First registration for a scheme wins;
+ *  later registrations are ignored (stable dispatch, no accidental overrides). */
+declare function registerURLResolver(registry: URLRegistry, resolver: URLResolver): void;
+/** Does `path` carry a `scheme://` prefix? Plain file paths return false. */
+declare function isURLPath(path: string): boolean;
+/** Extract the scheme from a `scheme://…` path, or null for plain file paths.
+ *  Scheme is the run of [a-z0-9+.-] before the first `://`. */
+declare function parseScheme(path: string): string | null;
+/** Resolve a `scheme://…` URL via the registry.
+ *  Returns { _tag: 'error' } for unregistered schemes. */
+declare function resolveURL(registry: URLRegistry, url: string, ctx: URLResolveContext): Promise<ResolveResult>;
+export { createURLRegistry, isURLPath, parseScheme, registerURLResolver, resolveURL };

package/dist/tools/resolver.js

@@ -0,0 +1,47 @@
+/** Create an empty URL resolver registry. */
+function createURLRegistry() {
+    return { resolvers: new Map() };
+}
+/** Register a resolver for its scheme. First registration for a scheme wins;
+ *  later registrations are ignored (stable dispatch, no accidental overrides). */
+function registerURLResolver(registry, resolver) {
+    if (!registry.resolvers.has(resolver.scheme)) {
+        registry.resolvers.set(resolver.scheme, resolver);
+    }
+}
+/** Does `path` carry a `scheme://` prefix? Plain file paths return false. */
+function isURLPath(path) {
+    return parseScheme(path) !== null;
+}
+/** Extract the scheme from a `scheme://…` path, or null for plain file paths.
+ *  Scheme is the run of [a-z0-9+.-] before the first `://`. */
+function parseScheme(path) {
+    const idx = path.indexOf('://');
+    if (idx <= 0)
+        return null;
+    const scheme = path.slice(0, idx);
+    // Schemes are ASCII alphanumeric plus +, -, . (RFC 3986).
+    if (!/^[a-z0-9+.-]+$/i.test(scheme))
+        return null;
+    return scheme.toLowerCase();
+}
+/** Resolve a `scheme://…` URL via the registry.
+ *  Returns { _tag: 'error' } for unregistered schemes. */
+async function resolveURL(registry, url, ctx) {
+    const scheme = parseScheme(url);
+    if (scheme === null) {
+        return { _tag: 'error', error: `Not a URL path: ${url}` };
+    }
+    const resolver = registry.resolvers.get(scheme);
+    if (!resolver) {
+        return { _tag: 'error', error: `No resolver registered for scheme "${scheme}://"` };
+    }
+    try {
+        const content = await resolver.resolve(url, ctx);
+        return { _tag: 'ok', content };
+    }
+    catch (e) {
+        return { _tag: 'error', error: e instanceof Error ? e.message : String(e) };
+    }
+}
+export { createURLRegistry, isURLPath, parseScheme, registerURLResolver, resolveURL };

package/dist/tools/truncate.d.ts

@@ -0,0 +1,8 @@
+import type { TruncateOptions, TruncateResult } from './types.js';
+/** Default truncation thresholds — tuned for LLM context windows. */
+export declare const DEFAULT_TRUNCATE_OPTIONS: TruncateOptions;
+/**
+ * Truncate output to fit within line and character limits.
+ * Preserves head and tail, inserting a marker for omitted content.
+ */
+export declare function truncateOutput(output: string, opts?: TruncateOptions): TruncateResult;

package/dist/tools/truncate.js

@@ -0,0 +1,50 @@
+/** Default truncation thresholds — tuned for LLM context windows. */
+export const DEFAULT_TRUNCATE_OPTIONS = {
+    maxLines: 2000,
+    maxChars: 100_000,
+    headLines: 50,
+    tailLines: 50,
+};
+/**
+ * Truncate output to fit within line and character limits.
+ * Preserves head and tail, inserting a marker for omitted content.
+ */
+export function truncateOutput(output, opts = DEFAULT_TRUNCATE_OPTIONS) {
+    if (output === '') {
+        return { output: '', truncated: false, totalLines: 0, totalChars: 0 };
+    }
+    const lines = output.split('\n');
+    const totalLines = lines.length;
+    const totalChars = output.length;
+    // Check if truncation is needed
+    const needsLineTrunc = totalLines > opts.maxLines;
+    const needsCharTrunc = totalChars > opts.maxChars;
+    if (!needsLineTrunc && !needsCharTrunc) {
+        return { output, truncated: false, totalLines, totalChars };
+    }
+    // Line-based truncation takes priority
+    if (needsLineTrunc) {
+        const head = lines.slice(0, opts.headLines);
+        const tailStart = totalLines - opts.tailLines;
+        // If tail would overlap head, show only head + marker
+        if (tailStart <= opts.headLines) {
+            const omitted = totalLines - head.length;
+            const marker = `[... ${omitted} lines truncated ...]`;
+            return { output: [...head, marker].join('\n'), truncated: true, totalLines, totalChars };
+        }
+        const tail = lines.slice(tailStart);
+        const omitted = totalLines - head.length - tail.length;
+        const marker = `[... ${omitted} lines truncated ...]`;
+        const result = [...head, marker, ...tail].join('\n');
+        return { output: result, truncated: true, totalLines, totalChars };
+    }
+    // Char-based truncation (keep proportional head/tail of chars)
+    const keepChars = opts.maxChars;
+    const headChars = Math.floor(keepChars * 0.5);
+    const tailChars = keepChars - headChars;
+    const head = output.slice(0, headChars);
+    const tail = output.slice(totalChars - tailChars);
+    const omitted = totalChars - keepChars;
+    const marker = `\n[... ${omitted} chars truncated ...]\n`;
+    return { output: head + marker + tail, truncated: true, totalLines, totalChars };
+}