@superdurable/dex-agents 0.1.0 → 0.2.0

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

@@ -1,61 +1,224 @@
-import { type AsyncContext, type Context, type StepDecision } from "@superdurable/dex";
+import { StepMovement, type AsyncContext, type Context, type RecoveryErrorInfo, type StepDecision } from "@superdurable/dex";
+import type { BuiltInTool } from "./agent-built-in-tools.js";
+import { type ResolvedCompactionPolicy } from "./agent-context-compaction.js";
 import { StreamAgentEventWriter } from "./agent-event-writer.js";
-import { type AgentFrameworkRunner, type ResolvedToolPolicy, type ToolPolicy } from "./agent-framework-runner.js";
+import { type AgentFrameworkRunner, type AgentTurnContext, type DeferredToolOutcome, type ResolvedToolPolicy, type ToolPolicy } from "./agent-framework-runner.js";
 import { type AgentSessionPersistence } from "./agent-session-persistence.js";
-import { type AgentInterrupt, type AgentMessage, type AgentState, type AgentToolCall, type AgentUsage, type FrameworkMessage, type ToolEffect } from "./agent-session-values.js";
-export declare const agentSessionStepTypes: {
-    readonly startAgentSession: "StartAgentSession";
-    readonly awaitUserMessage: "AwaitUserMessage";
-    readonly runModel: "RunModel";
-    readonly awaitToolApproval: "AwaitToolApproval";
-    readonly callTool: "CallTool";
-    readonly callSingleAttemptTool: "CallSingleAttemptTool";
-    readonly recordToolFailure: "RecordToolFailure";
-    readonly recordToolOutcomeUnknown: "RecordToolOutcomeUnknown";
-    readonly resumeTurn: "ResumeTurn";
-    readonly recordTurnFailure: "RecordTurnFailure";
-};
+import { type MessageChunkLoads } from "./agent-session-step-options.js";
+import type { AgentSessionTracer } from "./agent-session-tracer.js";
+import { type AgentInterrupt, type AgentInterruptKind, type AgentMessage, type AgentMessageChunk, type AgentMessageChunkRange, type AgentMessageIndex, type AgentPlan, type AgentState, type AgentToolCall, type AgentToolCallRecord, type AgentUsage, type AgentUserMessage, type ContextSummary, type SessionSettings, type TurnSessionSettings, type FrameworkMessage, type InteractionMode, type ToolCallCancellationReason, type ToolEffect } from "./agent-session-values.js";
+import type { ResolvedAgentTracingOptions } from "./agent-tracing-options.js";
+export { agentSessionStepTypes } from "./agent-session-step-types.js";
+/** Most archive chunks one commit writes, so a large 0.1.0 history migrates over several commits. */
+export declare const messageRolloverMaxChunksPerCommit = 4;
+/**
+ * Most chunk bytes one commit writes, 8 MiB, which keeps a Step result far under the engine's frame limit. A
+ * single chunk larger than it still moves, alone.
+ */
+export declare const messageRolloverMaxBytesPerCommit = 8388608;
+/** Consumes every pending message of a Channel at once; the plan's MAX. */
+export declare const allPendingMessages = 2147483647;
+/** The model-visible result of a call that steering or `cancel_turn` abandoned, by reason. */
+export declare const toolCallCancellationResults: Readonly<Record<ToolCallCancellationReason, string>>;
+/** Fields of one `interrupt_resolved` event. */
+export interface InterruptResolvedEvent {
+    readonly interruptId: string;
+    readonly kind: AgentInterruptKind;
+    readonly isApproved: boolean;
+    readonly isAnswered: boolean;
+    readonly rejectionMessage: string | null;
+    readonly cancellationReason?: ToolCallCancellationReason;
+}
 export interface AgentSessionConfig {
     readonly flowType: string;
     readonly toolPolicies: Readonly<Record<string, ToolPolicy>>;
     readonly defaultToolEffect: ToolEffect;
     readonly eventStreamCapacityBytes: number;
     readonly interruptDeadlineMs: number | undefined;
+    readonly tracing: ResolvedAgentTracingOptions;
+    readonly builtInTools: ReadonlySet<BuiltInTool>;
+    readonly maxDurableWaitMs: number;
+    readonly planModeEnabled: boolean;
+    readonly compaction: ResolvedCompactionPolicy | undefined;
+    readonly messageWindowSize: number;
+    readonly messageChunkSize: number;
+    readonly messageChunkMaxBytes: number;
+    readonly retainedMessageLimit: number | null;
 }
 /** Shared state reads, writes, and routing used by every session Step. */
 export declare class AgentSessionTransitions {
     readonly persistence: AgentSessionPersistence;
-    readonly runner: AgentFrameworkRunner;
+    readonly runner: AgentFrameworkRunner<DeferredToolOutcome>;
     readonly config: AgentSessionConfig;
-    constructor(persistence: AgentSessionPersistence, runner: AgentFrameworkRunner, config: AgentSessionConfig);
+    readonly tracer: AgentSessionTracer;
+    constructor(persistence: AgentSessionPersistence, runner: AgentFrameworkRunner<DeferredToolOutcome>, config: AgentSessionConfig, tracer: AgentSessionTracer);
     readOptionalAgentState(context: Context): AgentState | null;
     readAgentState(context: Context): AgentState;
     writeAgentState(context: Context, state: AgentState): void;
     readPendingInterrupts(context: Context): readonly AgentInterrupt[];
+    readOptionalAgentPlan(context: Context): AgentPlan | null;
     readAgentUsage(context: Context): AgentUsage;
+    /** The settings the next turn starts with, or `null` when the session has none. */
+    readSessionSettings(context: Context): SessionSettings | null;
+    /** The settings the active turn started with; see {@link selectTurnSessionSettings}. */
+    readTurnSessionSettings(context: Context): SessionSettings;
+    readContextSummary(context: Context): ContextSummary | null;
+    /** The summary the runner sees; a runner without the compaction methods keeps every message instead. */
+    readRunnerContextSummary(context: Context): ContextSummary | null;
     readFrameworkRunState(context: Context): string | null;
-    /** Returns messages with sequences in [start, end); requires the AgentMessages load. */
+    readMessageIndex(context: Context): AgentMessageIndex | null;
+    /** Sequence of the oldest stored message: retention deleted the earlier ones. */
+    readFirstStoredSequence(context: Context): number;
+    /**
+     * Returns the stored messages with sequences in [start, end), from the `AgentMessages` window and the
+     * `AgentMessageChunks` instances. It requires the whole window and every chunk it reads to be loaded.
+     */
     readMessages(context: Context, start: number, end: number): AgentMessage[];
+    private readWindowMessage;
+    /** Reads one loaded chunk and checks that it holds exactly the messages its range names. */
+    private readChunkMessages;
+    /**
+     * Counts the active turn's stored messages after the user messages that started it, before this Step's
+     * appends. A turn without its `TurnReplySequence`, such as one a 0.1.0 Worker started, is counted from its
+     * stored messages instead.
+     */
+    countStoredTurnReplies(context: Context, state: AgentState, turnId: string): number;
+    /** Returns the first sequence after the turn's user messages, from `TurnReplySequence` or the stored messages. */
+    private readTurnReplySequence;
+    /**
+     * Returns the turn's newest stored messages, read back until another turn's, the oldest stored message, or a
+     * chunk this Step did not load.
+     */
+    private readStoredTurnMessages;
+    /** Reads one stored message from the window or its chunk, or returns `undefined` when its chunk is not loaded. */
+    private readLoadedMessage;
+    /** First sequence of the model input: after the runner's summary, and never before the oldest stored message. */
+    readModelInputFirstSequence(context: Context, summary: ContextSummary | null): number;
+    /**
+     * Returns the archive chunks that hold messages in [start, end): every chunk when compaction is off, since
+     * the model input then covers them all, else exact instances.
+     */
+    messageChunkLoads(context: Context, start: number, end?: number): MessageChunkLoads;
+    /** The chunk loads of a Step that rebuilds the model input. */
+    modelInputChunkLoads(context: Context, summary: ContextSummary | null): MessageChunkLoads;
+    /** Moves to `RunModel`, loading the window and the archive chunks of the model input. */
+    goToRunModel(context: Context, summary?: ContextSummary | null): StepDecision;
+    /** Moves to `ApplyTurnControl`, which may rebuild the model input for unfinished-turn messages. */
+    goToApplyTurnControl(context: Context): StepDecision;
+    private goToModelInputStep;
     /** Returns the turn's tool call records in deferral order; requires the AgentToolCalls load. */
-    readTurnToolCalls(context: Context, turnId: string | null): AgentToolCall[];
+    readTurnToolCalls(context: Context, turnId: string | null): AgentToolCallRecord[];
     /** Returns one tool call record; requires the AgentToolCalls load. */
-    readToolCall(context: Context, toolCallId: string): AgentToolCall;
+    readToolCall(context: Context, toolCallId: string): AgentToolCallRecord;
     /** Tells `ResumeTurn` that one tool call of the batch has a final record. */
     publishToolCallResult(context: Context, toolCallId: string): void;
-    writeToolCall(context: Context, toolCall: AgentToolCall): void;
-    /** Appends messages, writes the advanced AgentState, and returns it. */
-    appendMessages(context: Context, state: AgentState, turnId: string, frameworkMessages: readonly FrameworkMessage[]): AgentState;
-    /** Appends the user message, opens the next turn, and moves to RunModel. */
-    beginTurn(context: Context, state: AgentState, text: string): StepDecision;
+    writeToolCall(context: Context, toolCall: AgentToolCallRecord): void;
+    /**
+     * Writes a final record, its `tool_call_finished` event, and its `ToolCallResults` notice in one commit.
+     * Pass the Step's open events writer, if it has one, so the event keeps its order.
+     */
+    finishToolCall(context: Context, toolCall: AgentToolCallRecord, events?: StreamAgentEventWriter): void;
+    writeInterruptRaised(events: StreamAgentEventWriter, interrupt: AgentInterrupt): void;
+    writeInterruptResolved(context: Context, turnId: string, resolution: InterruptResolvedEvent): void;
+    /** Writes the `interrupt_resolved` event of an interrupt that steering or `cancel_turn` removed. */
+    writeInterruptCancelled(context: Context, turnId: string, interruptId: string, kind: AgentInterruptKind, reason: ToolCallCancellationReason): void;
+    /**
+     * Returns why the turn ends at this boundary, or `null`. It reads committed state only: a matching
+     * `TurnCancellationRequest`, then any pending steered message.
+     */
+    readTurnControlReason(context: Context, turnId: string | null): ToolCallCancellationReason | null;
+    /** Builds the runner's view of a turn; every record must be final. */
+    createTurnContext(context: Context, state: AgentState, turnId: string, toolCalls: readonly AgentToolCallRecord[], events: StreamAgentEventWriter, heartbeat: () => Promise<void>): AgentTurnContext;
+    /**
+     * Returns the runner's unfinished-turn messages for an ending turn, or `null` when the runner has no such
+     * method or it throws, so the caller stores its note instead.
+     */
+    buildUnfinishedTurnMessages(context: Context, state: AgentState, turnId: string, finalToolCalls: readonly AgentToolCallRecord[]): readonly FrameworkMessage[] | null;
+    isEnabledBuiltInTool(toolName: string): toolName is BuiltInTool;
+    /**
+     * Appends messages, writes the advanced AgentState, and returns it.
+     *
+     * A message goes into the `AgentMessages` window, or, when its own chunk would exceed `messageChunkMaxBytes`,
+     * straight into a chunk of its own, so the first store writes the largest value it ever needs. In the same
+     * commit it moves the oldest window messages into archive chunks while the window is over its size and
+     * applies retention; it writes `AgentMessageIndex` only when one of them changed it. It requires the whole
+     * window to be loaded. With `startsTurn`, `TurnReplySequence` records where the turn's replies begin.
+     */
+    appendMessages(context: Context, state: AgentState, turnId: string, frameworkMessages: readonly FrameworkMessage[], startsTurn?: boolean): AgentState;
+    /**
+     * Moves the oldest window messages into immutable chunks while the window holds more than its size. A chunk
+     * closes at `messageChunkSize` messages, at `messageChunkMaxBytes` bytes, or before a message stored in its
+     * own chunk. One commit writes at most {@link messageRolloverMaxChunksPerCommit} chunks and
+     * {@link messageRolloverMaxBytesPerCommit} bytes, so a backlog drains over several commits.
+     */
+    private rollOverMessageWindow;
+    /**
+     * Deletes the oldest archive chunk while every message in it is summarized and at least `retainedMessageLimit`
+     * stored messages come after it, so the newest `retainedMessageLimit` messages always stay. It runs only with
+     * compaction and a limit.
+     */
+    applyMessageRetention(context: Context, index: AgentMessageIndex, nextMessageSequence: number, summary: ContextSummary | null): AgentMessageIndex;
+    /** Appends the turn's user messages, in order, opens the next turn, and moves to RunModel. */
+    beginTurn(context: Context, state: AgentState, messages: readonly AgentUserMessage[], stepType: string, interactionMode?: InteractionMode, executedPlan?: AgentPlan, wasPlanDraft?: boolean, sessionSettings?: SessionSettings | null): StepDecision;
+    /**
+     * Returns the mode of a turn that these user messages start: `planning` when plan mode is enabled and a
+     * message has `planMode` or a `draft` plan exists, else `chat`.
+     */
+    decideInteractionMode(context: Context, messages: readonly AgentUserMessage[]): InteractionMode;
+    /** Ends a steered or cancelled turn with its unfinished-turn messages, or with a note; returns the new state. */
+    endControlledTurn(context: Context, initialState: AgentState, turnId: string, steeredMessageCount: number): AgentState;
     goToAwaitUserMessage(): StepDecision;
+    /** Reports whether `cancel_turn` stopped this turn; reads committed state only. */
+    isTurnCancelled(context: Context, turnId: string | null): boolean;
     resolveToolPolicy(toolName: string, frameworkEffect?: ToolEffect): ResolvedToolPolicy;
     recordUsage(context: Context, usage: AgentUsage, events: StreamAgentEventWriter): void;
     createEventWriter(context: Context, turnId: string | null): StreamAgentEventWriter;
     writeEvents(context: Context, turnId: string | null, write: (events: StreamAgentEventWriter) => void): void;
     /** Runs an operation while recording a heartbeat every 20 seconds. */
-    runWithHeartbeats<Result>(context: AsyncContext, operation: () => Promise<Result>): Promise<Result>;
+    runWithHeartbeats<Result>(context: AsyncContext, operation: () => Promise<Result>, recordHeartbeat?: () => Promise<void>): Promise<Result>;
     recordHeartbeat(context: AsyncContext): Promise<void>;
 }
