indusagi 0.12.32 → 0.12.34

package/dist/types/capabilities/backends/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The Node-backed backends — public surface.
+ *
+ * One import site for the concrete {@link Fs}/{@link Shell} pair and the
+ * {@link ToolContext} assembler that the runtime and the test suite use to run
+ * tools against the real machine. Everything here is the single sanctioned
+ * place where the kernel's abstract capabilities touch `node:fs` and
+ * `node:child_process`.
+ */
+export { nodeFs, nodeShell, makeNodeContext } from "./node-backends";

package/dist/types/capabilities/backends/node-backends.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The Node-backed seam.
+ *
+ * The kernel deliberately hands tools only two abstract capabilities — {@link Fs}
+ * and {@link Shell} — and forbids any tool from reaching for `node:fs` or
+ * `node:child_process` on its own. This module is the single sanctioned place
+ * where those abstractions are bound to the real operating system. Everything
+ * here talks to Node directly *on purpose*; nothing above this layer does.
+ *
+ * Three things are exported: {@link nodeFs}, a filesystem backed by
+ * `node:fs/promises`; {@link nodeShell}, a command runner backed by
+ * `node:child_process`; and {@link makeNodeContext}, which staples those two
+ * onto a working directory, a cancellation signal, and an output budget to
+ * produce the {@link ToolContext} that tests and the live runtime feed to tools.
+ */
+import type { Fs, Shell, ToolContext, OutputBudget } from "../kernel";
+/** The shared Node-backed {@link Fs} instance. */
+export declare const nodeFs: Fs;
+/** The shared Node-backed {@link Shell} instance. */
+export declare const nodeShell: Shell;
+/**
+ * Assemble a {@link ToolContext} backed by the real Node filesystem and shell.
+ *
+ * This is the production wiring as well as the default test seam: a `cwd` is
+ * required, while the cancellation `signal` and output `budget` fall back to a
+ * never-aborting signal and the kernel's standard window when omitted.
+ */
+export declare function makeNodeContext(cwd: string, signal?: AbortSignal, budget?: OutputBudget): ToolContext;

package/dist/types/capabilities/capabilities.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Golden tests for the assembled capabilities layer.
+ *
+ * Every case runs against a real on-disk sandbox under {@link os.tmpdir} and the
+ * genuine Node-backed {@link makeNodeContext}, so the tools exercise their real
+ * filesystem and shell paths rather than stubs. The web tools are checked for
+ * their *offline* contract: they must surface a typed `isError` result instead
+ * of throwing when the network is unreachable.
+ *
+ * The suite also pins the registry/toolbox wiring: the `coding` collection must
+ * advertise exactly its members, and the runner must dispatch a call to the
+ * right tool by name (and reject an unknown name as an error, not a throw).
+ */
+export {};

package/dist/types/capabilities/files/diff.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A from-scratch line diff and unified-style renderer.
+ *
+ * The core is Myers' O(ND) shortest-edit-script algorithm. Given two token
+ * sequences (here: the lines of two text blobs), it finds the minimum number of
+ * single-token insertions and deletions that turns the first into the second.
+ * We run the greedy forward sweep, snapshotting the search frontier at every
+ * edit depth, then walk those snapshots backward to recover the actual ordered
+ * list of operations. From that list we group consecutive changes into
+ * "hunks" and print them in the familiar `@@ … @@` / `+` / `-` / ` ` shape.
+ *
+ * Nothing here touches the filesystem or any external diff utility — it is a
+ * self-contained string-to-string transformation, derived directly from the
+ * published algorithm rather than adapted from any existing implementation.
+ */
+/** One step in an edit script: a line that stayed, was added, or was removed. */
+export type DiffOpKind = "keep" | "add" | "remove";
+/** A single line-level operation produced by the diff. */
+export interface DiffOp {
+    readonly kind: DiffOpKind;
+    /** The line text, with its trailing newline already stripped. */
+    readonly text: string;
+    /** 1-based line number in the original blob (undefined for pure additions). */
+    readonly beforeLine?: number;
+    /** 1-based line number in the revised blob (undefined for pure removals). */
+    readonly afterLine?: number;
+}
+/** Outcome of {@link diffLines}: the flat op list plus a few useful tallies. */
+export interface LineDiff {
+    readonly ops: DiffOp[];
+    readonly added: number;
+    readonly removed: number;
+}
+/**
+ * Diff two text blobs at line granularity and return the full operation list.
+ *
+ * This is the public entry point used by tools that want structured change
+ * data; {@link renderUnifiedDiff} consumes the same data for display.
+ */
+export declare function diffLines(before: string, after: string): LineDiff;
+/**
+ * Render a line diff in the conventional unified format.
+ *
+ * Each hunk opens with an `@@ -beforeStart,beforeCount +afterStart,afterCount @@`
+ * header, followed by its lines prefixed with ` `, `-`, or `+`. When the two
+ * blobs are identical the result is the empty string. `context` controls how
+ * many unchanged lines frame each hunk (default 3).
+ */
+export declare function renderUnifiedDiff(before: string, after: string, context?: number): string;

