@comma-agents/core 2.0.0-rc.0

package/dist/timeline/index.d.ts

@@ -0,0 +1,4 @@
+export type { ProjectedConversationContext } from "./projections";
+export { projectConversationContext, projectFileState, } from "./projections";
+export { createTimeline } from "./timeline";
+export type { Timeline, TimelineEvent, TimelineFilter, } from "./timeline.types";

package/dist/timeline/projections/conversation-context.d.ts

@@ -0,0 +1,19 @@
+import type { ModelMessage } from "ai";
+import { type ConversationRecord } from "../../conversation-context";
+import type { TimelineEvent } from "../timeline.types";
+export interface ProjectedConversationContext {
+    readonly records: readonly ConversationRecord[];
+    readonly messages: readonly ModelMessage[];
+    readonly length: number;
+}
+/**
+ * Project agent-call events into canonical conversation records.
+ *
+ * @param events - Timeline events to project.
+ * @param agentName - Optional agent name to filter by.
+ * @example
+ * ```ts
+ * const context = projectConversationContext(events, "assistant");
+ * ```
+ */
+export declare function projectConversationContext(events: readonly TimelineEvent[], agentName?: string): ProjectedConversationContext;

package/dist/timeline/projections/file-state.d.ts

@@ -0,0 +1,8 @@
+import type { SessionFileState } from "../../tools/io/session-file-state";
+import type { TimelineEvent } from "../timeline.types";
+/**
+ * Pure projection: Replays timeline events to build a SessionFileState.
+ * This is the exact spiritual successor of `buildSessionFileState` from the tools package,
+ * retargeted to project from `tool_mutation` events in the timeline.
+ */
+export declare function projectFileState(events: readonly TimelineEvent[]): SessionFileState;

package/dist/timeline/projections/index.d.ts

@@ -0,0 +1,3 @@
+export type { ProjectedConversationContext } from "./conversation-context";
+export { projectConversationContext } from "./conversation-context";
+export { projectFileState } from "./file-state";

package/dist/timeline/timeline.d.ts

@@ -0,0 +1,11 @@
+import type { Timeline, TimelineEvent, TimelineFilter } from "./timeline.types";
+/**
+ * Filter an array of timeline events based on common filter parameters.
+ * Implemented as a pure helper in accordance with ts-patterns.
+ */
+export declare function filterEvents(events: readonly TimelineEvent[], filter?: TimelineFilter): readonly TimelineEvent[];
+/**
+ * Construct a fresh in-memory Timeline stream.
+ * Uses a closure to capture state privately.
+ */
+export declare function createTimeline(initialEvents?: readonly TimelineEvent[]): Timeline;

package/dist/timeline/timeline.types.d.ts

@@ -0,0 +1,97 @@
+import type { ConversationRecord, ConversationRetentionEvent } from "../conversation-context";
+/**
+ * Union type representing any event recorded on a strategy run's timeline.
+ * All events are immutable, timestamped, and conform to this common schema.
+ */
+export type TimelineEvent = {
+    readonly type: "run_started";
+    readonly ts: string;
+    readonly strategyPath: string;
+    readonly strategyName: string;
+    readonly cwd: string;
+    readonly initialInput?: string;
+    readonly manifestPath?: string;
+    readonly modelOverride?: string;
+} | {
+    readonly type: "run_completed";
+    readonly ts: string;
+    readonly status: "completed" | "error" | "cancelled";
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+} | {
+    readonly type: "agent_call";
+    readonly ts: string;
+    readonly record: ConversationRecord;
+} | {
+    readonly type: "conversation_retention";
+    readonly ts: string;
+    readonly event: ConversationRetentionEvent;
+} | {
+    readonly type: "user_input";
+    readonly ts: string;
+    readonly agentName: string;
+    readonly text: string;
+    readonly source: "human" | "agent";
+} | {
+    readonly type: "tool_mutation";
+    readonly ts: string;
+    readonly agentName: string;
+    readonly toolName: string;
+    readonly operation: "create" | "update" | "delete" | "move";
+    readonly path: string;
+    readonly toPath?: string;
+    readonly beforeSha256?: string;
+    readonly afterSha256?: string;
+    readonly diff?: string;
+    readonly success: boolean;
+    readonly error?: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+} | {
+    readonly type: "step_started";
+    readonly ts: string;
+    readonly stepName: string;
+    readonly flowName?: string;
+    readonly agentName?: string;
+    readonly index?: number;
+} | {
+    readonly type: "step_completed";
+    readonly ts: string;
+    readonly stepName: string;
+    readonly flowName?: string;
+    readonly agentName?: string;
+    readonly index?: number;
+} | {
+    readonly type: "permission_decision";
+    readonly ts: string;
+    readonly decision: "allow" | "deny" | "allow-session" | "deny-session";
+    readonly agentName?: string;
+    readonly toolName?: string;
+    readonly resource?: string;
+};
+/** Filter parameters for querying events from a Timeline. */
+export interface TimelineFilter {
+    /** Keep only events matching this exact type. */
+    readonly type?: TimelineEvent["type"];
+    /** Keep only events produced by or involving this agent. */
+    readonly agentName?: string;
+    /** Keep only events occurring after this ISO-8601 UTC timestamp. */
+    readonly since?: string;
+}
+/**
+ * Closure-based Timeline stream.
+ * Tracks strategy run progress as an append-only sequence of immutable events.
+ */
+export interface Timeline {
+    /** Append an event to the timeline. Throws if the event is malformed. */
+    append(event: TimelineEvent): void;
+    /** Retrieve a read-only list of events, optionally matching a filter. */
+    events(filter?: TimelineFilter): readonly TimelineEvent[];
+    /** Total number of events currently in the timeline. */
+    readonly size: number;
+    /** Clears all events from the timeline. */
+    clear(): void;
+    /** Iterator support for walking events. */
+    [Symbol.iterator](): Iterator<TimelineEvent>;
+}

