@leuduan/lagent 0.0.0-stage → 44.0.0

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,74 @@
+/**
+ * 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>;
+/**
+ * Route fields to fold over a route (`LlmService.resolveRoute`): absent fields keep the route's own;
+ * naming a different provider resets what is left unnamed to that provider's defaults. A `null`
+ * effort names the provider's own default, as a route records it, so a complete route resolves to
+ * itself.
+ */
+export type ModelSelection = {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly thinkingEffort?: ThinkingEffort | null;
+};
+/** 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,18 @@
+import { z } from 'zod';
+/**
+ * One agent: its name and the base of its prompt. Registered programmatically with
+ * `ctx.agents.register` (usually through `registerAgent`); the name is how threads
+ * and other agents refer to it.
+ *
+ * Strict: an agent says who it is, and nothing else. What it may call is granted to it by name
+ * (`grantTool`) by the plugins that compose the application; instruction and context sections come
+ * from plugins through `ctx.prompts`; how callers see it, a description and guidance, belongs to the
+ * `subAgents` endpoint that offers it. A plugin that needs per-agent configuration keys it by agent
+ * name in its own config, so a misspelled key is rejected here instead of silently ignored there.
+ */
+export declare const AgentDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    basePrompt: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export type AgentDefinition = z.infer<typeof AgentDefinitionSchema>;
+export type AgentDefinitionInput = z.input<typeof AgentDefinitionSchema>;

package/dist/loop/authorization.d.ts

@@ -0,0 +1,41 @@
+import type { AppendEntry, Journal } from '../journal/index.js';
+import type { ExtensionRecord, Seq } from '../records/journal.js';
+import type { LoopRuntime } from './runtime.js';
+import type { ToolAuthorization, ToolAuthorizationRequest } from './hooks.js';
+/**
+ * One owner for authorization ordering: flush policy writes, read approval, collect all policies,
+ * then commit only against the policy state they saw. Authorization and any approval request are
+ * one write guarded against cancellation. Both model and runtime dispatch use it.
+ */
+export declare function authorizeOperation(options: {
+    runtime: LoopRuntime;
+    request: ToolAuthorizationRequest;
+    signal: AbortSignal;
+    approval(): {
+        approved: boolean;
+        rejection_message: string | null;
+    } | undefined;
+    validate?(): void;
+    record(authorization: ToolAuthorization): readonly [AppendEntry<'tool/authorization' | 'execution/authorization'>, ...AppendEntry<'confirm/requested'>[]];
+}): Promise<{
+    kind: 'decided';
+    authorization: ToolAuthorization;
+    attemptSeq: Seq;
+} | {
+    kind: 'rejected';
+    reason: string | null;
+} | {
+    kind: 'unstarted';
+}>;
+/**
+ * Declares the `ext` rows of one plugin event state a `lagent/tool/authorize` listener decides
+ * from: one that lands while a call is authorized sends the decision round again, which no other
+ * `ext` row does. `defineExtensionEvent({ policyState: true })` is the way in.
+ */
+export declare function declarePolicyState(record: Pick<ExtensionRecord, 'plugin' | 'instance_id' | 'kind'>): void;
+/**
+ * Whether policy state — declared `ext` rows or answers (`confirm/resolved`) — landed after `from`
+ * on `threadId` or a thread that called it: what a running thread's policies read. A thread of that
+ * chain that is not loaded counts as changed if anything landed on it.
+ */
+export declare function policyChangedSince(journal: Journal, threadId: string, from: Seq): boolean;

package/dist/loop/auxiliary.d.ts

@@ -0,0 +1,58 @@
+import type { ContentPartInput } from '../llm/content.js';
+import type { ConversationMessage, LLMUsage, ResponseFinish } from '../llm/primitives.js';
+import type { ToolChoice } from '../llm/request.js';
+import type { ModelRoute } from '../llm/provider.js';
+import type { Seq } from '../records/journal.js';
+import type { LoopRuntime } from './runtime.js';
+import type { ModelSelection } from '../llm/provider.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>;

package/dist/loop/chunks.d.ts

@@ -0,0 +1,27 @@
+import type { LLMStreamChunk } from '../llm/primitives.js';
+/** One delta off a model stream, with enough context for a frontend to place it. */
+export type StreamedChunk = {
+    readonly threadId: string;
+    readonly llmCallId: string;
+    readonly turn: number;
+    readonly step: number;
+    readonly chunk: LLMStreamChunk;
+};
+/**
+ * The model's output as it arrives, published to whoever is watching and then forgotten.
+ *
+ * Deliberately not part of the journal. Nothing folds a chunk — the assistant message carries the same
+ * text once the stream ends — so keeping them in the journal only made history depend on a persistence
+ * setting: with chunks dropped on write, a live session and a reopened one read back different
+ * events. The journal is what happened; this is what it looked like happening.
+ *
+ * A frontend that wants to replay streaming can subscribe here and keep its own record.
+ */
+export declare class ChunkChannel {
+    private readonly listeners;
+    private readonly report;
+    constructor(report: (error: unknown) => void);
+    /** One frozen copy of the chunk for every listener, so no listener can change what the next one sees. */
+    emit(chunk: StreamedChunk): void;
+    subscribe(listener: (chunk: StreamedChunk) => void): () => void;
+}

package/dist/loop/completion.d.ts

@@ -0,0 +1,17 @@
+import type { ModelRoute } from '../llm/provider.js';
+import type { Seq, ThreadEnvironment } from '../records/journal.js';
+import type { CompletionRequest } from './hooks.js';
+import type { LoopRuntime } from './runtime.js';
+/** Dispatches a pure completion plan once, under its candidate's durable identity and current policy. */
+export declare function prepareCompletion(options: {
+    runtime: LoopRuntime;
+    threadId: string;
+    agentName: string;
+    environment: ThreadEnvironment;
+    route: ModelRoute;
+    turn: number;
+    candidateSeq: Seq;
+    request: CompletionRequest;
+    signal: AbortSignal;
+    validate(): void;
+}): Promise<'settled' | 'blocked'>;