package/dist/types/capabilities/files/edit.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The `edit` capability: substitute an exact (or whitespace-tolerant) snippet
+ * inside a file and report the change as a unified-style diff.
+ *
+ * The tool reads the target file through the kernel's {@link Fs} seam, locates
+ * the `oldText` to replace, swaps in `newText`, writes the result back, and
+ * hands the model a readable before/after diff produced by our own Myers-based
+ * {@link renderUnifiedDiff}. Matching is strict by default: the literal
+ * `oldText` must appear exactly once. If a literal match is missing we make a
+ * single whitespace-fuzzy attempt (ignoring differences in indentation and
+ * inter-token spacing) so trivial formatting drift doesn't block an otherwise
+ * unambiguous edit. Anything genuinely absent or ambiguous is refused with a
+ * specific message rather than guessed at.
+ */
+/**
+ * Public edit tool.
+ *
+ * Replaces a located snippet with new text inside a single file and returns a
+ * unified diff of the change.
+ */
+export declare const editTool: import("..").DefinedTool;

package/dist/types/capabilities/files/ls.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `ls` capability: enumerate the immediate contents of a directory.
+ *
+ * The directory's children are pulled through the {@link Fs} backend, and each
+ * one is `stat`-ed so the listing can report a concrete kind (file, directory,
+ * symlink, or other) and a byte size alongside its bare name. By default,
+ * dot-prefixed entries are hidden, matching the convention most shells follow;
+ * the caller can opt into seeing them. The rendered table is bounded by the
+ * context's {@link OutputBudget} so a very large folder cannot overrun the
+ * model's window.
+ *
+ * Authored entirely against the kernel surface — directory walking and metadata
+ * lookups go through `ctx.fs`, and trimming goes through `ctx.budget` / `clamp`.
+ * No Node API is reached for here.
+ */
+export declare const lsTool: import("..").DefinedTool;

package/dist/types/capabilities/files/read.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `read` capability: surface a text file's contents to the model.
+ *
+ * The file is loaded as UTF-8 through the {@link Fs} backend, optionally narrowed
+ * to a window of lines, and decorated with a left-hand line-number gutter so the
+ * model can refer to exact positions. Before the text is handed back it is run
+ * through the context's {@link OutputBudget} so an oversized file can never blow
+ * past the model's window; whenever that trimming actually fires, a short note is
+ * spliced in so the model knows it is looking at a partial view.
+ *
+ * Authored purely against the kernel surface — file access goes through
+ * `ctx.fs`, byte-bounding goes through `ctx.budget` / `clamp`. No Node API is
+ * touched here.
+ */
+export declare const readTool: import("..").DefinedTool;

package/dist/types/capabilities/files/write.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `write` capability: persist a text file through the kernel's filesystem
+ * seam, materializing any missing parent directories along the way.
+ *
+ * The tool is intentionally simple — it accepts a destination path and a body of
+ * UTF-8 text, ensures the enclosing folder exists, commits the bytes, and reports
+ * how many bytes landed on disk. All I/O flows through {@link ToolContext.fs};
+ * nothing reaches for `node:fs` directly, so a sandboxed or in-memory backend can
+ * stand in transparently.
+ */
+/**
+ * Write a text file, creating parent directories as needed.
+ *
+ * Exported as a named {@link DefinedTool} so a host can register it directly.
+ */
+export declare const writeTool: import("..").DefinedTool;

