@comma-agents/core 2.0.0-rc.0

package/dist/tools/built-in/run-command/run-command.utils.d.ts

@@ -0,0 +1,37 @@
+import type { PlatformInfo } from "./run-command.types";
+/** Map `process.platform` to a friendly OS name. */
+export declare function friendlyOsName(platform: NodeJS.Platform): string;
+/**
+ * Resolve the shell to use for executing a command string on the
+ * current platform.
+ *
+ * On POSIX systems we prefer the user's `$SHELL` when set, falling
+ * back to `/bin/sh`. On Windows we prefer `%ComSpec%`, falling back
+ * to `cmd.exe`. The chosen shell is invoked with `-c <command>` on
+ * POSIX or `/d /s /c <command>` on Windows.
+ */
+export declare function resolveShell(platform: NodeJS.Platform, env?: NodeJS.ProcessEnv): {
+    shellPath: string;
+    shellFlag: string;
+};
+/**
+ * Detect the platform info for the current process. Cached snapshot —
+ * call once at factory-creation time.
+ */
+export declare function detectPlatformInfo(): PlatformInfo;
+/**
+ * Build the model-facing tool description, baking in the detected
+ * platform info so the LLM picks correct commands for the host.
+ */
+export declare function buildRunCommandDescription(info: PlatformInfo): string;
+/**
+ * Truncate a captured stream to `maxBytes` UTF-8 bytes, appending a
+ * truncation marker when content was dropped. Operates on the raw
+ * Buffer to avoid splitting multi-byte sequences mid-character.
+ */
+export declare function truncateOutput(buffer: Buffer, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/** True iff `command` matches any pattern in `patterns`. */
+export declare function matchesAnyPattern(command: string, patterns: readonly RegExp[]): boolean;

package/dist/tools/built-in/search-files/index.d.ts

@@ -0,0 +1,2 @@
+export { createSearchFilesTool } from "./search-files";
+export type { SearchFilesData, SearchFilesMatch, SearchFilesToolConfig, } from "./search-files.types";

package/dist/tools/built-in/search-files/search-files.constants.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_EXCLUDE_GLOBS: readonly string[];
+export declare const DEFAULT_MAX_RESULTS = 100;
+export declare const DEFAULT_CONTEXT_LINES = 0;
+export declare const DEFAULT_MAX_FILE_BYTES: number;
+export declare const DEFAULT_TRAVERSAL_DEPTH = 32;

package/dist/tools/built-in/search-files/search-files.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { SearchFilesData, SearchFilesToolConfig } from "./search-files.types";
+declare const searchFilesParams: z.ZodObject<{
+    query: z.ZodString;
+    mode: z.ZodEnum<["path", "text", "regex"]>;
+    root: z.ZodOptional<z.ZodString>;
+    includeGlobs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    excludeGlobs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+    contextLines: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    mode: "path" | "regex" | "text";
+    root?: string | undefined;
+    excludeGlobs?: string[] | undefined;
+    maxResults?: number | undefined;
+    includeGlobs?: string[] | undefined;
+    contextLines?: number | undefined;
+}, {
+    query: string;
+    mode: "path" | "regex" | "text";
+    root?: string | undefined;
+    excludeGlobs?: string[] | undefined;
+    maxResults?: number | undefined;
+    includeGlobs?: string[] | undefined;
+    contextLines?: number | undefined;
+}>;
+export declare function createSearchFilesTool(config?: SearchFilesToolConfig): ToolDefinition<typeof searchFilesParams, SearchFilesData>;
+export {};

package/dist/tools/built-in/search-files/search-files.types.d.ts

@@ -0,0 +1,19 @@
+export interface SearchFilesToolConfig {
+    readonly maxResults?: number;
+    readonly maxFileBytes?: number;
+    readonly maxDepth?: number;
+}
+export interface SearchFilesMatch {
+    readonly path: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly preview: string;
+}
+export interface SearchFilesData {
+    readonly mode: "path" | "text" | "regex";
+    readonly query: string;
+    readonly root: string;
+    readonly matches: readonly SearchFilesMatch[];
+    readonly truncated: boolean;
+    readonly filesScanned: number;
+}

package/dist/tools/built-in/search-files/search-files.utils.d.ts

@@ -0,0 +1,11 @@
+import { toolError } from "../../result";
+export declare function toForwardSlash(pathString: string): string;
+export declare function matchesAnyGlob(relPath: string, patterns: readonly string[]): boolean;
+export declare function buildPreview(lines: readonly string[], lineIndex: number, contextLines: number): string;
+export declare function compileRegex(query: string): {
+    regex: RegExp;
+    error?: undefined;
+} | {
+    regex?: undefined;
+    error: ReturnType<typeof toolError>;
+};

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

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+/**
+ * Reset the todo state for a raw store key — typically `runId` when supplied
+ * or `agentName` for legacy callers. Exposed for tests and embedders.
+ */
+export declare function resetTodoStateForAgent(key: string): void;
+/**
+ * Reset all todo state across all agents and runs. Exposed for tests.
+ */
+export declare function resetAllTodoState(): void;
+declare const todoAddParams: z.ZodObject<{
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+}, {
+    content: string;
+}>;
+/**
+ * Create the `todo_add` tool, which appends a new pending item to the current
+ * todo list and returns its assigned id.
+ */
+export declare function createTodoAddTool(): ToolDefinition<typeof todoAddParams>;
+declare const todoRemoveParams: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+/**
+ * Create the `todo_remove` tool, which deletes a single obsolete todo item.
+ */
+export declare function createTodoRemoveTool(): ToolDefinition<typeof todoRemoveParams>;
+declare const todoCompleteParams: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+/**
+ * Create the `todo_complete` tool, which marks an item complete and returns
+ * the next pending item (or a "all done" message).
+ */
+export declare function createTodoCompleteTool(): ToolDefinition<typeof todoCompleteParams>;
+declare const todoGetParams: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+/**
+ * Create the `todo_get` tool, which returns the full current todo list.
+ */
+export declare function createTodoGetTool(): ToolDefinition<typeof todoGetParams>;
+declare const todoGetNextParams: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+/**
+ * Create the `todo_get_next` tool, which returns the next pending todo item.
+ */
+export declare function createTodoGetNextTool(): ToolDefinition<typeof todoGetNextParams>;
+declare const todoClearParams: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+/**
+ * Create the `todo_clear` tool, which removes all items from the current list.
+ */
+export declare function createTodoClearTool(): ToolDefinition<typeof todoClearParams>;
+export {};

package/dist/tools/built-in/todo/todo.types.d.ts

@@ -0,0 +1,7 @@
+export interface TodoItem {
+    readonly id: string;
+    readonly content: string;
+    status: "pending" | "completed";
+    readonly createdAt: string;
+    completedAt?: string;
+}

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

@@ -0,0 +1,3 @@
+export declare const DEFAULT_TIMEOUT_SECONDS = 30;
+export declare const DEFAULT_MAX_CONTENT_LENGTH = 50000;
+export declare const DEFAULT_USER_AGENT = "CommaAgents-WebFetch/1.0";

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

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { WebFetchToolConfig } from "./webfetch.types";
+declare const webFetchParams: z.ZodObject<{
+    url: z.ZodString;
+    format: z.ZodDefault<z.ZodOptional<z.ZodEnum<["text", "markdown", "html"]>>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    format: "text" | "markdown" | "html";
+    timeout?: number | undefined;
+}, {
+    url: string;
+    format?: "text" | "markdown" | "html" | undefined;
+    timeout?: number | undefined;
+}>;
+/**
+ * Create a webfetch tool for retrieving and converting web content.
+ *
+ * @param config - Optional configuration overriding default timeout, content length, and user-agent.
+ * @example
+ * ```ts
+ * const webfetch = createWebFetchTool();
+ *
+ * // With custom defaults
+ * const webfetch = createWebFetchTool({
+ *   defaultTimeout: 60,
+ *   maxContentLength: 100_000,
+ * });
+ * ```
+ */
+export declare function createWebFetchTool(config?: WebFetchToolConfig): ToolDefinition<typeof webFetchParams>;
+export {};

package/dist/tools/built-in/webfetch/webfetch.types.d.ts

@@ -0,0 +1,8 @@
+export interface WebFetchToolConfig {
+    /** Default per-request timeout in seconds (default: 30). */
+    readonly defaultTimeout?: number;
+    /** Maximum length of the returned content in characters (default: 50_000). */
+    readonly maxContentLength?: number;
+    /** Custom user-agent header (default: "CommaAgents-WebFetch/1.0"). */
+    readonly userAgent?: string;
+}

package/dist/tools/built-in/webfetch/webfetch.utils.d.ts

@@ -0,0 +1,19 @@
+import TurndownService from "turndown";
+/**
+ * Combine multiple AbortSignals into one. Aborts as soon as any input aborts.
+ */
+export declare function mergeAbortSignals(signals: readonly AbortSignal[]): AbortSignal;
+/**
+ * Lazily-instantiated Turndown service. Strips script/style noise and
+ * uses sensible defaults for LLM-friendly markdown output.
+ */
+export declare function getTurndown(): TurndownService;
+/**
+ * Strip common Markdown syntax from text, leaving readable plain text.
+ * Used for the "text" output format.
+ */
+export declare function stripMarkdown(markdown: string): string;
+/**
+ * Convert HTML into the requested output format.
+ */
+export declare function transformContent(html: string, format: "text" | "markdown" | "html"): string;

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

@@ -0,0 +1,2 @@
+export { createWriteFileTool } from "./write-file";
+export type { WriteFileData, WriteFileToolConfig } from "./write-file.types";

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

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../../tool.types";
+import type { WriteFileData, WriteFileToolConfig } from "./write-file.types";
+declare const writeFileParams: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+    expectedSha256: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    content: string;
+    expectedSha256: string;
+}, {
+    path: string;
+    content: string;
+    expectedSha256: string;
+}>;
+export declare function createWriteFileTool(config?: WriteFileToolConfig): ToolDefinition<typeof writeFileParams, WriteFileData>;
+export {};

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