package/dist/tools/build-tool-system-prompt.d.ts

@@ -0,0 +1,41 @@
+import type { ToolContext, ToolDefinition } from "./tool.types";
+/**
+ * Options for building tool system prompt contributions.
+ */
+interface BuildToolSystemPromptOptions {
+    /** The tool definitions to collect system prompts from. */
+    readonly toolDefinitions: Readonly<Record<string, ToolDefinition>>;
+    /** ToolContext passed to dynamic systemPrompt functions. */
+    readonly toolContext: ToolContext;
+}
+/**
+ * Collect and merge system prompt contributions from all tools.
+ *
+ * Tools can contribute via:
+ * - Static string: `systemPrompt: "Always use JSON format."`
+ * - Dynamic function: `systemPrompt: async (ctx) => \`CWD: ${ctx.guard.cwd}\``
+ *
+ * The contributions are merged into a single string, with each tool's
+ * contribution prefixed by `## tool-name` for clarity. Only tools with
+ * a `systemPrompt` field are included.
+ *
+ * @returns Merged system prompt string, or undefined if no tools have contributions.
+ *
+ * @example
+ * ```ts
+ * const toolDefs = { read_file: { systemPrompt: "..." }, ... };
+ * const prompt = await buildToolSystemPrompt({ toolDefs, toolContext });
+ * // => "## read_file\n..." or undefined
+ * ```
+ */
+export declare function buildToolSystemPrompt(options: BuildToolSystemPromptOptions): Promise<string | undefined>;
+/**
+ * Merge multiple system prompt strings into one.
+ *
+ * Handles undefined values and ensures proper separation between sections.
+ * The order of the input array is preserved.
+ *
+ * @returns Merged string, or undefined if all inputs are undefined/empty.
+ */
+export declare function mergeSystemPrompts(prompts: readonly (string | undefined)[]): string | undefined;
+export {};

package/dist/tools/built-in/ask-question/ask-question.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+export declare const askQuestionParams: z.ZodObject<{
+    question: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    question: string;
+}, {
+    question: string;
+}>;
+export interface AskQuestionData {
+    readonly response: string;
+}
+/**
+ * Create the `ask_question` tool.
+ *
+ * @example
+ * ```ts
+ * const askQuestion = createAskQuestionTool();
+ * ```
+ */
+export declare function createAskQuestionTool(): ToolDefinition<typeof askQuestionParams, AskQuestionData>;

package/dist/tools/built-in/ask-question/index.d.ts

@@ -0,0 +1,2 @@
+export type { AskQuestionData } from "./ask-question";
+export { askQuestionParams, createAskQuestionTool } from "./ask-question";

package/dist/tools/built-in/create-file/create-file.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { CreateFileData, CreateFileToolConfig } from "./create-file.types";
+declare const createFileParams: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+    createParentDirectories: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    content: string;
+    createParentDirectories?: boolean | undefined;
+}, {
+    path: string;
+    content: string;
+    createParentDirectories?: boolean | undefined;
+}>;
+export declare function createCreateFileTool(config?: CreateFileToolConfig): ToolDefinition<typeof createFileParams, CreateFileData>;
+export {};