package/dist/types/capabilities/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The capabilities layer — public surface.
+ *
+ * One import site for everything a host needs to stand up the built-in tools:
+ * the kernel authoring shape and type vocabulary, every individual tool, the
+ * Node-backed context assembler, and the assembled registry/toolbox helpers.
+ *
+ * The two outward contracts — the runtime's `ToolCall`/`ToolOutcome`/`ToolBox`/
+ * `ToolRunner` and the gateway's `ToolDescriptor`/`JsonSchema` — are deliberately
+ * not re-exported here; consumers import those straight from their own contracts
+ * so there is a single source of truth.
+ */
+export { defineTool, clamp, ToolRegistry, UnknownToolError } from "./kernel";
+export type { ToolSpec, ToolResult, ToolContentBlock, TextContentBlock, JsonContentBlock, ToolContext, DefinedTool, Fs, FsEntryInfo, DirChild, RemoveOptions, Shell, ShellLaunchOptions, ShellExecOptions, ShellExecResult, ShellHandle, OutputBudget, ClipEnd, RegistryContextFactory, ContextOverrides, ContextFactory, } from "./kernel";
+export { nodeFs, nodeShell, makeNodeContext } from "./backends/node-backends";
+export { readTool } from "./files/read";
+export { writeTool } from "./files/write";
+export { editTool } from "./files/edit";
+export { lsTool } from "./files/ls";
+export { grepTool } from "./search/grep";
+export { findTool } from "./search/find";
+export { bashTool } from "./shell/bash";
+export { processTool, resetProcessTable } from "./shell/process";
+export { todoSetTool, todoReadTool, todoStore, TodoStore, reset as resetTodos, } from "./planning/todo";
+export type { TodoItem, TodoStatus } from "./planning/todo";
+export { webSearchTool } from "./web/websearch";
+export { webFetchTool } from "./web/webfetch";
+export { builtinRegistry, toolBox } from "./registry";
+export type { ToolCollection } from "./registry";