+/**
+ * Heartbeats of one tool Step attempt. Each carries the latest checkpoint, else the Step execution ID,
+ * which every attempt shares and so never reads as a checkpoint.
+ */
+export declare class ToolStepHeartbeats {
+    private readonly context;
+    readonly previousCheckpoint: string | undefined;
+    private checkpoint;
+    constructor(context: AsyncContext);
+    record(): Promise<void>;
+    saveCheckpoint(checkpoint: string): Promise<void>;
+}
+/** Returns a record as a runner sees it; only records that runners may see are accepted. */
+export declare function toRunnerToolCall(record: AgentToolCallRecord): AgentToolCall;
+/** Moves to `FinishTurnCancellation` for one turn; its locks come from the Step's own options. */
+export declare function finishTurnCancellationMovement(turnId: string): StepMovement<string>;
+/** Reports whether `cancel_turn` abandons this call's started task. */
+export declare function isAbandonedToolTask(toolCall: AgentToolCallRecord): boolean;
+/** Reports whether steering or `cancel_turn` may abandon a call that waits in a session Step. */
+export declare function isCancellableByTurnControl(toolCall: AgentToolCallRecord): boolean;
+/** Returns a record that steering or `cancel_turn` abandoned before the call started. */
+export declare function cancelledToolCall(toolCall: AgentToolCallRecord, reason: ToolCallCancellationReason): AgentToolCallRecord;
+/**
+ * Returns the kept chunk that holds a message, found by binary search over the index's ordered ranges, or
+ * `undefined` when the message is in the window.
+ */
+export declare function findMessageChunkRange(index: AgentMessageIndex, sequence: number): AgentMessageChunkRange | undefined;
+/** Whether a chunk holds exactly the messages of its range, in order. */
+export declare function isMessageChunkOfRange(chunk: AgentMessageChunk, range: AgentMessageChunkRange): boolean;
+/** Counts a turn's stored messages after the user messages that started it. */
+export declare function countMessagesAfterUserMessages(messages: readonly AgentMessage[], turnId: string): number;
 export declare function toolStepTypeForEffect(effect: ToolEffect): string;
 /** Returns the text of the failure that selected a recovery Step. */
 export declare function readRecoveryDetail(context: Context): string;
+/** Returns the text of a recovery error: its detail, else its error type, else "unknown failure". */
+export declare function recoveryErrorDetail(recoveryError: RecoveryErrorInfo | undefined): string;
+/** Writes `plan_updated` with the plan's revision, status, and task count. */
+export declare function writePlanUpdated(events: StreamAgentEventWriter, plan: AgentPlan): void;
+/**
+ * Returns the settings of the active turn from its stored copy: the copy's settings while it belongs to that
+ * turn, else `{}`. A turn that a Worker without session settings started, such as 0.1.0, leaves an earlier
+ * turn's copy in place, which must not apply.
+ */
+export declare function selectTurnSessionSettings(stored: TurnSessionSettings | null, activeTurnId: string | null): SessionSettings;