@superdurable/dex-agents 0.2.0 → 0.4.0

package/dist/src/testing/index.d.ts

@@ -1,6 +1,7 @@
 export { AgentSessionTestClient, type AgentSessionWaitOptions, } from "./agent-session-test-client.js";
 export { AgentTestEnvironment, type AgentTestEnvironmentOptions, } from "./agent-test-environment.js";
 export { KillableWorkerProcess, agentWorkerBlobCacheDirectoryVariable, agentWorkerReadyLine, agentWorkerServerAddressVariable, runAgentWorkerProcess, type KillableWorkerProcessOptions, } from "./agent-worker-process.js";
+export { ContextWindowModelScript, ContextWindowSessionScenario, contextWindowExceededError, contextWindowSessionOptions, contextWindowSettingsEnvironment, contextWindowSettingsVariable, contextWindowSummaryGateName, contextWindowToolName, defaultContextWindowSettings, readContextWindowRequests, readContextWindowSettings, type ContextWindowReply, type ContextWindowRequest, type ContextWindowSessionScenarioOptions, type ContextWindowSettings, } from "./context-window.js";
 export { FileGate, InvocationLog } from "./coordination.js";
 export { pollUntil, type PollOptions } from "./polling.js";
 export { ScriptedModelClient, scriptedModelApi, scriptedModelProvider, type ScriptedModelReply, type ScriptedModelResponder, type ScriptedToolCall, } from "./scripted-model-client.js";

package/dist/src/testing/index.js

@@ -8,6 +8,7 @@
 export { AgentSessionTestClient, } from "./agent-session-test-client.js";
 export { AgentTestEnvironment, } from "./agent-test-environment.js";
 export { KillableWorkerProcess, agentWorkerBlobCacheDirectoryVariable, agentWorkerReadyLine, agentWorkerServerAddressVariable, runAgentWorkerProcess, } from "./agent-worker-process.js";
+export { ContextWindowModelScript, ContextWindowSessionScenario, contextWindowExceededError, contextWindowSessionOptions, contextWindowSettingsEnvironment, contextWindowSettingsVariable, contextWindowSummaryGateName, contextWindowToolName, defaultContextWindowSettings, readContextWindowRequests, readContextWindowSettings, } from "./context-window.js";
 export { FileGate, InvocationLog } from "./coordination.js";
 export { pollUntil } from "./polling.js";
 export { ScriptedModelClient, scriptedModelApi, scriptedModelProvider, } from "./scripted-model-client.js";

package/dist/src/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EACL,sBAAsB,GAEvB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,oBAAoB,GAErB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,qBAAqB,EACrB,qCAAqC,EACrC,oBAAoB,EACpB,gCAAgC,EAChC,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAoB,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GAItB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GAGtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,GAEtB,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EACL,sBAAsB,GAEvB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,oBAAoB,GAErB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,qBAAqB,EACrB,qCAAqC,EACrC,oBAAoB,EACpB,gCAAgC,EAChC,qBAAqB,GAEtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,wBAAwB,EACxB,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,6BAA6B,EAC7B,4BAA4B,EAC5B,qBAAqB,EACrB,4BAA4B,EAC5B,yBAAyB,EACzB,yBAAyB,GAK1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAoB,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,GAItB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GAGtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,GAEtB,MAAM,yBAAyB,CAAC"}

package/dist/src/tool-source-router.d.ts

