@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/llm/primitives.d.ts

@@ -0,0 +1,286 @@
+import { z } from 'zod';
+import type { DeepReadonly } from '../util/json.js';
+export declare const THINKING_EFFORT_VALUES: readonly ["none", "low", "medium", "high", "max"];
+export type ThinkingEffort = (typeof THINKING_EFFORT_VALUES)[number];
+export declare const ThinkingEffortSchema: z.ZodEnum<{
+    low: "low";
+    high: "high";
+    none: "none";
+    medium: "medium";
+    max: "max";
+}>;
+export type JsonObject = Record<string, unknown>;
+export declare const JsonObjectSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const defaultInputSchema: () => JsonObject;
+export declare const ToolSpecSchema: z.ZodPipe<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    input_schema: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodTransform<{
+    input_schema: JsonObject;
+    name: string;
+    description: string;
+}, {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}>>;
+export type ToolSpec = z.infer<typeof ToolSpecSchema>;
+/** A tool call whose arguments parsed to an object: the only kind a tool, a policy or a confirmation sees. */
+export declare const ParsedToolCallSchema: z.ZodObject<{
+    call_id: z.ZodString;
+    name: z.ZodString;
+    arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type ParsedToolCall = z.infer<typeof ParsedToolCallSchema>;
+/**
+ * A tool call whose arguments are not a JSON object: `arguments` is `null`, and `malformed` keeps the
+ * text the model sent and why it failed. The loop answers it with an error result and never runs it;
+ * the provider is handed back the raw text it sent.
+ */
+export declare const MalformedToolCallSchema: z.ZodObject<{
+    call_id: z.ZodString;
+    name: z.ZodString;
+    arguments: z.ZodNull;
+    malformed: z.ZodObject<{
+        raw: z.ZodString;
+        error: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$loose>;
+export type MalformedToolCall = z.infer<typeof MalformedToolCallSchema>;
+/** A tool call as the model emitted it. Extra keys are allowed so provider-specific fields survive checkpoints. */
+export declare const ToolCallSchema: z.ZodUnion<readonly [z.ZodObject<{
+    call_id: z.ZodString;
+    name: z.ZodString;
+    arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>, z.ZodObject<{
+    call_id: z.ZodString;
+    name: z.ZodString;
+    arguments: z.ZodNull;
+    malformed: z.ZodObject<{
+        raw: z.ZodString;
+        error: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$loose>]>;
+export type ToolCall = ParsedToolCall | MalformedToolCall;
+/** Whether a call's arguments parsed. */
+export declare const isParsedToolCall: (call: ToolCall) => call is ParsedToolCall;
+/** A call's arguments as text, as the model sent them: the raw text of a malformed call, JSON otherwise. */
+export declare const toolCallArgumentsText: (call: ToolCall) => string;
+export declare const LLMUsageSchema: z.ZodObject<{
+    input_tokens: z.ZodDefault<z.ZodNumber>;
+    output_tokens: z.ZodDefault<z.ZodNumber>;
+    cache_read_input_tokens: z.ZodDefault<z.ZodNumber>;
+    cache_write_input_tokens: z.ZodDefault<z.ZodNumber>;
+    reasoning_output_tokens: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type LLMUsage = z.infer<typeof LLMUsageSchema>;
+export declare const usageTotalTokens: (usage: LLMUsage) => number;
+/**
+ * A tool call the *provider* ran: a web search or code interpreter.
+ *
+ * Descriptive only. The engine never dispatches one and is never owed a result for it — it came
+ * back already answered, and it replays out of `provider_state`, not from here. This exists so a
+ * transcript can show what the model did instead of a gap between two blocks of text.
+ */
+export declare const ProviderCallSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    status: z.ZodDefault<z.ZodEnum<{
+        in_progress: "in_progress";
+        completed: "completed";
+        failed: "failed";
+    }>>;
+    summary: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$loose>;
+export type ProviderCall = z.infer<typeof ProviderCallSchema>;
+export declare const LLMStreamChunkSchema: z.ZodObject<{
+    text_delta: z.ZodDefault<z.ZodString>;
+    reasoning_delta: z.ZodDefault<z.ZodString>;
+    provider_call: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        status: z.ZodDefault<z.ZodEnum<{
+            in_progress: "in_progress";
+            completed: "completed";
+            failed: "failed";
+        }>>;
+        summary: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>;
+}, z.core.$strip>;
+export type LLMStreamChunk = z.infer<typeof LLMStreamChunkSchema>;
+/**
+ * What a provider needs back verbatim on the next request — encrypted reasoning, item ids, signed
+ * blocks. Tagged with the provider that wrote it, so another one ignores it rather than replaying
+ * a shape it does not understand.
+ */
+export declare const ProviderStateSchema: z.ZodObject<{
+    provider: z.ZodString;
+    data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ProviderState = z.infer<typeof ProviderStateSchema>;
+export declare const MESSAGE_ROLES: readonly ["system", "developer", "user", "assistant", "tool"];
+export type MessageRole = (typeof MESSAGE_ROLES)[number];
+export declare const ConversationMessageSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        system: "system";
+        developer: "developer";
+        user: "user";
+        assistant: "assistant";
+        tool: "tool";
+    }>;
+    content: z.ZodPreprocess<z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        detail: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            low: "low";
+            high: "high";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>], "type">>>, unknown>;
+    reasoning_content: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    tool_calls: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        call_id: z.ZodString;
+        name: z.ZodString;
+        arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$loose>, z.ZodObject<{
+        call_id: z.ZodString;
+        name: z.ZodString;
+        arguments: z.ZodNull;
+        malformed: z.ZodObject<{
+            raw: z.ZodString;
+            error: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$loose>]>>>;
+    provider_calls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        status: z.ZodDefault<z.ZodEnum<{
+            in_progress: "in_progress";
+            completed: "completed";
+            failed: "failed";
+        }>>;
+        summary: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$loose>>>;
+    tool_call_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    usage: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        input_tokens: z.ZodDefault<z.ZodNumber>;
+        output_tokens: z.ZodDefault<z.ZodNumber>;
+        cache_read_input_tokens: z.ZodDefault<z.ZodNumber>;
+        cache_write_input_tokens: z.ZodDefault<z.ZodNumber>;
+        reasoning_output_tokens: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>>;
+    provider_state: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        provider: z.ZodString;
+        data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ConversationMessage = z.infer<typeof ConversationMessageSchema>;
+export declare const conversationMessage: (fields: z.input<typeof ConversationMessageSchema>) => ConversationMessage;
+/** The text of a message. The one way to read content, so widening it stays a change in one place. */
+export declare const messageText: (message: DeepReadonly<ConversationMessage>) => string;
+/**
+ * Why a response stopped, normalized so a consumer can tell a truncated response without reading
+ * any provider's own fields: `completed` when the model finished its message (tool calls included),
+ * `length` when it hit the output-token cap, `other` for anything else, a cut-off stream, a content
+ * filter or a reason the provider did not say. Each provider maps its own; the raw fields stay in
+ * `provider_metadata`.
+ */
+export declare const RESPONSE_FINISHES: readonly ["completed", "length", "other"];
+export type ResponseFinish = (typeof RESPONSE_FINISHES)[number];
+export declare const ResponseFinishSchema: z.ZodEnum<{
+    length: "length";
+    completed: "completed";
+    other: "other";
+}>;
+export declare const ModelResponseSchema: z.ZodObject<{
+    message: z.ZodObject<{
+        role: z.ZodEnum<{
+            system: "system";
+            developer: "developer";
+            user: "user";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        content: z.ZodPreprocess<z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            detail: z.ZodDefault<z.ZodEnum<{
+                auto: "auto";
+                low: "low";
+                high: "high";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"file">;
+            file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>], "type">>>, unknown>;
+        reasoning_content: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        tool_calls: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            call_id: z.ZodString;
+            name: z.ZodString;
+            arguments: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$loose>, z.ZodObject<{
+            call_id: z.ZodString;
+            name: z.ZodString;
+            arguments: z.ZodNull;
+            malformed: z.ZodObject<{
+                raw: z.ZodString;
+                error: z.ZodString;
+            }, z.core.$strict>;
+        }, z.core.$loose>]>>>;
+        provider_calls: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+            name: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            status: z.ZodDefault<z.ZodEnum<{
+                in_progress: "in_progress";
+                completed: "completed";
+                failed: "failed";
+            }>>;
+            summary: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        }, z.core.$loose>>>;
+        tool_call_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        usage: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            input_tokens: z.ZodDefault<z.ZodNumber>;
+            output_tokens: z.ZodDefault<z.ZodNumber>;
+            cache_read_input_tokens: z.ZodDefault<z.ZodNumber>;
+            cache_write_input_tokens: z.ZodDefault<z.ZodNumber>;
+            reasoning_output_tokens: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>>;
+        provider_state: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+            provider: z.ZodString;
+            data: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    finish: z.ZodEnum<{
+        length: "length";
+        completed: "completed";
+        other: "other";
+    }>;
+    provider_metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ModelResponse = z.infer<typeof ModelResponseSchema>;

package/dist/llm/prompt.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+/**
+ * One block of a system prompt, in the order it is sent.
+ *
+ * The prompt reaches a provider as blocks rather than one string because where it goes is the
+ * provider's business — Responses has `instructions`, Chat Completions wants a leading message,
+ * Anthropic a top-level param — and because the boundary between the stable blocks and the
+ * volatile ones is where a provider with explicit cache control would cut.
+ */
+export declare const PromptBlockSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        base: "base";
+        instruction: "instruction";
+        context: "context";
+    }>;
+    tag: z.ZodNullable<z.ZodString>;
+    text: z.ZodString;
+}, z.core.$strip>;
+export type PromptBlock = z.infer<typeof PromptBlockSchema>;
+/** Joins blocks for an API that takes one string. */
+export declare const renderPromptBlocks: (blocks: readonly PromptBlock[]) => string;

package/dist/llm/provider.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The provider contract: what a model provider gives the engine, and the route a turn runs on. Here,
+ * beside the client contract, so a provider is written against the model layer alone.
+ */
+import { z } from 'zod';
+import type { LLMClient, ModelCapacity, ModelOption } from './client.js';
+import type { FailureClassification } from './failure.js';
+import { type ThinkingEffort } from './primitives.js';
+/**
+ * The model a turn runs on, with every field resolved: what `run()` named, merged over the thread's
+ * last route, then the registry's defaults. A `thinking_effort` of `null` leaves the effort to the
+ * provider's own default.
+ */
+export declare const ModelRouteSchema: z.ZodObject<{
+    provider: z.ZodString;
+    model: z.ZodString;
+    thinking_effort: z.ZodNullable<z.ZodEnum<{
+        low: "low";
+        high: "high";
+        none: "none";
+        medium: "medium";
+        max: "max";
+    }>>;
+}, z.core.$strip>;
+export type ModelRoute = z.infer<typeof ModelRouteSchema>;
+/** A model provider plugin registers one of these. */
+export interface LLMProvider {
+    readonly name: string;
+    readonly defaultModel: string;
+    /**
+     * The effort a route gets when nothing names one, resolved into the route (`routeOn`); absent, the
+     * route's effort is `null`. Declare the effort the client is built with: a request that carries none
+     * is sent at the client's own default.
+     */
+    readonly defaultThinkingEffort?: ThinkingEffort;
+    /** The models agents are told about. A declaration, not a restriction; absent tells only `defaultModel`. */
+    readonly models?: readonly ModelOption[];
+    /**
+     * What the provider can carry for `model`: its usable context window, `null` where the provider
+     * declares none, and whether a request may carry provider-executed tools. Answers for any model
+     * the provider can be asked for, told or not; `models` is what agents are told, not this lookup.
+     */
+    capacity(model: string): ModelCapacity;
+    /**
+     * The provider's one client, built from its own configuration; the engine asks once and keeps it
+     * until the provider is withdrawn. Every request carries its route's effort when that is not `null`;
+     * one that carries none is sent at the client's configured effort, else the protocol's own.
+     */
+    createClient(): LLMClient;
+    /**
+     * The kind of a failure its client threw that the engine's typed evidence does not already decide
+     * (a settlement failure, a `ContextOverflowError`): HTTP statuses, transport errors, a stream's
+     * error codes. `retryAfterMs` comes from structured fields only. Unknown is `other`.
+     */
+    classify(error: unknown): FailureClassification;
+}
+/**
+ * The route a turn gets on `provider` when nothing names a model or an effort. Needs no registry,
+ * so a host can read a provider's defaults before deciding whether to register it.
+ */
+export declare const defaultRoute: (provider: LLMProvider) => ModelRoute;
+/** A route on `provider`, taking its defaults for what is not named. */
+export declare const routeOn: (provider: LLMProvider, model: string | undefined, effort: ThinkingEffort | undefined) => ModelRoute;

package/dist/llm/readLedger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The bookkeeping of when a response's read has ended, which `StreamingLLMResponse` states and every
+ * implementation of it (an adapter's stream, a call through `ctx.llm`, a test double) keeps: a read
+ * ends only when its generator has finished, or the read was closed, and no operation the reader
+ * asked for (`next`, `return`, `throw`) is still pending, so a closure queued behind a pending
+ * `next` keeps it under way however early the generator itself finished.
+ */
+export declare class ReadLedger {
+    private pending;
+    private finished;
+    private over;
+    /** Whether the read has ended: finished, with nothing pending. */
+    get ended(): boolean;
+    /**
+     * Runs one operation the reader asked for and counts it out only once the promise the reader
+     * holds has settled, never before: a read that is over while its own `return` still reads as
+     * pending would let settlement in too early. `closes` marks the generator finished with it, as a
+     * `return` or `throw` finishes one that never started.
+     */
+    operation<T>(run: () => Promise<T>, closes?: boolean): Promise<T>;
+    /** The generator finished (ran through, failed or was closed), or an unread attempt was closed. */
+    finish(): void;
+    private check;
+}

package/dist/llm/request.d.ts

@@ -0,0 +1,58 @@
+import type { DeepReadonly } from '../util/json.js';
+import type { ConversationMessage, JsonObject, ThinkingEffort, ToolSpec } from './primitives.js';
+import type { PromptBlock } from './prompt.js';
+/** How the model may use tools this call. `{ name }` forces one. */
+export type ToolChoice = 'auto' | 'none' | 'required' | {
+    name: string;
+};
+/**
+ * Why a request is sent: a model step of the thread's conversation, or an auxiliary call a plugin
+ * makes beside it, whose reply is never the thread's. Correlation, so middleware that counts,
+ * retries or logs per request can tell the two apart; never configuration.
+ */
+export type RequestPurpose = 'step' | 'auxiliary';
+/** What the model's text must be. `json_schema` is the named, validated form. */
+export type ResponseFormat = {
+    kind: 'text';
+} | {
+    kind: 'json_object';
+} | {
+    kind: 'json_schema';
+    name: string;
+    schema: JsonObject;
+    strict: boolean;
+};
+/**
+ * One model call, as it will be sent.
+ *
+ * Middleware and providers use this same shape. The engine isolates the middleware draft from
+ * canonical history, then snapshots its final value, frozen, for journal recording and the provider.
+ * The data in it is shared and readonly all the way down: middleware replaces a field (the messages,
+ * the tools, the prompt blocks) rather than changing what is in it, and a provider reads it.
+ */
+export interface ModelRequest {
+    messages: readonly DeepReadonly<ConversationMessage>[];
+    model: string;
+    tools: readonly DeepReadonly<ToolSpec>[];
+    /**
+     * Provider-executed tool definitions, passed through verbatim (`{ type: 'web_search' }`, …).
+     * The engine never dispatches one; what it did comes back as
+     * `ConversationMessage.provider_calls`.
+     */
+    providerTools: readonly DeepReadonly<JsonObject>[];
+    toolChoice: DeepReadonly<ToolChoice>;
+    parallelToolCalls: boolean;
+    responseFormat: DeepReadonly<ResponseFormat>;
+    /** Overrides the client's own default for this call; absent means the provider decides. */
+    thinkingEffort?: ThinkingEffort;
+    maxOutputTokens?: number;
+    /** The system prompt, carried beside the conversation rather than as its first message. */
+    systemPrompt: readonly DeepReadonly<PromptBlock>[];
+    readonly signal: AbortSignal;
+    /** Correlation, not configuration: a provider may key a prompt cache on these. */
+    readonly agentName: string;
+    readonly threadId: string;
+    readonly llmCallId: string;
+    /** Correlation like the ids above, so read-only to middleware and left out of the head digest. */
+    readonly purpose: RequestPurpose;
+}

package/dist/loop/agent.d.ts

@@ -0,0 +1,134 @@
+import type { Seq, TurnEndReason } from '../models/index.js';
+import type { DeepReadonly, JsonValue } from '../util/json.js';
+import type { SurfacePrepareOutcome } from './hooks.js';
+import type { Lease, LoopRuntime } from './runtime.js';
+/**
+ * What one `compact()` is given: a cancellation signal, and options for the strategy, which the
+ * engine passes on as they are and never reads.
+ */
+export type CompactOptions = {
+    readonly signal?: AbortSignal;
+    readonly options?: JsonValue;
+};
+/**
+ * The run request an execution serves, as its turns see it: the id every `turn/start` records, the
+ * attempt cutoff of the execution, and the continuation decision, asked after each turn whether to
+ * open another.
+ */
+export type ServedRun = {
+    readonly id: string;
+    readonly attemptCutoff: Seq;
+    continueAfter(ending: DeepReadonly<TurnEndReason>, turnStart: Seq): boolean;
+};
+/** Executes journal-driven turns. Admission, readiness and cancellation ownership live outside the loop. */
+export declare class LoopAgent {
+    private readonly runtime;
+    private readonly threadId;
+    private readonly agentName;
+    private readonly inbox;
+    constructor(options: {
+        runtime: LoopRuntime;
+        threadId: string;
+        agentName: string;
+    });
+    private stepsTaken;
+    /**
+     * The caller already owns the lease, has resolved the agent in a ready runtime, has decided the
+     * run should advance, and supplies a combined turn signal and the run it serves. Opens a turn,
+     * then another for as long as the run's continuation decision says to advance.
+     */
+    run(options: {
+        signal: AbortSignal;
+        lease: Lease;
+        served: ServedRun;
+    }): Promise<void>;
+    /**
+     * One turn: decide, do it, append what happened, decide again.
+     *
+     * Every branch of the decision lives in {@link nextAction}; this only carries out what it asked
+     * for.
+     */
+    private turn;
+    /**
+     * Why a judgment made under `fence` may not stand, or `null` when it does. `activation-changed`:
+     * the activation's plugins changed since readiness, and takes precedence. `judgment-invalidated`:
+     * the constraint registrations the thread requires, by origin too, are not those it was judged
+     * under, one missing or replaced, or a fact a check declared it observed reads differently now.
+     * Such a registration's owner, or a plugin of the activation, can be the checker that would
+     * object, and core accepts whatever no check objects to; one that came back meanwhile did not
+     * judge it; and a verdict resting on a fact that moved while another check awaited is no verdict
+     * on the answer as it stands. Read inside the write that records the judgment.
+     */
+    private fenced;
+    /**
+     * Records how a judged turn ends, `ending` the checks' verdict or their failure, decided inside
+     * the write: one whose fence broke ends the turn `interrupted` instead, the answer still owed its
+     * checks, so a later run judges it again, held while a required owner is missing, rather than
+     * accepting it unchecked or failing the task because its checker was briefly gone or a fact it
+     * read moved. Returns the reason recorded.
+     */
+    private endJudged;
+    /**
+     * Records `turn/start` with the thread's route and the run the turn serves, decided in the write's
+     * builder, the turn's opening point: a cancel that landed while the loop awaited opens nothing,
+     * and a route whose provider is not registered opens nothing either, claims no input, and throws
+     * `RouteUnavailableError`, which fails the run before the turn. A provider lost once the row is
+     * built, its append still waiting on storage included, fails the opened turn.
+     *
+     * The route is the turn's for good, since every model step builds its client from it; it cannot
+     * change under an execution, which holds the thread while its request is pending.
+     */
+    private openTurn;
+    /** The thread's route as its rows stand. */
+    private threadRoute;
+    /**
+     * Asks the thread's strategy for a plan for a caller between turns (the `request` trigger): no turn
+     * opens, no step hook runs and no queued input is claimed; the route is resolved as a turn's would
+     * be. The caller owns the lease, as for a run, and composed the signal as a run's is. An
+     * interrupted open turn is closed first, as a run closes it; a thread with a tool call unanswered,
+     * a confirmation open or an answer unjudged is refused with `ThreadUnsettledError`. Resolves with
+     * the outcome, cancellation included.
+     */
+    compact(options: {
+        signal: AbortSignal;
+        lease: Lease;
+        options: JsonValue | null;
+    }): Promise<SurfacePrepareOutcome>;
+    /** One request to the thread's strategy, carried out by the engine. */
+    private prepare;
+    /**
+     * Asks the stop checks about the provisional answer. Returns how the turn ends — accepted as
+     * `completed`, or `rejected` — or `null` once their continuation messages are recorded.
+     *
+     * An acceptance ends the turn at once. Steering that arrived while the checks ran is still in the
+     * `next-step` inbox, and `run()` opens another turn for it.
+     */
+    private judge;
+    /**
+     * Lets the surface be prepared (`pressure`), then records plugin contributions and the claimed
+     * input, then asks the model.
+     *
+     * The dispatch is the first `await` between deciding this step and recording its input, and the
+     * lease does not exclude `send()` or `withdraw()`. So once it settles the signal is checked and the
+     * inbox read again: only input this step was decided on that is still queued is claimed, so a
+     * withdrawn input stays withdrawn, and input that arrived meanwhile waits for the next step. A step
+     * left with nothing to claim and no reply owed ends without a model call, and the decider decides
+     * again.
+     */
+    private askModel;
+    /** Reports a dispatch a listener ended in failure; one that was cancelled is the turn's to report. */
+    private reportFailedDispatch;
+    /** Runs a step's tool calls. What they did — answered, waited, ended the turn — lands in the journal. */
+    private answerCalls;
+    /**
+     * One model call. What it produced goes to the journal — `assistant/message`, or
+     * `assistant/attempt` when the stream gave nothing usable, which keeps it off the conversation.
+     *
+     * A request the provider refused as longer than the context window is recorded as an attempt
+     * marked `overflow`, and the thread's strategy is asked with `overflow` inside this step, before
+     * any `error` row. The rule is one sentence: an overflow fails the turn unless that request
+     * committed a replacement, however it ended. When it did, the step ends without an error and the
+     * decider asks the model again, from the replaced surface, in a new step.
+     */
+    private callModel;
+}

package/dist/loop/auxiliary.d.ts

@@ -0,0 +1,54 @@
+import type { ContentPartInput, ConversationMessage, LLMUsage, ModelRoute, ResponseFinish, ToolChoice } from '../llm/index.js';
+import type { Seq } from '../models/index.js';
+import type { LoopRuntime, ModelSelection } from './runtime.js';
+/**
+ * One auxiliary model call as a strategy asks for it. The engine builds the request: the head a step
+ * would send now (the recorded prompt and the tools the agent is granted), then the current surface
+ * up to and including the message behind `through`, then `instructions`, each a `user` message sent
+ * verbatim. So the request sends only what the journal holds and what its own row records.
+ */
+export type AuxiliaryCall = {
+    /** The row behind the last surface message sent. The prefix must end on a balanced cut. */
+    readonly through: Seq;
+    /** The messages after the prefix, at least one, each sent in role `user` exactly as given. */
+    readonly instructions: readonly (string | readonly ContentPartInput[])[];
+    /** Route fields folded over the dispatch's route (`LlmService.resolveRoute`). */
+    readonly route?: ModelSelection;
+    /** Fixed on the draft, so request middleware cannot change it. `auto` when absent. */
+    readonly toolChoice?: ToolChoice;
+    /** Fixed on the draft, so request middleware cannot change it; absent leaves it to the provider. */
+    readonly maxOutputTokens?: number;
+};
+/** What an auxiliary call returned, as its `auxiliary/result` row records it, with the message itself. */
+export type AuxiliaryReply = {
+    /** The `auxiliary/request` row; what a replacement made from this reply cites. */
+    readonly requestSeq: Seq;
+    readonly resultSeq: Seq;
+    /** The reply, tool calls and provider calls included, for a caller that must refuse them. */
+    readonly message: ConversationMessage;
+    /** Its text parts. */
+    readonly text: string;
+    readonly finish: ResponseFinish;
+    readonly usage: LLMUsage | null;
+};
+/** Where an auxiliary call is made, and what it may be sent on. */
+export type AuxiliaryContext = {
+    readonly threadId: string;
+    readonly agentName: string;
+    readonly turn: number | null;
+    readonly step: number | null;
+    /** The dispatch's route. */
+    readonly route: ModelRoute;
+    readonly signal: AbortSignal;
+};
+/**
+ * Makes one auxiliary call: through `lagent/llm/request` middleware and the guidance terminal exactly
+ * as a step's request, with `purpose: 'auxiliary'`, its route, tool choice and output cap fixed on
+ * the draft, and no chunk published, since the thread's chunk channel carries its reply.
+ *
+ * Recorded in two rows: `auxiliary/request` in the terminal, before the request is sent, and
+ * `auxiliary/result` when the call ends, with its text and finish or its error, cancellation
+ * included. A call refused for how it was asked, or that fails before its request row, records
+ * nothing; a failure after it is recorded and then thrown as itself.
+ */
+export declare function callAuxiliary(runtime: LoopRuntime, context: AuxiliaryContext, call: AuxiliaryCall): Promise<AuxiliaryReply>;