@rarebit-one/harness-kernel 0.7.0 → 0.8.0

package/dist/providers/anthropic.js

@@ -45,8 +45,31 @@ export function parseAnthropicContent(content) {
     }
     return { text, toolCalls };
 }
+/**
+ * Map an Anthropic `usage` block to the kernel's token accounting (pure; tested).
+ *
+ * Anthropic's `input_tokens` counts only UNCACHED input; cache reads and cache
+ * writes are reported separately. Total input is the sum of all three, so that
+ * is what `inputTokens` carries, with the cache split out alongside.
+ */
+export function anthropicUsage(usage) {
+    if (!usage)
+        return undefined;
+    const cacheRead = "cache_read_input_tokens" in usage ? (usage.cache_read_input_tokens ?? 0) : 0;
+    const cacheWrite = "cache_creation_input_tokens" in usage ? (usage.cache_creation_input_tokens ?? 0) : 0;
+    const inputTokens = usage.input_tokens + cacheRead + cacheWrite;
+    const outputTokens = usage.output_tokens;
+    return {
+        inputTokens,
+        outputTokens,
+        totalTokens: inputTokens + outputTokens,
+        ...(cacheRead > 0 ? { cacheReadTokens: cacheRead } : {}),
+        ...(cacheWrite > 0 ? { cacheWriteTokens: cacheWrite } : {}),
+    };
+}
 export class AnthropicProvider {
     name = "anthropic";
+    reportsUsage = true;
     client;
     model;
     constructor(apiKey, model = process.env.ANTHROPIC_MODEL ?? "claude-sonnet-4-6") {
@@ -72,7 +95,7 @@ export class AnthropicProvider {
             .map((block) => block.text)
             .join("\n");
     }
-    async converse(req) {
+    async converse(req, opts) {
         const message = await this.client.messages.create({
             model: this.model,
             max_tokens: maxTokens(),
@@ -83,8 +106,12 @@ export class AnthropicProvider {
                 input_schema: t.inputSchema,
             })),
             messages: toAnthropicMessages(req.messages),
-        });
-        return parseAnthropicContent(message.content);
+        }, 
+        // Per-request, so an abort cancels THIS call (retries included) and
+        // leaves the shared client untouched.
+        opts?.signal ? { signal: opts.signal } : undefined);
+        const usage = anthropicUsage(message.usage);
+        return { ...parseAnthropicContent(message.content), ...(usage ? { usage } : {}) };
     }
 }
 //# sourceMappingURL=anthropic.js.map

package/dist/providers/anthropic.js.map