@@ -0,0 +1,11 @@
+import type { AuditSink } from "../../io/audit.types";
+export interface WriteFileToolConfig {
+    readonly defaultAuditSink?: AuditSink;
+}
+export interface WriteFileData {
+    readonly path: string;
+    readonly beforeSha256: string;
+    readonly afterSha256: string;
+    readonly sizeBytes: number;
+    readonly diff: string;
+}

package/dist/tools/define/define-tool.d.ts

@@ -0,0 +1,15 @@
+import type { z } from "zod";
+import type { Policy } from "../../guard/guard.types";
+import type { ToolContext, ToolDefinition, ToolResult } from "../tool.types";
+export declare function defineTool<ParameterSchema extends z.ZodType, DataShape = unknown>(config: {
+    readonly description: string;
+    readonly parameters: ParameterSchema;
+    readonly policies?: readonly Policy[];
+    /**
+     * Optional system prompt contribution from this tool.
+     * Injected ONCE into the agent's system prompt at creation time.
+     * Can be a static string or a function receiving ToolContext.
+     */
+    readonly systemPrompt?: string | ((toolContext: ToolContext) => Promise<string> | string);
+    readonly execute: (validatedArguments: z.infer<ParameterSchema>, toolContext: ToolContext) => Promise<ToolResult<DataShape>>;
+}): ToolDefinition<ParameterSchema, DataShape>;

