@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/tool-catalog.js

@@ -0,0 +1,100 @@
+/**
+ * Deterministic, task-appropriate tool catalog built from the tools a node is already permitted
+ * to use, and lazy ordering of the skill catalog.
+ *
+ * Nothing here grants authority: the input is the capability-filtered catalog, the output is a
+ * subset of it, and every omitted tool stays restorable through `restore_tools` with the same
+ * permission checks. Only certainties omit a family (no repository, no index, an empty folder);
+ * unknown families are kept, protected tools are kept, tools the node names explicitly are kept,
+ * and a tool that an inherited transcript already called is kept so providers that require the
+ * schema of a historical call still see it. The selection is a pure function of its inputs, so
+ * the same node state yields the same ordered catalog and the same serialized schemas.
+ * @module tool-catalog
+ */
+import { toolFamily } from './decision/toolFamilies.js';
+import { canonicalToolName } from './tool-names.js';
+import { identifierTokens } from './context-selection.js';
+const PROTECTED = new Set(['complete_agent', 'complete', 'complete_task', 'submit_completion', 'update_todos', 'ask_user', 'load_project_skill', 'restore_tools', 'prepare_steps', 'update_widget', 'Skill', 'read_skill_resource', 'expand_tool_output', 'read_artifact', 'write_artifact']);
+const GIT_WORDS = /\b(git|commit|branch|rebase|merge|stash|diff|blame|checkout|pull request|pr\b|push|history|log)\b/i;
+const MEMORY_WORDS = /\b(remember|recall|memory|previous(ly)?|last time|earlier|convention|decision history)\b/i;
+const WEB_WORDS = /\b(docs?|documentation|https?:\/\/|url|website|web|online|latest version|api reference|changelog|npm package|look up|search the)\b/i;
+const BROWSER_WORDS = /\b(browser|page|website|ui|screenshot|click|render|visual|tab|login|form|html|css|frontend|react|vue|svelte|dom)\b/i;
+const DELEGATION_WORDS = /\b(delegate|subagent|parallel|in parallel|research)\b/i;
+export function schemaChars(tools) {
+    return JSON.stringify(tools.map(({ name, description, parameters }) => ({ name, description, parameters }))).length;
+}
+/** Families that facts can rule out, and the condition that rules each out. */
+function omissionReason(family, input) {
+    const facts = input.facts;
+    const task = input.task;
+    switch (family) {
+        case 'git': return facts && !facts.gitRepository && !GIT_WORDS.test(task) ? 'no_repository' : undefined;
+        case 'codegraph': return input.codeGraphAvailable === false ? 'index_unavailable' : facts?.empty ? 'empty_workspace' : undefined;
+        case 'memory': return input.memoryAvailable === false ? 'memory_unavailable' : facts?.empty && !MEMORY_WORDS.test(task) ? 'empty_workspace' : undefined;
+        case 'web': return WEB_WORDS.test(task) ? undefined : 'not_indicated';
+        case 'browser': return BROWSER_WORDS.test(task) ? undefined : 'not_indicated';
+        case 'subagents': return DELEGATION_WORDS.test(task) ? undefined : 'not_indicated';
+        default: return undefined;
+    }
+}
+/**
+ * Select the catalog. The order of the kept tools is the order of the input, so a stable input
+ * yields a byte-stable schema list.
+ */
+export function selectToolCatalog(input) {
+    const explicit = new Set((input.explicitTools ?? []).map(canonicalToolName));
+    const historical = new Set((input.historicalToolNames ?? []).map(canonicalToolName));
+    const reasons = {};
+    const omitted = [];
+    const tools = input.tools.filter(tool => {
+        if (PROTECTED.has(tool.name) || PROTECTED.has(canonicalToolName(tool.name)))
+            return true;
+        if (explicit.has(canonicalToolName(tool.name)) || historical.has(canonicalToolName(tool.name)))
+            return true;
+        const family = toolFamily(tool);
+        if (!family)
+            return true;
+        const reason = omissionReason(family, input);
+        if (!reason)
+            return true;
+        reasons[tool.name] = reason;
+        omitted.push(tool);
+        return false;
+    });
+    return { tools, omitted, reasons, schemaCharsBefore: schemaChars(input.tools), schemaCharsAfter: schemaChars(tools) };
+}
+/**
+ * Order the skill catalog by lexical relevance to the task and fit it into a budget, keeping
+ * explicitly requested and inherited skills first and whole. Entries that do not fit are named
+ * without their descriptions so they stay loadable.
+ */
+export function orderSkillCatalog(skills, task, required, budgetChars) {
+    const tokens = identifierTokens(task);
+    const score = (skill) => {
+        const name = identifierTokens(skill.id), body = identifierTokens(skill.description);
+        let hits = 0;
+        for (const token of tokens) {
+            if (name.has(token))
+                hits += 2;
+            if (body.has(token))
+                hits += 1;
+        }
+        return hits;
+    };
+    const requiredSet = new Set(required);
+    const ranked = [...skills].sort((a, b) => Number(requiredSet.has(b.id)) - Number(requiredSet.has(a.id)) || score(b) - score(a) || skills.indexOf(a) - skills.indexOf(b));
+    const entries = [];
+    const namedOnly = [];
+    let used = 2;
+    for (const skill of ranked) {
+        const entry = { id: skill.id, description: skill.description, ...(skill.unavailable ? { unavailable: skill.unavailable } : {}) };
+        const chars = JSON.stringify(entry).length + 1;
+        if (requiredSet.has(skill.id) || used + chars <= budgetChars) {
+            entries.push(entry);
+            used += chars;
+        }
+        else
+            namedOnly.push(skill.id);
+    }
+    return { entries, namedOnly };
+}

