@superdurable/dex-agents 0.2.0 → 0.4.0

package/dist/src/connectors/connector-step-context.js

@@ -0,0 +1,124 @@
+// 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 { compareCodePoints } from "./connector-input-schema.js";
+// The source reads it on a Retry; a failed save leaves the earlier value.
+const savedHeartbeatValues = new WeakMap();
+/** Returns the last heartbeat value this context saved in this attempt, or `undefined`. Internal to the core. */
+export function readSavedHeartbeatValue(context) {
+    return savedHeartbeatValues.get(context);
+}
+/**
+ * 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 class ConnectorStepContext {
+    context;
+    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, heartbeats) {
+        this.context = context;
+        this.heartbeats = heartbeats;
+    }
+    /** The Flow ID. */
+    get flowId() {
+        return this.context.flowId;
+    }
+    /** The Flow run ID. */
+    get runId() {
+        return this.context.runId;
+    }
+    /** The tool Step's execution ID, the same on every attempt. */
+    get stepExecutionId() {
+        return this.context.stepExecutionId;
+    }
+    /** The one-based attempt. */
+    get attempt() {
+        return this.context.attempt;
+    }
+    /** The attempt's deadline, or `undefined`. */
+    get deadline() {
+        return this.context.deadline;
+    }
+    /** The signal Dex aborts when it cancels the attempt. */
+    get cancellationSignal() {
+        return this.context.cancellationSignal;
+    }
+    /**
+     * 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() {
+        return this.heartbeats.previousCheckpoint !== undefined;
+    }
+    /**
+     * 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(codec) {
+        if (codec !== undefined) {
+            throw new TypeError("ConnectorStepContext keeps heartbeat values as JSON and takes no codec");
+        }
+        const previous = this.heartbeats.previousCheckpoint;
+        return previous === undefined ? undefined : JSON.parse(previous);
+    }
+    /**
+     * 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.
+     */
+    async recordHeartbeat(value, codec) {
+        if (codec !== undefined) {
+            throw new TypeError("ConnectorStepContext keeps heartbeat values as JSON and takes no codec");
+        }
+        if (value === undefined) {
+            await this.heartbeats.heartbeat();
+            return;
+        }
+        if (this.heartbeats.saveCheckpoint === undefined) {
+            throw new TypeError("this tool Step cannot save heartbeat checkpoints");
+        }
+        await this.heartbeats.saveCheckpoint(stringifyWithSortedKeys(value));
+        savedHeartbeatValues.set(this, value);
+    }
+}
+/** Returns compact JSON with object keys sorted by code point, the text the Python core stores. */
+export function stringifyWithSortedKeys(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    if (typeof value === "object" && value !== null) {
+        const record = value;
+        return Object.fromEntries(Object.keys(record)
+            .filter((key) => record[key] !== undefined)
+            .sort(compareCodePoints)
+            .map((key) => [key, sortKeys(record[key])]));
+    }
+    return value;
+}
+//# sourceMappingURL=connector-step-context.js.map

package/dist/src/connectors/connector-step-context.js.map

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

package/dist/src/connectors/connector-tool-source.d.ts