package/dist/types/capabilities/kernel/backends.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Coarse I/O backends a tool may reach for.
+ *
+ * Tools never touch `node:fs` or `node:child_process` directly. Instead they
+ * receive an {@link Fs} and a {@link Shell} through their {@link ToolContext},
+ * and every real-world side effect flows through one of those two seams. Keeping
+ * the surface intentionally small means a host can swap in a sandboxed, remote,
+ * or in-memory implementation without any tool being aware of it.
+ *
+ * Only the interfaces live here. The concrete Node-backed implementations are
+ * assembled in a later phase under `backends/`.
+ */
+/** Metadata about a single filesystem entry, as returned by {@link Fs.stat}. */
+export interface FsEntryInfo {
+    /** True when the entry is a regular file. */
+    readonly isFile: boolean;
+    /** True when the entry is a directory. */
+    readonly isDirectory: boolean;
+    /** True when the entry is a symbolic link. */
+    readonly isSymlink: boolean;
+    /** Size of the entry in bytes. */
+    readonly size: number;
+    /** Last-modified time, in epoch milliseconds. */
+    readonly modifiedMs: number;
+}
+/** One child of a directory, as yielded by {@link Fs.readdir}. */
+export interface DirChild {
+    /** The bare entry name (no leading path). */
+    readonly name: string;
+    /** True when this child is itself a directory. */
+    readonly isDirectory: boolean;
+}
+/** Options accepted by {@link Fs.rm}. */
+export interface RemoveOptions {
+    /** Remove directory trees, not just single files. Defaults to false. */
+    readonly recursive?: boolean;
+    /** Stay silent when the target is already absent. Defaults to false. */
+    readonly ignoreMissing?: boolean;
+}
+/**
+ * The filesystem capability handed to file-oriented tools.
+ *
+ * Paths are plain strings the caller has already resolved against the working
+ * directory; the backend does no path interpretation of its own. Text reads and
+ * writes go through {@link readFile} / {@link writeFile} with an explicit
+ * encoding, while raw bytes are exchanged as a `Uint8Array` when encoding is
+ * omitted.
+ */
+export interface Fs {
+    /** Load a file's contents. With an encoding, returns text; without, raw bytes. */
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    readFile(path: string): Promise<Uint8Array>;
+    /** Persist data to a file, creating it if absent and truncating if present. */
+    writeFile(path: string, data: string | Uint8Array, encoding?: BufferEncoding): Promise<void>;
+    /** Describe a single entry, following symlinks. Rejects when the path is absent. */
+    stat(path: string): Promise<FsEntryInfo>;
+    /** Enumerate the immediate children of a directory. */
+    readdir(path: string): Promise<DirChild[]>;
+    /** Create a directory, optionally building any missing parents. */
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Delete a file or directory subtree per {@link RemoveOptions}. */
+    rm(path: string, options?: RemoveOptions): Promise<void>;
+    /** Report whether anything exists at the given path. */
+    exists(path: string): Promise<boolean>;
+}
+/** Settings shared by both one-shot and long-lived shell launches. */
+export interface ShellLaunchOptions {
+    /** Working directory for the launched command. Defaults to the context cwd. */
+    readonly cwd?: string;
+    /** Environment overlay merged onto the inherited process environment. */
+    readonly env?: Record<string, string>;
+    /** Abort hook; firing it terminates the command. */
+    readonly signal?: AbortSignal;
+}
+/** Extra knobs for a blocking {@link Shell.exec}. */
+export interface ShellExecOptions extends ShellLaunchOptions {
+    /** Hard deadline in milliseconds after which the command is killed. */
+    readonly timeoutMs?: number;
+    /** Bytes piped to the command's standard input before it runs. */
+    readonly input?: string;
+}
+/** The settled result of a one-shot {@link Shell.exec}. */
+export interface ShellExecResult {
+    /** Everything the command emitted on standard output. */
+    readonly stdout: string;
+    /** Everything the command emitted on standard error. */
+    readonly stderr: string;
+    /** The process exit status; null when the command was signalled instead. */
+    readonly code: number | null;
+}
+/** A live handle to a process started via {@link Shell.spawn}. */
+export interface ShellHandle {
+    /** The operating-system process id, once assigned. */
+    readonly pid: number | undefined;
+    /** Request termination of the process (and, where supported, its group). */
+    kill(signal?: NodeJS.Signals): void;
+    /**
+     * Subscribe to the process finishing. The listener fires once with the exit
+     * code (or null on signal) and the signal name if one ended it. Returns an
+     * unsubscribe function.
+     */
+    onExit(listener: (code: number | null, signal: NodeJS.Signals | null) => void): () => void;
+}
+/**
+ * The shell capability handed to command-running tools.
+ *
+ * {@link exec} is the blocking path used by the bulk of tools: it runs a command
+ * to completion and resolves with its captured streams and status. {@link spawn}
+ * is the background path used by the daemon/process tool: it hands back a live
+ * {@link ShellHandle} the caller manages over time.
+ */
+export interface Shell {
+    /** Run a command to completion, capturing its output. */
+    exec(command: string, options?: ShellExecOptions): Promise<ShellExecResult>;
+    /** Start a long-lived command and return a handle to manage it. */
+    spawn(command: string, options?: ShellLaunchOptions): ShellHandle;
+}

