@superdurable/dex-agents 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,202 @@
+// 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 { StepRef, goTo, stringCodec, } from "@superdurable/dex";
+import { StreamAgentEventWriter } from "./agent-event-writer.js";
+import { resolveToolPolicy, } from "./agent-framework-runner.js";
+import { messageSequenceKey } from "./agent-session-persistence.js";
+import { addAgentUsage, emptyAgentUsage, } from "./agent-session-values.js";
+export const agentSessionStepTypes = {
+    startAgentSession: "StartAgentSession",
+    awaitUserMessage: "AwaitUserMessage",
+    runModel: "RunModel",
+    awaitToolApproval: "AwaitToolApproval",
+    callTool: "CallTool",
+    callSingleAttemptTool: "CallSingleAttemptTool",
+    recordToolFailure: "RecordToolFailure",
+    recordToolOutcomeUnknown: "RecordToolOutcomeUnknown",
+    resumeTurn: "ResumeTurn",
+    recordTurnFailure: "RecordTurnFailure",
+};
+// Keeps liveness well inside the shortest heartbeat timeout, one minute.
+const heartbeatIntervalMs = 20_000;
+/** Shared state reads, writes, and routing used by every session Step. */
+export class AgentSessionTransitions {
+    persistence;
+    runner;
+    config;
+    constructor(persistence, runner, config) {
+        this.persistence = persistence;
+        this.runner = runner;
+        this.config = config;
+    }
+    readOptionalAgentState(context) {
+        return this.persistence.agentState.get(context) ?? null;
+    }
+    readAgentState(context) {
+        const state = this.readOptionalAgentState(context);
+        if (state === null) {
+            throw new Error(`the agent session ${context.flowId} is not initialized`);
+        }
+        return state;
+    }
+    writeAgentState(context, state) {
+        this.persistence.agentState.set(context, state);
+    }
+    readPendingInterrupts(context) {
+        return this.persistence.pendingInterrupts.get(context) ?? [];
+    }
+    readAgentUsage(context) {
+        return this.persistence.agentUsage.get(context) ?? emptyAgentUsage();
+    }
+    readFrameworkRunState(context) {
+        const runState = this.persistence.frameworkRunState.get(context);
+        return runState === undefined || runState === "" ? null : runState;
+    }
+    /** Returns messages with sequences in [start, end); requires the AgentMessages load. */
+    readMessages(context, start, end) {
+        const messages = [];
+        for (let sequence = Math.max(1, start); sequence < end; sequence += 1) {
+            messages.push(this.persistence.agentMessages.get(context, messageSequenceKey(sequence)));
+        }
+        return messages;
+    }
+    /** Returns the turn's tool call records in deferral order; requires the AgentToolCalls load. */
+    readTurnToolCalls(context, turnId) {
+        if (turnId === null) {
+            return [];
+        }
+        const toolCalls = this.persistence.agentToolCalls;
+        return toolCalls
+            .getAllInstanceKeys(context)
+            .map((key) => toolCalls.get(context, key))
+            .filter((toolCall) => toolCall.turnId === turnId)
+            .sort((left, right) => left.deferralOrder - right.deferralOrder);
+    }
+    /** Returns one tool call record; requires the AgentToolCalls load. */
+    readToolCall(context, toolCallId) {
+        const toolCall = this.persistence.agentToolCalls.get(context, toolCallId);
+        if (toolCall === undefined) {
+            throw new Error(`tool call ${toolCallId} has no record in session ${context.flowId}`);
+        }
+        return toolCall;
+    }
+    /** Tells `ResumeTurn` that one tool call of the batch has a final record. */
+    publishToolCallResult(context, toolCallId) {
+        this.persistence.toolCallResults.publish(context, { toolCallId });
+    }
+    writeToolCall(context, toolCall) {
+        this.persistence.agentToolCalls.set(context, toolCall.toolCallId, toolCall);
+    }
+    /** Appends messages, writes the advanced AgentState, and returns it. */
+    appendMessages(context, state, turnId, frameworkMessages) {
+        let nextMessageSequence = state.nextMessageSequence;
+        const createdAt = new Date().toISOString();
+        for (const frameworkMessage of frameworkMessages) {
+            const message = {
+                sequence: nextMessageSequence,
+                turnId,
+                role: frameworkMessage.role,
+                text: frameworkMessage.text,
+                toolCallId: frameworkMessage.toolCallId,
+                toolName: frameworkMessage.toolName,
+                toolArguments: frameworkMessage.toolArguments,
+                toolOutput: frameworkMessage.toolOutput,
+                frameworkItem: frameworkMessage.frameworkItem,
+                createdAt,
+            };
+            this.persistence.agentMessages.set(context, messageSequenceKey(nextMessageSequence), message);
+            nextMessageSequence += 1;
+        }
+        const advancedState = { ...state, nextMessageSequence };
+        this.writeAgentState(context, advancedState);
+        return advancedState;
+    }
+    /** Appends the user message, opens the next turn, and moves to RunModel. */
+    beginTurn(context, state, text) {
+        const turnId = `turn-${state.turnCount + 1}`;
+        const userMessage = this.runner.buildUserMessage(text);
+        if (userMessage.role !== "user") {
+            throw new TypeError("buildUserMessage must return a message with role user");
+        }
+        const sequence = state.nextMessageSequence;
+        const stateWithMessage = this.appendMessages(context, state, turnId, [userMessage]);
+        this.writeAgentState(context, { ...stateWithMessage, status: "running_model", activeTurnId: turnId });
+        this.writeEvents(context, turnId, (events) => events.writeEvent("turn_started", { sequence }));
+        return goTo(new StepRef(agentSessionStepTypes.runModel), undefined);
+    }
+    goToAwaitUserMessage() {
+        return goTo(new StepRef(agentSessionStepTypes.awaitUserMessage), undefined);
+    }
+    resolveToolPolicy(toolName, frameworkEffect) {
+        return resolveToolPolicy(toolName, this.config.toolPolicies, this.config.defaultToolEffect, frameworkEffect);
+    }
+    recordUsage(context, usage, events) {
+        const sessionUsage = addAgentUsage(this.readAgentUsage(context), usage);
+        this.persistence.agentUsage.set(context, sessionUsage);
+        events.writeEvent("usage_recorded", {
+            recorded: usagePayload(usage),
+            session: usagePayload(sessionUsage),
+        });
+    }
+    createEventWriter(context, turnId) {
+        return new StreamAgentEventWriter(context, this.persistence.agentEvents, turnId);
+    }
+    writeEvents(context, turnId, write) {
+        const events = this.createEventWriter(context, turnId);
+        try {
+            write(events);
+        }
+        finally {
+            events.close();
+        }
+    }
+    /** Runs an operation while recording a heartbeat every 20 seconds. */
+    async runWithHeartbeats(context, operation) {
+        const heartbeatTimer = setInterval(() => {
+            // A rejected heartbeat means the attempt already ended; the operation result decides the outcome.
+            this.recordHeartbeat(context).catch(() => undefined);
+        }, heartbeatIntervalMs);
+        try {
+            return await operation();
+        }
+        finally {
+            clearInterval(heartbeatTimer);
+        }
+    }
+    recordHeartbeat(context) {
+        return context.recordHeartbeat(context.stepExecutionId, stringCodec);
+    }
+}
+export function toolStepTypeForEffect(effect) {
+    switch (effect) {
+        case "read":
+        case "idempotent_write":
+            return agentSessionStepTypes.callTool;
+        case "non_idempotent_write":
+        case "unclassified":
+            return agentSessionStepTypes.callSingleAttemptTool;
+    }
+}
+/** Returns the text of the failure that selected a recovery Step. */
+export function readRecoveryDetail(context) {
+    const recoveryError = context.recoveryError;
+    if (recoveryError === undefined) {
+        return "unknown failure";
+    }
+    return recoveryError.detail !== "" ? recoveryError.detail : recoveryError.errorType;
+}
+function usagePayload(usage) {
+    return {
+        model_calls: usage.modelCalls,
+        input_tokens: usage.inputTokens,
+        output_tokens: usage.outputTokens,
+        cached_input_tokens: usage.cachedInputTokens,
+        reasoning_tokens: usage.reasoningTokens,
+    };
+}
+//# sourceMappingURL=agent-session-transitions.js.map

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

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

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

