@superdurable/dex-agents 0.1.0 → 0.3.0

package/dist/src/stepwise/stepwise-agent-runner.d.ts

@@ -0,0 +1,171 @@
+import { type ContextSummaryRequest, type ContextSummaryResult } from "../agent-context-compaction.js";
+export { buildContextSummaryNote, buildContextSummaryOmissionNote, contextSummaryInstructions, contextSummaryNoteHeader, contextSummaryRequest, } from "../agent-context-compaction.js";
+import { type AgentFrameworkRunner, type AgentTurnContext, type AgentTurnOutcome, type DeferredToolExecution, type DeferredToolOutcome, type ToolTaskCancellation, type ToolTaskPoll, type ToolTaskPollOutcome } from "../agent-framework-runner.js";
+import { type FrameworkMessage } from "../agent-session-values.js";
+import type { AgentDefinition } from "./agent-definition.js";
+/** Default {@link AgentDefinition.toolSourceListingTimeoutMs}: 10 seconds. */
+export declare const defaultToolSourceListingTimeoutMs = 10000;
+export declare const defaultMaxModelCallsPerTurn = 100;
+/** Result of a tool call the model made after the turn's model call limit; the same text as the Python core. */
+export declare function buildToolCallLimitReachedResult(maxModelCallsPerTurn: number): string;
+/**
+ * The {@link AgentFrameworkRunner} of the built-in Stepwise loop.
+ *
+ * {@link createStepwiseAgentSessionFlow} creates one; construct it directly only to pass it to
+ * `createAgentSessionFlow` with options of your own. Each `RunModel` makes at most one model call
+ * through {@link AgentDefinition.model}, from committed state only: the stored messages, the results
+ * of the previous model response from the turn's final records, and the instructions. The runner
+ * stores the turn's transcript as it goes through {@link ToolCallsRequested.newMessages}, so a long turn
+ * never rewrites a growing run state. It supports plan mode: a `planning` turn offers only `write_todos`, and
+ * every model call shows the plan with {@link buildPlanNote} before the turn's messages. It implements the
+ * compaction methods, so a session with a compaction policy starts the model input with the summary. Its
+ * {@link pollToolTask} passes a tool task to the {@link ToolSource} that started it; function tools start no
+ * tasks. Its {@link cancelToolTask} passes a task that `cancel_turn` abandoned to that source's optional
+ * `cancelToolTask`.
+ *
+ * @example
+ * ```ts
+ * const runner = new StepwiseAgentRunner(definition);
+ * const flow = createAgentSessionFlow(runner, "SupportAgent", { builtInTools: ["ask_user"] });
+ * ```
+ */
+export declare class StepwiseAgentRunner implements AgentFrameworkRunner<DeferredToolOutcome> {
+    /** The agent definition, frozen at construction. */
+    readonly definition: AgentDefinition;
+    /** The runner honors {@link AgentTurnContext.interactionMode}, so plan mode can be enabled. */
+    readonly supportsPlanMode = true;
+    private readonly functionToolsByName;
+    private readonly toolSources;
+    private readonly toolSourcesByName;
+    private readonly maxModelCallsPerTurn;
+    private readonly toolSourceListingTimeoutMs;
+    /** The last listing of each source, so estimates count its tools without listing again. */
+    private readonly lastListings;
+    /**
+     * Creates the runner and checks the definition.
+     * @param definition - The agent definition.
+     * @throws {TypeError} When the name, instructions, model, or tools are invalid, two tools share a
+     * name, a function tool uses the name of an enabled built-in tool, `planModeEnabled` is set without
+     * `write_todos`, `planningToolChoice` is neither `auto` nor `required`, or a tool source lacks a
+     * {@link ToolSource} method.
+     * @throws {RangeError} When `maxModelCallsPerTurn` is not a positive integer.
+     */
+    constructor(definition: AgentDefinition);
+    /**
+     * Converts user text into a stored `user_text` item.
+     * @param text - User message text.
+     * @returns The message with role `user`.
+     */
+    buildUserMessage(text: string): FrameworkMessage;
+    /**
+     * Makes the turn's next model call.
+     * @param turn - The turn context.
+     * @returns {@link TurnCompleted} with the results and final answer not stored yet, or
+     * {@link ToolCallsRequested} with the previous results, this response, and its tool calls.
+     * @throws {TypeError} When a function tool uses the name of an enabled built-in tool, or a tool source lists a
+     * name that repeats a function tool, an enabled built-in tool, or another source's tool. No model request is
+     * made.
+     * @throws Any error of the model call or of a tool source's `listTools`, which retries the `RunModel` attempt.
+     */
+    runModelStep(turn: AgentTurnContext): Promise<AgentTurnOutcome>;
+    /**
+     * Runs one function tool call after checking its arguments against the tool's schema, or passes a call that a
+     * tool source built in `runModelStep` to that source, with the source's own `toolSourceReference` and without a
+     * listing. Any other name is an unknown tool and never reaches a source.
+     * @param call - The deferred call.
+     * @returns The output: a `string` result unchanged, any other result as JSON; the tool's
+     * {@link ToolInputRequested}; or a source's outcome, such as {@link ToolTaskStarted}.
+     * @throws {ToolExecutionError} For an unknown tool, arguments that are not a JSON object or break the
+     * schema, or a `ToolExecutionError` from the tool or its source.
+     * @throws {RangeError} When a source built the call but the definition no longer has it, so the effect decides
+     * the outcome.
+     * @throws Any other error of the tool source.
+     */
+    executeDeferredToolCall(call: DeferredToolExecution): Promise<DeferredToolOutcome>;
+    /**
+     * Polls a tool source's task once, through the source that built the call.
+     * @param poll - The call's record from `PollToolTask`.
+     * @returns The source's `pollToolTask` outcome.
+     * @throws {RangeError} When no tool source built the call. The task may still run, so `PollToolTask` retries
+     * and then records the call by its effect.
+     * @throws Any error of the source.
+     */
+    pollToolTask(poll: ToolTaskPoll): Promise<ToolTaskPollOutcome>;
+    /**
+     * Cancels a tool source's task through the source that built the call; a source without `cancelToolTask` leaves
+     * its task running.
+     * @param cancellation - The abandoned call's record from `CancelToolTask`.
+     * @returns A Promise that resolves once the source took the cancellation.
+     * @throws {RangeError} When no tool source built the call; `CancelToolTask` retries and then records the call
+     * `outcome_unknown`.
+     * @throws Any error of the source.
+     */
+    cancelToolTask(cancellation: ToolTaskCancellation): Promise<void>;
+    /**
+     * Returns the results of the turn's tool calls that are not stored yet.
+     * @param turn - The ended turn, with every record final.
+     * @returns One `tool_result` message per unstored result, in deferral order.
+     */
+    buildUnfinishedTurnMessages(turn: AgentTurnContext): readonly FrameworkMessage[];
+    /**
+     * Estimates the model input of the next `runModelStep` with the model client.
+     * @param turn - The context of the next model call.
+     * @returns `ModelClient.estimateInputTokens` of the request `runModelStep` would send: instructions,
+     * summary, messages, unstored tool results, and tools. Tool source tools come from each source's `cachedTools`
+     * when it has one, else from the runner's last listing, as in the Python core.
+     */
+    estimateInputTokens(turn: AgentTurnContext): Promise<number>;
+    /**
+     * Chooses the last message to summarize, at a boundary between model responses.
+     *
+     * The runner cuts only before a user message or before the first output item of a model response whose
+     * earlier tool calls all have stored results, so no tool call is separated from its result and no
+     * response is split. It keeps the newest messages that fit the budget, and never summarizes the newest
+     * stored message.
+     *
+     * @param turn - The context of the model call that crossed the threshold.
+     * @param retainedTokenBudget - Tokens that the kept messages may use.
+     * @returns The sequence of the last message to summarize: the earliest cut whose kept messages fit the
+     * budget, else the latest cut; `null` when every message already fits or no cut is possible.
+     */
+    selectCompactionCutoff(turn: AgentTurnContext, retainedTokenBudget: number): number | null;
+    /**
+     * Folds the previous summary and the messages of the range into new text, with one model call.
+     *
+     * The call uses {@link contextSummaryInstructions}, no tools, the previous summary as a note, the
+     * range's items, and {@link contextSummaryRequest} as the last user text. Its text streams nowhere,
+     * because it is not the assistant's answer. When the request would exceed `request.inputTokenBudget`,
+     * such as after a smaller context window or when compaction starts on a long session, the runner leaves
+     * out the oldest items of the range and says so with {@link buildContextSummaryOmissionNote}, so the
+     * call and its `maxOutputTokens`, when set, still fit. It leaves them out up to a boundary between model responses, as
+     * {@link selectCompactionCutoff} cuts, so it never splits a response or separates a tool call from its
+     * result.
+     *
+     * @param request - The previous summary and the messages to summarize.
+     * @returns The response text and the usage of the call.
+     * @throws {Error} When the model returned no text, or any error of the model call.
+     */
+    summarizeContext(request: ContextSummaryRequest): Promise<ContextSummaryResult>;
+    private buildSummaryRequest;
+    private buildModelRequest;
+    private estimateItems;
+    /** A built-in enabled only in the session options must not share a function tool's name. */
+    private requireNoBuiltInToolNameClash;
+    private listSourceTools;
+    private listOneSource;
+    private readCachedSourceTools;
+    private routeToToolSource;
+    private listOfferedTools;
+    /** A session policy wins; otherwise a function tool's own effect and approval apply, as in the Python core. */
+    private resolveModelToolPolicy;
+    private resolveModel;
+    private resolveInstructions;
+}
+/** Error of a call to a tool that no function tool or source listing offers; the same text as the Python core. */
+export declare function buildUnknownToolError(toolName: string): string;
+/** The runner's `toolSourceReference`: the source's name and its own reference, as JSON text. */
+export declare function writeToolSourceEnvelope(sourceName: string, reference: string | undefined): string;
+export declare function readToolSourceEnvelope(toolSourceReference: string | undefined): {
+    readonly sourceName: string;
+    readonly reference: string | undefined;
+} | undefined;