package/dist/types/capabilities/kernel/context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Context assembly.
+ *
+ * Tools run inside a {@link ToolContext}: a working directory, the {@link Fs} and
+ * {@link Shell} backends, a cancellation signal, and a default
+ * {@link OutputBudget}. Production code builds that from real Node-backed
+ * backends; tests want to build it cheaply with only the fields a single case
+ * cares about.
+ *
+ * This module fixes the *shape* of that helper — {@link ContextOverrides} and the
+ * {@link ContextFactory} signature — so call sites can type against it now. The
+ * concrete {@link makeContext} body is wired up in the backends phase, once the
+ * Node {@link Fs}/{@link Shell} implementations exist to serve as the defaults.
+ */
+import type { Fs, Shell } from "./backends";
+import type { ToolContext } from "./spec";
+import type { OutputBudget } from "./output";
+/**
+ * A partial {@link ToolContext} supplied to {@link makeContext}.
+ *
+ * Any field left out is filled with a default: `cwd` falls back to the current
+ * working directory, `fs`/`shell` to the Node backends, `signal` to a
+ * never-aborting signal, and `budget` to the kernel's standard window.
+ */
+export interface ContextOverrides {
+    readonly cwd?: string;
+    readonly fs?: Fs;
+    readonly shell?: Shell;
+    readonly signal?: AbortSignal;
+    readonly budget?: OutputBudget;
+}
+/**
+ * Build a {@link ToolContext}, defaulting every field the caller omits.
+ *
+ * Intended chiefly as a test seam: a case overrides only the slice it exercises
+ * (say, a stub `fs`) and inherits sensible defaults for the rest. The real
+ * implementation arrives with the Node backends; this declaration pins the
+ * contract every call site can rely on.
+ */
+export type ContextFactory = (overrides?: ContextOverrides) => ToolContext;
+/**
+ * The {@link ContextFactory} the rest of the codebase imports.
+ *
+ * Declared here, defined in the backends phase. Until then it is intentionally
+ * unbound so any premature call fails loudly rather than silently producing a
+ * half-formed context.
+ */
+export declare const makeContext: ContextFactory;

package/dist/types/capabilities/kernel/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The frozen tool kernel — public surface.
+ *
+ * One import site for everything a built-in tool (or a host wiring tools in)
+ * needs: the declarative {@link ToolSpec} authoring shape and its
+ * {@link defineTool} adapter, the result/content/context vocabulary, the coarse
+ * {@link Fs}/{@link Shell} backends, the {@link OutputBudget} windowing with its
+ * {@link clamp} applier, the {@link ToolRegistry} and its collections, and the
+ * {@link makeContext} test helper.
+ *
+ * The outward contracts — the runtime's `ToolCall`/`ToolOutcome`/`ToolBox` and
+ * the gateway's `ToolDescriptor`/`JsonSchema` — are deliberately *not*
+ * re-exported here; consumers import those straight from "../../runtime/contract"
+ * and "../../llmgateway/contract" so there is a single source of truth.
+ */
+export { defineTool } from "./spec";
+export type { ToolSpec, ToolResult, ToolContentBlock, TextContentBlock, JsonContentBlock, ToolContext, DefinedTool, } from "./spec";
+export type { Fs, FsEntryInfo, DirChild, RemoveOptions, Shell, ShellLaunchOptions, ShellExecOptions, ShellExecResult, ShellHandle, } from "./backends";
+export { clamp } from "./output";
+export type { OutputBudget, ClipEnd } from "./output";
+export { ToolRegistry, UnknownToolError } from "./registry";
+export type { ContextFactory as RegistryContextFactory } from "./registry";
+export { makeContext } from "./context";
+export type { ContextOverrides, ContextFactory } from "./context";

package/dist/types/capabilities/kernel/output.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Output windowing.
+ *
+ * Tool output is fed to a model with a finite context, so a single tool must
+ * never return an unbounded blob. This module collapses what used to be two
+ * separate head/tail truncators into one {@link OutputBudget} description plus a
+ * single {@link clamp} applier. A budget says how big the surviving window may
+ * be (`maxBytes`), which end of the text to keep (`kind`), and optionally how to
+ * announce what was dropped (`notice`).
+ *
+ * All measurement is in UTF-8 bytes via {@link Buffer}, and every cut is snapped
+ * to a character boundary so a multibyte sequence is never sliced in half.
+ */
+/** Which slice of an over-budget string survives clamping. */
+export type ClipEnd = "head" | "tail" | "middle";
+/**
+ * A request to bound a string's UTF-8 byte length.
+ *
+ * `kind` selects which portion to keep:
+ *   - `head`   — keep the opening bytes, drop the tail.
+ *   - `tail`   — keep the closing bytes, drop the head.
+ *   - `middle` — drop a band from the center, keeping both ends.
+ *
+ * `maxBytes` is the ceiling for the *kept* text (the optional notice is appended
+ * on top and is not counted against it). `notice`, when given, is called with
+ * the number of omitted bytes and returns a marker spliced in at the cut point.
+ */
+export interface OutputBudget {
+    readonly kind: ClipEnd;
+    readonly maxBytes: number;
+    readonly notice?: (omitted: number) => string;
+}
+/**
+ * Bound `text` to `policy.maxBytes` UTF-8 bytes, keeping the end named by
+ * `policy.kind` and splicing in a notice where bytes were removed.
+ *
+ * When the input already fits, it is returned untouched and no notice is added.
+ * Cuts always fall on character boundaries, so the result is always valid UTF-8.
+ */
+export declare function clamp(text: string, policy: OutputBudget): string;