package/dist/tools/io/atomic-write.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Options for {@link writeAtomic}.
+ */
+export interface WriteAtomicOptions {
+    /**
+     * Mode bits to apply to the final file. When omitted, we preserve the
+     * existing target's mode (if present) or fall back to the OS default.
+     */
+    readonly mode?: number;
+    /**
+     * Whether to `fsync` the temp file before renaming. Defaults to `true`.
+     * Set to `false` only in test harnesses where durability is irrelevant
+     * and disk IO is the bottleneck.
+     */
+    readonly fsync?: boolean;
+}
+/**
+ * Atomically write `content` to `absolutePath`.
+ *
+ * Implementation:
+ * 1. Determine the target mode (caller override → existing target → undefined).
+ * 2. Write `content` to `<dir>/<basename>.tmp-<8 hex bytes>`.
+ * 3. `fsync` the temp file (unless `fsync: false`).
+ * 4. `chmod` the temp file to the target mode (if known) — done before
+ *    rename so the final file appears with the correct permissions
+ *    atomically.
+ * 5. `rename` temp → target. On POSIX this is atomic when both paths
+ *    are on the same filesystem (always true here — same directory).
+ * 6. On any failure, attempt to `unlink` the temp file.
+ *
+ * The function does **not** create parent directories — callers (e.g.
+ * `create_file`) decide whether missing parents are an error.
+ *
+ * @throws Standard `fs` errors. Sandbox authorization is the caller's
+ *   responsibility; this helper assumes `absolutePath` is already permitted.
+ */
+export declare function writeAtomic(absolutePath: string, content: string | Uint8Array, options?: WriteAtomicOptions): Promise<void>;

package/dist/tools/io/audit-sink.d.ts