@@ -0,0 +1,211 @@
+import { type AgentTurnContext, type DeferredToolCall, type DeferredToolExecution, type DeferredToolOutcome, type ToolCallStepOptions, type ToolExecutionResult, type ToolTaskCancellation, type ToolTaskPoll, type ToolTaskPollOutcome } from "./agent-framework-runner.js";
+import type { AgentToolCall } from "./agent-session-values.js";
+import type { SourceToolDefinition, ToolSource } from "./stepwise/tool-source.js";
+/**
+ * Default `AgentDefinition.toolSourceListingTimeoutMs`: 10 seconds. It is also the default time one model call of a
+ * framework adapter waits for each tool source's listing. Exported from the package root since 0.4.0.
+ */
+export declare const defaultToolSourceListingTimeoutMs = 10000;
+/**
+ * One tool that a {@link ToolSource} listed for a model call, with the source that listed it.
+ * @since 0.4.0
+ */
+export interface ListedSourceTool {
+    /** The source that listed the tool. */
+    readonly source: ToolSource;
+    /** The tool definition as the source listed it. */
+    readonly tool: SourceToolDefinition;
+}
+/**
+ * Options of a {@link ToolSourceRouter}.
+ * @since 0.4.0
+ */
+export interface ToolSourceRouterOptions {
+    /**
+     * JSON key under which the router stores the building source's name in each call's `toolSourceReference`,
+     * such as `"vercel_ai_tool_source"`. Keep it fixed: stored calls are routed by it.
+     */
+    readonly sourceNameKey: string;
+    /** Names of the runner's own tools, which no source tool may repeat. Defaults to none. */
+    readonly localToolNames?: ReadonlySet<string>;
+    /**
+     * What the runner's own tools are, for the collision error, such as `"a function tool"`. Defaults to
+     * `"a tool of the agent"`.
+     */
+    readonly localToolDescription?: string;
+    /** Names of the built-in tools enabled for every session, which no source tool may repeat. Defaults to none. */
+    readonly builtInToolNames?: ReadonlySet<string>;
+    /**
+     * How long one {@link ToolSourceRouter.listSourceTools} waits for each source, in milliseconds. Defaults to
+     * {@link defaultToolSourceListingTimeoutMs}.
+     */
+    readonly listingTimeoutMs?: number;
+}
+/**
+ * Serves {@link ToolSource}s from a framework runner, so their calls run in tool Steps as the Stepwise runner runs
+ * them.
+ *
+ * A framework adapter that implements {@link AgentFrameworkRunner} builds one router from its `toolSources`. In each
+ * `RunModel` it awaits {@link listSourceTools} and offers every listed tool to its framework as a native tool that
+ * never runs inside the model call. When the model calls one, the adapter returns {@link buildDeferredToolCall}, so
+ * the source picks the effect, the approval, and whether the call is an ordered write, and the router stores the
+ * source's name with the source's own `toolSourceReference`. The tool Step then reaches that source through
+ * {@link executeDeferredToolCall} on any Worker, with the full execution: the Step context, the heartbeat
+ * checkpoint, and the attempt. {@link toolCallStepOptions}, {@link pollToolTask}, and {@link cancelToolTask} route
+ * the same way. A runner whose `executeDeferredToolCall` returns only results, and so polls no tool tasks, uses
+ * {@link executeDeferredToolCallForResult} instead. `StepwiseAgentRunner` uses a router too.
+ *
+ * Construction refuses a source without a {@link ToolSource} method or a non-blank, unique `sourceName`, and a
+ * name that a source declares through `declaredToolNames` when it repeats a local tool, a built-in tool, or another
+ * source's tool. Each listing refuses the same collisions among the listed names.
+ *
+ * @example
+ * ```ts
+ * const toolSources = new ToolSourceRouter([new ConnectorToolSource([refund])], {
+ *   sourceNameKey: "my_framework_tool_source",
+ *   localToolNames: new Set(Object.keys(frameworkTools)),
+ * });
+ * const listed = await toolSources.listSourceTools();
+ * const call = toolSources.buildDeferredToolCall(turn, listed.get("refund")!, modelCall);
+ * ```
+ * @since 0.4.0
+ */
+export declare class ToolSourceRouter {
+    private readonly toolSources;
+    private readonly toolSourcesByName;
+    private readonly sourceNameKey;
+    private readonly localToolNames;
+    private readonly localToolDescription;
+    private readonly listingTimeoutMs;
+    /** The last listing of each source, so estimates count its tools without listing again. */
+    private readonly lastListings;
+    /**
+     * Creates the router and checks the sources.
+     * @param toolSources - The sources, in the order the model sees their tools.
+     * @param options - The envelope key, the names source tools must not repeat, and the listing timeout.
+     * @throws {TypeError} When a source lacks a {@link ToolSource} method or a non-blank `sourceName`, two sources
+     * share a `sourceName`, `sourceNameKey` is blank, or a declared tool name repeats a local tool, a built-in tool, or
+     * another source's tool.
+     * @throws {RangeError} When `listingTimeoutMs` is not positive.
+     */
+    constructor(toolSources: readonly ToolSource[], options: ToolSourceRouterOptions);
+    /** Whether the router has at least one source. */
+    get hasToolSources(): boolean;
+    /**
+     * Returns the names the sources always list, from their optional `declaredToolNames`.
+     * @returns The names.
+     */
+    declaredToolNames(): ReadonlySet<string>;
+    /**
+     * Lists every source's tools for one model call, in source order.
+     *
+     * A source whose listing throws or takes longer than the listing timeout offers no tools in this call, with a
+     * warning, so a down server never fails a turn.
+     * @param builtInToolNames - The built-in tools enabled for this turn. Defaults to none.
+     * @returns The listed tools by name.
+     * @throws {TypeError} When a listed name repeats a local tool, an enabled built-in tool, or another source's tool.
+     */
+    listSourceTools(builtInToolNames?: ReadonlySet<string>): Promise<ReadonlyMap<string, ListedSourceTool>>;
+    /**
+     * Returns each source's tools without I/O: its `cachedTools` when it has them, else this router's last listing.
+     * A name listed twice keeps its first source. Use it to estimate the model input.
+     * @returns The cached tools by name.
+     */
+    readCachedSourceTools(): ReadonlyMap<string, ListedSourceTool>;
+    /**
+     * Builds the deferred call for one model call of a listed source tool.
+     *
+     * The source's `deferredToolCall` decides the policy, the `ordered` flag, and its own reference. The router
+     * keeps all of it and wraps the reference with the source's name.
+     * @param turn - The `RunModel` context.
+     * @param listedTool - The listed tool the model called, from {@link listSourceTools} of this model call.
+     * @param modelCall - The model's tool call ID and its arguments as JSON text.
+     * @returns The deferred call to return in `ToolCallsRequested`.
+     */
+    buildDeferredToolCall(turn: AgentTurnContext, listedTool: ListedSourceTool, modelCall: {
+        readonly toolCallId: string;
+        readonly arguments: string;
+    }): DeferredToolCall;
+    /**
+     * Whether a source built this call, so its tool Step and polls go to a source. It reads only the record, so it
+     * answers even when that source is not configured on this Worker; {@link executeDeferredToolCall} then throws.
+     * @param toolCall - The call's record.
+     * @returns `true` when the record holds this router's envelope, or a reference while the router has sources.
+     */
+    isSourceToolCall(toolCall: {
+        readonly toolName: string;
+        readonly toolSourceReference?: string;
+    }): boolean;
+    /**
+     * Runs one call in its tool Step through the source that built it, with the source's own reference and every
+     * other field of `call` unchanged, such as the Step context, the heartbeat checkpoint, and the attempt.
+     * @param call - The deferred execution from the tool Step.
+     * @returns The source's outcome.
+     * @throws {RangeError} When no source built the call, or its source is not configured on this Worker, so the
+     * effect decides the outcome.
+     * @throws Any error of the source, such as `ToolExecutionError` or `ToolOutcomeUnknownError`.
+     */
+    executeDeferredToolCall(call: DeferredToolExecution): Promise<DeferredToolOutcome>;
+    /**
+     * Runs one call as {@link executeDeferredToolCall} does, for a runner that polls no tool tasks and asks no tool
+     * questions, so its `executeDeferredToolCall` returns only a `ToolExecutionResult`. Such a runner has no
+     * `pollToolTask`, so the session tells the source that it cannot start tasks. `ConnectorToolSource` returns only
+     * results.
+     * @param call - The deferred execution from the tool Step.
+     * @returns The source's result.
+     * @throws {ToolExecutionError} When the source asked the user a question. A question comes before any effect, so
+     * the call records `failed` and the model reads why.
+     * @throws {Error} When the source started a tool task anyway. The task may run, so the effect decides the outcome.
+     * @throws Any error of {@link executeDeferredToolCall}.
+     */
+    executeDeferredToolCallForResult(call: DeferredToolExecution): Promise<ToolExecutionResult>;
+    /**
+     * Polls a source's tool task once, through the source that built the call.
+     * @param poll - The call's record from `PollToolTask`.
+     * @returns The source's outcome.
+     * @throws {RangeError} When no source built the call. The task may still run, so `PollToolTask` retries and then
+     * records the call by its effect.
+     * @throws Any error of the source.
+     */
+    pollToolTask(poll: ToolTaskPoll): Promise<ToolTaskPollOutcome>;
+    /**
+     * Cancels a source's task through the source that built the call; a source without `cancelToolTask` leaves its
+     * task running.
+     * @param cancellation - The abandoned call's record from `CancelToolTask`.
+     * @returns A Promise that resolves once the source took the cancellation.
+     * @throws {RangeError} When no source built the call.
+     * @throws Any error of the source.
+     */
+    cancelToolTask(cancellation: ToolTaskCancellation): Promise<void>;
+    /**
+     * Returns the source's options for one call's tool Step.
+     * @param toolCall - The record whose tool Step starts.
+     * @returns The source's options, or `undefined` when no source built the call or its source defines none.
+     * @throws {RangeError} When a source built the call but it is not configured on this Worker; the session then
+     * uses the defaults.
+     */
+    toolCallStepOptions(toolCall: AgentToolCall): ToolCallStepOptions | undefined;
+    private refuseDeclaredToolNameCollisions;
+    private refuseSourceToolName;
+    private listOneSource;
+    private requireToolSource;
+    private routeToToolSource;
+}
+/**
+ * The router's `toolSourceReference`: the source's name under `sourceNameKey` and its own reference, as JSON text.
+ * @param sourceNameKey - The envelope key of the runner.
+ * @param sourceName - The building source's name.
+ * @param reference - The source's own reference, or `undefined`.
+ * @returns The envelope text.
+ */
+export declare function writeToolSourceEnvelope(sourceNameKey: string, sourceName: string, reference: string | undefined): string;
+/**
+ * Reads an envelope that {@link writeToolSourceEnvelope} wrote with the same key.
+ * @param sourceNameKey - The envelope key of the runner.
+ * @param toolSourceReference - A record's `toolSourceReference`.
+ * @returns The source's name and its own reference, or `undefined` when the text is no such envelope.
+ */
+export declare function readToolSourceEnvelope(sourceNameKey: string, toolSourceReference: string | undefined): {
+    readonly sourceName: string;
+    readonly reference: string | undefined;
+} | undefined;