package/dist/types/capabilities/kernel/registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The tool registry.
+ *
+ * A {@link ToolRegistry} is the in-memory directory of every defined tool plus
+ * the named *collections* that group them (e.g. a read-only set vs. the full
+ * coding set). Its payoff method is {@link ToolRegistry.toToolBox}, which turns a
+ * chosen collection into a runtime {@link ToolBox}: the descriptors the model is
+ * shown together with a {@link ToolRunner} that dispatches the model's calls to
+ * the right tool's `invoke`.
+ *
+ * The registry stays decoupled from how a {@link ToolContext} is built: it asks
+ * for a `ctxFactory` at box-construction time and calls it per dispatch, so each
+ * tool run gets a fresh, correctly-scoped context.
+ */
+import type { ToolBox } from "../../runtime/contract";
+import type { DefinedTool, ToolContext } from "./spec";
+/** Thrown when a registry operation references a name that was never registered. */
+export declare class UnknownToolError extends Error {
+    /** The offending tool or collection name. */
+    readonly missing: string;
+    constructor(kind: "tool" | "collection", missing: string);
+}
+/** Supplies a fresh {@link ToolContext} for each individual tool dispatch. */
+export type ContextFactory = () => ToolContext;
+/**
+ * A mutable catalog of tools and the named collections over them.
+ *
+ * Register tools first, then describe collections by listing tool names. A
+ * collection is just a label for a subset; the same tool can belong to many.
+ */
+export declare class ToolRegistry {
+    private readonly tools;
+    private readonly collections;
+    /** Add a defined tool. A later registration under the same name replaces it. */
+    register(tool: DefinedTool): this;
+    /** Register several tools in one call. */
+    registerAll(tools: Iterable<DefinedTool>): this;
+    /** True when a tool with this name has been registered. */
+    has(name: string): boolean;
+    /** Fetch a registered tool, or throw {@link UnknownToolError} if absent. */
+    get(name: string): DefinedTool;
+    /** The names of every registered tool, in registration order. */
+    names(): string[];
+    /**
+     * Define (or redefine) a named collection as the given list of tool names.
+     * Every listed tool must already be registered.
+     */
+    collection(name: string, toolNames: readonly string[]): this;
+    /** The tool names belonging to a collection, or throw if it is undefined. */
+    membersOf(collectionName: string): string[];
+    /** The names of every defined collection. */
+    collectionNames(): string[];
+    /**
+     * Build a runtime {@link ToolBox} from a set of tools.
+     *
+     * Pass a collection name to box that collection, or omit it to box every
+     * registered tool. `ctxFactory` is invoked once per dispatched call to mint
+     * the {@link ToolContext} the chosen tool runs under.
+     */
+    toToolBox(ctxFactory: ContextFactory, collectionName?: string): ToolBox;
+}