@@ -0,0 +1,29 @@
+import type { AuditSink } from "./audit.types";
+/**
+ * In-memory audit sink. Used for tests and as a fallback when no
+ * `sessionId` is available on the `ToolContext`.
+ *
+ * `list()` returns a defensive copy so callers cannot mutate the
+ * internal buffer.
+ */
+export declare function createMemoryAuditSink(): AuditSink;
+/**
+ * Options for {@link createFileAuditSink}.
+ */
+export interface FileAuditSinkOptions {
+    /** Maximum number of bytes to keep per `diff` field. Longer diffs
+     *  are truncated with a `…(truncated)` marker so a single huge
+     *  rewrite doesn't bloat the log. Set to `Infinity` to disable. */
+    readonly maxDiffBytes?: number;
+}
+/**
+ * JSONL-backed audit sink under `<workspaceRoot>/.comma/audit/`.
+ *
+ * - One file per session: `<sessionId>.jsonl`.
+ * - Non-session entries (`sessionId` undefined) are routed to
+ *   `default.jsonl` so they survive across processes.
+ * - Each append: ensures the directory exists, writes the line,
+ *   then `fsync`s the file. We tolerate the extra syscalls because
+ *   audit volume is low (one per destructive op).
+ */
+export declare function createFileAuditSink(workspaceRoot: string, options?: FileAuditSinkOptions): AuditSink;