package/dist/src/tool-source-router.js

@@ -0,0 +1,380 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+import { ToolExecutionError, } from "./agent-framework-runner.js";
+/**
+ * Default `AgentDefinition.toolSourceListingTimeoutMs`: 10 seconds. It is also the default time one model call of a
+ * framework adapter waits for each tool source's listing. Exported from the package root since 0.4.0.
+ */
+export const defaultToolSourceListingTimeoutMs = 10_000;
+const toolSourceMethods = ["listTools", "deferredToolCall", "executeDeferredToolCall", "pollToolTask"];
+const toolSourceReferenceKey = "reference";
+/**
+ * Serves {@link ToolSource}s from a framework runner, so their calls run in tool Steps as the Stepwise runner runs
+ * them.
+ *
+ * A framework adapter that implements {@link AgentFrameworkRunner} builds one router from its `toolSources`. In each
+ * `RunModel` it awaits {@link listSourceTools} and offers every listed tool to its framework as a native tool that
+ * never runs inside the model call. When the model calls one, the adapter returns {@link buildDeferredToolCall}, so
+ * the source picks the effect, the approval, and whether the call is an ordered write, and the router stores the
+ * source's name with the source's own `toolSourceReference`. The tool Step then reaches that source through
+ * {@link executeDeferredToolCall} on any Worker, with the full execution: the Step context, the heartbeat
+ * checkpoint, and the attempt. {@link toolCallStepOptions}, {@link pollToolTask}, and {@link cancelToolTask} route
+ * the same way. A runner whose `executeDeferredToolCall` returns only results, and so polls no tool tasks, uses
+ * {@link executeDeferredToolCallForResult} instead. `StepwiseAgentRunner` uses a router too.
+ *
+ * Construction refuses a source without a {@link ToolSource} method or a non-blank, unique `sourceName`, and a
+ * name that a source declares through `declaredToolNames` when it repeats a local tool, a built-in tool, or another
+ * source's tool. Each listing refuses the same collisions among the listed names.
+ *
+ * @example
+ * ```ts
+ * const toolSources = new ToolSourceRouter([new ConnectorToolSource([refund])], {
+ *   sourceNameKey: "my_framework_tool_source",
+ *   localToolNames: new Set(Object.keys(frameworkTools)),
+ * });
+ * const listed = await toolSources.listSourceTools();
+ * const call = toolSources.buildDeferredToolCall(turn, listed.get("refund")!, modelCall);
+ * ```
+ * @since 0.4.0
+ */
+export class ToolSourceRouter {
+    toolSources;
+    toolSourcesByName;
+    sourceNameKey;
+    localToolNames;
+    localToolDescription;
+    listingTimeoutMs;
+    /** The last listing of each source, so estimates count its tools without listing again. */
+    lastListings = new Map();
+    /**
+     * Creates the router and checks the sources.
+     * @param toolSources - The sources, in the order the model sees their tools.
+     * @param options - The envelope key, the names source tools must not repeat, and the listing timeout.
+     * @throws {TypeError} When a source lacks a {@link ToolSource} method or a non-blank `sourceName`, two sources
+     * share a `sourceName`, `sourceNameKey` is blank, or a declared tool name repeats a local tool, a built-in tool, or
+     * another source's tool.
+     * @throws {RangeError} When `listingTimeoutMs` is not positive.
+     */
+    constructor(toolSources, options) {
+        if (typeof options.sourceNameKey !== "string" || options.sourceNameKey.trim() === "") {
+            throw new TypeError("ToolSourceRouterOptions.sourceNameKey must be a non-blank string");
+        }
+        for (const source of toolSources) {
+            const missing = toolSourceMethods.find((method) => typeof source?.[method] !== "function");
+            if (missing !== undefined) {
+                throw new TypeError(`tool source ${String(source)} has no ${missing} method`);
+            }
+        }
+        const toolSourcesByName = new Map();
+        for (const source of toolSources) {
+            if (typeof source.sourceName !== "string" || source.sourceName.trim() === "") {
+                throw new TypeError(`tool source ${String(source)} needs a non-blank sourceName`);
+            }
+            if (toolSourcesByName.has(source.sourceName)) {
+                throw new TypeError(`two tool sources are named ${source.sourceName}`);
+            }
+            toolSourcesByName.set(source.sourceName, source);
+        }
+        const listingTimeoutMs = options.listingTimeoutMs ?? defaultToolSourceListingTimeoutMs;
+        if (!(listingTimeoutMs > 0)) {
+            throw new RangeError("toolSourceListingTimeoutMs must be positive");
+        }
+        this.toolSources = [...toolSources];
+        this.toolSourcesByName = toolSourcesByName;
+        this.sourceNameKey = options.sourceNameKey;
+        this.localToolNames = new Set(options.localToolNames ?? []);
+        this.localToolDescription = options.localToolDescription ?? "a tool of the agent";
+        this.listingTimeoutMs = listingTimeoutMs;
+        this.refuseDeclaredToolNameCollisions(options.builtInToolNames ?? new Set());
+    }
+    /** Whether the router has at least one source. */
+    get hasToolSources() {
+        return this.toolSources.length > 0;
+    }
+    /**
+     * Returns the names the sources always list, from their optional `declaredToolNames`.
+     * @returns The names.
+     */
+    declaredToolNames() {
+        const names = new Set();
+        for (const source of this.toolSources) {
+            for (const toolName of source.declaredToolNames?.() ?? []) {
+                names.add(toolName);
+            }
+        }
+        return names;
+    }
+    /**
+     * Lists every source's tools for one model call, in source order.
+     *
+     * A source whose listing throws or takes longer than the listing timeout offers no tools in this call, with a
+     * warning, so a down server never fails a turn.
+     * @param builtInToolNames - The built-in tools enabled for this turn. Defaults to none.
+     * @returns The listed tools by name.
+     * @throws {TypeError} When a listed name repeats a local tool, an enabled built-in tool, or another source's tool.
+     */
+    async listSourceTools(builtInToolNames = new Set()) {
+        const listed = new Map();
+        for (const [index, source] of this.toolSources.entries()) {
+            for (const tool of await this.listOneSource(index, source)) {
+                this.refuseSourceToolName(tool.name, builtInToolNames, listed);
+                listed.set(tool.name, { source, tool });
+            }
+        }
+        return listed;
+    }
+    /**
+     * Returns each source's tools without I/O: its `cachedTools` when it has them, else this router's last listing.
+     * A name listed twice keeps its first source. Use it to estimate the model input.
+     * @returns The cached tools by name.
+     */
+    readCachedSourceTools() {
+        const cached = new Map();
+        for (const [index, source] of this.toolSources.entries()) {
+            const tools = source.cachedTools?.() ?? this.lastListings.get(index) ?? [];
+            for (const tool of tools) {
+                if (!cached.has(tool.name)) {
+                    cached.set(tool.name, { source, tool });
+                }
+            }
+        }
+        return cached;
+    }
+    /**
+     * Builds the deferred call for one model call of a listed source tool.
+     *
+     * The source's `deferredToolCall` decides the policy, the `ordered` flag, and its own reference. The router
+     * keeps all of it and wraps the reference with the source's name.
+     * @param turn - The `RunModel` context.
+     * @param listedTool - The listed tool the model called, from {@link listSourceTools} of this model call.
+     * @param modelCall - The model's tool call ID and its arguments as JSON text.
+     * @returns The deferred call to return in `ToolCallsRequested`.
+     */
+    buildDeferredToolCall(turn, listedTool, modelCall) {
+        const built = listedTool.source.deferredToolCall(turn, {
+            toolCallId: modelCall.toolCallId,
+            toolName: listedTool.tool.name,
+            arguments: modelCall.arguments,
+            listedTool: listedTool.tool,
+        });
+        return {
+            ...built,
+            toolSourceReference: writeToolSourceEnvelope(this.sourceNameKey, listedTool.source.sourceName, built.toolSourceReference),
+        };
+    }
+    /**
+     * Whether a source built this call, so its tool Step and polls go to a source. It reads only the record, so it
+     * answers even when that source is not configured on this Worker; {@link executeDeferredToolCall} then throws.
+     * @param toolCall - The call's record.
+     * @returns `true` when the record holds this router's envelope, or a reference while the router has sources.
+     */
+    isSourceToolCall(toolCall) {
+        if (readToolSourceEnvelope(this.sourceNameKey, toolCall.toolSourceReference) !== undefined) {
+            return true;
+        }
+        return (toolCall.toolSourceReference ?? undefined) !== undefined && this.hasToolSources;
+    }
+    /**
+     * Runs one call in its tool Step through the source that built it, with the source's own reference and every
+     * other field of `call` unchanged, such as the Step context, the heartbeat checkpoint, and the attempt.
+     * @param call - The deferred execution from the tool Step.
+     * @returns The source's outcome.
+     * @throws {RangeError} When no source built the call, or its source is not configured on this Worker, so the
+     * effect decides the outcome.
+     * @throws Any error of the source, such as `ToolExecutionError` or `ToolOutcomeUnknownError`.
+     */
+    async executeDeferredToolCall(call) {
+        const routed = this.requireToolSource(call.toolCall);
+        return routed.source.executeDeferredToolCall({
+            ...call,
+            toolCall: withToolSourceReference(call.toolCall, routed.reference),
+        });
+    }
+    /**
+     * Runs one call as {@link executeDeferredToolCall} does, for a runner that polls no tool tasks and asks no tool
+     * questions, so its `executeDeferredToolCall` returns only a `ToolExecutionResult`. Such a runner has no
+     * `pollToolTask`, so the session tells the source that it cannot start tasks. `ConnectorToolSource` returns only
+     * results.
+     * @param call - The deferred execution from the tool Step.
+     * @returns The source's result.
+     * @throws {ToolExecutionError} When the source asked the user a question. A question comes before any effect, so
+     * the call records `failed` and the model reads why.
+     * @throws {Error} When the source started a tool task anyway. The task may run, so the effect decides the outcome.
+     * @throws Any error of {@link executeDeferredToolCall}.
+     */
+    async executeDeferredToolCallForResult(call) {
+        const outcome = await this.executeDeferredToolCall(call);
+        if (!("kind" in outcome)) {
+            return outcome;
+        }
+        const toolName = call.toolCall.toolName;
+        if (outcome.kind === "tool_input_requested") {
+            throw new ToolExecutionError(`tool ${toolName} asked a question, which this agent cannot ask the user`);
+        }
+        throw new Error(`tool ${toolName} started a tool task, which this agent cannot poll`);
+    }
+    /**
+     * Polls a source's tool task once, through the source that built the call.
+     * @param poll - The call's record from `PollToolTask`.
+     * @returns The source's outcome.
+     * @throws {RangeError} When no source built the call. The task may still run, so `PollToolTask` retries and then
+     * records the call by its effect.
+     * @throws Any error of the source.
+     */
+    async pollToolTask(poll) {
+        const routed = this.requireToolSource(poll.toolCall);
+        return routed.source.pollToolTask({ ...poll, toolCall: withToolSourceReference(poll.toolCall, routed.reference) });
+    }
+    /**
+     * Cancels a source's task through the source that built the call; a source without `cancelToolTask` leaves its
+     * task running.
+     * @param cancellation - The abandoned call's record from `CancelToolTask`.
+     * @returns A Promise that resolves once the source took the cancellation.
+     * @throws {RangeError} When no source built the call.
+     * @throws Any error of the source.
+     */
+    async cancelToolTask(cancellation) {
+        const routed = this.requireToolSource(cancellation.toolCall);
+        await routed.source.cancelToolTask?.({
+            ...cancellation,
+            toolCall: withToolSourceReference(cancellation.toolCall, routed.reference),
+        });
+    }
+    /**
+     * Returns the source's options for one call's tool Step.
+     * @param toolCall - The record whose tool Step starts.
+     * @returns The source's options, or `undefined` when no source built the call or its source defines none.
+     * @throws {RangeError} When a source built the call but it is not configured on this Worker; the session then
+     * uses the defaults.
+     */
+    toolCallStepOptions(toolCall) {
+        const routed = this.routeToToolSource(toolCall);
+        return routed?.source.toolCallStepOptions?.(withToolSourceReference(toolCall, routed.reference));
+    }
+    refuseDeclaredToolNameCollisions(builtInToolNames) {
+        const declared = new Map();
+        for (const source of this.toolSources) {
+            const names = [...(source.declaredToolNames?.() ?? [])].sort();
+            for (const toolName of names) {
+                this.refuseSourceToolName(toolName, builtInToolNames, declared);
+            }
+            for (const toolName of names) {
+                declared.set(toolName, source);
+            }
+        }
+    }
+    refuseSourceToolName(toolName, builtInToolNames, otherSourceTools) {
+        if (builtInToolNames.has(toolName)) {
+            throw new TypeError(`tool ${toolName} uses the name of an enabled built-in tool`);
+        }
+        if (this.localToolNames.has(toolName)) {
+            throw new TypeError(`tool ${toolName} of a tool source uses the name of ${this.localToolDescription}`);
+        }
+        if (otherSourceTools.has(toolName)) {
+            throw new TypeError(`two tool sources list a tool named ${toolName}`);
+        }
+    }
+    async listOneSource(index, source) {
+        const listing = source.listTools();
+        // A listing that outlives this call keeps running; nobody else reads its error.
+        listing.catch(() => undefined);
+        let timer;
+        const timedOut = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("timed_out"), this.listingTimeoutMs);
+        });
+        try {
+            const tools = await Promise.race([listing, timedOut]);
+            if (tools === "timed_out") {
+                console.warn(`tool source ${index} listed nothing within ${this.listingTimeoutMs} ms`);
+                return [];
+            }
+            this.lastListings.set(index, tools);
+            return tools;
+        }
+        catch (error) {
+            console.warn(`tool source ${index} could not list its tools: ${error instanceof Error ? error.message : String(error)}`);
+            return [];
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    requireToolSource(toolCall) {
+        const routed = this.routeToToolSource(toolCall);
+        if (routed === undefined) {
+            throw new RangeError(`no tool source built the call of tool ${toolCall.toolName}`);
+        }
+        return routed;
+    }
+    routeToToolSource(toolCall) {
+        const envelope = readToolSourceEnvelope(this.sourceNameKey, toolCall.toolSourceReference);
+        if (envelope !== undefined) {
+            const source = this.toolSourcesByName.get(envelope.sourceName);
+            if (source === undefined) {
+                throw new RangeError(`tool source ${envelope.sourceName}, which built the call of tool ${toolCall.toolName}, is not configured on this Worker`);
+            }
+            return { source, reference: envelope.reference };
+        }
+        const reference = toolCall.toolSourceReference ?? undefined;
+        if (reference === undefined || this.toolSources.length === 0) {
+            return undefined;
+        }
+        const onlySource = this.toolSources.length === 1 ? this.toolSources[0] : undefined;
+        if (onlySource !== undefined) {
+            // A reference the source built itself, such as in a runner subclass.
+            return { source: onlySource, reference };
+        }
+        throw new RangeError(`cannot tell which tool source built the call of ${toolCall.toolName}`);
+    }
+}
+/**
+ * The router's `toolSourceReference`: the source's name under `sourceNameKey` and its own reference, as JSON text.
+ * @param sourceNameKey - The envelope key of the runner.
+ * @param sourceName - The building source's name.
+ * @param reference - The source's own reference, or `undefined`.
+ * @returns The envelope text.
+ */
+export function writeToolSourceEnvelope(sourceNameKey, sourceName, reference) {
+    return JSON.stringify({ [sourceNameKey]: sourceName, [toolSourceReferenceKey]: reference ?? null });
+}
+/**
+ * Reads an envelope that {@link writeToolSourceEnvelope} wrote with the same key.
+ * @param sourceNameKey - The envelope key of the runner.
+ * @param toolSourceReference - A record's `toolSourceReference`.
+ * @returns The source's name and its own reference, or `undefined` when the text is no such envelope.
+ */
+export function readToolSourceEnvelope(sourceNameKey, toolSourceReference) {
+    if (toolSourceReference === undefined || toolSourceReference === null) {
+        return undefined;
+    }
+    let envelope;
+    try {
+        envelope = JSON.parse(toolSourceReference);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) {
+        return undefined;
+    }
+    const sourceName = envelope[sourceNameKey];
+    const reference = envelope[toolSourceReferenceKey];
+    if (typeof sourceName !== "string") {
+        return undefined;
+    }
+    if (reference !== null && reference !== undefined && typeof reference !== "string") {
+        return undefined;
+    }
+    return { sourceName, reference: reference ?? undefined };
+}
+/** The record as the source built it: its own reference instead of the router's envelope. */
+function withToolSourceReference(toolCall, reference) {
+    const { toolSourceReference: _envelope, ...rest } = toolCall;
+    return (reference === undefined ? rest : { ...rest, toolSourceReference: reference });
+}
+//# sourceMappingURL=tool-source-router.js.map

package/dist/src/tool-source-router.js.map

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

package/dist/src/ui-stream/agent-event-sse.d.ts

@@ -63,8 +63,9 @@ export declare function formatAgentEventSseFrame(message: StreamMessage<AgentEve
  * Each event becomes one frame whose `id` is its Dex resume token and whose data is the `AgentEvent` wire
  * JSON: `type`, `turn_id`, `attempt`, `step_execution_id`, and `payload` text. Reconnecting with the last
  * `id` continues with the next event, with no repeated or missing event while the Stream retains them.
- * After each empty long poll it yields a keep-alive comment. The stream never ends on its own; stop
- * iterating, or abort `signal`, when the browser goes away.
+ * After each empty long poll it yields a keep-alive comment. The stream ends on its own only once the
+ * session's Flow failed and every event was sent; otherwise stop iterating, or abort `signal`, when the
+ * browser goes away.
  *
  * The browser applies the event rules of the session contract. Within one `step_execution_id` it keeps
  * only the highest `attempt` and drops the partial text of lower attempts. After `turn_completed`,