@@ -1 +1 @@
-{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/providers/anthropic.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/providers/anthropic.ts"],"names":[],"mappings":"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"}

package/dist/providers/mock.d.ts

@@ -1,4 +1,4 @@
-import type { CompletionRequest, ConverseRequest, ConverseResult, Provider } from "./types.js";
+import type { CompletionRequest, ConverseOptions, ConverseRequest, ConverseResult, Provider } from "./types.js";
 import type { ProviderSelection } from "./index.js";
 /**
  * Deterministic, offline provider. Used when no API key is configured — or when a
@@ -20,6 +20,6 @@ export declare class MockProvider implements Provider {
     private byoKeyMarker;
     private selectionLines;
     complete(req: CompletionRequest): Promise<string>;
-    converse(req: ConverseRequest): Promise<ConverseResult>;
+    converse(req: ConverseRequest, opts?: ConverseOptions): Promise<ConverseResult>;
 }
 //# sourceMappingURL=mock.d.ts.map

package/dist/providers/mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/providers/mock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,QAAQ,CAAC,IAAI,UAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,SAAS,GAAE,iBAAsB;IAS7C,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,cAAc;IAWtB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAyB3C,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAS9D"}
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/providers/mock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,cAAc,EACd,QAAQ,EACT,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;;;;GAWG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,QAAQ,CAAC,IAAI,UAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;gBAEjC,SAAS,GAAE,iBAAsB;IAS7C,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,cAAc;IAWtB,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B3C,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAWtF"}

package/dist/providers/mock.js

@@ -72,13 +72,17 @@ export class MockProvider {
     }
     // The mock never calls tools, so the agent loop terminates after one turn. It
     // echoes which tools were available, which is handy when running offline.
-    async converse(req) {
+    // It honours `signal` the way a real adapter does: an aborted call rejects
+    // with the signal's reason instead of returning a turn.
+    async converse(req, opts) {
+        opts?.signal?.throwIfAborted();
         const lastUser = [...req.messages].reverse().find((m) => m.role === "user");
         const prompt = lastUser && lastUser.role === "user" ? lastUser.text : "";
         const text = await this.complete({
             system: `${req.system}\n\nAvailable tools: ${req.tools.map((t) => t.name).join(", ") || "(none)"}`,
             prompt,
         });
+        opts?.signal?.throwIfAborted();
         return { text, toolCalls: [] };
     }
 }

package/dist/providers/mock.js.map

@@ -1 +1 @@
-{"version":3,"file":"mock.js","sourceRoot":"","sources":["../../src/providers/mock.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mock.js","sourceRoot":"","sources":["../../src/providers/mock.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,YAAY;IACd,IAAI,GAAG,MAAM,CAAA;IACL,SAAS,CAAmB;IAE7C,YAAY,YAA+B,EAAE;QAC3C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;IAC5B,CAAC;IAED,6EAA6E;IAC7E,0DAA0D;IAC1D,sEAAsE;IACtE,+EAA+E;IAC/E,gFAAgF;IACxE,aAAa;QACnB,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,CAAA;QACpF,MAAM,QAAQ,GACZ,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAA;QACzF,IAAI,QAAQ;YAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAA;QACtE,OAAO,EAAE,KAAK,EAAE,6BAA6B,EAAE,MAAM,EAAE,2BAA2B,EAAE,CAAA;IACtF,CAAC;IAED,gFAAgF;IAChF,gFAAgF;IAChF,sCAAsC;IAC9B,YAAY;QAClB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,IAAI,EAAE,CAAA;QAC9C,MAAM,OAAO,GAAI,CAAC,WAAW,EAAE,QAAQ,EAAE,YAAY,CAAW;aAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;aACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QAC7C,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,uCAAuC,CAAA;IACtF,CAAC;IAED,gFAAgF;IACxE,cAAc;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,EAAE,CAAA;QAClC,OAAO;YACL,wCAAwC;YACxC,EAAE;YACF,UAAU,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,MAAM,kBAAkB;YACxD,gBAAgB,IAAI,CAAC,YAAY,EAAE,EAAE;YACrC,EAAE;SACH,CAAA;IACH,CAAC;IAED,QAAQ,CAAC,GAAsB;QAC7B,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;QACxC,OAAO,OAAO,CAAC,OAAO,CACpB;YACE,mCAAmC;YACnC,EAAE;YACF,+EAA+E;YAC/E,yCAAyC;YACzC,EAAE;YACF,GAAG,IAAI,CAAC,cAAc,EAAE;YACxB,WAAW;YACX,EAAE;YACF,GAAG,CAAC,MAAM;YACV,EAAE;YACF,+BAA+B;YAC/B,EAAE;YACF,KAAK;YACL,OAAO;YACP,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAA;IACH,CAAC;IAED,8EAA8E;IAC9E,0EAA0E;IAC1E,2EAA2E;IAC3E,wDAAwD;IACxD,KAAK,CAAC,QAAQ,CAAC,GAAoB,EAAE,IAAsB;QACzD,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;QAC9B,MAAM,QAAQ,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAA;QAC3E,MAAM,MAAM,GAAG,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;QACxE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC;YAC/B,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE;YAClG,MAAM;SACP,CAAC,CAAA;QACF,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;QAC9B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAA;IAChC,CAAC;CACF"}

package/dist/providers/openai.d.ts

@@ -1,9 +1,17 @@
 import OpenAI from "openai";
-import type { AgentMessage, CompletionRequest, ConverseRequest, ConverseResult, Provider } from "./types.js";
+import type { TokenUsage } from "../models/types.js";
+import type { AgentMessage, CompletionRequest, ConverseOptions, ConverseRequest, ConverseResult, Provider } from "./types.js";
 /** Map provider-neutral messages to OpenAI chat messages (pure; tested). */
 export declare function toOpenAIMessages(messages: AgentMessage[]): OpenAI.Chat.Completions.ChatCompletionMessageParam[];
 /** Reduce an OpenAI response message to text + tool calls (pure; tested). */
 export declare function parseOpenAIMessage(message: OpenAI.Chat.Completions.ChatCompletionMessage): ConverseResult;
+/**
+ * Map an OpenAI `usage` block to the kernel's token accounting (pure; tested).
+ * `prompt_tokens` already includes cached input, so it maps to `inputTokens`
+ * as-is and `cached_tokens` is the cache-read breakdown. OpenAI's automatic
+ * caching reports no separate write count.
+ */
+export declare function openAIUsage(usage: OpenAI.Completions.CompletionUsage | null | undefined): TokenUsage | undefined;
 /** Constructor options for an OpenAI-compatible (chat.completions) provider. */
 export interface OpenAICompatibleOptions {
     apiKey: string;
@@ -24,11 +32,12 @@ export interface OpenAICompatibleOptions {
  */
 export declare class OpenAICompatibleProvider implements Provider {
     readonly name: string;
+    readonly reportsUsage = true;
     private client;
     private model;
     constructor(name: string, opts: OpenAICompatibleOptions);
     complete(req: CompletionRequest): Promise<string>;
-    converse(req: ConverseRequest): Promise<ConverseResult>;
+    converse(req: ConverseRequest, opts?: ConverseOptions): Promise<ConverseResult>;
 }
 export declare class OpenAIProvider extends OpenAICompatibleProvider {
     constructor(apiKey: string, model?: string);

package/dist/providers/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAE3B,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,QAAQ,EAET,MAAM,YAAY,CAAA;AAEnB,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EAAE,GACvB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,0BAA0B,EAAE,CA0BtD;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,qBAAqB,GACrD,cAAc,CAchB;AAaD,gFAAgF;AAChF,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;CAC/C;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,QAAQ;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,KAAK,CAAQ;gBAET,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB;IAejD,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAajD,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAiB9D;AAED,qBAAa,cAAe,SAAQ,wBAAwB;gBAC9C,MAAM,EAAE,MAAM,EAAE,KAAK,SAAwC;CAG1E"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEpD,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,cAAc,EACd,QAAQ,EAET,MAAM,YAAY,CAAA;AAEnB,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EAAE,GACvB,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,0BAA0B,EAAE,CA0BtD;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,qBAAqB,GACrD,cAAc,CAchB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,eAAe,GAAG,IAAI,GAAG,SAAS,GAC3D,UAAU,GAAG,SAAS,CASxB;AAaD,gFAAgF;AAChF,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAA;CAC/C;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,YAAW,QAAQ;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,YAAY,QAAO;IAC5B,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,KAAK,CAAQ;gBAET,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,uBAAuB;IAejD,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAajD,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAsBtF;AAED,qBAAa,cAAe,SAAQ,wBAAwB;gBAC9C,MAAM,EAAE,MAAM,EAAE,KAAK,SAAwC;CAG1E"}

package/dist/providers/openai.js

@@ -47,6 +47,23 @@ export function parseOpenAIMessage(message) {
     }
     return { text, toolCalls };
 }
+/**
+ * Map an OpenAI `usage` block to the kernel's token accounting (pure; tested).
+ * `prompt_tokens` already includes cached input, so it maps to `inputTokens`
+ * as-is and `cached_tokens` is the cache-read breakdown. OpenAI's automatic
+ * caching reports no separate write count.
+ */
+export function openAIUsage(usage) {
+    if (!usage)
+        return undefined;
+    const cached = usage.prompt_tokens_details?.cached_tokens ?? 0;
+    return {
+        inputTokens: usage.prompt_tokens,
+        outputTokens: usage.completion_tokens,
+        totalTokens: usage.total_tokens,
+        ...(cached > 0 ? { cacheReadTokens: cached } : {}),
+    };
+}
 /** Parse a tool-call arguments JSON string, tolerating empty/invalid input. */
 function parseArguments(raw) {
     if (!raw)
@@ -66,6 +83,7 @@ function parseArguments(raw) {
  */
 export class OpenAICompatibleProvider {
     name;
+    reportsUsage = true;
     client;
     model;
     constructor(name, opts) {
@@ -93,7 +111,7 @@ export class OpenAICompatibleProvider {
         });
         return completion.choices[0]?.message?.content ?? "";
     }
-    async converse(req) {
+    async converse(req, opts) {
         const tools = req.tools.map((t) => ({
             type: "function",
             function: { name: t.name, description: t.description, parameters: t.inputSchema },
@@ -103,11 +121,13 @@ export class OpenAICompatibleProvider {
             max_tokens: maxTokens(), // match AnthropicProvider rather than the model default
             messages: [{ role: "system", content: req.system }, ...toOpenAIMessages(req.messages)],
             ...(tools.length > 0 ? { tools } : {}),
-        });
+        }, 
+        // Per-request, so an abort cancels THIS call (retries included).
+        opts?.signal ? { signal: opts.signal } : undefined);
+        const usage = openAIUsage(completion.usage);
         const message = completion.choices[0]?.message;
-        if (!message)
-            return { text: "", toolCalls: [] };
-        return parseOpenAIMessage(message);
+        const parsed = message ? parseOpenAIMessage(message) : { text: "", toolCalls: [] };
+        return { ...parsed, ...(usage ? { usage } : {}) };
     }
 }
 export class OpenAIProvider extends OpenAICompatibleProvider {

package/dist/providers/openai.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"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"}

package/dist/providers/types.d.ts

@@ -1,3 +1,4 @@
+import type { TokenUsage } from "../models/types.js";
 export interface CompletionRequest {
     system: string;
     prompt: string;
@@ -49,12 +50,31 @@ export interface ConverseResult {
     text: string;
     /** Tools the model wants run; empty means the turn is final. */
     toolCalls: ToolCall[];
+    /** Token accounting for this call, when the provider's API reports it. */
+    usage?: TokenUsage;
+}
+/**
+ * Per-call options for {@link Provider.converse}.
+ *
+ * `signal` aborts the in-flight HTTP request rather than waiting it out: the
+ * SDK-backed adapters hand it to the SDK as a per-request option, so a caller
+ * cancel (or the loop's own deadline) stops a long generation mid-flight. A
+ * provider that cannot honour it should still check it before starting.
+ */
+export interface ConverseOptions {
+    signal?: AbortSignal;
 }
 export interface Provider {
     readonly name: string;
+    /**
+     * True when `converse` always populates `ConverseResult.usage`. `chatModel`
+     * declares `caps.usage` from this, so a provider that reports nothing (the
+     * mock, most custom providers) never advertises usage it will not deliver.
+     */
+    readonly reportsUsage?: boolean;
     /** One-shot completion (no tools) — kept for simple callers. */
     complete(req: CompletionRequest): Promise<string>;
     /** One step of a tool-use conversation; the agent loop drives the rest. */
-    converse(req: ConverseRequest): Promise<ConverseResult>;
+    converse(req: ConverseRequest, opts?: ConverseOptions): Promise<ConverseResult>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/providers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,kFAAkF;AAClF,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,CAAA;AAE3C,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,KAAK,EAAE,QAAQ,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAA;IACZ,gEAAgE;IAChE,SAAS,EAAE,QAAQ,EAAE,CAAA;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;CACxD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEpD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC;AAED,4CAA4C;AAC5C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,+BAA+B;AAC/B,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,kFAAkF;AAClF,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,CAAA;AAE3C,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,YAAY,EAAE,CAAA;IACxB,KAAK,EAAE,QAAQ,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAA;IACZ,gEAAgE;IAChE,SAAS,EAAE,QAAQ,EAAE,CAAA;IACrB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,UAAU,CAAA;CACnB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACjD,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAA;CAChF"}

package/dist/signals.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal helpers for the run's cancellation signals: a caller's cancel and a
+ * wall-clock deadline, merged into one signal whose `reason` still says which
+ * of the two fired. Not exported from `index.ts`.
+ */
+import type { RunOutcome } from "./events.js";
+/**
+ * A signal that fires when a wall-clock budget runs out. Clamped to what a
+ * timer can represent, so an "effectively unlimited" budget stays unlimited
+ * rather than overflowing into an immediate abort, and a negative one fires at
+ * once.
+ */
+export declare function deadlineSignal(maxDurationMs: number): AbortSignal;
+/**
+ * Map an external harness's ending onto the run outcome vocabulary: its own
+ * timer → `timed_out`, the caller's signal → `canceled`, otherwise the
+ * harness's error flag decides between `failed` and `completed`.
+ */
+export declare function harnessOutcome(isError: boolean, stoppedBy?: StoppedBy): RunOutcome;
+/**
+ * True when `err` is the run's abort surfacing, not an unrelated failure that
+ * merely happened after it. Requires the signal to have fired, and the error to
+ * be its reason, to carry it as `cause` (how `run_code` and `http_fetch` wrap
+ * it), or to be one of the abort errors the platform and the provider SDKs
+ * raise (`AbortError`, `TimeoutError`, the Anthropic/OpenAI SDKs'
+ * `APIUserAbortError`, matched by name or class name).
+ */
+export declare function isAbortError(err: unknown, signal: AbortSignal | undefined): boolean;
+/** What stopped a run early: its own deadline, or the caller's signal. */
+export type StoppedBy = "deadline" | "signal";
+/** A run's merged stop signal, plus which source fired. */
+export interface RunStop {
+    /** Fires on the deadline or the caller's abort; absent when neither exists. */
+    signal?: AbortSignal;
+    /** Which source fired, or `undefined` while the run has not been stopped. */
+    stoppedBy(): StoppedBy | undefined;
+}
+/**
+ * Merge an optional wall-clock budget with an optional caller signal.
+ *
+ * `AbortSignal.any` carries the first source's `reason` through by identity,
+ * so comparing it against the deadline's own reason tells a timeout from a
+ * cancel without a second flag that could drift from the signal.
+ */
+export declare function runStop(maxDurationMs: number | undefined, external?: AbortSignal): RunStop;
+//# sourceMappingURL=signals.d.ts.map

package/dist/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../src/signals.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAK7C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,WAAW,CAKjE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,UAAU,CAIlF;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAMnF;AAID,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAA;AAE7C,2DAA2D;AAC3D,MAAM,WAAW,OAAO;IACtB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,6EAA6E;IAC7E,SAAS,IAAI,SAAS,GAAG,SAAS,CAAA;CACnC;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAY1F"}

package/dist/signals.js

@@ -0,0 +1,72 @@
+/**
+ * Internal helpers for the run's cancellation signals: a caller's cancel and a
+ * wall-clock deadline, merged into one signal whose `reason` still says which
+ * of the two fired. Not exported from `index.ts`.
+ */
+/** Node's timers cap at 2^31-1 ms; a longer delay would fire after 1ms instead. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * A signal that fires when a wall-clock budget runs out. Clamped to what a
+ * timer can represent, so an "effectively unlimited" budget stays unlimited
+ * rather than overflowing into an immediate abort, and a negative one fires at
+ * once.
+ */
+export function deadlineSignal(maxDurationMs) {
+    const ms = Number.isFinite(maxDurationMs)
+        ? Math.min(Math.max(0, Math.ceil(maxDurationMs)), MAX_TIMER_MS)
+        : MAX_TIMER_MS;
+    return AbortSignal.timeout(ms);
+}
+/**
+ * Map an external harness's ending onto the run outcome vocabulary: its own
+ * timer → `timed_out`, the caller's signal → `canceled`, otherwise the
+ * harness's error flag decides between `failed` and `completed`.
+ */
+export function harnessOutcome(isError, stoppedBy) {
+    if (stoppedBy === "deadline")
+        return "timed_out";
+    if (stoppedBy === "signal")
+        return "canceled";
+    return isError ? "failed" : "completed";
+}
+/**
+ * True when `err` is the run's abort surfacing, not an unrelated failure that
+ * merely happened after it. Requires the signal to have fired, and the error to
+ * be its reason, to carry it as `cause` (how `run_code` and `http_fetch` wrap
+ * it), or to be one of the abort errors the platform and the provider SDKs
+ * raise (`AbortError`, `TimeoutError`, the Anthropic/OpenAI SDKs'
+ * `APIUserAbortError`, matched by name or class name).
+ */
+export function isAbortError(err, signal) {
+    if (!signal?.aborted)
+        return false;
+    if (err === signal.reason)
+        return true;
+    if (!(err instanceof Error))
+        return false;
+    if (err.cause !== undefined && err.cause === signal.reason)
+        return true;
+    return ABORT_ERROR_NAMES.has(err.name) || ABORT_ERROR_NAMES.has(err.constructor.name);
+}
+const ABORT_ERROR_NAMES = new Set(["AbortError", "TimeoutError", "APIUserAbortError"]);
+/**
+ * Merge an optional wall-clock budget with an optional caller signal.
+ *
+ * `AbortSignal.any` carries the first source's `reason` through by identity,
+ * so comparing it against the deadline's own reason tells a timeout from a
+ * cancel without a second flag that could drift from the signal.
+ */
+export function runStop(maxDurationMs, external) {
+    const deadline = maxDurationMs !== undefined && maxDurationMs > 0 ? deadlineSignal(maxDurationMs) : undefined;
+    const sources = [deadline, external].filter((s) => s !== undefined);
+    const signal = sources.length > 1 ? AbortSignal.any(sources) : sources[0];
+    return {
+        ...(signal ? { signal } : {}),
+        stoppedBy: () => {
+            if (!signal?.aborted)
+                return undefined;
+            return deadline !== undefined && signal.reason === deadline.reason ? "deadline" : "signal";
+        },
+    };
+}
+//# sourceMappingURL=signals.js.map

package/dist/signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.js","sourceRoot":"","sources":["../src/signals.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,mFAAmF;AACnF,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,aAAqB;IAClD,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC;QACvC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,EAAE,YAAY,CAAC;QAC/D,CAAC,CAAC,YAAY,CAAA;IAChB,OAAO,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,SAAqB;IACpE,IAAI,SAAS,KAAK,UAAU;QAAE,OAAO,WAAW,CAAA;IAChD,IAAI,SAAS,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAA;IAC7C,OAAO,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAA;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,GAAY,EAAE,MAA+B;IACxE,IAAI,CAAC,MAAM,EAAE,OAAO;QAAE,OAAO,KAAK,CAAA;IAClC,IAAI,GAAG,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IACtC,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACzC,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IACvE,OAAO,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAA;AACvF,CAAC;AAED,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,cAAc,EAAE,mBAAmB,CAAC,CAAC,CAAA;AAatF;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,aAAiC,EAAE,QAAsB;IAC/E,MAAM,QAAQ,GACZ,aAAa,KAAK,SAAS,IAAI,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAC9F,MAAM,OAAO,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAA;IACrF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IACzE,OAAO;QACL,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,SAAS,EAAE,GAAG,EAAE;YACd,IAAI,CAAC,MAAM,EAAE,OAAO;gBAAE,OAAO,SAAS,CAAA;YACtC,OAAO,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAA;QAC5F,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/tools/metadata.d.ts

@@ -34,8 +34,9 @@ export type ResultRetention = "ephemeral" | "standard" | "persistent";
 export type ClientResultVisibility = "full" | "suppressed";
 /**
  * Optional descriptive metadata on a {@link Tool}. Every field is optional and
- * an absent field always means "no restriction", so a tool that declares no
- * metadata behaves exactly as it did before this existed.
+ * an absent field means "no restriction" — except `replay`, where absent means
+ * `"unsafe"` (see the field). A tool that declares no metadata behaves exactly
+ * as it did before this existed.
  */
 export interface ToolMetadata {
     /** Human-facing label, where a UI wants something friendlier than `name`. */
@@ -60,6 +61,16 @@ export interface ToolMetadata {
     undoToolName?: string | null;
     /** How long undo stays available. */
     undoWindowSeconds?: number | null;
+    /**
+     * Whether the tool may be executed again after an interruption — e.g. when
+     * a run is resumed and this call was in flight. `"safe"` declares the effect
+     * idempotent (a read, or a write keyed so a repeat is a no-op); `"unsafe"`
+     * declares it is not. **Absent means unsafe**: this is the one field where
+     * "no claim" is NOT "no restriction", because re-running an effect nobody
+     * vouched for is exactly the failure a replay consumer must avoid. The
+     * kernel only records the claim; deciding to replay is the application's.
+     */
+    replay?: "safe" | "unsafe";
     resultRetention?: ResultRetention;
     clientResultVisibility?: ClientResultVisibility;
 }
@@ -88,6 +99,11 @@ export declare function selectTools(tools: Tool[], selection?: ToolSelection): T
 export declare function toToolSpecs(tools: Tool[]): ToolSpec[];
 /** Tools that must not execute until a human has approved them. */
 export declare function toolsRequiringConfirmation(tools: Tool[]): Tool[];
+/**
+ * Tools that declared `replay: "safe"` — the only ones a consumer may re-run
+ * after an interruption. An undeclared tool is excluded: absent means unsafe.
+ */
+export declare function replaySafeTools(tools: Tool[]): Tool[];
 /** Look up the tool that undoes `name`, when one is declared and reversible. */
 export declare function undoToolFor(tools: Tool[], name: string): Tool | undefined;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/tools/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,kBAAkB,CAAA;AAElE,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,CAAA;AAErE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,YAAY,CAAA;AAE1D;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACpC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAA;IACzC,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,gCAAgC;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,qCAAqC;IACrC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,sBAAsB,CAAC,EAAE,sBAAsB,CAAA;CAChD;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,GAAE,aAAkB,GAAG,OAAO,CAmBhF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,GAAE,aAAkB,GAAG,IAAI,EAAE,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAErD;AAED,mEAAmE;AACnE,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAEhE;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAIzE"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AAEzC;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,kBAAkB,CAAA;AAElE,iEAAiE;AACjE,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,CAAA;AAErE;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,YAAY,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IACpC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,cAAc,EAAE,GAAG,IAAI,CAAA;IACzC,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,gCAAgC;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,qCAAqC;IACrC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC1B,eAAe,CAAC,EAAE,eAAe,CAAA;IACjC,sBAAsB,CAAC,EAAE,sBAAsB,CAAA;CAChD;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,IAAI,CAAC,EAAE,cAAc,CAAA;IACrB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,GAAE,aAAkB,GAAG,OAAO,CAmBhF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,GAAE,aAAkB,GAAG,IAAI,EAAE,CAEhF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,CAErD;AAED,mEAAmE;AACnE,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAEhE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,IAAI,EAAE,CAErD;AAED,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAIzE"}

package/dist/tools/metadata.js

@@ -39,6 +39,13 @@ export function toToolSpecs(tools) {
 export function toolsRequiringConfirmation(tools) {
     return tools.filter((tool) => tool.meta?.requiresConfirmation === true);
 }
+/**
+ * Tools that declared `replay: "safe"` — the only ones a consumer may re-run
+ * after an interruption. An undeclared tool is excluded: absent means unsafe.
+ */
+export function replaySafeTools(tools) {
+    return tools.filter((tool) => tool.meta?.replay === "safe");
+}
 /** Look up the tool that undoes `name`, when one is declared and reversible. */
 export function undoToolFor(tools, name) {
     const tool = tools.find((t) => t.spec.name === name);

package/dist/tools/metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"AAiFA,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAAC,IAAU,EAAE,YAA2B,EAAE;IACrE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IACtB,IAAI,SAAS,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAA;IAClF,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IAEtB,0EAA0E;IAC1E,6EAA6E;IAC7E,4CAA4C;IAC5C,IAAI,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC,SAAS,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YACrF,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAA;IACrF,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,YAA2B,EAAE;IACtE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAA;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACvC,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACtD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC,CAAA;AACzE,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,IAAY;IACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IACpD,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY;QAAE,OAAO,SAAS,CAAA;IACxE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;AACnE,CAAC"}
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"AA4FA,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAAC,IAAU,EAAE,YAA2B,EAAE;IACrE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;IACtB,IAAI,SAAS,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAA;IAClF,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAA;IAEtB,0EAA0E;IAC1E,6EAA6E;IAC7E,4CAA4C;IAC5C,IAAI,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC,SAAS,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;YACrF,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,IAAI,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5D,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAA;IACrF,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,YAA2B,EAAE;IACtE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAA;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACvC,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACtD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,CAAC,CAAA;AACzE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;AAC7D,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,IAAY;IACrD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IACpD,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY;QAAE,OAAO,SAAS,CAAA;IACxE,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAA;AACnE,CAAC"}

package/dist/tools/modelTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modelTool.d.ts","sourceRoot":"","sources":["../../src/tools/modelTool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,eAAe,CAAA;AAErD,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB,CAAC,GAAG,EAAE,GAAG;IACxC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,uEAAuE;IACvE,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,GAAG,CAAA;IAClD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,MAAM,CAAA;IAChD,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAClC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,EAChC,OAAO,EAAE,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,EACnC,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM,GACnC,IAAI,CAwBN"}
+{"version":3,"file":"modelTool.d.ts","sourceRoot":"","sources":["../../src/tools/modelTool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,IAAI,EAA2B,MAAM,eAAe,CAAA;AAElE,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB,CAAC,GAAG,EAAE,GAAG;IACxC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,uEAAuE;IACvE,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,GAAG,CAAA;IAClD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,MAAM,CAAA;IAChD,IAAI,CAAC,EAAE,YAAY,CAAA;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,EAClC,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,EAChC,OAAO,EAAE,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,EACnC,OAAO,GAAE,OAAO,CAAC,aAAa,CAAM,GACnC,IAAI,CAiCN"}

package/dist/tools/modelTool.js

@@ -13,10 +13,14 @@
  */
 export function modelAsTool(model, options, context = {}) {
     const project = options.toContent ?? ((result) => JSON.stringify(result.value));
-    const run = async (input) => {
+    const run = async (input, toolCtx) => {
+        // The run's signal (from the loop) and any signal bound at construction
+        // both cancel the call; either one firing is enough.
+        const signals = [context.signal, toolCtx?.signal].filter((s) => s !== undefined);
+        const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
         const ctx = {
             log: context.log ?? (() => { }),
-            ...(context.signal ? { signal: context.signal } : {}),
+            ...(signal ? { signal } : {}),
             ...(context.correlationId ? { correlationId: context.correlationId } : {}),
             ...(context.budget ? { budget: context.budget } : {}),
         };
@@ -30,7 +34,7 @@ export function modelAsTool(model, options, context = {}) {
             inputSchema: options.inputSchema,
         },
         ...(options.meta ? { meta: options.meta } : {}),
-        execute: async (input) => (await run(input)).content,
+        execute: async (input, toolCtx) => (await run(input, toolCtx)).content,
         executeStructured: run,
     };
 }

package/dist/tools/modelTool.js.map

@@ -1 +1 @@
-{"version":3,"file":"modelTool.js","sourceRoot":"","sources":["../../src/tools/modelTool.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,KAAgC,EAChC,OAAmC,EACnC,UAAkC,EAAE;IAEpC,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,MAAwB,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IAEjG,MAAM,GAAG,GAAG,KAAK,EAAE,KAA8B,EAAuB,EAAE;QACxE,MAAM,GAAG,GAAkB;YACzB,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;YAC9B,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtD,CAAA;QACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAA;QAChE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;IAC/D,CAAC,CAAA;IAED,OAAO;QACL,IAAI,EAAE;YACJ,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC;QACD,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO;QACpD,iBAAiB,EAAE,GAAG;KACvB,CAAA;AACH,CAAC"}
+{"version":3,"file":"modelTool.js","sourceRoot":"","sources":["../../src/tools/modelTool.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CACzB,KAAgC,EAChC,OAAmC,EACnC,UAAkC,EAAE;IAEpC,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,MAAwB,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAA;IAEjG,MAAM,GAAG,GAAG,KAAK,EACf,KAA8B,EAC9B,OAAqB,EACA,EAAE;QACvB,wEAAwE;QACxE,qDAAqD;QACrD,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CACtD,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,KAAK,SAAS,CACzC,CAAA;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;QACzE,MAAM,GAAG,GAAkB;YACzB,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;YAC9B,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7B,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1E,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtD,CAAA;QACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAA;QAChE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;IAC/D,CAAC,CAAA;IAED,OAAO;QACL,IAAI,EAAE;YACJ,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC;QACD,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO;QACtE,iBAAiB,EAAE,GAAG;KACvB,CAAA;AACH,CAAC"}

package/dist/tools/registry.d.ts

@@ -17,6 +17,23 @@ export interface ToolOutput {
     /** The typed payload, preserved for callers and clients. */
     structured?: unknown;
 }
+/**
+ * What the loop hands a tool alongside its input.
+ *
+ * `signal` fires when the run is canceled or its deadline passes; a tool that
+ * does real work (a subprocess, an HTTP call, a remote MCP call) should stop
+ * when it does. `callId` is the model's id for this call — the same id the
+ * `tool.called` event carries — so a tool can key an idempotency token or a log
+ * line to it. `runId` is present when the caller supplied one.
+ *
+ * Optional on both executors, so a tool written before this existed, and a
+ * caller that invokes a tool directly, keep working unchanged.
+ */
+export interface ToolContext {
+    signal: AbortSignal;
+    callId: string;
+    runId?: string;
+}
 /** A tool the agent can call: its public spec plus a server-side executor. */
 export interface Tool {
     spec: ToolSpec;
@@ -26,7 +43,7 @@ export interface Tool {
      * Execute and return the model-facing string. This is the required contract
      * every tool implements, and the only one the loop needs.
      */
-    execute(input: Record<string, unknown>): Promise<string>;
+    execute(input: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
     /**
      * Optional richer executor. When present the loop calls this instead and
      * keeps the typed payload alongside the string; when absent nothing changes.
@@ -36,10 +53,10 @@ export interface Tool {
      * types `execute` as returning a plain `string`, and widening it to a union
      * would break them at the type level for a payload most tools never produce.
      */
-    executeStructured?(input: Record<string, unknown>): Promise<ToolOutput>;
+    executeStructured?(input: Record<string, unknown>, ctx?: ToolContext): Promise<ToolOutput>;
 }
-/** Run a tool through its richest available executor. */
-export declare function executeTool(tool: Tool, input: Record<string, unknown>): Promise<ToolOutput>;
+/** Run a tool through its richest available executor, handing it `ctx` when given. */
+export declare function executeTool(tool: Tool, input: Record<string, unknown>, ctx?: ToolContext): Promise<ToolOutput>;
 /**
  * General-purpose primitives, scoped to the run sandbox. `env` carries the
  * resolved secrets (see secretsToEnv) into executed code. Domain logic is the
@@ -58,7 +75,9 @@ export declare function primitiveTools(sandboxDir: string, env: NodeJS.ProcessEn
  * namespaced `<connector>__<tool>` to avoid collisions. Returns a `close` to
  * tear down the connections when the run ends.
  */
-export declare function connectorTools(connectors: ConnectorConfig[], connect?: (config: ConnectorConfig) => Promise<McpConnection>): Promise<{
+export declare function connectorTools(connectors: ConnectorConfig[], connect?: (config: ConnectorConfig) => Promise<McpConnection>, opts?: {
+    signal?: AbortSignal;
+}): Promise<{
     tools: Tool[];
     close: () => Promise<void>;
 }>;