@superdurable/dex-agents 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,179 @@
+import { StepMovement, Wait, type AsyncContext, type Codec, type Context, type RecoveryErrorInfo, type Step, type StepDecision, type StepOptions } from "@superdurable/dex";
+import { type ToolInputRequested } from "./agent-framework-runner.js";
+import { type AgentSessionTransitions } from "./agent-session-transitions.js";
+import { type AgentSessionPersistence } from "./agent-session-persistence.js";
+import { type AgentInterruptKind, type AgentSessionStartInput, type AgentToolCallRecord, type CompactContextInput, type PlanStatus } from "./agent-session-values.js";
+/** Start of the Flow failure reason when `StartAgentSession` refuses the start input's settings. */
+export declare const invalidStartSessionSettingsReason = "dex-agents: the start input's session_settings are not valid session settings";
+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;
+}
+/** Waits for one queued user message, or an approved plan execution, and starts its turn. */
+export declare class AwaitUserMessageStep implements Step<void> {
+    private readonly transitions;
+    readonly inputCodec: Codec<void>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    waitFor(context: Context): Wait;
+    execute(context: Context): StepDecision;
+    private beginUserMessageTurn;
+}
+/** Plan statuses that `execute_plan` accepts and `AwaitUserMessage` waits for. */
+export declare function isExecutablePlanStatus(status: PlanStatus): boolean;
+/** 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>;
+    /** Returns RunModel's move instead of a model call, or `null` to call the model. */
+    private decideBeforeModelCall;
+    private completeTurn;
+    /** Returns the sequence to summarize through before this model call, or `null` to make the call. */
+    private selectCompactionBeforeModelCall;
+    private startCompaction;
+    private requestToolCalls;
+    /** A planning turn hides executable tools; a call to one never runs. */
+    private rejectPlanningTurnToolCall;
+    private deferApplicationToolCall;
+    /** Records a built-in call with its fixed policy and routes it to its wait Step; invalid arguments fail at once. */
+    private deferBuiltInToolCall;
+    /** Replaces the plan and records the call final, in this commit; no tool Step runs. */
+    private writeTodos;
+    private failBuiltInToolCall;
+}
+/** Summarizes the messages through a sequence for the model input, then moves back to `RunModel`. */
+export declare class CompactContextStep implements Step<CompactContextInput | undefined> {
+    private readonly transitions;
+    readonly inputCodec: Codec<CompactContextInput | undefined>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    execute(context: AsyncContext, input: CompactContextInput | undefined): Promise<StepDecision>;
+    private summarize;
+}
+/** 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 applyResolution;
+    private rejectToolCall;
+}
+/** 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>;
+    /** Records `awaiting_answer` with the tool's question; `AwaitQuestionAnswer` raises it under the lock. */
+    private requestToolInput;
+    /** Records `waiting_for_task` and moves to `PollToolTask`, or records a task it cannot poll by effect. */
+    private startToolTask;
+}
+/**
+ * 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`. Either records `failed` with
+ * {@link toolCallNotRunErrorPrefix} when the tool certainly never ran.
+ */
+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;
+}
+/** Returns the final record that a tool Step's failure route writes. */
+export declare function recoveredToolCall(toolCall: AgentToolCallRecord, recoveryError: RecoveryErrorInfo | undefined, status: "failed" | "outcome_unknown"): AgentToolCallRecord;
+/**
+ * Waits until every tool call of the batch has a final record, then makes the next model call.
+ *
+ * A steer wakes it early: it cancels the turn's pending interrupts and Timers, and waits again. After a steer or
+ * `cancel_turn`, once every result is in, it moves to `ApplyTurnControl` instead of `RunModel`.
+ */
+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, expectedResultCount: number): StepDecision;
+    /** Cancels the turn's pending interrupts and wakes each Step waiting for a person or a Timer. */
+    private wakeWaitingToolCalls;
+}
+/** Ends a steered or cancelled turn, then starts a turn with the steered messages. */
+export declare class ApplyTurnControlStep implements Step<void> {
+    private readonly transitions;
+    readonly inputCodec: Codec<void>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    waitFor(): Wait;
+    execute(context: Context): StepDecision;
+}
+/** Ends a failed turn; it is the failure route of `RunModel` and `CompactContext`, so it takes either's input. */
+export declare class RecordTurnFailureStep implements Step<CompactContextInput | undefined> {
+    private readonly transitions;
+    readonly inputCodec: Codec<CompactContextInput | undefined>;
+    constructor(transitions: AgentSessionTransitions);
+    getStepType(): string;
+    getStepOptions(): StepOptions;
+    execute(context: Context): StepDecision;
+}
+/** `last_turn_error` of a turn whose runner stored messages incrementally without the builder. */
+export declare const missingUnfinishedTurnMessageBuilder = "a runner that sets ToolCallsRequested.newMessages must implement buildUnfinishedTurnMessages";
+/**
+ * Returns the full options of a tool Step type. With a tool call ID, the Step loads only that call's
+ * record; a movement's options replace the Step's static options, so every option is repeated here.
+ */
+export declare function toolStepOptions(persistence: AgentSessionPersistence, stepType: string, toolCallId?: string): StepOptions;
+export declare function toolStepMovement(persistence: AgentSessionPersistence, stepType: string, toolCallId: string): StepMovement<string>;
+/** Moves to `PollToolTask`; a poll that keeps failing leaves the task running, so the call is recorded by effect. */
+export declare function toolTaskPollMovement(persistence: AgentSessionPersistence, toolCall: AgentToolCallRecord): StepMovement<string>;
+/** Returns the record of a tool's question: `awaiting_answer`, or `failed` when it is blank. */
+export declare function recordToolInputRequest(toolCall: AgentToolCallRecord, request: ToolInputRequested): AgentToolCallRecord;
+/** Returns a final record for a task that cannot be polled: `failed` for a read, else `outcome_unknown`. */
+export declare function recordToolTaskDefect(toolCall: AgentToolCallRecord, error: string): AgentToolCallRecord;
+/** Returns a poll interval in whole seconds from 1 to a day, or `null` when it is not a finite number. */
+export declare function toolTaskPollIntervalSeconds(seconds: unknown): number | null;
+/** Record fields of a call without a pending tool question. */
+export declare const noPendingToolQuestion: {
+    readonly inputQuestion: null;
+    readonly inputChoices: readonly [];
+    readonly inputAllowsFreeText: true;
+};
+/** Moves to `AwaitQuestionAnswer`, which reads the answer count to tell an unraised question from an answer. */
+export declare function questionAnswerMovement(persistence: AgentSessionPersistence, toolCall: AgentToolCallRecord): StepMovement<string>;
+/** An `ask_user` question uses the tool call ID; a tool's `n`-th question appends `-input-<n>`. */
+export declare function questionInterruptId(toolCall: AgentToolCallRecord): string;
+/** The interrupt a waiting tool call answers to: its ID and kind. */
+export interface WaitingToolCallInterrupt {
+    readonly interruptId: string;
+    readonly kind: AgentInterruptKind;
+}
+/**
+ * Records a call that `ToolCallCancellations` woke as cancelled, or waits again. Pass `interrupt` `null` for a
+ * durable wait.
+ */
+export declare function cancelWaitingToolCall(transitions: AgentSessionTransitions, context: Context, toolCall: AgentToolCallRecord, interrupt: WaitingToolCallInterrupt | null, waitAgain: StepMovement<string>): StepDecision;
+export declare function isToolInputRequested(outcome: unknown): outcome is ToolInputRequested;