@@ -0,0 +1,337 @@
+/**
+ * Status of an agent session, stored in the `status` field of {@link AgentState}.
+ *
+ * - `waiting_for_user_message`: the session is idle in `AwaitUserMessage`.
+ * - `running_model`: `RunModel` makes the turn's next model call.
+ * - `running_tools`: the requested tool calls run in parallel Steps, some possibly waiting for
+ *   approval, and `ResumeTurn` waits for their results.
+ */
+export type AgentSessionStatus = "waiting_for_user_message" | "running_model" | "running_tools";
+/**
+ * Input of the `StartAgentSession` Step, passed to `Client.startFlow`.
+ *
+ * @example
+ * ```ts
+ * await client.startFlow(flow, "session-42", { initialMessage: "Summarize my inbox" });
+ * ```
+ */
+export interface AgentSessionStartInput {
+    /**
+     * First user message, or `null` to start idle in `AwaitUserMessage`.
+     * Blank text is treated as `null`. Wire field: `initial_message`.
+     */
+    readonly initialMessage: string | null;
+}
+/** Small durable summary of an agent session, stored in the `AgentState` Attribute. */
+export interface AgentState {
+    /** Current session status. Wire field: `status`. */
+    readonly status: AgentSessionStatus;
+    /** Number of completed or failed turns. Wire field: `turn_count`. */
+    readonly turnCount: number;
+    /** ID of the running turn, `turn-<n>`, or `null` when idle. Wire field: `active_turn_id`. */
+    readonly activeTurnId: string | null;
+    /** Sequence assigned to the next stored message; starts at 1. Wire field: `next_message_sequence`. */
+    readonly nextMessageSequence: number;
+    /** Error text of the most recent failed turn, or `null`. Wire field: `last_turn_error`. */
+    readonly lastTurnError: string | null;
+}
+/** Author of one stored agent message. */
+export type AgentMessageRole = "user" | "assistant" | "tool";
+/**
+ * Framework-neutral projection of one framework message, produced by an {@link AgentFrameworkRunner}.
+ *
+ * The session stores it as an {@link AgentMessage} after adding a sequence, turn ID, and time.
+ * Only `frameworkItem` is replayed to the framework; the other fields are display projections.
+ */
+export interface FrameworkMessage {
+    /** Author of the message. */
+    readonly role: AgentMessageRole;
+    /** Display text, or `null` for a message without text, such as a bare tool call. */
+    readonly text: string | null;
+    /** Tool call ID for a tool call or tool result message, otherwise `null`. */
+    readonly toolCallId: string | null;
+    /** Tool name for a tool call or tool result message, otherwise `null`. */
+    readonly toolName: string | null;
+    /** Tool call arguments as JSON text, otherwise `null`. */
+    readonly toolArguments: string | null;
+    /** Tool result text, otherwise `null`. */
+    readonly toolOutput: string | null;
+    /** Framework-native JSON for this message; the session replays it to the framework unchanged. */
+    readonly frameworkItem: string;
+}
+/** One message stored in the `AgentMessages` AttributeMap under its zero-padded sequence. */
+export interface AgentMessage extends FrameworkMessage {
+    /** Monotonic session-wide sequence, starting at 1. Wire field: `sequence`. */
+    readonly sequence: number;
+    /** Turn that produced the message. Wire field: `turn_id`. */
+    readonly turnId: string;
+    /** RFC 3339 time at which the session stored the message. Wire field: `created_at`. */
+    readonly createdAt: string;
+}
+/**
+ * Side-effect class of a tool, which decides where and how often the session runs it.
+ *
+ * - `read`: runs in `CallTool`, up to 3 attempts; no approval by default.
+ * - `idempotent_write`: runs in `CallTool`, up to 3 attempts with one idempotency key; when they run
+ *   out, the session records `outcome_unknown`.
+ * - `non_idempotent_write`: runs once in `CallSingleAttemptTool`; a crash records `outcome_unknown`.
+ * - `unclassified`: treated like `non_idempotent_write`; the default for tools without a policy.
+ */
+export type ToolEffect = "read" | "idempotent_write" | "non_idempotent_write" | "unclassified";
+/**
+ * Status of one deferred tool call record.
+ *
+ * `awaiting_approval` and `approved` are open. The other statuses are final: the session
+ * never runs a call whose record is final, and the runner reports the result to the model.
+ * `failed` means the tool threw {@link ToolExecutionError}, or a `read` call ended without a result after
+ * its attempts ran out. `outcome_unknown` means a write's tool Step ended without a result, through a
+ * Worker crash, a timeout, or another error after its attempts ran out.
+ */
+export type AgentToolCallStatus = "awaiting_approval" | "approved" | "rejected" | "succeeded" | "failed" | "outcome_unknown";
+/** Durable record of one deferred tool call, stored in `AgentToolCalls` under its tool call ID. */
+export interface AgentToolCall {
+    /** Framework tool call ID; non-empty and slash-free. Wire field: `tool_call_id`. */
+    readonly toolCallId: string;
+    /** Turn that deferred the call. Wire field: `turn_id`. */
+    readonly turnId: string;
+    /** Tool name. Wire field: `tool_name`. */
+    readonly toolName: string;
+    /** Tool arguments as JSON text. Wire field: `arguments`. */
+    readonly arguments: string;
+    /** Effect that selected the tool Step. Wire field: `effect`. */
+    readonly effect: ToolEffect;
+    /** Whether the call waited for `resolve_interrupt`. Wire field: `requires_approval`. */
+    readonly requiresApproval: boolean;
+    /** Current status. Wire field: `status`. */
+    readonly status: AgentToolCallStatus;
+    /** Tool output text after `succeeded`, otherwise `null`. Wire field: `output`. */
+    readonly output: string | null;
+    /**
+     * The `ToolExecutionError` message, or the failed Step's recovery detail, after `failed` or
+     * `outcome_unknown`; otherwise `null`. Wire field: `error`.
+     */
+    readonly error: string | null;
+    /** Rejection text after `rejected`, otherwise `null`. Wire field: `rejection_message`. */
+    readonly rejectionMessage: string | null;
+    /**
+     * Zero-based order in which the turn deferred the call; approved calls run in this order.
+     * It extends the planned contract, as in the Python core. Wire field: `deferral_order`.
+     */
+    readonly deferralOrder: number;
+}
+/** One pending approval request, stored in the `PendingInterrupts` Attribute. */
+export interface AgentInterrupt {
+    /** Interrupt ID; equals the tool call ID for tool approvals. Wire field: `interrupt_id`. */
+    readonly interruptId: string;
+    /** Interrupt kind. Wire field: `kind`. */
+    readonly kind: "tool_approval";
+    /** Tool call awaiting approval. Wire field: `tool_call_id`. */
+    readonly toolCallId: string;
+    /** Tool name. Wire field: `tool_name`. */
+    readonly toolName: string;
+    /** Tool arguments as JSON text. Wire field: `arguments`. */
+    readonly arguments: string;
+    /** RFC 3339 time at which the interrupt was raised. Wire field: `created_at`. */
+    readonly createdAt: string;
+    /** RFC 3339 approval deadline, or `null` for no deadline. Wire field: `deadline`. */
+    readonly deadline: string | null;
+}
+/** Resolution of one interrupt, published to the `InterruptResolutions` ChannelMap. */
+export interface AgentInterruptResolution {
+    /** Whether the tool call may run. Wire field: `approved`. */
+    readonly approved: boolean;
+    /** Text shown to the model when rejected, or `null`. Wire field: `rejection_message`. */
+    readonly rejectionMessage: string | null;
+}
+/**
+ * Model usage counters, stored cumulatively in the `AgentUsage` Attribute.
+ *
+ * Runners report the usage of one model call in an {@link AgentTurnOutcome}; the session adds it.
+ * Use {@link emptyAgentUsage} and {@link addAgentUsage} to accumulate per-model-call usage.
+ */
+export interface AgentUsage {
+    /** Number of model calls. Wire field: `model_calls`. */
+    readonly modelCalls: number;
+    /** Input tokens, including cached input tokens. Wire field: `input_tokens`. */
+    readonly inputTokens: number;
+    /** Output tokens, including reasoning tokens when the provider counts them so. Wire field: `output_tokens`. */
+    readonly outputTokens: number;
+    /** Input tokens served from a provider cache. Wire field: `cached_input_tokens`. */
+    readonly cachedInputTokens: number;
+    /** Reasoning tokens reported by the provider. Wire field: `reasoning_tokens`. */
+    readonly reasoningTokens: number;
+}
+/**
+ * Notice that one tool call of the current batch reached a final record, published to the internal
+ * `ToolCallResults` Channel. `ResumeTurn` waits for one per requested tool call; the result itself is
+ * in the call's `AgentToolCalls` record.
+ */
+export interface ToolCallCompleted {
+    /** Tool call whose record is final. Wire field: `tool_call_id`. */
+    readonly toolCallId: string;
+}
+/** One user message, the input of the `send_user_message` RPC and the `QueuedUserMessages` Channel value. */
+export interface AgentUserMessage {
+    /** Message text. Blank text is rejected. Wire field: `text`. */
+    readonly text: string;
+}
+/**
+ * Standard type of one {@link AgentEvent}. Adapters may write other types with an adapter prefix.
+ *
+ * Payloads are JSON objects with snake_case keys, serialized with sorted keys:
+ * - `turn_started`: `{"sequence"}`, the sequence of the user message that started the turn.
+ * - `turn_completed`: `{"message_count"}`, the number of messages the turn appended.
+ * - `turn_failed`: `{"error"}`.
+ * - `text_delta` and `reasoning_delta`: `{"text"}`.
+ * - `tool_call_started`: `{"tool_call_id","tool_name"}`.
+ * - `tool_call_finished`: `{"tool_call_id","tool_name","status"}`, when a record becomes final,
+ *   including a rejection.
+ * - `tool_call_deferred`: `{"tool_call_id","tool_name","effect","requires_approval"}`, when the model
+ *   asks for a call, which then runs in its own Step.
+ * - `interrupt_raised`: `{"interrupt_id","tool_call_id","tool_name","deadline"}`.
+ * - `interrupt_resolved`: `{"interrupt_id","approved","rejection_message"}`.
+ * - `usage_recorded`: `{"recorded","session"}`: one model call's and the cumulative usage, each with
+ *   {@link AgentUsage} wire fields.
+ */
+export type AgentEventType = "turn_started" | "turn_completed" | "turn_failed" | "text_delta" | "reasoning_delta" | "tool_call_started" | "tool_call_finished" | "tool_call_deferred" | "interrupt_raised" | "interrupt_resolved" | "usage_recorded";
+/** One best-effort live event, written to the `AgentEvents` Stream. */
+export interface AgentEvent {
+    /** An {@link AgentEventType} or an adapter-specific type such as `"vercel_ai.step"`. Wire field: `type`. */
+    readonly type: string;
+    /** Turn the event belongs to, or `null`. Wire field: `turn_id`. */
+    readonly turnId: string | null;
+    /** One-based attempt of the Step that wrote the event. Wire field: `attempt`. */
+    readonly attempt: number;
+    /**
+     * Dex Step execution ID of the Step that wrote the event; all attempts of one Step execution share
+     * it. Events written before this field existed decode with `""`. Wire field: `step_execution_id`.
+     *
+     * Group live text by `(turnId, stepExecutionId, attempt)`. Within one `stepExecutionId`, keep only the
+     * events of the highest `attempt` seen and drop the partial text of lower attempts. Different
+     * `stepExecutionId` values of one turn are its model calls and tool Steps, and each keeps its
+     * own events. After `turn_completed` or `turn_failed`, replace the turn's live text with the stored
+     * messages.
+     */
+    readonly stepExecutionId: string;
+    /** Event payload as JSON text. Wire field: `payload`. */
+    readonly payload: string;
+}
+/** Input of the `resolve_interrupt` RPC. */
+export interface ResolveInterruptInput {
+    /** Pending interrupt to resolve. Wire field: `interrupt_id`. */
+    readonly interruptId: string;
+    /** Whether the tool call may run. Wire field: `approved`. */
+    readonly approved: boolean;
+    /** Text shown to the model when rejected, or `null`. Wire field: `rejection_message`. */
+    readonly rejectionMessage: string | null;
+}
+/** Output of the `get_agent_snapshot` RPC, enough for a UI to rebuild its view. */
+export interface AgentSnapshot {
+    /** Current session state, or `null` before `StartAgentSession` committed. Wire field: `state`. */
+    readonly state: AgentState | null;
+    /** Up to the last 200 messages in ascending sequence order. Wire field: `messages`. */
+    readonly messages: readonly AgentMessage[];
+    /** Interrupts that `resolve_interrupt` still accepts. Wire field: `pending_interrupts`. */
+    readonly pendingInterrupts: readonly AgentInterrupt[];
+    /** Deferred tool call records of the active turn, in deferral order. Wire field: `tool_calls`. */
+    readonly toolCalls: readonly AgentToolCall[];
+    /** Cumulative usage. Wire field: `usage`. */
+    readonly usage: AgentUsage;
+    /** User messages queued and not yet consumed. Wire field: `queued_message_count`. */
+    readonly queuedMessageCount: number;
+}
+/** Input of the `list_agent_messages` RPC. */
+export interface ListAgentMessagesInput {
+    /** Return messages with a smaller sequence, or `null` for the newest. Wire field: `before_sequence`. */
+    readonly beforeSequence: number | null;
+    /** Page size; the session clamps it to 1..200. A missing wire value means 50. Wire field: `limit`. */
+    readonly limit: number;
+}
+/** Output of the `list_agent_messages` RPC. */
+export interface AgentMessagesPage {
+    /** Messages in ascending sequence order. Wire field: `messages`. */
+    readonly messages: readonly AgentMessage[];
+    /**
+     * Value to pass as `beforeSequence` for the next older page, or `null` when no older message exists.
+     * Wire field: `next_before_sequence`.
+     */
+    readonly nextBeforeSequence: number | null;
+}
+/**
+ * Returns usage with every counter at zero.
+ *
+ * @returns A new {@link AgentUsage} whose counters are all `0`.
+ */
+export declare function emptyAgentUsage(): AgentUsage;
+/**
+ * Adds two usage values counter by counter.
+ *
+ * @example
+ * ```ts
+ * let usage = emptyAgentUsage();
+ * usage = addAgentUsage(usage, { ...emptyAgentUsage(), modelCalls: 1, inputTokens: 120, outputTokens: 30 });
+ * ```
+ * @param left - First usage value.
+ * @param right - Second usage value.
+ * @returns A new {@link AgentUsage} holding the sums; neither input is changed.
+ */
+export declare function addAgentUsage(left: AgentUsage, right: AgentUsage): AgentUsage;
+/**
+ * Reports whether a tool call status is final.
+ *
+ * @param status - Status to classify.
+ * @returns `true` for `rejected`, `succeeded`, `failed`, and `outcome_unknown`; `false` for
+ * `awaiting_approval` and `approved`.
+ */
+export declare function isFinalToolCallStatus(status: AgentToolCallStatus): boolean;
+/** Tool result text the model sees for an `outcome_unknown` call; the same text as the Python core. */
+export declare const outcomeUnknownToolResult: string;
+/** First line of the note `RecordTurnFailure` stores after a failed turn ran tools. */
+export declare const turnFailureNoteHeader = "[Dex] The previous turn failed after these tool calls ran:";
+/** Last line of that note. */
+export declare const turnFailureNoteFooter = "Do not repeat these tool calls unless the user asks again.";
+/** Tool result text the model sees for a rejection without a message; the same text as the Python core. */
+export declare const defaultRejectionToolResult = "The user rejected this tool call.";
+/** Rejection message recorded when an approval deadline passes. */
+export declare const approvalDeadlinePassed = "approval deadline passed";
+/**
+ * Returns the note text that tells the model what a failed turn already did.
+ *
+ * `RecordTurnFailure` stores this note through {@link AgentFrameworkRunner.buildUserMessage} when a
+ * failed turn has final tool call records, as the failed turn's last message, so the next turn's model
+ * does not repeat a write. The text matches the Python core's `build_turn_failure_note`:
+ *
+ * ```text
+ * [Dex] The previous turn failed after these tool calls ran:
+ * - charge {"amount": 5} -> succeeded: charged 5
+ * Do not repeat these tool calls unless the user asks again.
+ * ```
+ *
+ * @param toolCalls - Final records of the failed turn; they are listed in `deferralOrder`.
+ * @returns {@link turnFailureNoteHeader}, one `- <toolName> <arguments> -> <status>: <outcome>` line
+ * per record, with the outcome from {@link describeToolCallOutcome}, and {@link turnFailureNoteFooter},
+ * joined with newlines.
+ * @throws {TypeError} When a record is not final.
+ */
+export declare function buildTurnFailureNote(toolCalls: readonly AgentToolCall[]): string;
+/**
+ * Returns the tool result text a runner shows the model for a final tool call record.
+ *
+ * Use it when resuming a framework whose tool result must be text. A runner whose framework has a
+ * native rejection, such as a rejection message argument, may pass `rejectionMessage` there instead.
+ * The texts match the Python core's `describe_tool_call_outcome`.
+ *
+ * @example
+ * ```ts
+ * const record = turn.recordedToolCall(pendingCallId);
+ * if (record !== undefined && isFinalToolCallStatus(record.status)) {
+ *   frameworkToolResult = describeToolCallOutcome(record);
+ * }
+ * ```
+ * @param toolCall - Record whose status is final.
+ * @returns The output for `succeeded`; `The tool call failed: <error>` for `failed`; the rejection
+ * message, or {@link defaultRejectionToolResult}, for `rejected`; {@link outcomeUnknownToolResult}
+ * for `outcome_unknown`.
+ * @throws {TypeError} When the record status is `awaiting_approval` or `approved`.
+ */
+export declare function describeToolCallOutcome(toolCall: AgentToolCall): string;