package/dist/src/tool-dependencies.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Order tools by their actual side effects, not by the most restrictive tool in
+ * a whole model response. Every barrier waits for outstanding reads. A read after
+ * a barrier waits for it, but independent reads within each segment can overlap.
+ */
+export interface PlannedToolCall {
+    id: string;
+    name: string;
+}
+export interface ToolSchedulingPolicy {
+    executionMode?: 'parallel' | 'sequential';
+    capability?: string;
+}
+export interface PlannedToolDependency {
+    toolCallId: string;
+    toolName: string;
+    dependsOn: string[];
+    concurrentSafe: boolean;
+    destructive: boolean;
+    readOnly: boolean;
+}
+export declare function requiresToolBarrier(name: string, tool?: ToolSchedulingPolicy): boolean;
+export declare function planToolDependencies(calls: readonly PlannedToolCall[], lookup: (call: PlannedToolCall) => ToolSchedulingPolicy | undefined, forceSequential?: boolean): PlannedToolDependency[];

package/dist/src/tool-dependencies.js

@@ -0,0 +1,36 @@
+const SEQUENTIAL = new Set([
+    'Write', 'Edit', 'Bash', 'PowerShell', 'NativeExec', 'AsyncProcess',
+    'PowerShellFast', 'write_file', 'edit_file', 'shell', 'write', 'edit',
+    'powershell', 'bash', 'write_artifact', 'ask_user', 'update_todos',
+    'update_widget', 'prepare_steps',
+]);
+const READ_CAPABILITIES = new Set(['git.read', 'github.read']);
+export function requiresToolBarrier(name, tool) {
+    // AsyncProcess status/logs/wait do not mutate the job and may overlap reads.
+    // The caller must explicitly classify only those actions as parallel.
+    if (name === 'AsyncProcess' && tool?.executionMode === 'parallel')
+        return false;
+    if (tool?.executionMode === 'sequential' || SEQUENTIAL.has(name))
+        return true;
+    return !!tool?.capability && !READ_CAPABILITIES.has(tool.capability);
+}
+export function planToolDependencies(calls, lookup, forceSequential = false) {
+    let previousBarrier;
+    let pendingReaders = [];
+    return calls.map(call => {
+        const barrier = forceSequential || requiresToolBarrier(call.name, lookup(call));
+        const dependsOn = barrier
+            ? [...(previousBarrier ? [previousBarrier] : []), ...pendingReaders]
+            : previousBarrier ? [previousBarrier] : [];
+        if (barrier) {
+            previousBarrier = call.id;
+            pendingReaders = [];
+        }
+        else
+            pendingReaders.push(call.id);
+        return {
+            toolCallId: call.id, toolName: call.name, dependsOn,
+            concurrentSafe: !barrier, destructive: barrier, readOnly: !barrier,
+        };
+    });
+}

