stitchkit 0.93.0 → 0.94.1

package/dist/tools/cli/stream.d.ts

@@ -0,0 +1,93 @@
+/**
+ * One operation per line, and a batch that can be resumed.
+ *
+ * Every agent-facing CLI grows the same two commands, and the mechanics contain
+ * nothing about any product: read a line, run the operation, answer with the
+ * same id, do not let one bad line stop the stream — and for a batch, do not
+ * run again what already ran.
+ *
+ * They are factories rather than framework-owned command names. Reserving
+ * `jsonl` and `batch` would take two names out of a namespace that belongs to
+ * the consumer: an application that already has a `batch` command would either
+ * fail at startup or find its own command silently shadowed. So the consumer
+ * mounts these under whatever it calls them, exactly like its own commands.
+ */
+import { z } from 'zod';
+import type { CliInvocationResult, CliInvoker } from './invoke.js';
+/** One line's answer: the id it came with, plus what running it produced. */
+export interface CliStreamAnswer extends CliInvocationResult {
+    /** Correlation id, echoed from the line. */
+    id: string;
+    /** Present when this answer was replayed from a checkpoint rather than run. */
+    replayed?: true;
+}
+export interface CliStreamCommandConfig {
+    /** Command name — the consumer's namespace, not the framework's. */
+    name?: string;
+    description?: string;
+    /** The compiled surface to run against. */
+    invoker: CliInvoker | (() => Promise<CliInvoker>);
+    /**
+     * Where the lines come from. Default: `process.stdin`, **as they arrive**.
+     *
+     * This is the difference between a pipe and a conversation. The framework's
+     * ordinary stdin routing accumulates the whole stream and hands the command a
+     * string, which is right for `--prompt "$(cat file)"` and fatally wrong here:
+     * an agent that writes one line and waits for its answer would wait for its
+     * own EOF, which never comes. So the stream owns its input and answers each
+     * line as it is read.
+     */
+    readLines?: () => AsyncIterable<string>;
+}
+/**
+ * Lines from a byte stream, delivered as they arrive.
+ *
+ * Split on `\n` with a trailing `\r` dropped, so a producer on Windows is not a
+ * silent parse failure on every line. A final line with no newline is delivered
+ * at end of stream rather than discarded.
+ */
+export declare function readStdinLines(source?: AsyncIterable<Uint8Array | string>): AsyncIterable<string>;
+/**
+ * Run each line as it arrives, answering before reading the next.
+ *
+ * Sequential on purpose: the answers carry ids, so a consumer could correlate
+ * out-of-order ones — but a stream that runs ahead of its answers removes the
+ * one form of backpressure an agent has, which is not answering yet.
+ */
+export declare function runCliStream(invoker: CliInvoker, lines: AsyncIterable<string>, onAnswer: (answer: CliStreamAnswer) => void, hooks?: CliStreamHooks): Promise<void>;
+/** What a caller decides per line, without owning the loop that reads them. */
+export interface CliStreamHooks {
+    /** Answer this line without running it — a replay, or a refusal. */
+    before?: (id: string, line: {
+        command: string;
+        args: Record<string, unknown>;
+    }) => CliStreamAnswer | undefined;
+    /** Observe what running it produced, before the answer is written. */
+    after?: (id: string, line: {
+        command: string;
+        args: Record<string, unknown>;
+    }, outcome: CliInvocationResult) => void;
+}
+/**
+ * A stream command the consumer mounts under its own name.
+ *
+ * Answers go to stdout one JSON object per line; nothing else does, so a script
+ * can read stdout as data while diagnostics stay on stderr.
+ */
+export declare function defineCliStreamCommand(config: CliStreamCommandConfig): import("./command.js").CliCommandDefinitionWithoutOutput<z.ZodObject<{}, z.core.$strip>>;
+export interface CliBatchCommandConfig extends CliStreamCommandConfig {
+    /** Where the checkpoint lives. Relative paths resolve against the process cwd. */
+    checkpointPath?: string;
+}
+/**
+ * A resumable batch.
+ *
+ * The checkpoint records, per line id, the digest of the line that produced the
+ * recorded answer. A re-run replays what already ran; a line whose CONTENT
+ * changed under the same id is refused rather than quietly re-run or quietly
+ * replayed, because both of those answer a question nobody asked.
+ */
+export declare function defineCliBatchCommand(config: CliBatchCommandConfig): import("./command.js").CliCommandDefinitionWithoutOutput<z.ZodObject<{
+    checkpoint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/tools/cli/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEhE,6EAA6E;AAC7E,MAAM,WAAW,eAAgB,SAAQ,mBAAmB;IAC1D,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,IAAI,CAAC;CACjB;AASD,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,OAAO,EAAE,UAAU,GAAG,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IAClD;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAuB,cAAc,CACnC,MAAM,GAAE,aAAa,CAAC,UAAU,GAAG,MAAM,CAAiB,GACzD,aAAa,CAAC,MAAM,CAAC,CAcvB;AAqCD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,UAAU,EACnB,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,EAC5B,QAAQ,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,EAC3C,KAAK,GAAE,cAAmB,GACzB,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,MAAM,CAAC,EAAE,CACP,EAAE,EAAE,MAAM,EACV,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,KACrD,eAAe,GAAG,SAAS,CAAC;IACjC,sEAAsE;IACtE,KAAK,CAAC,EAAE,CACN,EAAE,EAAE,MAAM,EACV,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EACxD,OAAO,EAAE,mBAAmB,KACzB,IAAI,CAAC;CACX;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,yFAcpE;AAED,MAAM,WAAW,qBAAsB,SAAQ,sBAAsB;IACnE,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB;;mBA+DlE"}

package/dist/tools/cli/update.d.ts

@@ -0,0 +1,145 @@
+import { type CliBuildAsset, type CliBuildManifest, type CliBuildTarget } from './manifest.js';
+import { type CliSignatureVerdict, type CliTrustRoot } from './signature.js';
+export interface CliUpdateCheckConfig {
+    manifestUrl: string;
+    currentVersion: string;
+    /** At most one network check per interval; default 24 h. */
+    intervalMs?: number;
+    /** When the last check happened, from the application's own state. */
+    lastCheckedAt?: number;
+    now?: number;
+    /** Header+body deadline for the check; default 2 s. */
+    timeoutMs?: number;
+    target?: CliBuildTarget;
+    allowPrivateHosts?: boolean;
+    /**
+     * Keys this build trusts. With none, nothing is enforced and the verdict says
+     * so out loud (`unenforced`) rather than leaving "checked" to be assumed.
+     */
+    trust?: CliTrustRoot;
+}
+/**
+ * Four answers, never three. "Could not ask" is not "up to date": collapsing
+ * them is how a tool goes quiet about its own staleness for months.
+ */
+export type CliUpdateCheck = {
+    status: 'skipped';
+    nextCheckAt: number;
+} | {
+    status: 'current';
+    version: string;
+    signature?: CliSignatureVerdict;
+} | {
+    status: 'outdated';
+    version: string;
+    manifest: CliBuildManifest;
+    asset?: CliBuildAsset;
+    /** What the signature check concluded — always present once it ran. */
+    signature?: CliSignatureVerdict;
+} | {
+    status: 'unknown';
+    reason: string;
+};
+/**
+ * Compare two versions, or refuse to. `undefined` means "these are not
+ * comparable", which the caller reports as unknown rather than guessing an
+ * order — an update prompt derived from a guess is worse than no prompt.
+ */
+export declare function compareCliVersions(left: string, right: string): number | undefined;
+/** Ask whether a newer build exists. Never throws; never blocks for long. */
+export declare function checkCliUpdate(config: CliUpdateCheckConfig): Promise<CliUpdateCheck>;
+export interface CliUpdateApplyConfig {
+    asset: CliBuildAsset;
+    /** The file to replace; defaults to the running executable. */
+    targetPath?: string;
+    timeoutMs?: number;
+    maxBytes?: number;
+    allowPrivateHosts?: boolean;
+    /**
+     * The document the asset came from, so authorship can be checked here too.
+     *
+     * `CliBuildAsset` cannot carry the proof: the signature covers the manifest's
+     * identity and every asset's digest together, which is what closes the chain
+     * on the file that executes. Passing both is what lets this refuse **before**
+     * it downloads anything.
+     */
+    manifest?: CliBuildManifest;
+    /** Keys this build trusts. With `manifest`, the pair is checked before the fetch. */
+    trust?: CliTrustRoot;
+    /**
+     * Keep the bytes being replaced, here, so there is something to go back to.
+     *
+     * Written after the new bytes are verified and before the target is replaced:
+     * a backup taken earlier could preserve a binary that was about to be
+     * replaced by a download that then failed its digest, and a backup taken
+     * later has nothing left to copy. The target's own mode is carried over — the
+     * point of a backup is to be runnable.
+     */
+    backupPath?: string;
+    /**
+     * Prove the new build starts before it replaces anything.
+     *
+     * The verified bytes are written beside the target as an executable
+     * candidate, and this runs with its path — a path rather than a command,
+     * because a JavaScript bundle is started through its runtime
+     * (`bun <candidate> version`). It runs before the backup and the replacement:
+     * if it throws, or outlives `verifyTimeoutMs`, the candidate is removed, the
+     * target and any earlier backup are untouched, and the update is refused with
+     * the reason as its cause.
+     *
+     * Without it the digest proves the bytes are the ones published, not that
+     * they load. A build that does not load, installed by a daemon that updates
+     * itself, takes the updater down with it, and every machine is then repaired
+     * by hand.
+     */
+    verify?: (candidatePath: string, signal: AbortSignal) => void | Promise<void>;
+    /** How long `verify` may take, in milliseconds; its `signal` aborts at the deadline. Default 30 000. */
+    verifyTimeoutMs?: number;
+}
+export interface AppliedCliUpdate {
+    path: string;
+    bytes: number;
+    sha256: string;
+    /** Where the replaced bytes were kept, when a backup was asked for and there was one. */
+    backupPath?: string;
+    /** Digest of the replaced bytes — what `rollbackCliUpdate` expects to find. */
+    backupSha256?: string;
+}
+/**
+ * Download, verify and replace the binary.
+ *
+ * The digest is taken over the decompressed bytes — the file that will be
+ * executed — and the last step is a rename inside the target's own directory,
+ * so the executable on the PATH is either the old one or the new one and never
+ * a partial write.
+ */
+export declare function applyCliUpdate(config: CliUpdateApplyConfig): Promise<AppliedCliUpdate>;
+export interface CliRollbackConfig {
+    /** The file to restore onto; defaults to the running executable. */
+    targetPath?: string;
+    /** The copy kept by a previous `applyCliUpdate({ backupPath })`. */
+    backupPath: string;
+    /**
+     * The digest the backup must have — `backupSha256` from that update.
+     *
+     * Required, not optional. A rollback that installs whatever happens to be at
+     * the backup path is a second install of an unverified binary, and the moment
+     * it is used is the moment nobody is in a position to check.
+     */
+    expectedSha256: string;
+}
+export interface RolledBackCliUpdate {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+/**
+ * Put the previous build back.
+ *
+ * Rolling back is a property of updating, not of the application: the same
+ * attention to atomicity and file mode the replacement gets, applied in the
+ * other direction. The digest is checked first, so a corrupted or swapped
+ * backup is a refusal rather than an unbootable tool.
+ */
+export declare function rollbackCliUpdate(config: CliRollbackConfig): RolledBackCliUpdate;
+//# sourceMappingURL=update.d.ts.map

package/dist/tools/cli/update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/update.ts"],"names":[],"mappings":"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"}

package/dist/tools/cli/view.d.ts

@@ -0,0 +1,12 @@
+import type { CliResultView } from './args-view.js';
+/** What a view produces: a JSON value, or the one human-facing shape. */
+export type CliViewOutput = {
+    kind: 'json';
+    data: unknown;
+} | {
+    kind: 'text';
+    text: string;
+};
+/** Compute the requested view, or refuse it with a message naming the field. */
+export declare function renderCliView(data: unknown, view: CliResultView): CliViewOutput;
+//# sourceMappingURL=view.d.ts.map

package/dist/tools/cli/view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/view.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAwK7F,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,GAAG,aAAa,CA+B/E"}

package/dist/tools/cli/wait.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `--wait` polling — block on an async tool result until it reaches a terminal
+ * state. The headline CLI feature (a `Bash(run_in_background)` generation that
+ * notifies when done), kept strictly generic per ADR 0002: the core knows
+ * nothing about generations or statuses. The consumer supplies how to read the
+ * poll target from the first result (`poll`), which tool to re-call (`tool`)
+ * and when it is done (`done`).
+ */
+import type { ToolResult } from '../execute-result.js';
+export interface CliWaitConfig {
+    /**
+     * Extract the poll-tool arguments from the initial result (e.g. `{ id }` from
+     * a `generate` response). Return `null` when there is nothing to wait on.
+     */
+    poll: (result: unknown) => Record<string, unknown> | null;
+    /** The tool/command name to call on each poll tick (e.g. `get_generation`). */
+    tool: string;
+    /** Done when this returns `true` for a poll result. */
+    done: (result: unknown) => boolean;
+    /**
+     * Terminal domain failure. A `true` result stops polling and turns the
+     * otherwise-successful tool payload into a `WAIT_FAILED` CLI failure. Checked
+     * before `done`, including for the initial result, so contradictory
+     * predicates fail closed.
+     */
+    failed?: (result: unknown) => boolean;
+    /** Backoff schedule in seconds; the last entry repeats. Default `[2,3,5,5,8,10]`. */
+    backoff?: number[];
+    /** Max seconds before giving up. Default `600`. */
+    timeout?: number;
+}
+export interface PollParams {
+    /** The result of the initial (non-poll) call. */
+    initial: ToolResult;
+    wait: CliWaitConfig;
+    /** Run a tool by name — the CLI binds this to its tool map + runner. */
+    call: (toolName: string, args: Record<string, unknown>) => Promise<ToolResult>;
+    /** Override `wait.timeout` (from `--wait-timeout`). */
+    timeoutSec?: number;
+    /** Progress callback — the CLI logs ticks to stderr unless `--quiet`. */
+    onTick?: (attempt: number, elapsedSec: number) => void;
+    /** Injectable sleep for tests. */
+    sleepFn?: (ms: number) => Promise<void>;
+    /** Explicit caller cancellation. Process SIGINT wiring remains application-owned. */
+    signal?: AbortSignal;
+}
+/**
+ * Poll `wait.tool` until `wait.done` or the timeout. Returns the last poll
+ * result; returns the initial result untouched when the initial call failed,
+ * already satisfies `done`, or yields no poll target. A terminal result matched
+ * by `failed` produces `WAIT_FAILED`; a timeout produces `TIMEOUT`.
+ */
+export declare function pollUntilDone(params: PollParams): Promise<ToolResult>;
+//# sourceMappingURL=wait.d.ts.map

package/dist/tools/cli/wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1D,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACnC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACtC,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAeD,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,wEAAwE;IACxE,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/E,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACvD,kCAAkC;IAClC,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,qFAAqF;IACrF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAuC3E"}

package/dist/tools/connections/runtime.d.ts

@@ -1,5 +1,5 @@
 import { type ZodObject } from 'zod';
-import type { RuntimeContext } from '../../contract/index.js';
+import type { RuntimeContext } from '../../contract/runtime-context.js';
 import type { RuntimeToolDefinition } from '../runtime-tool.js';
 /** A connection's optional principal-scoped credential resolver. */
 export type ConnectionTokenProvider = (context?: RuntimeContext) => string | undefined | Promise<string | undefined>;

package/dist/tools/connections/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAK,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG7D,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,CAAC,EAAE,cAAc,KACrB,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtD,UAAU,cAAc;IACtB,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,MAAM,EAAE;IACN,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,EACD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,SAAS,CAKX;AAcD,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAElF,6EAA6E;AAC7E,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAIhF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EACzC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACjC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,qBAAqB,EAC/C,SAAS,EAAE,0BAA0B,GACpC,qBAAqB,EAAE,CAczB"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAK,MAAM,KAAK,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAErE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG7D,oEAAoE;AACpE,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,CAAC,EAAE,cAAc,KACrB,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtD,UAAU,cAAc;IACtB,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,MAAM,EAAE;IACN,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,EACD,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9C,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,SAAS,CAKX;AAcD,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAElF,6EAA6E;AAC7E,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAIhF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EACzC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EACjC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,qBAAqB,EAC/C,SAAS,EAAE,0BAA0B,GACpC,qBAAqB,EAAE,CAczB"}

package/dist/tools/connections/types.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeToolTransport } from '../runtime-tool.js';
+import type { ToolTransport } from '../../contract/define.js';
 import type { ConnectionTokenProvider, ConnectionToolSkipReporter } from './runtime.js';
 /** Where one external MCP server lives, plus static request headers. */
 export interface McpConnectionTransport {
@@ -31,7 +31,7 @@ export interface McpClientConnectionConfig {
      * connection without it contributes nothing to the CLI, because CLI exposure
      * is explicit everywhere else in the framework too.
      */
-    transports?: readonly RuntimeToolTransport[];
+    transports?: readonly ToolTransport[];
 }
 /** A defined MCP connection. */
 export interface McpClientConnection extends McpClientConnectionConfig {
@@ -50,7 +50,7 @@ export interface OpenApiConnectionConfig {
     /** Response body ceiling in bytes; defaults to 1 MiB. */
     maxResponseBytes?: number;
     /** Which surfaces every mounted operation appears on; default MCP and AGENT. */
-    transports?: readonly RuntimeToolTransport[];
+    transports?: readonly ToolTransport[];
 }
 /** A defined OpenAPI connection. */
 export interface OpenApiConnection extends OpenApiConnectionConfig {

package/dist/tools/connections/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAErF,wEAAwE;AACxE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,sBAAsB,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC9C;AAED,gCAAgC;AAChC,MAAM,WAAW,mBAAoB,SAAQ,yBAAyB;IACpE,IAAI,EAAE,KAAK,CAAC;CACb;AAED,kFAAkF;AAClF,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,UAAU,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC9C;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAkB,SAAQ,uBAAuB;IAChE,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAE3E,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,0BAA0B,CAAC;CAC5C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tools/connections/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,uBAAuB,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAErF,wEAAwE;AACxE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,sBAAsB,CAAC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACvC;AAED,gCAAgC;AAChC,MAAM,WAAW,mBAAoB,SAAQ,yBAAyB;IACpE,IAAI,EAAE,KAAK,CAAC;CACb;AAED,kFAAkF;AAClF,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;CACvC;AAED,oCAAoC;AACpC,MAAM,WAAW,iBAAkB,SAAQ,uBAAuB;IAChE,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,MAAM,oBAAoB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC;AAE3E,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,0BAA0B,CAAC;CAC5C"}

package/dist/tools/durability-context.d.ts

@@ -1,4 +1,4 @@
-import type { LocalStepDurability } from '../agent-runtime/durability-contract.js';
+import type { LocalStepDurability } from '../durability/contract.js';
 type Factory = (callId: string, signal?: AbortSignal) => LocalStepDurability;
 /** Opaque SDK context; no credentials, functions or runtime objects enter provider messages. */
 export declare function createToolDurabilityContext(factory: Factory): object;

package/dist/tools/durability-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durability-context.d.ts","sourceRoot":"","sources":["../../src/tools/durability-context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAEhF,KAAK,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,mBAAmB,CAAC;AAG7E,gGAAgG;AAChG,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAIpE;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,mBAAmB,GAAG,SAAS,CAGjC"}
+{"version":3,"file":"durability-context.d.ts","sourceRoot":"","sources":["../../src/tools/durability-context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE,KAAK,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,mBAAmB,CAAC;AAG7E,gGAAgG;AAChG,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAIpE;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,mBAAmB,GAAG,SAAS,CAGjC"}

package/dist/tools/execute-args.d.ts

@@ -0,0 +1,23 @@
+import type { ToolExecutionOptions, ToolOperation } from './execute.js';
+/** What one tool call's arguments parse to — or why they did not. */
+export type ParsedToolCallArguments = {
+    ok: true;
+    params: unknown;
+    input: unknown;
+} | {
+    ok: false;
+    message: string;
+    thrown?: unknown;
+};
+/**
+ * Split and validate a flat tool-argument object exactly as a call does.
+ *
+ * Exported so the ONE thing that needs the parsed value without running the
+ * call — an elicitation resolver choosing this call's questions — gets the same
+ * value the handler will get, rather than a second parse written beside this
+ * one that drifts on the next coercion change. It is pure: no lifecycle, no
+ * hooks, no audit row, so asking what the arguments mean costs nothing that a
+ * gate would charge for.
+ */
+export declare function parseToolCallArguments(method: ToolOperation, callArgs: Record<string, unknown>, { coerceJson, toolSurface, }?: Pick<ToolExecutionOptions, 'coerceJson' | 'toolSurface'>): ParsedToolCallArguments;
+//# sourceMappingURL=execute-args.d.ts.map

package/dist/tools/execute-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-args.d.ts","sourceRoot":"","sources":["../../src/tools/execute-args.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAKrE,qEAAqE;AACrE,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAC7C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAErD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,EACE,UAAkB,EAClB,WAAmB,GACpB,GAAE,IAAI,CAAC,oBAAoB,EAAE,YAAY,GAAG,aAAa,CAAM,GAC/D,uBAAuB,CAsDzB"}

package/dist/tools/execute-hooks.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The hook vocabulary of a tool call: the context every hook is handed, the
+ * three per-call hooks (`beforeToolCall`, `afterToolCall`, `onToolError`), the
+ * error-hint policy, and the lifecycle gate a tool shares with HTTP.
+ */
+import type { TransportSource } from '../contract/define.js';
+import type { McpCallContext, RuntimeContext } from '../contract/runtime-context.js';
+import type { OperationIdentity } from '../server/types.js';
+import type { ToolResult } from './execute-result.js';
+export interface ToolCallContext {
+    source: TransportSource;
+    /** Validated metadata for an MCP call; absent on every other transport. */
+    mcp?: McpCallContext;
+    /**
+     * The provider's id for this tool call, on a surface that has one — today
+     * `mountAgent`, where it is the AI SDK's `toolCallId`.
+     *
+     * Without it a consumer running its own agent loop could see the outcome of a
+     * call through `afterToolCall` and had no way to say WHICH call it belonged
+     * to, so it reconstructed the answer from the serialised error text instead.
+     * That reconstruction is the defect: it is written once per consumer and
+     * disagrees silently.
+     */
+    toolCallId?: string;
+    [key: string]: unknown;
+}
+export interface BeforeToolCallOptions {
+    toolName: string;
+    args: Record<string, unknown>;
+    context: ToolCallContext;
+    endpoint: OperationIdentity;
+}
+export interface AfterToolCallOptions extends BeforeToolCallOptions {
+    result: ToolResult;
+    durationMs: number;
+    /** The value as thrown; absent for failures that did not throw. */
+    error?: unknown;
+    /**
+     * The arguments the call actually ran on, when `beforeToolCall` replaced
+     * them. Absent when nothing rewrote them — so `args` alone stays the honest
+     * record of what the caller sent, and a rewrite is visible as a rewrite
+     * rather than by overwriting the evidence.
+     */
+    effectiveArgs?: Record<string, unknown>;
+}
+export interface ToolErrorOptions {
+    toolName: string;
+    error: unknown;
+    context: ToolCallContext;
+    endpoint: OperationIdentity;
+}
+export interface ToolCallHooks {
+    /**
+     * Before the arguments are validated — and the one place they can still be
+     * changed.
+     *
+     * Returning a record replaces the arguments for this call; returning
+     * `undefined`, `null` or nothing leaves them exactly as they arrived. The
+     * replacement is validated by the contract schema like any other input, so
+     * this is a way to shape a call, never a way around the schema: a hook that
+     * returns something the schema refuses produces an ordinary
+     * `VALIDATION_ERROR`.
+     *
+     * This exists because the pipeline was asymmetric. `lifecycle.afterHandle`
+     * could already transform the OUTPUT, while the only way to affect the input
+     * was to throw — so a caller wanting to expand a reference into a value
+     * before validation had nowhere to stand: this hook sees the raw arguments
+     * and could not change them, and `lifecycle.beforeHandle` runs after the
+     * schemas have already refused.
+     *
+     * The audit trail is unaffected: `afterToolCall` still reports `args` as they
+     * arrived from the caller, and reports the replacement separately as
+     * `effectiveArgs`.
+     *
+     * Typed `unknown` for the same reason `lifecycle.afterHandle` is — the twin
+     * this mirrors. Every hook written against the old `void` signature still
+     * assigns, which is the whole compatibility claim, and a narrower union here
+     * would break exactly the hooks that exist today. What the value must BE is
+     * enforced where it is used, not where it is declared: anything that is not a
+     * record, `null` or `undefined` is refused by name at the call.
+     */
+    beforeToolCall?: (options: BeforeToolCallOptions) => unknown | Promise<unknown>;
+    /**
+     * Every finished call, success and failure alike — the record of the call.
+     *
+     * `error` is the value **as thrown**, present only when the call failed by
+     * throwing (never for an argument-validation failure, an output-schema
+     * mismatch or a `beforeToolCall` rejection — those never had a raw value).
+     * It is the same value `onToolError` receives, handed here too so a single
+     * hook can build one row that names the cause: the `result` alone cannot,
+     * because an unexpected throw is scrubbed to a bare `INTERNAL_SERVER_ERROR`.
+     */
+    afterToolCall?: (options: AfterToolCallOptions) => void | Promise<void>;
+    /**
+     * The tool execution path threw — the value **as thrown**, before it is normalised
+     * into a `ToolResult`. The tool-side answer to HTTP's `hooks.onError`, and the
+     * only place the real cause of an unexpected failure is reachable: an error
+     * that is not an `AppError` is scrubbed to a bare `INTERNAL_SERVER_ERROR` with
+     * no details, so by the time `afterToolCall` sees the result, the stack, the
+     * `cause` chain and the message are gone.
+     *
+     * Fires for a throw from executable input parsing (`ToolExtend`, params or
+     * input), extension resolution, `lifecycle.beforeHandle`, the handler, or
+     * `lifecycle.afterHandle` — every span where the raw cause would otherwise be
+     * destroyed. It does **not** fire for a normal validation result, a
+     * `beforeToolCall` rejection or an output-schema mismatch: each is already
+     * described in full by the `ToolResult` that `afterToolCall` receives.
+     *
+     * This is observation, not an error handler — the tool envelope is always
+     * `toolResultFromError`, so the return value is ignored and a throw from the
+     * hook itself is reported and swallowed rather than replacing the failure it
+     * was called to observe. Awaited before `afterToolCall`, so anything the hook
+     * records (a request-context error, say) is already in place when the audit
+     * hook reads it.
+     */
+    onToolError?: (options: ToolErrorOptions) => void | Promise<void>;
+}
+/**
+ * A per-tool hint appended to a failed tool result — given the tool name and the
+ * error code, return extra guidance for the model (or `null` for none). Shared
+ * by every tool mount (`mountMcp` / `mountAgent` / `createCli`), so a project
+ * writes one recovery-hint policy and it reaches all three transports.
+ */
+export type ErrorHintFn = (toolName: string, errorCode: string) => string | null;
+/**
+ * The tool-side twin of the HTTP server's `beforeHandle` / `afterHandle`. A
+ * tool call runs the same handler an HTTP request would — `ToolLifecycle` makes
+ * it run the same gate. Pass a `createAuthHook` result as `beforeHandle` here
+ * and tools are scope-guarded exactly as HTTP routes are; without it a tool
+ * call bypasses the auth a `createServer` `beforeHandle` enforces.
+ *
+ * Structurally a subset of `LifecycleHooks` — the same hook object used for
+ * `createServer({ hooks })` is assignable here.
+ *
+ * There is deliberately no `onError` twin: `LifecycleHooks.onError` returns a
+ * `Response`, which the tool path has no use for, and narrowing the return type
+ * here would break the assignability above. Observing a thrown tool error is
+ * `ToolCallHooks.onToolError`.
+ */
+export interface ToolLifecycle {
+    /** Auth / scope gate — throw to reject the call. */
+    beforeHandle?: (ctx: RuntimeContext, endpoint: OperationIdentity) => void | Promise<void>;
+    /** Transform the handler result before it is returned. */
+    afterHandle?: (ctx: RuntimeContext, result: unknown, endpoint: OperationIdentity) => unknown | Promise<unknown>;
+}
+//# sourceMappingURL=execute-hooks.d.ts.map

package/dist/tools/execute-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-hooks.d.ts","sourceRoot":"","sources":["../../src/tools/execute-hooks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAqB,SAAQ,qBAAqB;IACjE,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,eAAe,CAAC;IACzB,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChF;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAEjF;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1F,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,iBAAiB,KACxB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC"}

package/dist/tools/execute-result.d.ts

@@ -0,0 +1,40 @@
+/**
+ * What a tool call answers — success with data, or a canonical failure — and
+ * the one place a thrown value becomes that failure. The normalized error and
+ * the raw cause ride beside a failure in-process, never inside it.
+ */
+import { AppError } from '../contract/errors.js';
+export type ToolResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    code: string;
+    details?: unknown;
+    hint?: string;
+    /**
+     * A declared retry class, carried so it survives a process hop.
+     *
+     * The normalized `AppError` lives in a `WeakMap` keyed by the result
+     * object, which a serialized failure crossing MCP or the CLI cannot take
+     * with it — `toolErrorFromResult` rebuilds from `{code, details, hint}`
+     * and resolves the status from the code. A declaration that contradicts
+     * its status class would be lost exactly there, which is the failure
+     * already recorded for coding-tool refusals.
+     */
+    retryable?: boolean;
+};
+export type ToolFailure = Extract<ToolResult, {
+    ok: false;
+}>;
+/**
+ * Normalise any thrown value into a failed `ToolResult` — the one place an
+ * `AppError` becomes a tool error. Shared by `executeToolMethod` and both
+ * transport mounts so every tool error has one shape.
+ */
+export declare function toolResultFromError(err: unknown): ToolFailure;
+/** Recover the normalized AppError behind one canonical failed tool result. */
+export declare function toolErrorFromResult(result: ToolFailure): AppError;
+/** Original in-process failure; never part of the serialized tool envelope. */
+export declare function toolCauseFromResult(result: ToolFailure): unknown;
+//# sourceMappingURL=execute-result.d.ts.map

package/dist/tools/execute-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute-result.d.ts","sourceRoot":"","sources":["../../src/tools/execute-result.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,QAAQ,EAIT,MAAM,oBAAoB,CAAC;AAI5B,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3B;IACE,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEN,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAa7D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAkB7D;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,CAgBjE;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAEhE"}