package/dist/types/capabilities/kernel/spec.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The frozen tool kernel.
+ *
+ * Every built-in capability is authored as a declarative {@link ToolSpec}: a
+ * name, a model-facing description, a JSON-Schema parameter shape, and a single
+ * async `run`. The bespoke per-tool plumbing — advertising a descriptor to the
+ * model, coercing the model's raw arguments, running under cancellation, and
+ * shaping the result back into the runtime's tool boundary — is concentrated in
+ * one adapter, {@link defineTool}. A tool author writes only `run`; the kernel
+ * supplies the rest uniformly.
+ *
+ * The two outward contracts are imported, never redefined here: the runtime's
+ * {@link ToolCall} / {@link ToolOutcome} boundary and the gateway's
+ * {@link ToolDescriptor} / {@link JsonSchema} model-facing shape.
+ */
+import type { ToolCall, ToolOutcome } from "../../runtime/contract";
+import type { ToolDescriptor, JsonSchema } from "../../llmgateway/contract";
+import type { Fs, Shell } from "./backends";
+import type { OutputBudget } from "./output";
+/** A plain-text fragment a tool returns to the model. */
+export interface TextContentBlock {
+    readonly kind: "text";
+    readonly text: string;
+}
+/** A structured fragment a tool returns; serialized when handed to the model. */
+export interface JsonContentBlock {
+    readonly kind: "json";
+    readonly value: unknown;
+}
+/** One unit of a {@link ToolResult}: either prose or structured data. */
+export type ToolContentBlock = TextContentBlock | JsonContentBlock;
+/**
+ * The value a tool's `run` resolves to.
+ *
+ * `content` is the ordered set of fragments shown to the model. `isError`, when
+ * true, marks the whole result as a failure the model should be told about; the
+ * kernel propagates it onto the {@link ToolOutcome}.
+ */
+export interface ToolResult {
+    readonly content: ToolContentBlock[];
+    readonly isError?: boolean;
+}
+/**
+ * Everything a tool's `run` is handed besides its own parsed input.
+ *
+ * It carries the working directory, the two coarse I/O backends, a cancellation
+ * `signal`, and the default {@link OutputBudget} a tool should apply when its
+ * output risks overflowing the model's window.
+ */
+export interface ToolContext {
+    readonly cwd: string;
+    readonly fs: Fs;
+    readonly shell: Shell;
+    readonly signal: AbortSignal;
+    readonly budget: OutputBudget;
+}
+/**
+ * The declarative description of one tool.
+ *
+ * `I` is the input shape `run` expects after coercion. The kernel validates the
+ * raw call against `parameters` loosely (presence and basic typing) and hands a
+ * best-effort `I` to `run`; rigorous validation, where a tool wants it, lives in
+ * `run` itself.
+ */
+export interface ToolSpec<I = unknown> {
+    /** The name advertised to and invoked by the model. */
+    readonly name: string;
+    /** The model-facing description of what the tool does and when to use it. */
+    readonly description: string;
+    /** The JSON-Schema object describing the tool's parameters. */
+    readonly parameters: JsonSchema;
+    /** The tool's behavior; receives coerced input and the live context. */
+    run(input: I, ctx: ToolContext): Promise<ToolResult>;
+}
+/**
+ * A {@link ToolSpec} after {@link defineTool} has wrapped it.
+ *
+ * `descriptor()` yields the model-facing advertisement; `invoke()` is the
+ * runner-side entry point that turns a {@link ToolCall} into a
+ * {@link ToolOutcome}.
+ */
+export interface DefinedTool {
+    /** The tool's name (mirrors the spec, exposed for registry bookkeeping). */
+    readonly name: string;
+    /** The descriptor handed to the model on each invocation. */
+    descriptor(): ToolDescriptor;
+    /** Execute one call under the given context and normalize the result. */
+    invoke(call: ToolCall, ctx: ToolContext): Promise<ToolOutcome>;
+    /** Display label for the facade (mirrors the name). */
+    readonly label: string;
+    /** Top-level description for the facade's tool validation + the model schema. */
+    readonly description: string;
+    /** Top-level JSON-schema parameters for the facade's tool validation. */
+    readonly parameters: JsonSchema;
+    /** Facade execution entry point: run the tool and return facade-shaped content. */
+    execute(toolCallId: string, params: unknown, signal?: AbortSignal, onUpdate?: (partial: unknown) => void): Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: Record<string, unknown>;
+        isError: boolean;
+    }>;
+}
+/**
+ * Wrap a {@link ToolSpec} into a {@link DefinedTool}.
+ *
+ * The returned `invoke` coerces the call's input, honors an already-aborted
+ * signal up front, runs the spec, and folds both the success result and any
+ * thrown failure into a {@link ToolOutcome}. No spec ever has to write this
+ * boilerplate itself.
+ */
+export declare function defineTool<I = unknown>(spec: ToolSpec<I>): DefinedTool;