package/dist/src/tool-diff-stats.d.ts

@@ -0,0 +1,24 @@
+export interface LineDiffStats {
+    linesAdded: number;
+    linesRemoved: number;
+}
+/**
+ * The file a mutating call will change, resolved inside the workspace, or null for anything else.
+ *
+ * Canonical spelling names the file `file_path` and every adopted spelling names it `path`; both are
+ * read so a legacy journal replayed through the same runtime gets the same figures as a live call.
+ * A path that leaves the workspace resolves to nothing: the tools refuse such a call, and reporting
+ * stats for a file the sandbox forbids would measure what was never written.
+ */
+export declare function fileDiffTarget(name: string, args: Record<string, unknown>, workspace: string): string | null;
+/**
+ * Read a snapshot for the diff, answering the three states apart.
+ *
+ * `null` is an absent file — the before-half of a newly created file, every line of which counts as
+ * added. `undefined` is "not measurable": a directory, a file over the size ceiling, or any read the
+ * file system refused for a reason the transcript cannot explain. A caller holding `undefined` for
+ * either half reports no stats rather than inventing them.
+ */
+export declare function readFileSnapshot(target: string): Promise<string | null | undefined>;
+/** The added/removed line counts for a snapshot pair; nothing when either half was unmeasurable. */
+export declare function diffLineStats(before: string | null | undefined, after: string | null | undefined): LineDiffStats | undefined;

package/dist/src/tool-diff-stats.js