@@ -0,0 +1,353 @@
+import type { RetryPolicy } from "@superdurable/dex";
+import { type Call, type ConnectionRef, type Mutation, type Query, type QueryResult } from "@superdurable/connectors-sdk";
+import { type AgentTurnContext, type DeferredToolCall, type DeferredToolExecution, type ToolCallStepOptions, type ToolExecutionResult, type ToolTaskPoll, type ToolTaskPollOutcome } from "../agent-framework-runner.js";
+import type { AgentToolCall, ToolEffect } from "../agent-session-values.js";
+import type { SourceToolDefinition, ToolSource } from "../stepwise/tool-source.js";
+import { ConnectorStepContext } from "./connector-step-context.js";
+/**
+ * Default {@link ConnectorToolSource.sourceName}.
+ * @since 0.4.0
+ */
+export declare const defaultConnectorSourceName = "connectors";
+/**
+ * Default bound, in bytes of UTF-8 text, on the result one connector tool call gives the model: 64 KiB.
+ * @since 0.4.0
+ */
+export declare const defaultConnectorResultMaxBytes: number;
+/**
+ * Note appended to a truncated result; `{total_bytes}` is the size of the full result. The same text as the
+ * Python core.
+ * @since 0.4.0
+ */
+export declare const connectorResultTruncatedNote = "[Dex] truncated, {total_bytes} bytes";
+/**
+ * Error text of a single-attempt write whose fence proved no send before the connector's Retry; the same text as
+ * the Python core.
+ * @since 0.4.0
+ */
+export declare const connectorNotSentRetryLater = "not sent; the provider asked to retry later";
+/**
+ * Decides from a call's decoded JSON arguments whether that call waits for approval.
+ * @since 0.4.0
+ */
+export type ApprovalPredicate = (toolArguments: Readonly<Record<string, unknown>>) => boolean;
+/**
+ * What a connector tool call records for the branch its operation selected.
+ *
+ * - `succeeded`: a required branch, such as `sent` or `refunded`. The model reads the result value.
+ * - `rejected`: a branch the manifest lists as `rejected` under `agent.branches`, such as `providerRejected`.
+ *   Nothing took effect. The record is `failed` with an error the model reads, and the session continues.
+ * - `failed`: `defect`, or an optional branch of a Query that `agent.branches` does not list.
+ * - `outcome_unknown`: `uncertain`, a branch listed as `unknown`, or an optional branch of a Mutation that
+ *   `agent.branches` does not list. The write may have taken effect.
+ * @since 0.4.0
+ */
+export type ConnectorBranchOutcome = "succeeded" | "rejected" | "failed" | "outcome_unknown";
+/**
+ * The validator a Connector package exports for an operation's input, such as `CreateRefundInputSchema`. A zod
+ * schema satisfies it.
+ * @since 0.4.0
+ */
+export interface ConnectorInputValidator<Input> {
+    /**
+     * Checks and converts decoded JSON arguments into the operation's input.
+     * @param value - The decoded arguments.
+     * @returns `success` and the input, or `success: false`.
+     */
+    safeParse(value: unknown): {
+        readonly success: true;
+        readonly data: Input;
+    } | {
+        readonly success: false;
+    };
+}
+/**
+ * The parts of a Connector package's `dex-connector.json` that `connectorTool` reads.
+ * @since 0.4.0
+ */
+export interface ConnectorPackageManifest {
+    /** The Connector ID, such as `stripe`. */
+    readonly connectorId: string;
+    /** One entry per operation. */
+    readonly factories: readonly ConnectorManifestFactory[];
+}
+/**
+ * One operation's entry in `dex-connector.json`.
+ * @since 0.4.0
+ */
+export interface ConnectorManifestFactory {
+    /** `query` or `mutation`. */
+    readonly kind: string;
+    /** The operation ID, such as `createRefund`. */
+    readonly operationId: string;
+    /** The input type's name, such as `CreateRefundInput`. */
+    readonly inputType?: string;
+    /** Model-facing description. */
+    readonly description?: string;
+    /** The JSON Schema of the input. */
+    readonly inputSchema?: Readonly<Record<string, unknown>>;
+    /** The agent review: `exposed`, `approval`, `retry`, and `branches`. */
+    readonly agent?: {
+        readonly exposed?: unknown;
+        readonly approval?: unknown;
+        readonly retry?: unknown;
+        readonly branches?: unknown;
+    };
+}
+/**
+ * Options of {@link connectorTool}.
+ * @typeParam Input - The operation's input type.
+ * @since 0.4.0
+ */
+export interface ConnectorToolOptions<Input> {
+    /**
+     * The package's parsed `dex-connector.json`, such as
+     * `import manifest from "@superdurable/connector-stripe/dex-connector.json" with { type: "json" }`.
+     */
+    readonly manifest: ConnectorPackageManifest;
+    /** The validator the package exports for the operation's input, such as `CreateRefundInputSchema`. */
+    readonly inputValidator: ConnectorInputValidator<Input>;
+    /** Tool name; defaults to `<connectorId>_<operation in snake case>`, such as `stripe_create_refund`. */
+    readonly name?: string;
+    /** Model-facing description; defaults to the manifest's. */
+    readonly description?: string;
+    /**
+     * `true` or `false` overrides the manifest's `agent.approval` for every call; a predicate decides per call from
+     * the decoded JSON arguments, and a predicate that throws requires approval. Omit it to follow the manifest.
+     */
+    readonly requiresApproval?: boolean | ApprovalPredicate;
+    /** Bound on the result the model reads; defaults to the source's `maxResultBytes`. */
+    readonly maxResultBytes?: number;
+}
+/**
+ * One Connector operation offered to a Stepwise agent as a tool. Create it with {@link connectorTool}.
+ * @since 0.4.0
+ */
+export interface ConnectorTool {
+    /** Tool name the model calls. */
+    readonly name: string;
+    /** Tool description for the model. */
+    readonly description: string;
+    /** JSON Schema of the arguments, the manifest's `inputSchema`. */
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    /** The Connector ID. */
+    readonly connectorId: string;
+    /** The operation ID. */
+    readonly operationId: string;
+    /** `query` or `mutation`. */
+    readonly kind: "query" | "mutation";
+    /**
+     * `read` for a Query, `idempotent_write` for a Mutation with `agent.retry: safe`, and `non_idempotent_write`
+     * for any other Mutation.
+     */
+    readonly effect: ToolEffect;
+    /** Whether the manifest says `agent.approval: recommended`. */
+    readonly isApprovalRecommended: boolean;
+    /** The application's approval choice, or `undefined` to follow the manifest. */
+    readonly requiresApproval: boolean | ApprovalPredicate | undefined;
+    /** Bound on the result the model reads, or `undefined` for the source's bound. */
+    readonly maxResultBytes: number | undefined;
+    /** The logical connection the operation runs with. */
+    readonly connection: ConnectionRef;
+    /** The manifest's `agent.branches`. */
+    readonly agentBranches: Readonly<Record<string, string>>;
+    /** The operation's branches that are not optional. */
+    readonly requiredBranches: ReadonlySet<string>;
+    /** The operation's Execute timeout in milliseconds, or `undefined`. */
+    readonly executeMethodTimeout: number | undefined;
+    /** The operation's Execute retry policy, which bounds a `CallTool` call's retries. */
+    readonly retryPolicy: RetryPolicy;
+    /** Validates, decodes, and runs one invocation. */
+    readonly invoke: (call: Call, toolArguments: Readonly<Record<string, unknown>>) => Promise<QueryResult<unknown>>;
+}
+/**
+ * Returns what a connector tool call records for one selected branch.
+ *
+ * The rule fails closed: an optional branch of a Mutation that the manifest does not classify is
+ * `outcome_unknown`, because the write may have happened.
+ *
+ * @example
+ * ```ts
+ * classifyConnectorBranch({ kind: "mutation", branch: "invalidResponse", requiredBranches: new Set(["refunded"]),
+ *   agentBranches: {} }); // "outcome_unknown"
+ * ```
+ * @param options - The operation kind, the selected branch, the required branches, and `agent.branches`.
+ * @returns The outcome to record.
+ * @since 0.4.0
+ */
+export declare function classifyConnectorBranch(options: {
+    readonly kind: "query" | "mutation";
+    readonly branch: string;
+    readonly requiredBranches: ReadonlySet<string>;
+    readonly agentBranches: Readonly<Record<string, string>>;
+}): ConnectorBranchOutcome;
+/**
+ * Offers one reviewed Connector operation to a Stepwise agent as a tool.
+ *
+ * The tool's name, description, and argument schema come from the operation's entry in its package's
+ * `dex-connector.json`. Only an operation whose entry says `agent.exposed: true` can become a tool; nothing is
+ * exposed by default, and the application still names each operation it offers.
+ *
+ * The manifest decides how the call runs. A Query is `read` and runs in `CallTool`. A Mutation with
+ * `agent.retry: safe` is `idempotent_write` and runs in `CallTool`, whose retries stay inside the operation's own
+ * Execute retry policy and timeout. Any other Mutation is `non_idempotent_write` and runs once in
+ * `CallSingleAttemptTool`. The effect always comes from the manifest; a session's `toolPolicies` entry for the
+ * tool changes only its approval.
+ *
+ * A call waits for `resolve_interrupt` when the manifest says `agent.approval: recommended`;
+ * {@link ConnectorToolOptions.requiresApproval} overrides that. Arguments that break the schema never run, so
+ * they never wait for approval.
+ *
+ * @example
+ * ```ts
+ * import manifest from "@superdurable/connector-stripe/dex-connector.json" with { type: "json" };
+ * import { CreateRefundInputSchema, newProjectConnection } from "@superdurable/connector-stripe";
+ *
+ * const stripe = newProjectConnection(project, "billing-stripe");
+ * const refund = connectorTool(stripe.operations.createRefund(), stripe.reference, {
+ *   manifest,
+ *   inputValidator: CreateRefundInputSchema,
+ *   requiresApproval: (args) => Number(args["amount"]) > 5000,
+ * });
+ * const source = new ConnectorToolSource([refund]);
+ * ```
+ * @typeParam Input - The operation's input type.
+ * @typeParam Output - The operation's result value type.
+ * @param operation - The connector operation, a Query or a Mutation.
+ * @param connection - The logical connection reference the call runs with. Only the reference is stored; the
+ * Worker resolves credentials.
+ * @param options - The manifest, the input validator, and the application's choices.
+ * @returns The tool.
+ * @throws {TypeError} When the manifest has no entry for the operation, the entry is not `agent.exposed: true`,
+ * its kind differs from the operation's, its `agent` block holds an unknown value or lists a branch it may not,
+ * or its `inputSchema` uses a keyword the agent core cannot check.
+ * @throws {RangeError} When `maxResultBytes` is not positive.
+ * @since 0.4.0
+ */
+export declare function connectorTool<Input, Output>(operation: Query<Input, Output> | Mutation<Input, Output>, connection: ConnectionRef, options: ConnectorToolOptions<Input>): ConnectorTool;
+/**
+ * Offers reviewed Connector operations to a Stepwise agent as tools.
+ *
+ * Put it in `AgentDefinition.toolSources`, as `McpToolSource` is. It lists exactly the tools the application
+ * passes; no Connector is exposed by default. Each call runs one operation invocation in its own tool Step, through
+ * the Connector SDK's `runQuery` or `runMutation`, so the connector's Call ID, idempotency key, credential
+ * handling, and single-dispatch fence apply. The Call ID is derived from the Flow ID and the tool Step's execution
+ * ID, so it is the same on every attempt of that Step.
+ *
+ * Before anything runs, the model's arguments are checked against the manifest's `inputSchema` and then decoded
+ * with the package's input validator. Either failure is a `failed` call the model can correct; the operation never
+ * runs.
+ *
+ * Connector writes of one model response run one at a time in the model's order, and reads run in parallel. A
+ * write whose approval is needed waits for it only when its turn comes. Once a write does not succeed, the later
+ * writes of that response are recorded `failed` with `skipped` set.
+ *
+ * The selected branch maps as {@link classifyConnectorBranch} describes. A connector retry throws through the
+ * Step, so the tool Step's retry policy applies. A single-attempt write that asks to retry ends `outcome_unknown`,
+ * unless its single-dispatch fence saved a `notSent` or `canResend` marker in this attempt: that proves the
+ * provider did not process the request, so the call records `failed` with {@link connectorNotSentRetryLater}.
+ * Either way it stops the later writes. A result longer than `maxResultBytes` reaches the model truncated, with
+ * {@link connectorResultTruncatedNote}, and the record's `truncatedOutputBytes` holds the full size.
+ *
+ * Install `@superdurable/connectors-sdk` next to this package; it is an optional peer dependency.
+ *
+ * @example
+ * ```ts
+ * const flow = createStepwiseAgentSessionFlow(
+ *   { name: "support", instructions: "You help customers.", model,
+ *     toolSources: [new ConnectorToolSource([refund, reply])] },
+ *   "SupportAgent",
+ * );
+ * ```
+ * @since 0.4.0
+ */
+export declare class ConnectorToolSource implements ToolSource {
+    /** The source's stable name, stored with each call; keep it across deploys. */
+    readonly sourceName: string;
+    private readonly toolsByName;
+    private readonly definitions;
+    private readonly maxResultBytes;
+    /**
+     * Creates the source.
+     * @param tools - The tools to offer, in the order the model sees them.
+     * @param options - `sourceName`, default {@link defaultConnectorSourceName}, and `maxResultBytes`, default
+     * {@link defaultConnectorResultMaxBytes}.
+     * @throws {TypeError} When two tools share a name or `sourceName` is blank.
+     * @throws {RangeError} When `maxResultBytes` is not positive.
+     */
+    constructor(tools: readonly ConnectorTool[], options?: {
+        readonly sourceName?: string;
+        readonly maxResultBytes?: number;
+    });
+    /**
+     * Returns the tools; the list is fixed when the source is built.
+     * @returns The tool definitions.
+     */
+    listTools(): Promise<readonly SourceToolDefinition[]>;
+    /**
+     * Returns the tools without I/O.
+     * @returns The tool definitions.
+     */
+    cachedTools(): readonly SourceToolDefinition[];
+    /**
+     * Returns every tool name, so the runner refuses a collision.
+     * @returns The names.
+     */
+    declaredToolNames(): ReadonlySet<string>;
+    /**
+     * Builds the call with the manifest's effect and the call's approval.
+     * @param turn - The `RunModel` context; a `toolPolicies` entry for the tool changes only its approval.
+     * @param call - The model's tool call.
+     * @returns The deferred call, ordered when it is a write.
+     */
+    deferredToolCall(turn: AgentTurnContext, call: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+        readonly arguments: string;
+        readonly listedTool: SourceToolDefinition;
+    }): DeferredToolCall;
+    /**
+     * Returns the operation's timeout and retry policy for the call's tool Step.
+     * @param toolCall - The record whose tool Step starts.
+     * @returns The options, or `undefined` when this source no longer has the tool.
+     */
+    toolCallStepOptions(toolCall: AgentToolCall): ToolCallStepOptions | undefined;
+    /**
+     * Checks, decodes, and runs one call, then maps the selected branch.
+     * @param call - The approved call, with the tool Step's live context.
+     * @returns The result value as JSON text, bounded by `maxResultBytes`.
+     * @throws {ToolExecutionError} When the arguments break the schema or do not decode, the operation selected a
+     * `rejected` or failed branch, or a single-attempt write asked to retry after its fence recorded `notSent` or
+     * `canResend` in this attempt, which proves the provider did not process it ({@link connectorNotSentRetryLater}).
+     * @throws {ToolOutcomeUnknownError} When the operation selected an unknown branch.
+     * @throws {RangeError} When this source no longer has the tool, so the effect decides the outcome.
+     * @throws Any other error, such as a connector retry for the tool Step's retry policy.
+     */
+    executeDeferredToolCall(call: DeferredToolExecution): Promise<ToolExecutionResult>;
+    /**
+     * Refuses a poll: connector tools never start tool tasks.
+     * @param poll - The call.
+     * @returns Never.
+     * @throws {RangeError} Always.
+     */
+    pollToolTask(poll: ToolTaskPoll): Promise<ToolTaskPollOutcome>;
+    private requireTool;
+}
+/**
+ * Returns `output` whole, or its first `maxResultBytes` bytes and {@link connectorResultTruncatedNote}.
+ * @param output - The full result text.
+ * @param maxResultBytes - The bound, in bytes of UTF-8 text, on the kept part.
+ * @returns The result, with `truncatedOutputBytes` set when it was cut.
+ * @since 0.4.0
+ */
+export declare function boundConnectorResult(output: string, maxResultBytes: number): ToolExecutionResult;
+/**
+ * Returns the text the model reads for one result value, the same in every core: keys sorted by code point, no
+ * spaces, unescaped UTF-8, and a number with no fractional part written as an integer.
+ * @param jsonText - The result value as JSON text.
+ * @returns The canonical text.
+ * @since 0.4.0
+ */
+export declare function formatConnectorResult(jsonText: string): string;
+/** Reports whether this attempt's last saved fence marker proves the write was not sent. */
+export declare function isProvenNotSent(call: Call, context: ConnectorStepContext): boolean;