@superdurable/dex-agents 0.0.0-stage → 0.1.0

package/dist/src/agent-session-flow.js

@@ -0,0 +1,276 @@
+// 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
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { StepList, booleanCodec, rpc, } from "@superdurable/dex";
+import { agentMessagesPageCodec, agentSnapshotCodec, agentUserMessageCodec, listAgentMessagesInputCodec, resolveInterruptInputCodec, } from "./agent-session-codecs.js";
+import { createAgentSessionPersistence, defaultAgentEventsCapacityBytes, } from "./agent-session-persistence.js";
+import { AwaitToolApprovalStep, AwaitUserMessageStep, RecordTurnFailureStep, ResumeTurnStep, RunModelStep, StartAgentSessionStep, ToolCallFailureRecordingStep, ToolCallStep, } from "./agent-session-steps.js";
+import { AgentSessionTransitions, agentSessionStepTypes, } from "./agent-session-transitions.js";
+const snapshotMessageLimit = 200;
+const messagePageLimit = 200;
+const toolEffects = [
+    "read",
+    "idempotent_write",
+    "non_idempotent_write",
+    "unclassified",
+];
+/**
+ * Creates the shared agent session Flow for one agent and its framework runner.
+ *
+ * Construct it once per agent at application startup and pass the same object to the Registry and
+ * every Client call. Each call creates a distinct Flow with its own Step instances, persistence
+ * definitions, and RPC methods, so one Registry can hold several agents under different Flow types.
+ * Adapter packages wrap this function; applications usually call the adapter's factory instead.
+ *
+ * It is a function rather than a class because the Dex Client identifies an RPC by its method
+ * function, and two Flows of one class would share their RPC methods.
+ *
+ * @example
+ * ```ts
+ * const triage = createAgentSessionFlow(triageRunner, "TriageAgent", {
+ *   toolPolicies: { lookup_customer: { effect: "read" } },
+ *   interruptDeadlineMs: 24 * 60 * 60 * 1000,
+ * });
+ * const billing = createAgentSessionFlow(billingRunner, "BillingAgent");
+ * const registry = new Registry([triage, billing]);
+ * ```
+ * @param runner - Framework runner; the Flow owns no other dependency.
+ * @param flowType - Flow type, unique within the Registry, such as `"TriageAgent"`. Keep it stable:
+ * running sessions resume by it.
+ * @param options - Tool policies, Stream capacity, and approval deadline. Defaults to all defaults.
+ * @returns A new Flow to register in one Registry.
+ * @throws {TypeError} When `flowType` is blank, the runner is incomplete, or an effect is unknown.
+ * @throws {RangeError} When `eventStreamCapacityBytes` or `interruptDeadlineMs` is not positive.
+ */
+export function createAgentSessionFlow(runner, flowType, options = {}) {
+    const config = resolveAgentSessionConfig(runner, flowType, options);
+    const persistence = createAgentSessionPersistence(config.eventStreamCapacityBytes);
+    const transitions = new AgentSessionTransitions(persistence, runner, config);
+    const resolvedOptions = Object.freeze({
+        toolPolicies: config.toolPolicies,
+        defaultToolEffect: config.defaultToolEffect,
+        eventStreamCapacityBytes: config.eventStreamCapacityBytes,
+        interruptDeadlineMs: config.interruptDeadlineMs,
+    });
+    // A class per Flow gives each Flow its own RPC methods, which the Dex Client identifies by function.
+    let AgentSessionFlowDefinition = (() => {
+        let _instanceExtraInitializers = [];
+        let _sendUserMessage_decorators;
+        let _resolveInterrupt_decorators;
+        let _getAgentSnapshot_decorators;
+        let _listAgentMessages_decorators;
+        return class AgentSessionFlowDefinition {
+            static {
+                const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+                _sendUserMessage_decorators = [rpc({
+                        name: "send_user_message",
+                        inputCodec: agentUserMessageCodec,
+                        outputCodec: booleanCodec,
+                    })];
+                _resolveInterrupt_decorators = [rpc({
+                        name: "resolve_interrupt",
+                        inputCodec: resolveInterruptInputCodec,
+                        outputCodec: booleanCodec,
+                        lockAttributes: [persistence.pendingInterrupts.lock()],
+                    })];
+                _getAgentSnapshot_decorators = [rpc({
+                        name: "get_agent_snapshot",
+                        outputCodec: agentSnapshotCodec,
+                        loadAttributeMaps: [persistence.agentMessages, persistence.agentToolCalls],
+                    })];
+                _listAgentMessages_decorators = [rpc({
+                        name: "list_agent_messages",
+                        inputCodec: listAgentMessagesInputCodec,
+                        outputCodec: agentMessagesPageCodec,
+                        loadAttributeMaps: [persistence.agentMessages],
+                    })];
+                __esDecorate(this, null, _sendUserMessage_decorators, { kind: "method", name: "sendUserMessage", static: false, private: false, access: { has: obj => "sendUserMessage" in obj, get: obj => obj.sendUserMessage }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _resolveInterrupt_decorators, { kind: "method", name: "resolveInterrupt", static: false, private: false, access: { has: obj => "resolveInterrupt" in obj, get: obj => obj.resolveInterrupt }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _getAgentSnapshot_decorators, { kind: "method", name: "getAgentSnapshot", static: false, private: false, access: { has: obj => "getAgentSnapshot" in obj, get: obj => obj.getAgentSnapshot }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _listAgentMessages_decorators, { kind: "method", name: "listAgentMessages", static: false, private: false, access: { has: obj => "listAgentMessages" in obj, get: obj => obj.listAgentMessages }, metadata: _metadata }, null, _instanceExtraInitializers);
+                if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            }
+            runner = (__runInitializers(this, _instanceExtraInitializers), runner);
+            options = resolvedOptions;
+            agentState = persistence.agentState;
+            agentMessages = persistence.agentMessages;
+            frameworkRunState = persistence.frameworkRunState;
+            agentToolCalls = persistence.agentToolCalls;
+            pendingInterrupts = persistence.pendingInterrupts;
+            agentUsage = persistence.agentUsage;
+            queuedUserMessages = persistence.queuedUserMessages;
+            interruptResolutions = persistence.interruptResolutions;
+            toolCallResults = persistence.toolCallResults;
+            agentEvents = persistence.agentEvents;
+            steps = StepList.startStep(new StartAgentSessionStep(transitions)).otherSteps(new AwaitUserMessageStep(transitions), new RunModelStep(transitions), new AwaitToolApprovalStep(transitions), new ToolCallStep(transitions, agentSessionStepTypes.callTool), new ToolCallStep(transitions, agentSessionStepTypes.callSingleAttemptTool), new ToolCallFailureRecordingStep(transitions, agentSessionStepTypes.recordToolFailure, true), new ToolCallFailureRecordingStep(transitions, agentSessionStepTypes.recordToolOutcomeUnknown, false), new ResumeTurnStep(transitions), new RecordTurnFailureStep(transitions));
+            getFlowType() {
+                return config.flowType;
+            }
+            getSteps() {
+                return this.steps;
+            }
+            getPersistenceSchema() {
+                return {
+                    attributes: [
+                        persistence.agentState,
+                        persistence.agentMessages,
+                        persistence.frameworkRunState,
+                        persistence.agentToolCalls,
+                        persistence.pendingInterrupts,
+                        persistence.agentUsage,
+                    ],
+                    channels: [
+                        persistence.queuedUserMessages,
+                        persistence.interruptResolutions,
+                        persistence.toolCallResults,
+                    ],
+                    streams: [persistence.agentEvents],
+                };
+            }
+            sendUserMessage(context, message) {
+                if (message.text.trim() === "") {
+                    return { output: false };
+                }
+                persistence.queuedUserMessages.publish(context, { text: message.text });
+                return { output: true };
+            }
+            resolveInterrupt(context, input) {
+                const pendingInterrupts = transitions.readPendingInterrupts(context);
+                const interrupt = pendingInterrupts.find((pending) => pending.interruptId === input.interruptId);
+                // After the deadline, AwaitToolApproval rejects the call; a late answer must not win.
+                if (interrupt === undefined ||
+                    (interrupt.deadline !== null && Date.parse(interrupt.deadline) <= Date.now())) {
+                    return { output: false };
+                }
+                persistence.pendingInterrupts.set(context, pendingInterrupts.filter((interrupt) => interrupt.interruptId !== input.interruptId));
+                persistence.interruptResolutions.publish(context, input.interruptId, {
+                    approved: input.approved,
+                    rejectionMessage: input.approved ? null : input.rejectionMessage,
+                });
+                return { output: true };
+            }
+            getAgentSnapshot(context) {
+                const state = transitions.readOptionalAgentState(context);
+                if (state === null) {
+                    return {
+                        output: {
+                            state: null,
+                            messages: [],
+                            pendingInterrupts: [],
+                            toolCalls: [],
+                            usage: transitions.readAgentUsage(context),
+                            queuedMessageCount: 0,
+                        },
+                    };
+                }
+                const end = state.nextMessageSequence;
+                return {
+                    output: {
+                        state,
+                        messages: transitions.readMessages(context, end - snapshotMessageLimit, end),
+                        pendingInterrupts: transitions.readPendingInterrupts(context),
+                        toolCalls: transitions.readTurnToolCalls(context, state.activeTurnId),
+                        usage: transitions.readAgentUsage(context),
+                        queuedMessageCount: context.channelSize(persistence.queuedUserMessages),
+                    },
+                };
+            }
+            listAgentMessages(context, input) {
+                const state = transitions.readOptionalAgentState(context);
+                if (state === null) {
+                    return { output: { messages: [], nextBeforeSequence: null } };
+                }
+                const limit = Math.max(1, Math.min(input.limit, messagePageLimit));
+                let end = state.nextMessageSequence;
+                if (input.beforeSequence !== null) {
+                    end = Math.max(1, Math.min(input.beforeSequence, end));
+                }
+                const start = Math.max(1, end - limit);
+                return {
+                    output: {
+                        messages: transitions.readMessages(context, start, end),
+                        nextBeforeSequence: start > 1 ? start : null,
+                    },
+                };
+            }
+        };
+    })();
+    return new AgentSessionFlowDefinition();
+}
+function resolveAgentSessionConfig(runner, flowType, options) {
+    if (typeof runner?.buildUserMessage !== "function" ||
+        typeof runner.runModelStep !== "function" ||
+        typeof runner.executeDeferredToolCall !== "function") {
+        throw new TypeError("createAgentSessionFlow requires an AgentFrameworkRunner");
+    }
+    if (typeof flowType !== "string" || flowType.trim() === "") {
+        throw new TypeError("flowType must be a non-blank string");
+    }
+    const defaultToolEffect = options.defaultToolEffect ?? "unclassified";
+    requireToolEffect(defaultToolEffect, "defaultToolEffect");
+    const toolPolicies = {};
+    for (const [toolName, policy] of Object.entries(options.toolPolicies ?? {})) {
+        requireToolEffect(policy.effect, `tool policy ${toolName}`);
+        toolPolicies[toolName] = Object.freeze({ ...policy });
+    }
+    const eventStreamCapacityBytes = options.eventStreamCapacityBytes ?? defaultAgentEventsCapacityBytes;
+    if (!Number.isSafeInteger(eventStreamCapacityBytes) || eventStreamCapacityBytes <= 0) {
+        throw new RangeError("eventStreamCapacityBytes must be a positive integer");
+    }
+    const interruptDeadlineMs = options.interruptDeadlineMs;
+    if (interruptDeadlineMs !== undefined &&
+        (!Number.isFinite(interruptDeadlineMs) || interruptDeadlineMs <= 0)) {
+        throw new RangeError("interruptDeadlineMs must be positive");
+    }
+    return {
+        flowType,
+        toolPolicies: Object.freeze(toolPolicies),
+        defaultToolEffect,
+        eventStreamCapacityBytes,
+        interruptDeadlineMs,
+    };
+}
+function requireToolEffect(effect, description) {
+    if (!toolEffects.includes(effect)) {
+        throw new TypeError(`${description} has unknown tool effect ${String(effect)}`);
+    }
+}
+//# sourceMappingURL=agent-session-flow.js.map

package/dist/src/agent-session-flow.js.map

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

package/dist/src/agent-session-persistence.d.ts

@@ -0,0 +1,56 @@
+import { Attribute, AttributeMap, Channel, ChannelMap, Stream } from "@superdurable/dex";
+import type { AgentEvent, AgentInterrupt, AgentInterruptResolution, AgentMessage, AgentState, AgentToolCall, AgentUsage, AgentUserMessage, ToolCallCompleted } from "./agent-session-values.js";
+/** Default byte budget of the `AgentEvents` Stream: 10 MiB. */
+export declare const defaultAgentEventsCapacityBytes: number;
+/**
+ * Persistence definitions registered by one agent session Flow.
+ *
+ * Every Flow returned by {@link createAgentSessionFlow} owns its own definition objects, available as
+ * properties of the Flow. Pass them to `Client.getAttributes`, `Client.readStream`, or
+ * `Client.listStreamMessages` to read a session from outside the Flow. The persisted names are wire
+ * contracts shared with the Python core.
+ *
+ * @example
+ * ```ts
+ * const [state, usage] = await client.getAttributes(sessionId, flow.agentState, flow.agentUsage);
+ * const page = await client.listStreamMessages(sessionId, flow.agentEvents, 50);
+ * ```
+ */
+export interface AgentSessionPersistence {
+    /** The `AgentState` Attribute. It is always set after `StartAgentSession`. */
+    readonly agentState: Attribute<AgentState>;
+    /** The `AgentMessages` AttributeMap, keyed by sequence as 12-digit zero-padded decimal. */
+    readonly agentMessages: AttributeMap<AgentMessage>;
+    /** The `FrameworkRunState` Attribute: opaque framework JSON, set only while a turn is suspended. */
+    readonly frameworkRunState: Attribute<string>;
+    /** The `AgentToolCalls` AttributeMap, keyed by tool call ID; holds only the active turn's records. */
+    readonly agentToolCalls: AttributeMap<AgentToolCall>;
+    /** The `PendingInterrupts` Attribute: interrupts that `resolve_interrupt` still accepts. */
+    readonly pendingInterrupts: Attribute<readonly AgentInterrupt[]>;
+    /** The `AgentUsage` Attribute: cumulative usage of every turn. */
+    readonly agentUsage: Attribute<AgentUsage>;
+    /** The `QueuedUserMessages` Channel; `send_user_message` publishes and `AwaitUserMessage` consumes. */
+    readonly queuedUserMessages: Channel<AgentUserMessage>;
+    /** The `InterruptResolutions` ChannelMap, keyed by interrupt ID. */
+    readonly interruptResolutions: ChannelMap<AgentInterruptResolution>;
+    /**
+     * The internal `ToolCallResults` Channel. Every tool call of a batch publishes one message when its
+     * record becomes final, and `ResumeTurn` consumes them. Applications never publish to it.
+     */
+    readonly toolCallResults: Channel<ToolCallCompleted>;
+    /** The best-effort `AgentEvents` Stream. Rebuild durable state with `get_agent_snapshot`. */
+    readonly agentEvents: Stream<AgentEvent>;
+}
+export declare function createAgentSessionPersistence(agentEventsCapacityBytes: number): AgentSessionPersistence;
+/**
+ * Returns the `AgentMessages` map instance of a message sequence.
+ *
+ * @example
+ * ```ts
+ * const [message] = await client.getAttributes(sessionId, flow.agentMessages.instance(messageSequenceKey(7)));
+ * ```
+ * @param sequence - Positive message sequence.
+ * @returns The sequence as a 12-digit zero-padded decimal, such as `"000000000007"`.
+ * @throws {RangeError} When `sequence` is not a positive safe integer.
+ */
+export declare function messageSequenceKey(sequence: number): string;

package/dist/src/agent-session-persistence.js

@@ -0,0 +1,43 @@
+// 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 { Attribute, AttributeMap, Channel, ChannelMap, Stream, stringCodec } from "@superdurable/dex";
+import { agentEventCodec, agentInterruptListCodec, agentInterruptResolutionCodec, agentMessageCodec, agentStateCodec, agentToolCallCodec, agentUsageCodec, agentUserMessageCodec, toolCallCompletedCodec, } from "./agent-session-codecs.js";
+/** Default byte budget of the `AgentEvents` Stream: 10 MiB. */
+export const defaultAgentEventsCapacityBytes = 10 * 1024 * 1024;
+export function createAgentSessionPersistence(agentEventsCapacityBytes) {
+    return {
+        agentState: new Attribute("AgentState", agentStateCodec),
+        agentMessages: new AttributeMap("AgentMessages", agentMessageCodec),
+        frameworkRunState: new Attribute("FrameworkRunState", stringCodec),
+        agentToolCalls: new AttributeMap("AgentToolCalls", agentToolCallCodec),
+        pendingInterrupts: new Attribute("PendingInterrupts", agentInterruptListCodec),
+        agentUsage: new Attribute("AgentUsage", agentUsageCodec),
+        queuedUserMessages: new Channel("QueuedUserMessages", agentUserMessageCodec),
+        interruptResolutions: new ChannelMap("InterruptResolutions", agentInterruptResolutionCodec),
+        toolCallResults: new Channel("ToolCallResults", toolCallCompletedCodec),
+        agentEvents: new Stream("AgentEvents", agentEventCodec, agentEventsCapacityBytes),
+    };
+}
+/**
+ * Returns the `AgentMessages` map instance of a message sequence.
+ *
+ * @example
+ * ```ts
+ * const [message] = await client.getAttributes(sessionId, flow.agentMessages.instance(messageSequenceKey(7)));
+ * ```
+ * @param sequence - Positive message sequence.
+ * @returns The sequence as a 12-digit zero-padded decimal, such as `"000000000007"`.
+ * @throws {RangeError} When `sequence` is not a positive safe integer.
+ */
+export function messageSequenceKey(sequence) {
+    if (!Number.isSafeInteger(sequence) || sequence <= 0) {
+        throw new RangeError(`message sequence must be a positive integer: ${sequence}`);
+    }
+    return String(sequence).padStart(12, "0");
+}
+//# sourceMappingURL=agent-session-persistence.js.map

package/dist/src/agent-session-persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-persistence.js","sourceRoot":"","sources":["../../src/agent-session-persistence.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEtG,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,6BAA6B,EAC7B,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AAanC,+DAA+D;AAC/D,MAAM,CAAC,MAAM,+BAA+B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AA0ChE,MAAM,UAAU,6BAA6B,CAC3C,wBAAgC;IAEhC,OAAO;QACL,UAAU,EAAE,IAAI,SAAS,CAAC,YAAY,EAAE,eAAe,CAAC;QACxD,aAAa,EAAE,IAAI,YAAY,CAAC,eAAe,EAAE,iBAAiB,CAAC;QACnE,iBAAiB,EAAE,IAAI,SAAS,CAAC,mBAAmB,EAAE,WAAW,CAAC;QAClE,cAAc,EAAE,IAAI,YAAY,CAAC,gBAAgB,EAAE,kBAAkB,CAAC;QACtE,iBAAiB,EAAE,IAAI,SAAS,CAAC,mBAAmB,EAAE,uBAAuB,CAAC;QAC9E,UAAU,EAAE,IAAI,SAAS,CAAC,YAAY,EAAE,eAAe,CAAC;QACxD,kBAAkB,EAAE,IAAI,OAAO,CAAC,oBAAoB,EAAE,qBAAqB,CAAC;QAC5E,oBAAoB,EAAE,IAAI,UAAU,CAAC,sBAAsB,EAAE,6BAA6B,CAAC;QAC3F,eAAe,EAAE,IAAI,OAAO,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;QACvE,WAAW,EAAE,IAAI,MAAM,CAAC,aAAa,EAAE,eAAe,EAAE,wBAAwB,CAAC;KAClF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,UAAU,CAAC,gDAAgD,QAAQ,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;AAC5C,CAAC"}

package/dist/src/agent-session-steps.d.ts

@@ -0,0 +1,86 @@
+import { Wait, type AsyncContext, type Codec, type Context, type Step, type StepDecision, type StepOptions } from "@superdurable/dex";
+import { type AgentSessionTransitions } from "./agent-session-transitions.js";
+import { type AgentSessionStartInput } from "./agent-session-values.js";
+export declare class StartAgentSessionStep implements Step<AgentSessionStartInput> {
+    private readonly transitions;
+    readonly inputCodec: Codec<AgentSessionStartInput>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    execute(context: Context, input: AgentSessionStartInput): StepDecision;
+}
+export declare class AwaitUserMessageStep implements Step<void> {
+    private readonly transitions;
+    readonly inputCodec: Codec<void>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    waitFor(): Wait;
+    execute(context: Context): StepDecision;
+}
+/** Makes the turn's next model call and fans the requested tool calls out to parallel Steps. */
+export declare class RunModelStep implements Step<void> {
+    private readonly transitions;
+    readonly inputCodec: Codec<void>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    execute(context: AsyncContext): Promise<StepDecision>;
+    private completeTurn;
+    private requestToolCalls;
+}
+/** Waits for one tool call's approval or its deadline, then runs or rejects the call. */
+export declare class AwaitToolApprovalStep implements Step<string> {
+    private readonly transitions;
+    readonly inputCodec: Codec<string>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    waitFor(context: Context, toolCallId: string): Wait;
+    execute(context: Context, toolCallId: string): StepDecision;
+    private rejectToolCall;
+    private writeInterruptResolved;
+}
+/** Runs one tool call; one class serves `CallTool` and `CallSingleAttemptTool`. */
+export declare class ToolCallStep implements Step<string> {
+    private readonly transitions;
+    private readonly stepType;
+    readonly inputCodec: Codec<string>;
+    constructor(transitions: AgentSessionTransitions, stepType: string);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    execute(context: AsyncContext, toolCallId: string): Promise<StepDecision>;
+}
+/**
+ * Failure route of a tool Step; it receives the failed Step's input, the tool call ID.
+ * `RecordToolFailure` records `failed` for a `read` call and `outcome_unknown` for a write;
+ * `RecordToolOutcomeUnknown` always records `outcome_unknown`.
+ */
+export declare class ToolCallFailureRecordingStep implements Step<string> {
+    private readonly transitions;
+    private readonly stepType;
+    private readonly isReadFailureRecorded;
+    readonly inputCodec: Codec<string>;
+    constructor(transitions: AgentSessionTransitions, stepType: string, isReadFailureRecorded: boolean);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    execute(context: Context, toolCallId: string): StepDecision;
+}
+/** Waits until every tool call of the batch has a final record, then makes the next model call. */
+export declare class ResumeTurnStep implements Step<number> {
+    private readonly transitions;
+    readonly inputCodec: Codec<number>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    waitFor(_context: Context, expectedResultCount: number): Wait;
+    execute(context: Context): StepDecision;
+}
+export declare class RecordTurnFailureStep implements Step<void> {
+    private readonly transitions;
+    readonly inputCodec: Codec<void>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    execute(context: Context): StepDecision;
+}