@@ -0,0 +1,122 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { canonicalCodingToolName } from './tool-names.js';
+/**
+ * The line counts behind a successful file mutation, reported on its `node.tool.completed` event.
+ *
+ * The transcript shows `+N -M` beside an Edit or Write the way a diff stat does: what the call added
+ * and removed, counted against the file's real content. The runtime is the only place both halves
+ * exist — the tool's arguments say what was asked, but the before-and-after on disk says what
+ * happened (a Write over an existing file changes fewer lines than it carries). So the runtime
+ * snapshots the target file before execution and re-reads it on success, and this module turns the
+ * pair into counts. A call whose file cannot be read at one of those moments reports nothing: the
+ * row then shows the change without figures rather than figures about a file no one measured.
+ */
+/** Files past this size are skipped rather than measured; the same ceiling the read path enforces. */
+const MAX_STAT_BYTES = 2_000_000;
+/** The changed middle is diffed exactly up to this many lines per side; beyond it the whole span counts. */
+const LCS_LINE_LIMIT = 4_000;
+/**
+ * The file a mutating call will change, resolved inside the workspace, or null for anything else.
+ *
+ * Canonical spelling names the file `file_path` and every adopted spelling names it `path`; both are
+ * read so a legacy journal replayed through the same runtime gets the same figures as a live call.
+ * A path that leaves the workspace resolves to nothing: the tools refuse such a call, and reporting
+ * stats for a file the sandbox forbids would measure what was never written.
+ */
+export function fileDiffTarget(name, args, workspace) {
+    const canonical = canonicalCodingToolName(name);
+    if (canonical !== 'Write' && canonical !== 'Edit')
+        return null;
+    const raw = typeof args.file_path === 'string' ? args.file_path
+        : typeof args.path === 'string' ? args.path : undefined;
+    if (raw === undefined || raw.includes('\0'))
+        return null;
+    const root = path.resolve(workspace);
+    const resolved = path.resolve(root, raw);
+    const relative = path.relative(root, resolved);
+    if (relative === '' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        return null;
+    return resolved;
+}
+/**
+ * Read a snapshot for the diff, answering the three states apart.
+ *
+ * `null` is an absent file — the before-half of a newly created file, every line of which counts as
+ * added. `undefined` is "not measurable": a directory, a file over the size ceiling, or any read the
+ * file system refused for a reason the transcript cannot explain. A caller holding `undefined` for
+ * either half reports no stats rather than inventing them.
+ */
+export async function readFileSnapshot(target) {
+    try {
+        const stat = await fs.stat(target);
+        if (!stat.isFile() || stat.size > MAX_STAT_BYTES)
+            return undefined;
+        return await fs.readFile(target, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            return null;
+        return undefined;
+    }
+}
+/** The added/removed line counts for a snapshot pair; nothing when either half was unmeasurable. */
+export function diffLineStats(before, after) {
+    if (before === undefined || after === undefined)
+        return undefined;
+    const [linesAdded, linesRemoved] = countDiff(contentLines(before ?? ''), contentLines(after ?? ''));
+    return { linesAdded, linesRemoved };
+}
+/** A file's content as counted lines: no trailing empty line, CRLF and bare CR folded to LF. */
+function contentLines(content) {
+    if (content === '')
+        return [];
+    const lines = content.split(/\r\n|\r|\n/);
+    if (lines.at(-1) === '')
+        lines.pop();
+    return lines;
+}
+/**
+ * Count the lines a diff would mark added and removed between two line arrays.
+ *
+ * The shared head and tail are trimmed first — a change in the middle of a file has nothing to do
+ * with its unchanged ends — and what is left of the change is matched with a longest-common-
+ * subsequence count, the figure a diff tool marks as changed lines. Past the guard the middle is
+ * counted whole: a file whose changed span exceeds it is a rewrite, where every middle line really
+ * is different for the reader's purposes.
+ */
+function countDiff(oldLines, newLines) {
+    let low = 0;
+    while (low < oldLines.length && low < newLines.length && oldLines[low] === newLines[low])
+        low++;
+    let oldEnd = oldLines.length, newEnd = newLines.length;
+    while (oldEnd > low && newEnd > low && oldLines[oldEnd - 1] === newLines[newEnd - 1]) {
+        oldEnd--;
+        newEnd--;
+    }
+    const midOld = oldLines.slice(low, oldEnd);
+    const midNew = newLines.slice(low, newEnd);
+    if (midOld.length === 0)
+        return [midNew.length, 0];
+    if (midNew.length === 0)
+        return [0, midOld.length];
+    if (midOld.length > LCS_LINE_LIMIT || midNew.length > LCS_LINE_LIMIT)
+        return [midNew.length, midOld.length];
+    // Row-by-row LCS over the changed span, two rolling rows: the counts are all that survive.
+    let previous = new Uint32Array(midOld.length + 1);
+    let current = new Uint32Array(midOld.length + 1);
+    for (let i = 1; i <= midNew.length; i++) {
+        current[0] = 0;
+        for (let j = 1; j <= midOld.length; j++) {
+            current[j] = midNew[i - 1] === midOld[j - 1]
+                ? previous[j - 1] + 1
+                : Math.max(previous[j], current[j - 1]);
+        }
+        const spent = previous;
+        previous = current;
+        current = spent;
+    }
+    const common = previous[midOld.length];
+    return [midNew.length - common, midOld.length - common];
+}

package/dist/src/tool-errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A refusal that tells the model which Read must happen before the same call can succeed.
+ *
+ * This is not a call that cannot work: the model is expected to Read the file and retry the
+ * byte-identical call, so the repeated-failure guard must not count it like a broken tool.
+ */
+export declare class FileReadRequiredError extends Error {
+    readonly refusal: "fresh-read";
+    constructor(message: string);
+}
+/** The actionable refusal classes the engine separates from real tool failures. */
+export type ToolRefusal = FileReadRequiredError['refusal'];

package/dist/src/tool-errors.js

@@ -0,0 +1,13 @@
+/**
+ * A refusal that tells the model which Read must happen before the same call can succeed.
+ *
+ * This is not a call that cannot work: the model is expected to Read the file and retry the
+ * byte-identical call, so the repeated-failure guard must not count it like a broken tool.
+ */
+export class FileReadRequiredError extends Error {
+    refusal = 'fresh-read';
+    constructor(message) {
+        super(message);
+        this.name = 'FileReadRequiredError';
+    }
+}

package/dist/src/tool-failure-tracker.d.ts

@@ -0,0 +1,17 @@
+import type { ToolCall } from './types.js';
+import type { ToolRefusal } from './tool-errors.js';
+/**
+ * Stops unchanged retries while allowing another attempt after a workspace repair, and counts a
+ * Read-gate refusal as guidance rather than as a broken call.
+ *
+ * Real failures keep the three-strike rule: a command that fails the same way three times with no
+ * successful file repair between them is a loop. A refusal that names the Read still owed for a
+ * file is different, because the model is expected to retry the identical call after that Read:
+ * counts are kept per call, a successful Read of that file clears them, and only a model that
+ * keeps retrying without reading reaches the ceiling.
+ */
+export declare class ToolFailureTracker {
+    private readonly failures;
+    private readonly guidance;
+    record(call: ToolCall, failed: boolean, executionSucceeded?: boolean, refusal?: ToolRefusal): boolean;
+}

package/dist/src/tool-failure-tracker.js

@@ -0,0 +1,71 @@
+import { canonicalToolName } from './tool-names.js';
+/**
+ * How many times one call may be refused for a missing Read before the guard calls it a loop.
+ *
+ * A staged read of a long file is expected to take several refusals and several Reads; a model
+ * that never reads is what this ceiling stops.
+ */
+const GUIDANCE_CEILING = 8;
+/** The file a call names, so a Read can answer the refusal for that file alone. */
+function argumentPath(call) {
+    let args;
+    try {
+        args = JSON.parse(call.arguments);
+    }
+    catch {
+        return undefined;
+    }
+    if (!args || typeof args !== 'object')
+        return undefined;
+    const value = args.file_path ?? args.path;
+    if (typeof value !== 'string' || !value)
+        return undefined;
+    const unified = value.replace(/\\/g, '/').replace(/^\.\//, '');
+    return process.platform === 'win32' ? unified.toLowerCase() : unified;
+}
+/**
+ * Stops unchanged retries while allowing another attempt after a workspace repair, and counts a
+ * Read-gate refusal as guidance rather than as a broken call.
+ *
+ * Real failures keep the three-strike rule: a command that fails the same way three times with no
+ * successful file repair between them is a loop. A refusal that names the Read still owed for a
+ * file is different, because the model is expected to retry the identical call after that Read:
+ * counts are kept per call, a successful Read of that file clears them, and only a model that
+ * keeps retrying without reading reaches the ceiling.
+ */
+export class ToolFailureTracker {
+    failures = new Map();
+    guidance = new Map();
+    record(call, failed, executionSucceeded = !failed, refusal) {
+        const signature = `${call.name}:${call.arguments}`;
+        if (refusal) {
+            const path = argumentPath(call);
+            const count = (this.guidance.get(signature)?.count ?? 0) + 1;
+            this.guidance.set(signature, { ...(path ? { path } : {}), count });
+            return count >= GUIDANCE_CEILING;
+        }
+        // Guidance counts answer the call that was refused; any other outcome for that call ends them.
+        this.guidance.delete(signature);
+        const canonical = canonicalToolName(call.name);
+        // Reads, shell diagnostics, metadata writes and failed/blocked repairs are not
+        // evidence that the files used by a failing command have been repaired.
+        if (executionSucceeded && !failed && ['Write', 'Edit', 'apply_patch'].includes(canonical)) {
+            this.failures.clear();
+            this.guidance.clear();
+        }
+        if (failed)
+            this.failures.set(signature, (this.failures.get(signature) ?? 0) + 1);
+        else
+            this.failures.delete(signature);
+        // A completed Read answers the refusals for the file it read — and only those, so a failing
+        // command's history elsewhere survives (its files were not repaired).
+        if (!failed && canonical === 'Read') {
+            const path = argumentPath(call);
+            if (path)
+                for (const [key, entry] of this.guidance)
+                    if (entry.path === path)
+                        this.guidance.delete(key);
+        }
+        return (this.failures.get(signature) ?? 0) >= 3;
+    }
+}

package/dist/src/tool-names.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical provider-visible coding tools.
+ *
+ * Models see one canonical surface. Historical Pi/Andorra spellings remain
+ * configuration aliases so existing saved graph revisions keep working
+ * without advertising duplicate schemas on every model request.
+ */
+export declare const CANONICAL_CODING_TOOLS: readonly ["Read", "Write", "Edit", "Glob", "Grep", "Bash", "PowerShell"];
+export type CanonicalCodingTool = typeof CANONICAL_CODING_TOOLS[number];
+export declare function canonicalCodingToolName(name: string): CanonicalCodingTool | undefined;
+export declare function canonicalToolName(name: string): string;
+export declare function toolNameMatches(configured: string, actual: string): boolean;
+export declare function canonicalizeToolList(names: readonly string[] | undefined): string[] | undefined;
+export declare const LEGACY_CODING_TOOL_NAMES: readonly string[];
+/** Translate historical Pi/Andorra tool arguments into the canonical coding-tool contract. */
+export declare function adaptLegacyCodingToolArguments(name: string, args: Record<string, unknown>): Record<string, unknown>;

package/dist/src/tool-names.js

@@ -0,0 +1,75 @@
+/**
+ * Canonical provider-visible coding tools.
+ *
+ * Models see one canonical surface. Historical Pi/Andorra spellings remain
+ * configuration aliases so existing saved graph revisions keep working
+ * without advertising duplicate schemas on every model request.
+ */
+export const CANONICAL_CODING_TOOLS = [
+    'Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash', 'PowerShell',
+];
+const ALIASES = {
+    Read: 'Read', read: 'Read', read_file: 'Read',
+    Write: 'Write', write: 'Write', write_file: 'Write',
+    Edit: 'Edit', edit: 'Edit', edit_file: 'Edit',
+    Glob: 'Glob', glob: 'Glob', find: 'Glob', list_files: 'Glob', ls: 'Glob',
+    Grep: 'Grep', grep: 'Grep', search_files: 'Grep',
+    Bash: 'Bash', bash: 'Bash',
+    PowerShell: 'PowerShell', powershell: 'PowerShell',
+    shell: process.platform === 'win32' ? 'PowerShell' : 'Bash',
+};
+export function canonicalCodingToolName(name) {
+    return ALIASES[name];
+}
+export function canonicalToolName(name) {
+    return canonicalCodingToolName(name) ?? name;
+}
+export function toolNameMatches(configured, actual) {
+    return canonicalToolName(configured) === canonicalToolName(actual);
+}
+export function canonicalizeToolList(names) {
+    if (!names)
+        return undefined;
+    return [...new Set(names.map(canonicalToolName))];
+}
+export const LEGACY_CODING_TOOL_NAMES = Object.freeze(Object.keys(ALIASES).filter(name => !CANONICAL_CODING_TOOLS.includes(name)));
+function escapeRegexLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Translate historical Pi/Andorra tool arguments into the canonical coding-tool contract. */
+export function adaptLegacyCodingToolArguments(name, args) {
+    const canonical = canonicalCodingToolName(name);
+    if (!canonical || name === canonical)
+        return args;
+    if (canonical === 'Read') {
+        if (name === 'read_file') {
+            const start = typeof args.startLine === 'number' ? args.startLine : undefined;
+            const end = typeof args.endLine === 'number' ? args.endLine : undefined;
+            return { file_path: args.path, ...(start !== undefined ? { offset: start } : {}), ...(end !== undefined ? { limit: Math.max(1, end - (start ?? 1) + 1) } : {}) };
+        }
+        return { file_path: args.path, ...(args.offset !== undefined ? { offset: args.offset } : {}), ...(args.limit !== undefined ? { limit: args.limit } : {}) };
+    }
+    if (canonical === 'Write')
+        return { file_path: args.path, content: args.content };
+    if (canonical === 'Edit') {
+        if (name === 'edit_file')
+            return { file_path: args.path, old_string: args.old_text, new_string: args.new_text };
+        const edits = Array.isArray(args.edits) ? args.edits.map(edit => { const item = edit; return { old_string: item.oldText, new_string: item.newText }; }) : undefined;
+        return { file_path: args.path, ...(edits ? { edits } : {}) };
+    }
+    if (canonical === 'Glob') {
+        if (name === 'list_files')
+            return { pattern: '**/*', ...(args.path !== undefined ? { path: args.path } : {}), head_limit: 1000 };
+        if (name === 'ls')
+            return { pattern: '*', ...(args.path !== undefined ? { path: args.path } : {}) };
+        return { pattern: args.pattern ?? '**/*', ...(args.path !== undefined ? { path: args.path } : {}), ...(args.limit !== undefined ? { head_limit: args.limit } : {}) };
+    }
+    if (canonical === 'Grep') {
+        const raw = String(args.pattern ?? args.query ?? '');
+        const literal = name === 'search_files' || args.literal === true;
+        return { pattern: literal ? escapeRegexLiteral(raw) : raw, ...(args.path !== undefined ? { path: args.path } : {}), ...(args.glob !== undefined ? { glob: args.glob } : {}), output_mode: 'content', ...(args.ignoreCase === true ? { '-i': true } : {}), ...(args.context !== undefined ? { context: args.context } : {}), ...(args.limit !== undefined ? { head_limit: args.limit } : {}) };
+    }
+    if (canonical === 'Bash' || canonical === 'PowerShell')
+        return { command: args.command, ...(args.timeout_ms !== undefined ? { timeout: args.timeout_ms } : {}), ...(args.timeout !== undefined ? { timeout: args.timeout } : {}) };
+    return args;
+}

package/dist/src/tool-result-filter.d.ts

@@ -0,0 +1,65 @@
+export type ToolResultFormat = 'test-report' | 'compiler' | 'search' | 'listing' | 'progress';
+export type ToolResultFilterReason = 'filtered' | 'below_threshold' | 'unknown_format' | 'protected_tool' | 'error_output' | 'no_benefit';
+export interface ToolResultFilterInput {
+    toolName: string;
+    args?: Record<string, unknown>;
+    output: string;
+    isError: boolean;
+    /** Outputs at or under this many characters are left alone. */
+    thresholdChars: number;
+    /** Upper bound on the filtered result. Default 8000. */
+    maxKeptChars?: number;
+    /** The reference the complete original is stored under; named in the filtered result. */
+    reference?: string;
+}
+export interface ToolResultFilterResult {
+    output: string;
+    filtered: boolean;
+    reason: ToolResultFilterReason;
+    format?: ToolResultFormat;
+    originalChars: number;
+    keptChars: number;
+    originalLines: number;
+    omittedLines: number;
+    /** Parsed facts, all counts; never free text from the output. */
+    facts: Record<string, number>;
+}
+/** Which family of output a tool is expected to produce, or undefined when it must not be filtered. */
+export declare function toolResultFilterCandidate(toolName: string, args: Record<string, unknown> | undefined): 'shell' | 'search' | 'listing' | undefined;
+/** Parse and reduce one tool result. The original is never modified; the caller stores it. */
+export declare function filterToolResult(input: ToolResultFilterInput): ToolResultFilterResult;
+/**
+ * The runtime-owned store of complete originals for one invocation.
+ *
+ * References are opaque and scoped to the invocation that created them: another run, node or
+ * invocation cannot name them, and a range request is bounded so an expansion is a deliberate,
+ * accounted read rather than the original flooding back into context.
+ */
+export declare class ToolOutputArchive {
+    private readonly scope;
+    private readonly maxBytes;
+    private readonly persist?;
+    private readonly entries;
+    private readonly persisted;
+    private bytes;
+    constructor(scope: string, maxBytes?: number, persist?: ((ref: string, content: string) => Promise<string | undefined | void>) | undefined);
+    put(content: string): Promise<string | undefined>;
+    has(ref: unknown): ref is string;
+    read(ref: string, offset?: number, limit?: number): {
+        content: string;
+        totalChars: number;
+        offset: number;
+        nextOffset?: number;
+    };
+    size(): number;
+    /** The references that reached durable storage, by the artifact holding each: what a checkpoint records. */
+    exportPersisted(): Record<string, string>;
+    /**
+     * Re-admit a stopped attempt's references from the artifacts its checkpoint named. Only
+     * `tool-output://` references are accepted, an artifact that cannot be loaded is skipped, and the
+     * byte budget still applies. Returns how many references serve again.
+     */
+    import(mapping: Record<string, string>, load: (artifactRef: string) => Promise<string | undefined>): Promise<number>;
+}
+export declare const EXPAND_TOOL_OUTPUT = "expand_tool_output";
+export declare const EXPAND_MAX_CHARS = 8000;