package/dist/tools/io/audit.types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The kind of destructive file operation an audit entry records.
+ *
+ * - `"create"` — file did not exist before (or was a move target with
+ *   no prior content).
+ * - `"update"` — file existed and was modified in place.
+ * - `"delete"` — file existed and was removed (or trashed).
+ * - `"move"`   — `path` is the source, `toPath` the destination.
+ *   `beforeSha256` is the source's pre-move hash; `afterSha256` is the
+ *   destination's hash (typically identical to `beforeSha256` for a
+ *   plain rename, but recorded explicitly to handle copy-then-delete
+ *   moves across filesystems).
+ */
+export type AuditOperation = "create" | "update" | "delete" | "move";
+/**
+ * One row in the audit log. Persisted as a single JSONL line.
+ *
+ * Fields are typed as `readonly` because audit entries are immutable
+ * once appended — replaying the log must produce identical state
+ * regardless of how many times it runs.
+ */
+export interface AuditEntry {
+    /** ISO-8601 timestamp (UTC) when the operation completed. */
+    readonly timestamp: string;
+    /**
+     * Session identifier from `ToolContext.sessionId`. Omitted for
+     * non-session callers (in-memory sink only).
+     */
+    readonly sessionId?: string;
+    /** Name of the agent that invoked the tool. */
+    readonly agentName: string;
+    /** Name of the tool that produced the mutation. */
+    readonly toolName: string;
+    /** Which kind of mutation this entry records. */
+    readonly operation: AuditOperation;
+    /**
+     * Workspace-relative path of the target. For `"move"`, this is the
+     * source path; for everything else, the affected file.
+     */
+    readonly path: string;
+    /** Destination path for `"move"` operations. Omitted otherwise. */
+    readonly toPath?: string;
+    /**
+     * SHA-256 of the file's content before the operation. Omitted for
+     * `"create"`. For `"delete"`, this is the hash at deletion time.
+     */
+    readonly beforeSha256?: string;
+    /**
+     * SHA-256 of the file's content after the operation. Omitted for
+     * `"delete"`. For `"create"` / `"update"` / `"move"`, this is the
+     * hash of the newly-written content.
+     */
+    readonly afterSha256?: string;
+    /**
+     * Unified diff in standard `diff -u` format. Optional — omitted for
+     * `"create"` (no prior content) and `"delete"` (no resulting content).
+     * Truncated by the sink if it exceeds the sink's configured limit.
+     */
+    readonly diff?: string;
+    /**
+     * `true` if the operation completed successfully. Failed operations
+     * are still recorded (for forensics and to keep replay deterministic)
+     * but their hash fields will reflect the pre-operation state.
+     */
+    readonly success: boolean;
+    /**
+     * Human-readable error message when `success` is false. Structured
+     * `ToolError` is *not* serialized — the message is enough for replay
+     * and the structured form is already on the `ToolResult`.
+     */
+    readonly error?: string;
+    /**
+     * Optional tool-specific metadata that doesn't fit the common fields.
+     * Examples: `{ trashedTo }` for `delete_file`, `{ overwrote: true }`
+     * for `move_file`, `{ atomic: true, hunkCount: 5 }` for `apply_patch`.
+     *
+     * Implementations must JSON-serialize this verbatim — keep it simple
+     * (strings, numbers, booleans, plain objects/arrays).
+     */
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Storage interface for audit entries.
+ *
+ * Implementations:
+ * - `createFileAuditSink(workspaceRoot)` — JSONL at
+ *   `<workspaceRoot>/.comma/audit/<sessionId>.jsonl`.
+ * - `createMemoryAuditSink()` — in-memory array, for tests and for
+ *   non-session callers.
+ *
+ * The sink is responsible for its own durability guarantees. File
+ * sinks fsync per-append; the in-memory sink simply pushes.
+ */
+export interface AuditSink {
+    /**
+     * Append a single entry. Resolves once the entry is durable (for
+     * file sinks) or stored (for the in-memory sink).
+     */
+    append(entry: AuditEntry): Promise<void>;
+    /**
+     * Return entries for `sessionId`, or all entries when `sessionId`
+     * is omitted. Order matches insertion order (oldest → newest).
+     *
+     * File sinks read from disk on every call — callers that need
+     * repeated access should cache the result.
+     */
+    list(sessionId?: string): Promise<readonly AuditEntry[]>;
+    /**
+     * Load a specific session's entries. Equivalent to
+     * `list(sessionId)` but signals intent ("hydrate this session")
+     * and may use a different code path for file sinks (e.g. open
+     * the specific JSONL file directly).
+     */
+    load(sessionId: string): Promise<readonly AuditEntry[]>;
+}

package/dist/tools/io/audit.utils.d.ts

@@ -0,0 +1,48 @@
+import type { ToolContext } from "../tool.types";
+import type { AuditEntry, AuditSink } from "./audit.types";
+/**
+ * Build a base audit entry with common fields from tool context.
+ *
+ * Extracts timestamp, sessionId, and agentName from the context, then
+ * merges in the operation-specific fields. The returned object is
+ * missing only the `success` field, which is added by the caller.
+ *
+ * @param context - Tool execution context containing sessionId and agentName
+ * @param toolName - Name of the tool performing the operation
+ * @param operation - Type of file operation (create, update, delete, move)
+ * @param path - Workspace-relative path of the affected file
+ * @param additionalFields - Operation-specific fields to merge into the entry
+ * @returns Base audit entry without the `success` field
+ *
+ * @example
+ * ```ts
+ * const base = buildAuditBase(context, "edit_file", "update", "src/foo.ts", {
+ *   beforeSha256: "abc...",
+ *   afterSha256: "def...",
+ *   diff: "--- a/src/foo.ts\n+++ b/src/foo.ts\n..."
+ * });
+ * await sink.append({ ...base, success: true });
+ * ```
+ */
+export declare function buildAuditBase(context: ToolContext, toolName: string, operation: AuditEntry["operation"], path: string, additionalFields?: Partial<Omit<AuditEntry, "timestamp" | "sessionId" | "agentName" | "toolName" | "operation" | "path" | "success">>): Omit<AuditEntry, "success">;
+/**
+ * Log a successful audit entry to the sink.
+ *
+ * No-op if sink is undefined. Swallows errors from the sink append
+ * operation since audit failures should not block the main operation.
+ *
+ * @param sink - Audit sink to write to (may be undefined)
+ * @param base - Base audit entry from `buildAuditBase`
+ */
+export declare function logAuditSuccess(sink: AuditSink | undefined, base: Omit<AuditEntry, "success">): Promise<void>;
+/**
+ * Log a failed audit entry to the sink.
+ *
+ * No-op if sink is undefined. Swallows errors from the sink append
+ * operation since audit failures should not block error handling.
+ *
+ * @param sink - Audit sink to write to (may be undefined)
+ * @param base - Base audit entry from `buildAuditBase`
+ * @param error - Human-readable error message
+ */
+export declare function logAuditFailure(sink: AuditSink | undefined, base: Omit<AuditEntry, "success">, error: string): Promise<void>;

package/dist/tools/io/binary.d.ts

@@ -0,0 +1,16 @@
+/** Sample size in bytes used for binary detection. */
+export declare const BINARY_DETECTION_SAMPLE_BYTES: number;
+/**
+ * Heuristically classify a buffer as binary by scanning the first
+ * `BINARY_DETECTION_SAMPLE_BYTES` bytes for a NUL byte.
+ *
+ * NUL bytes are vanishingly rare in legitimate text encodings
+ * (UTF-8, UTF-16 with BOM stripped, Latin-1) but ubiquitous in
+ * binary formats (images, compiled artefacts, archives). This matches
+ * the heuristic used by `git diff`, `grep`, and most editors.
+ *
+ * False positives (text files containing NUL) and false negatives
+ * (binary files with no NUL in the first 8 KiB) are tolerated by
+ * design — the opt-in flow lets the LLM override.
+ */
+export declare function isLikelyBinary(buffer: Uint8Array): boolean;

package/dist/tools/io/bom.d.ts

@@ -0,0 +1,15 @@
+/** The UTF-8 BOM as a string. */
+export declare const BOM = "\uFEFF";
+/**
+ * `true` if `content` starts with the UTF-8 BOM.
+ */
+export declare function hasBom(content: string): boolean;
+/**
+ * Return `content` with a leading BOM removed (if present).
+ */
+export declare function stripBom(content: string): string;
+/**
+ * Return `content` with the BOM re-applied if `hadBom` is true. Idempotent —
+ * does not double-prefix when `content` already starts with `\uFEFF`.
+ */
+export declare function applyBom(content: string, hadBom: boolean): string;

package/dist/tools/io/diff.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Options for {@link unifiedDiff}.
+ */
+export interface UnifiedDiffOptions {
+    /**
+     * Path label used for both the `---` and `+++` headers in the diff.
+     * Tools pass the workspace-relative path so the diff is portable.
+     */
+    readonly path: string;
+    /**
+     * Number of unchanged context lines on each side of a hunk.
+     * @default 3
+     */
+    readonly contextLines?: number;
+}
+/**
+ * Produce a unified diff (`diff -u` format) describing the transformation
+ * from `before` to `after`.
+ *
+ * The output is suitable for:
+ * - logging in audit entries,
+ * - showing the LLM a confirmation of the edit it just made,
+ * - feeding into review UIs.
+ *
+ * Returns an empty string when the inputs are byte-identical.
+ */
+export declare function unifiedDiff(before: string, after: string, options: UnifiedDiffOptions): string;

package/dist/tools/io/hash.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Compute the SHA-256 of an arbitrary buffer / string. Synchronous —
+ * intended for in-memory content that has already been read.
+ *
+ * @param data - The bytes (or UTF-8 string) to hash.
+ * @returns Lowercase hex-encoded SHA-256 digest (64 chars).
+ *
+ * @example
+ * ```ts
+ * sha256OfBuffer("hello") // "2cf24dba..."
+ * ```
+ */
+export declare function sha256OfBuffer(data: string | Uint8Array | ArrayBuffer): string;
+/**
+ * Compute the SHA-256 of a file on disk.
+ *
+ * Streams the file into the hasher to avoid loading large files fully
+ * into memory.
+ *
+ * @param absolutePath - Absolute path to the file. The caller is
+ *   responsible for sandbox authorization.
+ * @throws Standard `fs.readFile` errors (`ENOENT`, `EACCES`, …); the
+ *   tool layer translates these into structured `ToolError`s.
+ */
+export declare function sha256OfFile(absolutePath: string): Promise<string>;

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

@@ -0,0 +1,19 @@
+export type { WriteAtomicOptions } from "./atomic-write";
+export { writeAtomic } from "./atomic-write";
+export type { AuditEntry, AuditOperation, AuditSink } from "./audit.types";
+export { buildAuditBase, logAuditFailure, logAuditSuccess, } from "./audit.utils";
+export type { FileAuditSinkOptions } from "./audit-sink";
+export { createFileAuditSink, createMemoryAuditSink } from "./audit-sink";
+export { BINARY_DETECTION_SAMPLE_BYTES, isLikelyBinary } from "./binary";
+export { applyBom, BOM, hasBom, stripBom } from "./bom";
+export type { UnifiedDiffOptions } from "./diff";
+export { unifiedDiff } from "./diff";
+export { sha256OfBuffer, sha256OfFile } from "./hash";
+export type { NewlineStyle } from "./newline";
+export { applyNewline, detectNewline, toLF } from "./newline";
+export { sandboxErrorToToolError } from "./sandbox-error";
+export type { SessionFileEntry, SessionFileState } from "./session-file-state";
+export { buildSessionFileState, verifySessionFileState, } from "./session-file-state";
+export { STALE_FILE_RECOVERY_HINT } from "./stale-file";
+export type { TrashEntry, TrashMetadata } from "./trash";
+export { clearTrash, listTrash, moveToTrash, restoreFromTrash, trashWorkspaceDir, } from "./trash";