package/dist/tools/built-in/create-file/create-file.types.d.ts

@@ -0,0 +1,11 @@
+import type { AuditSink } from "../../io/audit.types";
+export interface CreateFileToolConfig {
+    readonly defaultAuditSink?: AuditSink;
+}
+export interface CreateFileData {
+    readonly created: true;
+    readonly path: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
+    readonly diff: string;
+}

package/dist/tools/built-in/create-file/index.d.ts

@@ -0,0 +1,2 @@
+export { createCreateFileTool } from "./create-file";
+export type { CreateFileData, CreateFileToolConfig } from "./create-file.types";

package/dist/tools/built-in/delete-file/delete-file.constants.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export declare const deleteFileParams: z.ZodObject<{
+    path: z.ZodString;
+    expectedSha256: z.ZodOptional<z.ZodString>;
+    permanent: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    expectedSha256?: string | undefined;
+    permanent?: boolean | undefined;
+}, {
+    path: string;
+    expectedSha256?: string | undefined;
+    permanent?: boolean | undefined;
+}>;

package/dist/tools/built-in/delete-file/delete-file.d.ts

@@ -0,0 +1,5 @@
+import type { ToolDefinition } from "../../tool.types";
+import { deleteFileParams } from "./delete-file.constants";
+import type { DeleteFileData, DeleteFileToolConfig } from "./delete-file.types";
+/** Create the `delete_file` tool. */
+export declare function createDeleteFileTool(config?: DeleteFileToolConfig): ToolDefinition<typeof deleteFileParams, DeleteFileData>;

package/dist/tools/built-in/delete-file/delete-file.types.d.ts

@@ -0,0 +1,26 @@
+import type { AuditSink } from "../../io/audit.types";
+/** Configuration for `delete_file`. */
+export interface DeleteFileToolConfig {
+    /** Default audit sink when `toolContext.auditSink` is undefined. */
+    readonly defaultAuditSink?: AuditSink;
+}
+/** Structured payload returned by `delete_file`. */
+export interface DeleteFileData {
+    /** Always `true` on success. */
+    readonly deleted: true;
+    /** Workspace-relative path of the deleted file (echoed). */
+    readonly path: string;
+    /** SHA-256 of the file's content at deletion time. */
+    readonly beforeSha256: string;
+    /** Byte length of the deleted content. */
+    readonly sizeBytes: number;
+    /** Unified diff from file → /dev/null. */
+    readonly diff: string;
+    /**
+     * Absolute path of the trash entry, when the delete was recoverable.
+     * Omitted when `permanent: true`.
+     */
+    readonly trashedTo?: string;
+    /** Whether the delete was permanent (no recovery). */
+    readonly permanent: boolean;
+}

package/dist/tools/built-in/delete-file/index.d.ts

@@ -0,0 +1,2 @@
+export { createDeleteFileTool } from "./delete-file";
+export type { DeleteFileData, DeleteFileToolConfig } from "./delete-file.types";

package/dist/tools/built-in/describe-tool.d.ts

@@ -0,0 +1,61 @@
+import type { ToolErrorKind } from "../tool.types";
+/** Single input parameter description. */
+export interface DescribeToolInput {
+    /** Parameter name as it appears in the JSON schema. */
+    readonly name: string;
+    /** Human-readable type, e.g. `"string"`, `"number"`, `"object<string, string>"`. */
+    readonly type: string;
+    /** Whether the parameter is required. Optional parameters render their default when supplied. */
+    readonly required: boolean;
+    /** Default value when omitted, rendered as text. Only used when `required: false`. */
+    readonly defaultValue?: string;
+    /** One-line description of the parameter's semantics. */
+    readonly description: string;
+}
+/** Single error-kind row. */
+export interface DescribeToolError {
+    /** A {@link ToolErrorKind} this tool may emit. */
+    readonly kind: ToolErrorKind;
+    /** Why this kind fires and what the model should do next. */
+    readonly description: string;
+}
+/** Input to {@link describeTool}. */
+export interface DescribeToolOptions {
+    /**
+     * One-line purpose sentence (no trailing period required — the helper
+     * will not add one). Multi-line purposes are allowed; each entry is
+     * rendered as its own paragraph above the `Inputs:` section.
+     */
+    readonly purpose: string | readonly string[];
+    /** Inputs in declaration order. */
+    readonly inputs: readonly DescribeToolInput[];
+    /**
+     * One or more lines describing the structured `data` payload returned
+     * on success. The string `"data"` should NOT be repeated — the helper
+     * prefixes the section with `Outputs (\`data\`):`.
+     */
+    readonly outputs: string | readonly string[];
+    /** Error kinds this tool may surface. */
+    readonly errors: readonly DescribeToolError[];
+    /**
+     * Optional usage examples. Each entry is rendered verbatim on its own
+     * line under the `Examples:` heading.
+     */
+    readonly examples?: readonly string[];
+    /**
+     * Optional free-form notes (cross-references to protocols, host
+     * platform info for run_command, etc.). Each entry becomes its own
+     * line under `Notes:`.
+     */
+    readonly notes?: readonly string[];
+}
+/**
+ * Render a tool description in the canonical built-in format.
+ *
+ * Layout (sections emitted in fixed order):
+ *   Purpose → Inputs → Outputs → Errors → Examples → Notes.
+ * Token-efficient plain-text — no Markdown, no XML — so every provider
+ * sees the same content. Deterministic: same options produce the same
+ * string, which backs the snapshot test catching accidental drift.
+ */
+export declare function describeTool(options: DescribeToolOptions): string;

