@superdurable/dex-agents 0.3.0 → 0.5.0

package/dist/src/builtin-loop/json-schema-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-validation.js","sourceRoot":"","sources":["../../../src/builtin-loop/json-schema-validation.ts"],"names":[],"mappings":"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"}

package/dist/src/{stepwise → builtin-loop}/model-client.d.ts

@@ -1,13 +1,21 @@
-import type { AgentUsage } from "../agent-session-values.js";
+import type { AgentImageReference, AgentUsage } from "../agent-session-values.js";
 /**
  * User text in a model input, stored for a user message and for Dex notes such as the turn-failure note.
- * Wire shape: `{"type":"user_text","text"}`.
+ * Wire shape: `{"type":"user_text","text"}`, plus `"images"` when the message has images.
  */
 export interface ModelUserTextItem {
     /** Discriminator. Wire field: `type`. */
     readonly type: "user_text";
     /** The text. Wire field: `text`. */
     readonly text: string;
+    /**
+     * The images of a user message, after the text, in order. The item holds references only; the request's
+     * {@link ModelRequest.imageBytes} holds their bytes. Omitted or empty for a message without images and for every
+     * note Dex adds. Wire field: `images`, a list of snake_case image references, written only when non-empty.
+     *
+     * @since 0.5.0
+     */
+    readonly images?: readonly AgentImageReference[];
 }
 /** One tool call of a model response, in provider-neutral form. */
 export interface ModelToolCall {
@@ -44,7 +52,8 @@ export interface ModelOutputItem {
 }
 /**
  * The result of one tool call in a model input, in provider-neutral form.
- * Wire shape: `{"type":"tool_result","tool_call_id","tool_name","output"}`.
+ * Wire shape: `{"type":"tool_result","tool_call_id","tool_name","output"}`, plus `"images"` when the tool returned
+ * images.
  */
 export interface ModelToolResultItem {
     /** Discriminator. Wire field: `type`. */
@@ -55,9 +64,17 @@ export interface ModelToolResultItem {
     readonly toolName: string;
     /** Model-visible result text, from `describeToolCallOutcome`. Wire field: `output`. */
     readonly output: string;
+    /**
+     * The images the tool returned with {@link output}, from `AgentToolCall.images`, in order. The item holds
+     * references only; the request's {@link ModelRequest.imageBytes} holds their bytes. Wire field: `images`, written
+     * only when non-empty.
+     *
+     * @since 0.5.0
+     */
+    readonly images?: readonly AgentImageReference[];
 }
 /**
- * One item of a model input. The Stepwise runner stores each one as the `framework_item` of an
+ * One item of a model input. The built-in loop runner stores each one as the `framework_item` of an
  * `AgentMessage`, as snake_case JSON.
  */
 export type ModelInputItem = ModelUserTextItem | ModelOutputItem | ModelToolResultItem;
@@ -99,7 +116,7 @@ export interface ModelRequestMetadata {
     /** One-based attempt of the `RunModel` Step. */
     readonly attempt: number;
 }
-/** One model call, built by the Stepwise runner from committed session state only. */
+/** One model call, built by the built-in loop runner from committed session state only. */
 export interface ModelRequest {
     /** System instructions for this call. */
     readonly instructions: string;
@@ -115,6 +132,14 @@ export interface ModelRequest {
     readonly metadata: ModelRequestMetadata;
     /** Signal aborted when Dex cancels the attempt; pass it to the provider request. */
     readonly cancellationSignal: AbortSignal;
+    /**
+     * The bytes of every image of {@link inputItems}, keyed by `AgentImageReference.sha256`. The runner reads them
+     * from its media store right before `callModel`, so a client never reads a store. Omitted when the input has no
+     * images, and in the requests passed to `estimateInputTokens`, which count each image without its bytes.
+     *
+     * @since 0.5.0
+     */
+    readonly imageBytes?: ReadonlyMap<string, Uint8Array>;
 }
 /** Result of one model call. */
 export interface ModelResponse {
@@ -131,7 +156,7 @@ export interface ModelResponse {
     /** Provider finish reason, such as `"stop"` or `"tool-calls"`. */
     readonly finishReason: string;
 }
-/** Receives the live text of one model call; the Stepwise runner forwards it to `AgentEvents`. */
+/** Receives the live text of one model call; the built-in loop runner forwards it to `AgentEvents`. */
 export interface ModelOutputWriter {
     /**
      * Writes visible text as a `text_delta` event.
@@ -145,7 +170,7 @@ export interface ModelOutputWriter {
     writeReasoningDelta(text: string): void;
 }
 /**
- * Makes one model call for the Stepwise runner.
+ * Makes one model call for the built-in loop runner.
  *
  * Use `createAiSdkModelClient` from `@superdurable/dex-agents/ai-sdk` for any AI SDK provider, or
  * implement this interface for another model API. Every client follows these rules:
@@ -158,6 +183,10 @@ export interface ModelOutputWriter {
  *   thinking signatures or encrypted reasoning, from display text.
  * - Dex-authored items, {@link ModelUserTextItem} and {@link ModelToolResultItem}, are converted at call
  *   time. An item from another provider or API is replayed as its text and tool calls.
+ * - Images. A user text or tool result item may carry `images`. A client that sends images converts each one to
+ *   the provider's image part, with its bytes from {@link ModelRequest.imageBytes}, and throws when they are
+ *   missing. A client that ignores `images` shows the model the text only. The runner sends images only when it
+ *   has a media store; see `BuiltinLoopAgentRunner`.
  *
  * @example
  * ```ts

package/dist/src/builtin-loop/model-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-client.js","sourceRoot":"","sources":["../../../src/builtin-loop/model-client.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D"}

package/dist/src/{stepwise → builtin-loop}/scripted-model-client.d.ts

@@ -29,12 +29,12 @@ export interface ScriptedModelReply {
 /** The script: a function from the whole request to the reply. */
 export type ScriptedModelResponder = (request: ModelRequest) => ScriptedModelReply | Promise<ScriptedModelReply>;
 /**
- * A Stepwise {@link ModelClient} that answers every model call from a script, for demos and tests without a
+ * A built-in agent loop {@link ModelClient} that answers every model call from a script, for demos and tests without a
  * model key. It mirrors the Python core's `ScriptedModelClient`.
  *
- * Use it as `AgentDefinition.model` to run a Stepwise agent with no provider account: a local demo
+ * Use it as `AgentDefinition.model` to run a built-in loop agent with no provider account: a local demo
  * mode of an application, a tutorial, or an integration test. It is a supported part of
- * `@superdurable/dex-agents/stepwise` and needs no optional peer. `@superdurable/dex-agents/testing`
+ * `@superdurable/dex-agents/builtin-loop` and needs no optional peer. `@superdurable/dex-agents/testing`
  * exports the same class.
  *
  * The script is a function of the whole {@link ModelRequest}, so it can read the user text, with
@@ -50,7 +50,7 @@ export type ScriptedModelResponder = (request: ModelRequest) => ScriptedModelRep
  *   ScriptedModelClient.toolResults(request).length > 0
  *     ? { text: "done" }
  *     : { toolCalls: [{ toolName: "lookup_order", arguments: { order_id: "7" } }] });
- * const flow = createStepwiseAgentSessionFlow(
+ * const flow = createBuiltinAgentSessionFlow(
  *   { name: "demo", instructions: "Help.", model, tools: [lookupOrder] }, "DemoAgent");
  * ```
  */
@@ -92,8 +92,11 @@ export declare class ScriptedModelClient implements ModelClient {
     static userTexts(request: ModelRequest): string[];
     /**
      * Returns the tool results after the last user item of a request.
+     *
+     * A continuation message from `decideTurnContinuation` is a user item too. After one, this returns only the
+     * results that follow it, so a script that decides from these results must also read the earlier ones itself.
      * @param request - The request.
-     * @returns The current turn's tool results, oldest first.
+     * @returns The tool results after the last user item, oldest first.
      */
     static toolResults(request: ModelRequest): ModelToolResultItem[];
 }

package/dist/src/{stepwise → builtin-loop}/scripted-model-client.js

@@ -13,12 +13,12 @@ export const scriptedModelApi = "scripted";
 /** Default number of latest requests {@link ScriptedModelClient.requests} keeps. */
 export const defaultMaxRecordedRequests = 100;
 /**
- * A Stepwise {@link ModelClient} that answers every model call from a script, for demos and tests without a
+ * A built-in agent loop {@link ModelClient} that answers every model call from a script, for demos and tests without a
  * model key. It mirrors the Python core's `ScriptedModelClient`.
  *
- * Use it as `AgentDefinition.model` to run a Stepwise agent with no provider account: a local demo
+ * Use it as `AgentDefinition.model` to run a built-in loop agent with no provider account: a local demo
  * mode of an application, a tutorial, or an integration test. It is a supported part of
- * `@superdurable/dex-agents/stepwise` and needs no optional peer. `@superdurable/dex-agents/testing`
+ * `@superdurable/dex-agents/builtin-loop` and needs no optional peer. `@superdurable/dex-agents/testing`
  * exports the same class.
  *
  * The script is a function of the whole {@link ModelRequest}, so it can read the user text, with
@@ -34,7 +34,7 @@ export const defaultMaxRecordedRequests = 100;
  *   ScriptedModelClient.toolResults(request).length > 0
  *     ? { text: "done" }
  *     : { toolCalls: [{ toolName: "lookup_order", arguments: { order_id: "7" } }] });
- * const flow = createStepwiseAgentSessionFlow(
+ * const flow = createBuiltinAgentSessionFlow(
  *   { name: "demo", instructions: "Help.", model, tools: [lookupOrder] }, "DemoAgent");
  * ```
  */
@@ -127,8 +127,11 @@ export class ScriptedModelClient {
     }
     /**
      * Returns the tool results after the last user item of a request.
+     *
+     * A continuation message from `decideTurnContinuation` is a user item too. After one, this returns only the
+     * results that follow it, so a script that decides from these results must also read the earlier ones itself.
      * @param request - The request.
-     * @returns The current turn's tool results, oldest first.
+     * @returns The tool results after the last user item, oldest first.
      */
     static toolResults(request) {
         let results = [];

package/dist/src/builtin-loop/scripted-model-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripted-model-client.js","sourceRoot":"","sources":["../../../src/builtin-loop/scripted-model-client.ts"],"names":[],"mappings":"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"}

package/dist/src/{stepwise → builtin-loop}/tool-source.d.ts

@@ -1,4 +1,5 @@
-import type { AgentTurnContext, DeferredToolCall, DeferredToolExecution, DeferredToolOutcome, ToolTaskCancellation, ToolTaskPoll, ToolTaskPollOutcome } from "../agent-framework-runner.js";
+import type { AgentTurnContext, DeferredToolCall, DeferredToolExecution, DeferredToolOutcome, ToolCallStepOptions, ToolTaskCancellation, ToolTaskPoll, ToolTaskPollOutcome } from "../agent-framework-runner.js";
+import type { AgentToolCall } from "../agent-session-values.js";
 /**
  * One tool that a {@link ToolSource} lists, as the model sees it. `McpTool` satisfies it; the runner reads only
  * these three fields.
@@ -15,7 +16,7 @@ export interface SourceToolDefinition {
     readonly inputSchema: Readonly<Record<string, unknown>>;
 }
 /**
- * Tools that a Stepwise agent lists at run time, such as an MCP server's tools, run one tool Step per call.
+ * Tools that a built-in loop agent lists at run time, such as an MCP server's tools, run one tool Step per call.
  *
  * Put a source in `AgentDefinition.toolSources`. `McpToolSource` from `@superdurable/dex-agents/mcp`
  * implements it. In every `RunModel` of a chat or executing turn, the runner awaits {@link listTools} and
@@ -38,7 +39,7 @@ export interface SourceToolDefinition {
  * @example
  * ```ts
  * const tools = new McpToolSource([{ name: "files", transport: "stdio", command: "mcp-files" }]);
- * const flow = createStepwiseAgentSessionFlow(
+ * const flow = createBuiltinAgentSessionFlow(
  *   { name: "files", instructions: "You manage reports.", model, toolSources: [tools] },
  *   "FilesAgent",
  * );
@@ -100,4 +101,13 @@ export interface ToolSource {
      * @returns A Promise that resolves once the remote system took the cancellation.
      */
     cancelToolTask?(cancellation: ToolTaskCancellation): Promise<void>;
+    /**
+     * Optional: the timeout and retry policy of one call's tool Step, or `undefined` for the defaults, as
+     * {@link AgentFrameworkRunner.toolCallStepOptions} describes. `ConnectorToolSource` uses it for each
+     * operation's timeout and retry policy.
+     * @param toolCall - The record whose tool Step starts, with this source's own reference.
+     * @returns The options, or `undefined`.
+     * @since 0.4.0
+     */
+    toolCallStepOptions?(toolCall: AgentToolCall): ToolCallStepOptions | undefined;
 }

package/dist/src/builtin-loop/tool-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-source.js","sourceRoot":"","sources":["../../../src/builtin-loop/tool-source.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D"}

package/dist/src/connectors/connector-input-schema.d.ts

@@ -0,0 +1,19 @@
+type JsonSchema = Readonly<Record<string, unknown>>;
+/**
+ * Throws when a schema uses a keyword the agent core cannot enforce.
+ * @param schema - A Connector operation's `inputSchema`.
+ * @throws {TypeError} When the schema is not an object schema, uses an unknown keyword or type, or has a `$ref`
+ * outside `#/$defs/`.
+ */
+export declare function checkConnectorInputSchema(schema: JsonSchema): void;
+/**
+ * Returns the first way the arguments break the schema, such as `arguments.amount must be integer`, or
+ * `undefined`. The texts match the Python core.
+ * @param value - The decoded JSON arguments.
+ * @param schema - A schema that {@link checkConnectorInputSchema} accepted.
+ * @returns The violation text, or `undefined`.
+ */
+export declare function findConnectorInputViolation(value: unknown, schema: JsonSchema): string | undefined;
+/** Orders keys by code point, as Python's `sorted` does. */
+export declare function compareCodePoints(left: string, right: string): number;
+export {};

package/dist/src/connectors/connector-input-schema.js

@@ -0,0 +1,228 @@
+// 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
+// Checks the JSON Schema subset of Connector `inputSchema` values with the Python core's messages.
+import { serializeJsonWithSpacedSeparators } from "../builtin-loop/json-schema-validation.js";
+// Keywords that constrain a value; an unlisted keyword refuses the tool, so nothing is unchecked.
+const checkedKeywords = new Set([
+    "type",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "enum",
+    "anyOf",
+    "$ref",
+    "$defs",
+    "minimum",
+    "maximum",
+]);
+// Annotations: format is an annotation in draft 2020-12, and the operation's validator checks it.
+const annotationKeywords = new Set([
+    "description",
+    "title",
+    "format",
+    "contentEncoding",
+    "default",
+    "$schema",
+    "$id",
+    "examples",
+]);
+const jsonTypes = new Set(["string", "boolean", "null", "array", "object", "number", "integer"]);
+const definitionsPrefix = "#/$defs/";
+/**
+ * Throws when a schema uses a keyword the agent core cannot enforce.
+ * @param schema - A Connector operation's `inputSchema`.
+ * @throws {TypeError} When the schema is not an object schema, uses an unknown keyword or type, or has a `$ref`
+ * outside `#/$defs/`.
+ */
+export function checkConnectorInputSchema(schema) {
+    if (schema["type"] !== "object") {
+        throw new TypeError("inputSchema must have type object");
+    }
+    const definitions = schema["$defs"] ?? {};
+    if (!isRecord(definitions)) {
+        throw new TypeError("inputSchema $defs must be an object");
+    }
+    checkNode(schema, definitions, "inputSchema");
+}
+function checkNode(node, definitions, path) {
+    if (!isRecord(node)) {
+        throw new TypeError(`${path} must be a schema object`);
+    }
+    for (const [keyword, value] of Object.entries(node)) {
+        if (annotationKeywords.has(keyword)) {
+            continue;
+        }
+        if (!checkedKeywords.has(keyword)) {
+            throw new TypeError(`${path} uses ${keyword}, which agent tools do not check`);
+        }
+        if (keyword === "type") {
+            const names = typeof value === "string" ? [value] : value;
+            if (!Array.isArray(names) || names.some((name) => typeof name !== "string" || !jsonTypes.has(name))) {
+                throw new TypeError(`${path}.type is not a JSON type`);
+            }
+        }
+        else if (keyword === "properties" || keyword === "$defs") {
+            if (!isRecord(value)) {
+                throw new TypeError(`${path}.${keyword} must be an object`);
+            }
+            for (const [name, child] of Object.entries(value)) {
+                checkNode(child, definitions, `${path}.${keyword}.${name}`);
+            }
+        }
+        else if (keyword === "items" || (keyword === "additionalProperties" && typeof value !== "boolean")) {
+            checkNode(value, definitions, `${path}.${keyword}`);
+        }
+        else if (keyword === "anyOf") {
+            if (!Array.isArray(value) || value.length === 0) {
+                throw new TypeError(`${path}.anyOf must be a non-empty array`);
+            }
+            value.forEach((child, index) => checkNode(child, definitions, `${path}.anyOf[${index}]`));
+        }
+        else if (keyword === "$ref") {
+            if (typeof value !== "string" || !value.startsWith(definitionsPrefix)) {
+                throw new TypeError(`${path}.$ref must point into #/$defs/`);
+            }
+            if (!Object.hasOwn(definitions, value.slice(definitionsPrefix.length))) {
+                throw new TypeError(`${path}.$ref names a missing definition`);
+            }
+        }
+        else if (keyword === "required" && (!Array.isArray(value) || value.some((name) => typeof name !== "string"))) {
+            throw new TypeError(`${path}.required must be an array of names`);
+        }
+        else if (keyword === "enum" && !Array.isArray(value)) {
+            throw new TypeError(`${path}.enum must be an array`);
+        }
+    }
+}
+/**
+ * Returns the first way the arguments break the schema, such as `arguments.amount must be integer`, or
+ * `undefined`. The texts match the Python core.
+ * @param value - The decoded JSON arguments.
+ * @param schema - A schema that {@link checkConnectorInputSchema} accepted.
+ * @returns The violation text, or `undefined`.
+ */
+export function findConnectorInputViolation(value, schema) {
+    const definitions = schema["$defs"];
+    return findViolation(value, schema, isRecord(definitions) ? definitions : {}, "arguments");
+}
+function findViolation(value, schema, definitions, path) {
+    const reference = schema["$ref"];
+    if (typeof reference === "string") {
+        const problem = findViolation(value, definitions[reference.slice(definitionsPrefix.length)], definitions, path);
+        if (problem !== undefined) {
+            return problem;
+        }
+    }
+    const anyOf = schema["anyOf"];
+    if (Array.isArray(anyOf) &&
+        anyOf.every((option) => findViolation(value, option, definitions, path) !== undefined)) {
+        return `${path} matches none of the allowed types`;
+    }
+    const expected = schema["type"];
+    if (expected !== undefined) {
+        const expectedTypes = (typeof expected === "string" ? [expected] : expected).map(String);
+        if (!expectedTypes.some((type) => matchesJsonType(type, value))) {
+            return `${path} must be ${expectedTypes.join(" or ")}`;
+        }
+    }
+    const allowedValues = schema["enum"];
+    if (Array.isArray(allowedValues) && !allowedValues.some((allowed) => isJsonEqual(value, allowed))) {
+        return `${path} must be one of ${serializeJsonWithSpacedSeparators(allowedValues)}`;
+    }
+    if (isRecord(value)) {
+        return findObjectViolation(value, schema, definitions, path);
+    }
+    const items = schema["items"];
+    if (Array.isArray(value) && isRecord(items)) {
+        for (const [index, item] of value.entries()) {
+            const problem = findViolation(item, items, definitions, `${path}[${index}]`);
+            if (problem !== undefined) {
+                return problem;
+            }
+        }
+    }
+    if (typeof value === "number") {
+        if (typeof schema["minimum"] === "number" && value < schema["minimum"]) {
+            return `${path} must be at least ${schema["minimum"]}`;
+        }
+        if (typeof schema["maximum"] === "number" && value > schema["maximum"]) {
+            return `${path} must be at most ${schema["maximum"]}`;
+        }
+    }
+    return undefined;
+}
+function findObjectViolation(value, schema, definitions, path) {
+    const properties = (schema["properties"] ?? {});
+    for (const name of (schema["required"] ?? [])) {
+        if (!Object.hasOwn(value, name)) {
+            return `${path}.${name} is required`;
+        }
+    }
+    const additional = schema["additionalProperties"] ?? true;
+    for (const name of Object.keys(value).sort(compareCodePoints)) {
+        const item = value[name];
+        let problem;
+        if (Object.hasOwn(properties, name)) {
+            problem = findViolation(item, properties[name] ?? {}, definitions, `${path}.${name}`);
+        }
+        else if (additional === false) {
+            problem = `${path}.${name} is not allowed`;
+        }
+        else if (isRecord(additional)) {
+            problem = findViolation(item, additional, definitions, `${path}.${name}`);
+        }
+        if (problem !== undefined) {
+            return problem;
+        }
+    }
+    return undefined;
+}
+/** JSON equality: booleans never equal numbers, and `1` equals `1.0`. */
+function isJsonEqual(left, right) {
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((item, index) => isJsonEqual(item, right[index])));
+    }
+    if (isRecord(left) && isRecord(right)) {
+        const leftKeys = Object.keys(left);
+        return (leftKeys.length === Object.keys(right).length &&
+            leftKeys.every((key) => Object.hasOwn(right, key) && isJsonEqual(left[key], right[key])));
+    }
+    return left === right;
+}
+function matchesJsonType(type, value) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        case "array":
+            return Array.isArray(value);
+        case "object":
+            return isRecord(value);
+        case "number":
+            return typeof value === "number";
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        default:
+            throw new TypeError(`unsupported JSON Schema type ${type}`);
+    }
+}
+/** Orders keys by code point, as Python's `sorted` does. */
+export function compareCodePoints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=connector-input-schema.js.map

package/dist/src/connectors/connector-input-schema.js.map

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

package/dist/src/connectors/connector-step-context.d.ts

@@ -0,0 +1,94 @@
+import type { AsyncContext } from "@superdurable/dex";
+/** What one call's saved fence markers in this attempt prove; a later checkpoint cannot erase it. Internal. */
+export interface FenceEvidence {
+    /** A claim stands: no valid `canResend` followed it. */
+    isClaimed: boolean;
+    /** The attempt claimed a send at some point. */
+    hasClaimed: boolean;
+    /** A claim recorded a provider ID. */
+    hasProviderId: boolean;
+    /** A `notSent` before any claim, or a valid `canResend`. */
+    hasNotSentProof: boolean;
+}
+/** Returns the evidence of one call's saved fence markers in this attempt, or `undefined`. Internal to the core. */
+export declare function readFenceEvidence(context: ConnectorStepContext, callId: string): Readonly<FenceEvidence> | undefined;
+/** Reports whether a value is a single-dispatch fence marker with only its declared fields. Internal to the core. */
+export declare function isFenceMarker(value: unknown): value is Readonly<Record<string, unknown>>;
+/** Returns the text checkpoint an earlier attempt saved, or `undefined`. Internal to the core. */
+export declare function readPreviousCheckpoint(context: ConnectorStepContext): string | undefined;
+/** Reports whether the operation asked this context for an earlier attempt's checkpoint. Internal to the core. */
+export declare function hasReadCheckpoint(context: ConnectorStepContext): boolean;
+/** How a {@link ConnectorStepContext} reaches the tool Step's heartbeats. */
+export interface ConnectorStepHeartbeats {
+    /** The text checkpoint an earlier attempt of the tool Step saved, or `undefined`. */
+    readonly previousCheckpoint: string | undefined;
+    /**
+     * Records a plain heartbeat, which repeats the attempt's saved checkpoint.
+     * @returns A Promise that resolves when the Worker accepted the heartbeat.
+     */
+    heartbeat(): Promise<void>;
+    /**
+     * Records a heartbeat carrying a text checkpoint; absent when the tool Step cannot save checkpoints.
+     * @param checkpoint - The text to hand to the next attempt.
+     * @returns A Promise that resolves when the Worker accepted the heartbeat.
+     */
+    saveCheckpoint?(checkpoint: string): Promise<void>;
+}
+/**
+ * The Step context a connector operation sees inside an agent tool Step, with heartbeat values kept as text.
+ *
+ * The single-dispatch fence records markers as heartbeat values and reads the previous attempt's marker back. The
+ * agent session's tool Step keeps one text checkpoint per attempt and repeats it on every background heartbeat.
+ * This context stores each heartbeat value as that text checkpoint, as JSON with sorted keys, and parses it on the
+ * next attempt, so a marker survives the session's own heartbeats and a retry can read it. It exposes only the
+ * members the fence uses, plus the identities a Call needs; the agent core's conformance tests pin that list.
+ *
+ * `ConnectorToolSource` builds one per tool Step attempt. Applications do not construct it.
+ * @since 0.4.0
+ */
+export declare class ConnectorStepContext {
+    private readonly context;
+    private readonly heartbeats;
+    /**
+     * Creates the context for one tool Step attempt.
+     * @param context - The tool Step's live context.
+     * @param heartbeats - The tool Step's checkpoint and heartbeat functions.
+     */
+    constructor(context: AsyncContext, heartbeats: ConnectorStepHeartbeats);
+    /** The Flow ID. */
+    get flowId(): string;
+    /** The Flow run ID. */
+    get runId(): string;
+    /** The tool Step's execution ID, the same on every attempt. */
+    get stepExecutionId(): string;
+    /** The one-based attempt. */
+    get attempt(): number;
+    /** The attempt's deadline, or `undefined`. */
+    get deadline(): Date | undefined;
+    /** The signal Dex aborts when it cancels the attempt. */
+    get cancellationSignal(): AbortSignal;
+    /**
+     * Reports whether an earlier attempt of this tool Step saved a heartbeat value.
+     * @returns `true` when the session read a checkpoint for this attempt.
+     */
+    hasLastHeartbeatValue(): boolean;
+    /**
+     * Parses the earlier attempt's heartbeat value from its JSON text.
+     * @param codec - Must be omitted; values are JSON.
+     * @returns The parsed value, or `undefined` when there is none.
+     * @throws {TypeError} When a codec is given.
+     * @throws {SyntaxError} When the checkpoint is not JSON.
+     */
+    getLastHeartbeatValue<T = unknown>(codec?: unknown): T | undefined;
+    /**
+     * Records a heartbeat, saving a value as the attempt's text checkpoint.
+     * @param value - The heartbeat value, such as a fence marker; `undefined` records a plain heartbeat, which
+     * repeats the saved checkpoint.
+     * @param codec - Must be omitted; values are JSON.
+     * @returns A Promise that resolves when the Worker accepted the heartbeat.
+     * @throws {TypeError} When a codec is given, or a value is given and the tool Step cannot save checkpoints.
+     */
+    recordHeartbeat<T>(value?: T, codec?: unknown): Promise<void>;
+}
+/** Returns compact JSON with object keys sorted by code point, the text the Python core stores. */
+export declare function stringifyWithSortedKeys(value: unknown): string;