@superdurable/dex-agents 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,623 @@
+// 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, StepRef, booleanCodec, rpc, } from "@superdurable/dex";
+import { builtInToolNames, isBlankText } from "./agent-built-in-tools.js";
+import { isContextCompactionRunner, resolveCompactionPolicy, } from "./agent-context-compaction.js";
+import { agentMessagesPageCodec, agentSnapshotCodec, agentUserMessageCodec, answerQuestionRequestCodec, cancelTurnRequestCodec, deleteQueuedMessageRequestCodec, executePlanRequestCodec, listAgentMessagesInputCodec, resolveInterruptInputCodec, steerUserMessageRequestCodec, updateSessionSettingsRequestCodec, } from "./agent-session-codecs.js";
+import { createAgentSessionPersistence, defaultAgentEventsCapacityBytes, planExecutionKey, } from "./agent-session-persistence.js";
+import { checkStoredSessionSettings } from "./agent-session-settings.js";
+import { ApplyTurnControlStep, AwaitToolApprovalStep, AwaitUserMessageStep, CompactContextStep, isExecutablePlanStatus, RecordTurnFailureStep, ResumeTurnStep, RunModelStep, StartAgentSessionStep, ToolCallFailureRecordingStep, ToolCallStep, } from "./agent-session-steps.js";
+import { AgentSessionTracer } from "./agent-session-tracer.js";
+import { CancelToolTaskStep, FinishTurnCancellationStep } from "./agent-session-cancellation-steps.js";
+import { AwaitQuestionAnswerStep, AwaitTimerStep, PollToolTaskStep } from "./agent-session-wait-steps.js";
+import { AgentSessionTransitions, agentSessionStepTypes, finishTurnCancellationMovement, messageRolloverMaxBytesPerCommit, messageRolloverMaxChunksPerCommit, } from "./agent-session-transitions.js";
+import { genAISemanticConventionsSchemaUrls, } from "./agent-tracing-options.js";
+export const snapshotMessageLimit = 200;
+export const defaultMaxDurableWaitMs = 365 * 24 * 60 * 60 * 1_000;
+export const messagePageLimit = 200;
+/** Default {@link AgentSessionOptions.messageWindowSize}. */
+export const defaultMessageWindowSize = 64;
+/** Default {@link AgentSessionOptions.messageChunkSize}. */
+export const defaultMessageChunkSize = 32;
+/** Default {@link AgentSessionOptions.messageChunkMaxBytes}: 1 MiB. */
+export const defaultMessageChunkMaxBytes = 1_048_576;
+/** Default {@link AgentSessionOptions.retainedMessageLimit}. */
+export const defaultRetainedMessageLimit = 1_000;
+export { messageRolloverMaxBytesPerCommit, messageRolloverMaxChunksPerCommit };
+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]);
+ * ```
+ * @typeParam Runner - Type of the runner, kept as the Flow's `runner` property type.
+ * @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, approval deadline, and tracing. Defaults to all
+ * defaults.
+ * @returns A new Flow to register in one Registry.
+ * @throws {TypeError} When `flowType` is blank, the runner is incomplete, an effect or built-in tool is
+ * unknown, a tool policy names an enabled built-in tool, a tracing option is invalid, `planModeEnabled`
+ * is set without `write_todos` or for a runner without {@link AgentFrameworkRunner.supportsPlanMode}, or
+ * `compaction` is set for a runner without the compaction methods.
+ * @throws {RangeError} When `eventStreamCapacityBytes` or `interruptDeadlineMs` is not positive,
+ * `maxDurableWaitMs` is not a positive whole number of seconds, or the compaction policy is out of range.
+ */
+export function createAgentSessionFlow(runner, flowType, options = {}) {
+    const config = resolveAgentSessionConfig(runner, flowType, options);
+    const persistence = createAgentSessionPersistence(config.eventStreamCapacityBytes);
+    const transitions = new AgentSessionTransitions(persistence, runner, config, new AgentSessionTracer(config.tracing, persistence));
+    const resolvedOptions = Object.freeze({
+        toolPolicies: config.toolPolicies,
+        defaultToolEffect: config.defaultToolEffect,
+        eventStreamCapacityBytes: config.eventStreamCapacityBytes,
+        interruptDeadlineMs: config.interruptDeadlineMs,
+        tracing: config.tracing,
+        builtInTools: Object.freeze(builtInToolNames.filter((name) => config.builtInTools.has(name))),
+        maxDurableWaitMs: config.maxDurableWaitMs,
+        planModeEnabled: config.planModeEnabled,
+        ...(config.compaction === undefined ? {} : { compaction: config.compaction }),
+        messageWindowSize: config.messageWindowSize,
+        messageChunkSize: config.messageChunkSize,
+        messageChunkMaxBytes: config.messageChunkMaxBytes,
+        retainedMessageLimit: config.retainedMessageLimit,
+    });
+    // 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 _executePlan_decorators;
+        let _steerUserMessage_decorators;
+        let _deleteQueuedMessage_decorators;
+        let _cancelTurn_decorators;
+        let _updateSessionSettings_decorators;
+        let _resolveInterrupt_decorators;
+        let _answerQuestion_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,
+                        isTransactional: true,
+                    })];
+                _executePlan_decorators = [rpc({
+                        name: "execute_plan",
+                        inputCodec: executePlanRequestCodec,
+                        outputCodec: booleanCodec,
+                        lockAttributes: [persistence.pendingPlanExecution.lock()],
+                    })];
+                _steerUserMessage_decorators = [rpc({
+                        name: "steer_user_message",
+                        inputCodec: steerUserMessageRequestCodec,
+                        outputCodec: booleanCodec,
+                        isTransactional: true,
+                        loadChannels: [persistence.queuedUserMessages],
+                    })];
+                _deleteQueuedMessage_decorators = [rpc({
+                        name: "delete_queued_message",
+                        inputCodec: deleteQueuedMessageRequestCodec,
+                        outputCodec: booleanCodec,
+                        isTransactional: true,
+                        loadChannels: [persistence.queuedUserMessages],
+                    })];
+                _cancelTurn_decorators = [rpc({
+                        name: "cancel_turn",
+                        inputCodec: cancelTurnRequestCodec,
+                        outputCodec: booleanCodec,
+                        lockAttributes: [persistence.turnCancellationRequest.lock(), persistence.pendingInterrupts.lock()],
+                    })];
+                _updateSessionSettings_decorators = [rpc({
+                        name: "update_session_settings",
+                        inputCodec: updateSessionSettingsRequestCodec,
+                        outputCodec: booleanCodec,
+                        isTransactional: true,
+                    })];
+                _resolveInterrupt_decorators = [rpc({
+                        name: "resolve_interrupt",
+                        inputCodec: resolveInterruptInputCodec,
+                        outputCodec: booleanCodec,
+                        lockAttributes: [persistence.pendingInterrupts.lock()],
+                    })];
+                _answerQuestion_decorators = [rpc({
+                        name: "answer_question",
+                        inputCodec: answerQuestionRequestCodec,
+                        outputCodec: booleanCodec,
+                        lockAttributes: [persistence.pendingInterrupts.lock()],
+                    })];
+                _getAgentSnapshot_decorators = [rpc({
+                        name: "get_agent_snapshot",
+                        outputCodec: agentSnapshotCodec,
+                        loadAttributeMaps: [persistence.agentMessages, persistence.agentMessageChunks, persistence.agentToolCalls],
+                        loadChannels: [persistence.queuedUserMessages, persistence.steeredUserMessages],
+                    })];
+                _listAgentMessages_decorators = [rpc({
+                        name: "list_agent_messages",
+                        inputCodec: listAgentMessagesInputCodec,
+                        outputCodec: agentMessagesPageCodec,
+                        loadAttributeMaps: [persistence.agentMessages, persistence.agentMessageChunks],
+                    })];
+                __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, _executePlan_decorators, { kind: "method", name: "executePlan", static: false, private: false, access: { has: obj => "executePlan" in obj, get: obj => obj.executePlan }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _steerUserMessage_decorators, { kind: "method", name: "steerUserMessage", static: false, private: false, access: { has: obj => "steerUserMessage" in obj, get: obj => obj.steerUserMessage }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _deleteQueuedMessage_decorators, { kind: "method", name: "deleteQueuedMessage", static: false, private: false, access: { has: obj => "deleteQueuedMessage" in obj, get: obj => obj.deleteQueuedMessage }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _cancelTurn_decorators, { kind: "method", name: "cancelTurn", static: false, private: false, access: { has: obj => "cancelTurn" in obj, get: obj => obj.cancelTurn }, metadata: _metadata }, null, _instanceExtraInitializers);
+                __esDecorate(this, null, _updateSessionSettings_decorators, { kind: "method", name: "updateSessionSettings", static: false, private: false, access: { has: obj => "updateSessionSettings" in obj, get: obj => obj.updateSessionSettings }, 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, _answerQuestion_decorators, { kind: "method", name: "answerQuestion", static: false, private: false, access: { has: obj => "answerQuestion" in obj, get: obj => obj.answerQuestion }, 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;
+            agentMessageChunks = persistence.agentMessageChunks;
+            agentMessageIndex = persistence.agentMessageIndex;
+            frameworkRunState = persistence.frameworkRunState;
+            agentToolCalls = persistence.agentToolCalls;
+            pendingInterrupts = persistence.pendingInterrupts;
+            agentUsage = persistence.agentUsage;
+            queuedUserMessages = persistence.queuedUserMessages;
+            interruptResolutions = persistence.interruptResolutions;
+            toolCallResults = persistence.toolCallResults;
+            steeredUserMessages = persistence.steeredUserMessages;
+            turnControlRequests = persistence.turnControlRequests;
+            turnCancellationRequest = persistence.turnCancellationRequest;
+            toolCallCancellations = persistence.toolCallCancellations;
+            agentEvents = persistence.agentEvents;
+            agentTraceContext = persistence.agentTraceContext;
+            agentPlan = persistence.agentPlan;
+            planExecutions = persistence.planExecutions;
+            pendingPlanExecution = persistence.pendingPlanExecution;
+            contextSummary = persistence.contextSummary;
+            sessionSettings = persistence.sessionSettings;
+            turnSessionSettings = persistence.turnSessionSettings;
+            /** The `TurnReplySequence` Attribute; see {@link AgentSessionPersistence.turnReplySequence}. */
+            turnReplySequence = persistence.turnReplySequence;
+            steps = StepList.startStep(new StartAgentSessionStep(transitions)).otherSteps(new AwaitUserMessageStep(transitions), new RunModelStep(transitions), new CompactContextStep(transitions), new AwaitToolApprovalStep(transitions), new AwaitQuestionAnswerStep(transitions), new AwaitTimerStep(transitions), new ToolCallStep(transitions, agentSessionStepTypes.callTool), new ToolCallStep(transitions, agentSessionStepTypes.callSingleAttemptTool), new PollToolTaskStep(transitions), new ToolCallFailureRecordingStep(transitions, agentSessionStepTypes.recordToolFailure, true), new ToolCallFailureRecordingStep(transitions, agentSessionStepTypes.recordToolOutcomeUnknown, false), new ResumeTurnStep(transitions), new ApplyTurnControlStep(transitions), new RecordTurnFailureStep(transitions), new FinishTurnCancellationStep(transitions), new CancelToolTaskStep(transitions));
+            getFlowType() {
+                return config.flowType;
+            }
+            getSteps() {
+                return this.steps;
+            }
+            // AgentTraceContext and ContextSummary are always registered, so Workers with and without tracing or
+            // compaction serve one Flow type.
+            getPersistenceSchema() {
+                return {
+                    attributes: [
+                        persistence.agentState,
+                        persistence.agentMessages,
+                        persistence.agentMessageChunks,
+                        persistence.agentMessageIndex,
+                        persistence.frameworkRunState,
+                        persistence.agentToolCalls,
+                        persistence.pendingInterrupts,
+                        persistence.agentUsage,
+                        persistence.turnCancellationRequest,
+                        persistence.agentTraceContext,
+                        persistence.agentPlan,
+                        persistence.pendingPlanExecution,
+                        persistence.contextSummary,
+                        persistence.sessionSettings,
+                        persistence.turnSessionSettings,
+                        persistence.turnReplySequence,
+                    ],
+                    channels: [
+                        persistence.queuedUserMessages,
+                        persistence.interruptResolutions,
+                        persistence.toolCallResults,
+                        persistence.planExecutions,
+                        persistence.steeredUserMessages,
+                        persistence.turnControlRequests,
+                        persistence.toolCallCancellations,
+                    ],
+                    streams: [persistence.agentEvents],
+                };
+            }
+            sendUserMessage(context, message) {
+                const planMode = message.planMode ?? false;
+                if (isBlankText(message.text) || (planMode && !config.planModeEnabled)) {
+                    return { output: false };
+                }
+                persistence.queuedUserMessages.publish(context, { text: message.text, planMode });
+                return { output: true };
+            }
+            executePlan(context, input) {
+                const state = transitions.readOptionalAgentState(context);
+                const plan = transitions.readOptionalAgentPlan(context);
+                const pending = persistence.pendingPlanExecution.get(context);
+                if (state === null ||
+                    state.status !== "waiting_for_user_message" ||
+                    state.activeTurnId !== null ||
+                    plan === null ||
+                    plan.revision !== input.revision ||
+                    !isExecutablePlanStatus(plan.status) ||
+                    (pending !== undefined && pending.revision === plan.revision) ||
+                    context.channelSize(persistence.queuedUserMessages) > 0 ||
+                    context.channelSize(persistence.steeredUserMessages) > 0 ||
+                    transitions.readPendingInterrupts(context).length > 0) {
+                    return { output: false };
+                }
+                const request = { revision: plan.revision };
+                persistence.pendingPlanExecution.set(context, request);
+                persistence.planExecutions.publish(context, planExecutionKey(plan.revision), request);
+                return { output: true };
+            }
+            steerUserMessage(context, input) {
+                if ((input.messageId === null) === (input.text === null)) {
+                    return { output: false };
+                }
+                const state = transitions.readOptionalAgentState(context);
+                if (state?.activeTurnId == null) {
+                    // Any Worker version waits for queued messages while idle; a steer might wait forever.
+                    if (input.text === null) {
+                        return { output: findQueuedMessage(context, persistence, input.messageId ?? "") !== undefined };
+                    }
+                    return this.sendUserMessage(context, { text: input.text });
+                }
+                if (state.acceptsTurnControl !== true) {
+                    return { output: false };
+                }
+                let steered;
+                if (input.text !== null) {
+                    if (isBlankText(input.text)) {
+                        return { output: false };
+                    }
+                    steered = { text: input.text };
+                }
+                else {
+                    const queued = findQueuedMessage(context, persistence, input.messageId ?? "");
+                    if (queued === undefined) {
+                        return { output: false };
+                    }
+                    persistence.queuedUserMessages.delete(context, queued.messageId);
+                    steered = queued.message;
+                }
+                persistence.steeredUserMessages.publish(context, steered);
+                persistence.turnControlRequests.publish(context, { kind: "steer" });
+                return { output: true };
+            }
+            deleteQueuedMessage(context, input) {
+                const queued = findQueuedMessage(context, persistence, input.messageId);
+                if (queued === undefined) {
+                    return { output: false };
+                }
+                persistence.queuedUserMessages.delete(context, queued.messageId);
+                return { output: true };
+            }
+            // PendingInterrupts orders it with ResumeTurn, and TurnCancellationRequest with turn starts.
+            cancelTurn(context, input) {
+                const state = transitions.readOptionalAgentState(context);
+                const activeTurnId = state?.activeTurnId ?? null;
+                if (activeTurnId === null ||
+                    state?.acceptsTurnControl !== true ||
+                    (input.turnId !== null && input.turnId !== activeTurnId)) {
+                    return { output: false };
+                }
+                if (transitions.isTurnCancelled(context, activeTurnId)) {
+                    return { output: true };
+                }
+                persistence.turnCancellationRequest.set(context, {
+                    turnId: activeTurnId,
+                    requestedAt: new Date().toISOString(),
+                });
+                // Each cancelled Step has no outside effect or only waits; the model call's answer is lost.
+                return {
+                    output: true,
+                    nextSteps: [finishTurnCancellationMovement(activeTurnId)],
+                    cancelingSteps: [
+                        agentSessionStepTypes.runModel,
+                        agentSessionStepTypes.compactContext,
+                        agentSessionStepTypes.recordTurnFailure,
+                        agentSessionStepTypes.awaitToolApproval,
+                        agentSessionStepTypes.awaitQuestionAnswer,
+                        agentSessionStepTypes.awaitTimer,
+                        agentSessionStepTypes.pollToolTask,
+                    ].map((stepType) => new StepRef(stepType)),
+                };
+            }
+            updateSessionSettings(context, input) {
+                const sessionSettings = input.sessionSettings;
+                if (transitions.readOptionalAgentState(context) === null || sessionSettings === null) {
+                    return { output: false };
+                }
+                try {
+                    checkStoredSessionSettings(sessionSettings);
+                }
+                catch {
+                    return { output: false };
+                }
+                if (Object.keys(sessionSettings).length > 0) {
+                    persistence.sessionSettings.set(context, sessionSettings);
+                }
+                else if (transitions.readSessionSettings(context) !== null) {
+                    persistence.sessionSettings.delete(context);
+                }
+                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()) ||
+                    (interrupt.kind === "question" && input.approved)) {
+                    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,
+                    answer: null,
+                });
+                return { output: true };
+            }
+            answerQuestion(context, input) {
+                const pendingInterrupts = transitions.readPendingInterrupts(context);
+                const interrupt = pendingInterrupts.find((pending) => pending.interruptId === input.interruptId);
+                if (interrupt === undefined ||
+                    interrupt.kind !== "question" ||
+                    (interrupt.deadline !== null && Date.parse(interrupt.deadline) <= Date.now()) ||
+                    isBlankText(input.answer) ||
+                    isAnswerOutsideChoices(interrupt.choices ?? [], interrupt.allowsFreeText ?? true, input.answer)) {
+                    return { output: false };
+                }
+                persistence.pendingInterrupts.set(context, pendingInterrupts.filter((pending) => pending.interruptId !== input.interruptId));
+                persistence.interruptResolutions.publish(context, input.interruptId, {
+                    approved: true,
+                    rejectionMessage: null,
+                    answer: input.answer,
+                });
+                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,
+                            plan: null,
+                            queuedMessages: [],
+                            steeredMessages: [],
+                            contextSummary: null,
+                            sessionSettings: null,
+                        },
+                    };
+                }
+                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),
+                        plan: transitions.readOptionalAgentPlan(context),
+                        queuedMessages: readPendingUserMessages(context, persistence.queuedUserMessages),
+                        steeredMessages: readPendingUserMessages(context, persistence.steeredUserMessages),
+                        contextSummary: transitions.readContextSummary(context),
+                        sessionSettings: transitions.readSessionSettings(context),
+                    },
+                };
+            }
+            listAgentMessages(context, input) {
+                const state = transitions.readOptionalAgentState(context);
+                if (state === null) {
+                    return { output: { messages: [], nextBeforeSequence: null, deletedBeforeSequence: null } };
+                }
+                const limit = Math.max(1, Math.min(input.limit, messagePageLimit));
+                const firstSequence = transitions.readFirstStoredSequence(context);
+                let end = state.nextMessageSequence;
+                if (input.beforeSequence !== null) {
+                    end = Math.max(firstSequence, Math.min(input.beforeSequence, end));
+                }
+                const start = Math.max(firstSequence, end - limit);
+                return {
+                    output: {
+                        messages: transitions.readMessages(context, start, end),
+                        nextBeforeSequence: start > firstSequence ? start : null,
+                        deletedBeforeSequence: firstSequence > 1 ? firstSequence : 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");
+    }
+    const builtInTools = new Set();
+    for (const builtInTool of options.builtInTools ?? []) {
+        if (!builtInToolNames.includes(builtInTool)) {
+            throw new TypeError(`builtInTools has unknown built-in tool ${String(builtInTool)}`);
+        }
+        builtInTools.add(builtInTool);
+    }
+    for (const toolName of Object.keys(toolPolicies)) {
+        if (builtInTools.has(toolName)) {
+            throw new TypeError(`tool policy ${toolName} names an enabled built-in tool, whose policy is fixed`);
+        }
+    }
+    const planModeEnabled = options.planModeEnabled ?? false;
+    if (planModeEnabled && !builtInTools.has("write_todos")) {
+        throw new TypeError("planModeEnabled requires the write_todos built-in tool");
+    }
+    if (planModeEnabled && runner.supportsPlanMode !== true) {
+        throw new TypeError("planModeEnabled requires a runner that supports plan mode");
+    }
+    const maxDurableWaitMs = options.maxDurableWaitMs ?? defaultMaxDurableWaitMs;
+    if (!Number.isSafeInteger(maxDurableWaitMs) || maxDurableWaitMs < 1_000 || maxDurableWaitMs % 1_000 !== 0) {
+        throw new RangeError("maxDurableWaitMs must be a positive whole number of seconds, in milliseconds");
+    }
+    const compaction = options.compaction === undefined ? undefined : resolveCompactionPolicy(options.compaction);
+    if (compaction !== undefined && !isContextCompactionRunner(runner)) {
+        throw new TypeError("compaction needs a runner that implements estimateInputTokens, selectCompactionCutoff, and summarizeContext");
+    }
+    const messageChunkSize = options.messageChunkSize ?? defaultMessageChunkSize;
+    if (!Number.isSafeInteger(messageChunkSize) || messageChunkSize <= 0) {
+        throw new RangeError("messageChunkSize must be positive");
+    }
+    const messageWindowSize = options.messageWindowSize ?? defaultMessageWindowSize;
+    if (!Number.isSafeInteger(messageWindowSize) || messageWindowSize < messageChunkSize) {
+        throw new RangeError("messageWindowSize must be at least messageChunkSize");
+    }
+    const messageChunkMaxBytes = options.messageChunkMaxBytes ?? defaultMessageChunkMaxBytes;
+    if (!Number.isSafeInteger(messageChunkMaxBytes) ||
+        messageChunkMaxBytes < 1 ||
+        messageChunkMaxBytes > messageRolloverMaxBytesPerCommit) {
+        throw new RangeError(`messageChunkMaxBytes must be between 1 and ${messageRolloverMaxBytesPerCommit}`);
+    }
+    const retainedMessageLimit = options.retainedMessageLimit === undefined ? defaultRetainedMessageLimit : options.retainedMessageLimit;
+    if (retainedMessageLimit !== null && (!Number.isSafeInteger(retainedMessageLimit) || retainedMessageLimit < 0)) {
+        throw new RangeError("retainedMessageLimit must not be negative");
+    }
+    return {
+        flowType,
+        toolPolicies: Object.freeze(toolPolicies),
+        defaultToolEffect,
+        eventStreamCapacityBytes,
+        interruptDeadlineMs,
+        tracing: resolveAgentTracingOptions(flowType, options.tracing ?? {}),
+        builtInTools,
+        maxDurableWaitMs,
+        planModeEnabled,
+        compaction,
+        messageWindowSize,
+        messageChunkSize,
+        messageChunkMaxBytes,
+        retainedMessageLimit,
+    };
+}
+function resolveAgentTracingOptions(flowType, tracing) {
+    const agentName = tracing.agentName ?? flowType;
+    if (typeof agentName !== "string" || agentName.trim() === "") {
+        throw new TypeError("tracing.agentName must be a non-blank string");
+    }
+    const semanticConventionsVersion = tracing.semanticConventionsVersion ?? "1.42.0-dev";
+    if (!Object.hasOwn(genAISemanticConventionsSchemaUrls, semanticConventionsVersion)) {
+        throw new TypeError(`tracing.semanticConventionsVersion ${String(semanticConventionsVersion)} is unknown`);
+    }
+    const tracerProvider = tracing.tracerProvider;
+    if (tracerProvider !== undefined && typeof tracerProvider?.getTracer !== "function") {
+        throw new TypeError("tracing.tracerProvider must be an OpenTelemetry TracerProvider");
+    }
+    return Object.freeze({
+        isEnabled: tracing.isEnabled ?? true,
+        tracerProvider,
+        agentName,
+        shouldCaptureMessageContent: tracing.shouldCaptureMessageContent ?? false,
+        semanticConventionsVersion,
+    });
+}
+function readPendingUserMessages(context, channel) {
+    return channel
+        .pendingMessages(context)
+        .map((pending) => ({ messageId: pending.messageId, message: pending.value }));
+}
+function findQueuedMessage(context, persistence, messageId) {
+    return readPendingUserMessages(context, persistence.queuedUserMessages).find((queued) => queued.messageId === messageId);
+}
+function isAnswerOutsideChoices(choices, allowsFreeText, answer) {
+    return choices.length > 0 && !allowsFreeText && !choices.includes(answer);
+}
+function requireToolEffect(effect, description) {
+    if (!toolEffects.includes(effect)) {
+        throw new TypeError(`${description} has unknown tool effect ${String(effect)}`);
+    }
+}
+//# sourceMappingURL=agent-session-flow.js.map