package/dist/tools/built-in/edit-file/edit-file.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { EditFileData, EditFileToolConfig } from "./edit-file.types";
+export declare const editFileParams: z.ZodObject<{
+    path: z.ZodString;
+    expectedSha256: z.ZodOptional<z.ZodString>;
+    edits: z.ZodArray<z.ZodObject<{
+        oldText: z.ZodString;
+        newText: z.ZodString;
+        expectedOccurrences: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        oldText: string;
+        newText: string;
+        expectedOccurrences?: number | undefined;
+    }, {
+        oldText: string;
+        newText: string;
+        expectedOccurrences?: number | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    edits: {
+        oldText: string;
+        newText: string;
+        expectedOccurrences?: number | undefined;
+    }[];
+    expectedSha256?: string | undefined;
+}, {
+    path: string;
+    edits: {
+        oldText: string;
+        newText: string;
+        expectedOccurrences?: number | undefined;
+    }[];
+    expectedSha256?: string | undefined;
+}>;
+/**
+ * Create the `edit_file` tool.
+ *
+ * @param config - Optional configuration overriding the default audit sink.
+ * @example
+ * ```ts
+ * const editFile = createEditFileTool();
+ * ```
+ */
+export declare function createEditFileTool(config?: EditFileToolConfig): ToolDefinition<typeof editFileParams, EditFileData>;

package/dist/tools/built-in/edit-file/edit-file.replacers.d.ts

@@ -0,0 +1,81 @@
+/** A candidate substring of the snapshot that should be treated as the match. */
+export type ReplacerCandidate = string;
+/**
+ * A replacer generator. Yields zero or more candidate substrings of
+ * `content` that should be treated as matches for `find`. The caller
+ * filters to candidates that actually appear in `content` and picks
+ * one as the match.
+ */
+export type Replacer = (content: string, find: string) => Generator<ReplacerCandidate, void, unknown>;
+/**
+ * Exact match (the strictest replacer). Yields `find` itself if it appears
+ * in `content`, otherwise nothing. Equivalent to the original behaviour;
+ * kept in the chain so the same code path covers exact and fallback cases.
+ */
+export declare const exactReplacer: Replacer;
+/**
+ * Line-trimmed match. Strips leading/trailing whitespace from each line
+ * before comparison so the LLM's slightly-off indentation is forgiven.
+ * Yields the *actual* unchanged substring of `content` that lines up,
+ * so the eventual replacement preserves the file's original whitespace.
+ */
+export declare const lineTrimmedReplacer: Replacer;
+/**
+ * Block-anchor match. When `find` has ≥3 lines, find blocks in
+ * `content` whose first and last lines (trimmed) equal the first and
+ * last lines of `find` (trimmed). The middle is allowed to differ —
+ * use this when the LLM gave us the right "envelope" but maybe wrote
+ * the body slightly differently.
+ *
+ * Only emitted when there is exactly one block-anchor candidate, to
+ * avoid silently picking the wrong location.
+ */
+export declare const blockAnchorReplacer: Replacer;
+/**
+ * Whitespace-normalized match for SINGLE-LINE finds only. Collapses all
+ * whitespace runs in both content and find to single spaces (trimmed),
+ * then looks for the normalized find as a normalized line. Yields the
+ * original (unchanged) line.
+ *
+ * Kept conservative — only handles single-line finds because multi-line
+ * whitespace normalization gets ambiguous and merges with
+ * `lineTrimmedReplacer`'s territory.
+ */
+export declare const whitespaceNormalizedReplacer: Replacer;
+/**
+ * The default chain, applied in order. The first replacer to yield a
+ * unique candidate wins. Order matters: stricter strategies come first
+ * so that exact LLM intent is preferred over heuristic recovery.
+ *
+ * The chain is intentionally short (4 replacers, not OpenCode's 9).
+ * Each extra replacer is another opportunity for a heuristic to
+ * "succeed" on something the LLM didn't actually mean — over-eager
+ * fallbacks risk silently editing the wrong block. These four cover
+ * the trivial cases (indentation drift, single-line whitespace, block
+ * envelopes) without venturing into Levenshtein territory.
+ */
+export declare const DEFAULT_REPLACER_CHAIN: readonly Replacer[];
+/**
+ * Try the replacer chain in order and return the first unique candidate
+ * substring that appears in `content`. Returns `undefined` if no
+ * replacer yielded a candidate, or if every replacer that yielded
+ * something yielded multiple distinct candidates (ambiguous).
+ *
+ * Distinguishes:
+ * - "no candidates" → caller emits `old_text_not_found`.
+ * - "ambiguous" (multiple distinct candidates from a replacer) →
+ *   caller emits `multiple_matches` with the candidates so the LLM
+ *   can disambiguate.
+ *
+ * @param content - The current file snapshot (normalized to LF).
+ * @param find - The LLM-supplied `oldText` (normalized to LF).
+ * @param replacers - Override the default chain (used by tests).
+ */
+export declare function findFallbackMatch(content: string, find: string, replacers?: readonly Replacer[]): {
+    match: string;
+    replacerName: string;
+    isExact: boolean;
+} | {
+    ambiguous: readonly string[];
+    replacerName: string;
+} | undefined;

package/dist/tools/built-in/edit-file/edit-file.types.d.ts

@@ -0,0 +1,59 @@
+import type { AuditSink } from "../../io/audit.types";
+export interface EditFileToolConfig {
+    /**
+     * Default audit sink to use when `ctx.auditSink` is undefined. Tests
+     * typically pass `createMemoryAuditSink()` so they can assert on
+     * audit entries; production callers should rely on the
+     * `buildAgentToolSet` injection path.
+     */
+    readonly defaultAuditSink?: AuditSink;
+}
+export interface AppliedEdit {
+    /** Index of the edit in the input array. */
+    readonly editIndex: number;
+    /** Number of occurrences replaced. */
+    readonly occurrences: number;
+    /**
+     * True when the exact substring match failed and a fallback replacer
+     * recovered the edit (line-trimmed, whitespace-normalized, or block
+     * anchor). Surfaces in the tool's text output so the LLM can spot when
+     * its `oldText` was approximate and tighten it next time.
+     */
+    readonly usedFallback?: boolean;
+    /**
+     * Name of the replacer that produced the match. Always present;
+     * `"exactReplacer"` for the strict path.
+     */
+    readonly replacerName?: string;
+    /**
+     * The actual substring of the file that was matched and replaced.
+     * Populated only when a fallback was used so the caller can show the
+     * LLM exactly what got swapped (the LLM's `oldText` is approximate by
+     * definition in that case).
+     */
+    readonly matchedText?: string;
+}
+export interface MatchRange {
+    /** 1-indexed inclusive line where the match starts. */
+    readonly startLine: number;
+    /** 1-indexed inclusive line where the match ends. */
+    readonly endLine: number;
+    /** Logical (LF, no-BOM) character offset of match start. */
+    readonly startOffset: number;
+    /** Logical character offset of match end (exclusive). */
+    readonly endOffset: number;
+}
+export interface EditFileData {
+    /** Workspace-relative path (echoed). */
+    readonly path: string;
+    /** SHA-256 of the file's contents before the edits. */
+    readonly beforeSha256: string;
+    /** SHA-256 of the file's contents after the edits. */
+    readonly afterSha256: string;
+    /** Byte length of the post-edit content. */
+    readonly sizeBytes: number;
+    /** Per-edit application summary. */
+    readonly appliedEdits: readonly AppliedEdit[];
+    /** Unified diff from `before` → `after`. Empty string when unchanged. */
+    readonly diff: string;
+}

package/dist/tools/built-in/edit-file/edit-file.utils.d.ts

@@ -0,0 +1,70 @@
+import type { AppliedEdit } from "./edit-file.types";
+interface PlannedReplacement {
+    readonly editIndex: number;
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly newText: string;
+}
+/** Outcome details for a single edit, surfaced into the AppliedEdit return. */
+interface EditMatchOutcome {
+    /** The actual substring matched in the snapshot (post-fallback if used). */
+    readonly matchedText: string;
+    /** Which replacer in the chain produced this match. */
+    readonly replacerName: string;
+    /** True iff the match was found via exact substring lookup (no fallback). */
+    readonly isExact: boolean;
+}
+/**
+ * Compute 1-indexed line numbers spanning a (start, end) character offset
+ * pair in `text`. End is exclusive; an edit ending at a newline counts
+ * the line containing that newline.
+ */
+export declare function offsetsToLineRange(text: string, startOffset: number, endOffset: number): {
+    startLine: number;
+    endLine: number;
+};
+/** Find every occurrence of `needle` in `haystack` and return start offsets. */
+export declare function findAllOccurrences(haystack: string, needle: string): number[];
+/**
+ * Locate every occurrence of each edit's `oldText` in the snapshot, verify
+ * match counts, and build the planned replacements list.
+ *
+ * Matching is tiered:
+ *
+ * 1. **Exact substring.** The strict legacy behaviour — `oldText` is
+ *    matched character-for-character. If found, use it.
+ * 2. **Fallback chain.** If exact match yields zero hits, the
+ *    `DEFAULT_REPLACER_CHAIN` (line-trimmed → whitespace-normalized →
+ *    block-anchor) is tried in priority order. The first replacer to
+ *    produce a *unique* candidate substring of the snapshot wins.
+ *    `expectedOccurrences > 1` disables fallback entirely (because the
+ *    LLM is asking for batch replacement of a literal string).
+ *
+ * Returns `{ planned, appliedEdits }` on success, or a `ToolError`-shaped
+ * object on failure. `AppliedEdit` carries a `usedFallback` flag and the
+ * `replacerName` so callers can surface the heuristic to the LLM.
+ */
+export declare function locateEditOccurrences(snapshot: string, edits: readonly {
+    oldText: string;
+    newText: string;
+    expectedOccurrences?: number;
+}[], filePath: string): {
+    planned: PlannedReplacement[];
+    appliedEdits: AppliedEdit[];
+} | {
+    errorKind: "old_text_not_found" | "multiple_matches";
+    errorMessage: string;
+    errorDetails: Record<string, unknown>;
+};
+/**
+ * Detect overlapping replacement ranges. Returns the conflicting edit indices
+ * if any overlap is found, or `undefined` if all ranges are disjoint.
+ */
+export declare function detectOverlappingEdits(planned: readonly PlannedReplacement[]): number[] | undefined;
+/**
+ * Apply all planned replacements deterministically (descending by start offset).
+ * Each replacement splices into a working copy of the snapshot.
+ */
+export declare function applyReplacements(snapshot: string, planned: readonly PlannedReplacement[]): string;
+/** Re-export for outcome reporting. */
+export type { EditMatchOutcome };

package/dist/tools/built-in/edit-file/index.d.ts

@@ -0,0 +1,2 @@
+export { createEditFileTool } from "./edit-file";
+export type { AppliedEdit, EditFileData, EditFileToolConfig, MatchRange, } from "./edit-file.types";

package/dist/tools/built-in/glob/glob.constants.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_EXCLUDE_GLOBS: readonly string[];
+export declare const DEFAULT_MAX_RESULTS = 1000;
+export declare const DEFAULT_TRAVERSAL_DEPTH = 32;

package/dist/tools/built-in/glob/glob.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { GlobData, GlobToolConfig } from "./glob.types";
+export declare const globParams: z.ZodObject<{
+    pattern: z.ZodString;
+    root: z.ZodOptional<z.ZodString>;
+    excludeGlobs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    pattern: string;
+    root?: string | undefined;
+    excludeGlobs?: string[] | undefined;
+    maxResults?: number | undefined;
+}, {
+    pattern: string;
+    root?: string | undefined;
+    excludeGlobs?: string[] | undefined;
+    maxResults?: number | undefined;
+}>;
+/**
+ * Create a Glob Tool to find both files and folders matching a glob pattern.
+ *
+ * @param config - Config options for limits like maxResults and maxDepth.
+ */
+export declare function createGlobTool(config?: GlobToolConfig): ToolDefinition<typeof globParams, GlobData>;