@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/loop/errors.d.ts

@@ -0,0 +1,139 @@
+import type { ReadonlyJsonValue } from '../util/json.js';
+import type { Refusal, RowRef } from '../state/index.js';
+/** What holds a thread while an operation on it is refused busy. */
+export type ThreadHolding = 'run' | 'compact' | 'rebuild' | 'configure' | 'release' | 'cancel';
+/** A human's answer to an approval request. */
+export type ApprovalDecision = {
+    readonly approved: boolean;
+    readonly rejection_message: string | null;
+};
+/** No agent is registered under this name. */
+export declare class UnknownAgentError extends ReferenceError {
+    readonly agentName: string;
+    constructor(agentName: string);
+}
+/**
+ * An operation already holds this thread: a run, compaction, prompt rebuild, configuration change,
+ * release or cancel (`holding`), admitted one at a time.
+ */
+export declare class ThreadBusyError extends Error {
+    readonly threadId: string;
+    readonly holding?: ThreadHolding;
+    /** @param holding - what holds the thread, when known: `run`, `compact`, `rebuild`, `configure`, `release` or `cancel`. */
+    constructor(threadId: string, holding?: ThreadHolding);
+}
+/**
+ * A configuration change was recorded, but the thread's plugins could not be restored from it: the
+ * thread is configured as asked and cannot run until a later change lets it restore. `cause` is
+ * the setup's error.
+ */
+export declare class RestoreFailedError extends Error {
+    readonly threadId: string;
+    constructor(threadId: string, cause: unknown);
+}
+/** Creating this thread would nest deeper than `maxThreadDepth` allows. */
+export declare class DepthExceededError extends Error {
+    readonly threadId: string;
+    readonly limit: number;
+    constructor(threadId: string, limit: number);
+}
+/**
+ * Thrown inside a step whose activation went stale before its dispatch, or by a judgment once the
+ * activation went stale under it: the turn ends `interrupted` (`activation-changed`).
+ */
+export declare class StaleActivation extends Error {
+    constructor();
+}
+/**
+ * Thrown by a judgment whose fence broke while the activation stayed valid (`TurnRunner.fenced`): a
+ * required registration is gone or was replaced, or a fact a stop check declared it observed
+ * changed. The turn ends `interrupted` (`judgment-invalidated`), the answer still owed its checks.
+ */
+export declare class JudgmentInvalidated extends Error {
+    constructor();
+}
+/** A turn that failed after appending its own `turn/end`; the journal already says what happened. */
+export declare class RecordedTurnFailure extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+/** What a thread's recorded birth says about one field of a request that differs from it. */
+export type BirthConflict = {
+    readonly field: 'agent' | 'origin' | 'kind' | 'cut' | 'route' | 'environment' | 'installations' | 'requires';
+    /** What the thread recorded: for `kind`, `fresh` or `fork`. */
+    readonly recorded: ReadonlyJsonValue;
+    readonly requested: ReadonlyJsonValue;
+};
+/**
+ * A creation or fork asked for an id a thread already holds, and the request is not that thread:
+ * under `identity` reuse its agent, origin, kind or cut differ, under `configuration` its birth
+ * does too. Never adopted, nothing was written; `conflicts` name every field that differs.
+ */
+export declare class BirthConflictError extends Error {
+    readonly threadId: string;
+    readonly conflicts: readonly BirthConflict[];
+    constructor(threadId: string, conflicts: readonly BirthConflict[]);
+}
+/**
+ * A `create` or `fork` whose write-time `rows` callback vetoed it: nothing was recorded. The
+ * callback's own {@link Refusal} is `refusal`; an error the callback threw is not this, it propagates
+ * as it was thrown.
+ */
+export declare class WriteRefusedError extends Error {
+    readonly refusal: Refusal;
+    readonly operation: 'create' | 'fork';
+    constructor(refusal: Refusal, operation: 'create' | 'fork');
+}
+/**
+ * A change of a thread's installations was asked while its activation is still getting ready: the
+ * change would wait on the setup it came from. Nothing was recorded; `whenReady()` or `close()` the
+ * thread first.
+ */
+export declare class ThreadActivatingError extends Error {
+    readonly threadId: string;
+    constructor(threadId: string);
+}
+/**
+ * An answer to a confirmation that already has one, which it carries. Core compares nothing: a retry
+ * that repeats the recorded answer is refused like any other, and the caller decides whether the
+ * recorded decision is the one it meant. A revoked approval is a recorded rejection.
+ */
+export declare class ConfirmationAnsweredError extends Error {
+    readonly threadId: string;
+    readonly requestId: string;
+    readonly decision: ApprovalDecision;
+    constructor(threadId: string, requestId: string, decision: ApprovalDecision);
+}
+/**
+ * The thread is not settled enough for what was asked: a request to prepare its surface or a change
+ * of its installations met a tool call without a result, a confirmation unfinished (open, or
+ * approved and not yet executed; the reason names its request ids) or an answer its stop checks have
+ * not judged. Nothing was recorded: no replacement or auxiliary call, no installation change.
+ */
+export declare class ThreadUnsettledError extends Error {
+    readonly threadId: string;
+    constructor(threadId: string, reason: string);
+}
+/**
+ * A thread whose surface refused a replacement row, one written past `replaceSurface`: a bug or a
+ * hand-edited store. Its history can be read, and forked before that row, but nothing executes on
+ * it: not a run, not a compaction, not the close of an interrupted turn. What only records, a
+ * configuration change or a prompt rebuild, is not execution and is not refused.
+ */
+export declare class CorruptHistoryError extends Error {
+    readonly threadId: string;
+    readonly row: RowRef;
+    readonly reason: string;
+    constructor(threadId: string, 
+    /** The first refused row; it may belong to the lineage a fork inherited. */
+    row: RowRef, reason: string);
+}
+/**
+ * An auxiliary call the engine refused to send, because of how it was asked for: a prefix that does
+ * not end on a row of the current surface or that separates a tool call from its result, no
+ * instructions, or no route. Nothing was recorded or sent; it is the caller's error, never the
+ * model's.
+ */
+export declare class AuxiliaryRefusedError extends Error {
+    constructor(message: string);
+}

package/dist/loop/hooks.d.ts

@@ -0,0 +1,274 @@
+import type { AgentDefinition } from './agent.js';
+import type { ExtensionRecord, JournalEvent, JournalEventInput, QueuedInput, Seq, StepContribution, StepContributionInput, TurnRejection } from '../records/journal.js';
+import type { ModelCallClient } from '../llm/failure.js';
+import type { JsonObject, ParsedToolCall, ResponseFinish, ThinkingEffort } from '../llm/primitives.js';
+import type { ModelRequest, RequestPurpose } from '../llm/request.js';
+import type { ModelRoute } from '../llm/provider.js';
+import type { StreamingLLMResponse } from '../llm/client.js';
+import type { LoopRuntime } from './runtime.js';
+import type { RowRef } from '../state/index.js';
+import type { InvocationContext, Tool, ToolOutcome } from './tool.js';
+/**
+ * Every point at which the loop hands control to a plugin.
+ *
+ * Dispatches are named here so there is one place to read what a plugin can intercept — and the
+ * only place in the loop that reaches for `runtime.ctx`. They are thin on purpose: the cordis event
+ * *is* the seam, and wrapping it in an interface the engine implements would put a third hop between
+ * the loop and the listener without making either easier to read.
+ */
+/** A tool call about to run; `lagent/tool/execute` listeners may wrap, replace or short-circuit it. */
+export interface ToolInvocation {
+    readonly tool: Tool;
+    readonly call: ParsedToolCall;
+    readonly context: InvocationContext;
+    readonly toolName: string;
+    readonly threadId: string;
+}
+/** A tool call, before it is dispatched or held for confirmation. */
+export interface ToolAuthorizationRequest {
+    readonly toolCall: ParsedToolCall;
+    readonly agent: AgentDefinition;
+    readonly threadId: string;
+    /** Runtime provenance is explicit; an absent origin is an ordinary model tool call. */
+    readonly origin?: {
+        readonly owner: string;
+        readonly candidateSeq: Seq;
+        readonly requestSeq: Seq;
+    };
+}
+/** A denial that tells the model why, so it can change course rather than retry the call. */
+export interface ToolDenial {
+    readonly decision: 'deny';
+    readonly reason: string;
+}
+/**
+ * One policy's say on a call. `deny` refuses it, `confirm` requires confirmation before it runs,
+ * and `approve` satisfies such a requirement — a policy vouching for the call, as the user would.
+ * A {@link ToolDenial} refuses it with a reason. No answer has no opinion.
+ */
+export type ToolPolicyDecision = 'deny' | 'confirm' | 'approve' | ToolDenial;
+/**
+ * What authorization concluded: the reasons every denying policy gave, and who satisfied a
+ * confirmation requirement when one was met.
+ */
+export type ToolAuthorization = {
+    decision: 'deny';
+    confirmedBy: null;
+    reasons: string[];
+} | {
+    decision: 'confirm';
+    confirmedBy: null;
+} | {
+    decision: 'allow';
+    confirmedBy: 'policy' | 'user' | null;
+};
+/**
+ * Every policy contributes, and the outcome is independent of registration order: denial wins over
+ * everything; a confirmation requirement holds the call unless the user approved it or a policy
+ * approves it. Approval can therefore satisfy a confirmation, never override a denial.
+ */
+export declare function authorizeToolCall(runtime: LoopRuntime, request: ToolAuthorizationRequest, options: {
+    userApproved: boolean;
+}): Promise<ToolAuthorization>;
+/** A model step about to record its input. `lagent/llm/step` listeners may contribute to it. */
+export interface ModelStep {
+    readonly threadId: string;
+    readonly turn: number;
+    readonly step: number;
+    /** The route the turn recorded on `turn/start`, which every request it sends through lagent uses. */
+    readonly route: ModelRoute;
+    /** The inbox input this step will record after the contributions. */
+    readonly claimed: readonly QueuedInput[];
+    /**
+     * Adds a message ahead of the claimed input. Valid only while the listener runs. Lower `rank`s
+     * are recorded first and equal ones keep listener order; it is any finite number, and omitted it
+     * is 0, so an environment fact needs none and a notice that must sit before or after it says so
+     * (`1`, `-1`, `0.5`). A rank is presentation order only. A contribution identical to one the step
+     * already carries, source and message alike, is recorded once, so a plugin mounted in two layers
+     * that reach one thread tells it once; the same contribution at two different ranks throws.
+     */
+    contribute(message: StepContributionInput, rank?: number): void;
+}
+/**
+ * What plugins add to a model step, validated, by ascending rank and then listener order, each
+ * identical one once.
+ *
+ * Synchronous on purpose: the loop records the result with no await in between, so a contribution
+ * always matches the plugin state it was read from. A throwing listener, or an invalid
+ * contribution, fails the step before any of its input is recorded.
+ */
+export declare function collectStepContributions(runtime: LoopRuntime, step: Omit<ModelStep, 'contribute'>): StepContribution[];
+/**
+ * How one request to prepare the surface settled: the replacement rows it committed, and how it
+ * ended. `completed` when the strategy's plan replaced something, with its reason; `skipped` when
+ * it planned nothing, or no strategy prepares the thread; `failed` when it planned a failure or
+ * threw, the error's text as the reason; `cancelled` when the request's signal aborted.
+ */
+export type SurfacePrepareOutcome = {
+    readonly committed: RowRef[];
+    readonly ended: 'completed' | 'skipped' | 'failed' | 'cancelled';
+    readonly reason?: string;
+};
+/** A provisional answer, awaiting the stop checks' judgement. */
+export interface TurnStop {
+    readonly threadId: string;
+    readonly turn: number;
+    /**
+     * A frozen copy, so a listener cannot alter what it judges. `seq` is its row: the reply's
+     * `assistant/message`, or the concluding `tool/result`. `text` is the reply's text parts, or the
+     * concluding result's output. A reply also says why the model stopped: `length` is a reply cut at
+     * the output cap, which a check may send back to be continued.
+     */
+    readonly answer: {
+        readonly seq: Seq;
+        readonly kind: 'reply';
+        readonly text: string;
+        readonly finish: ResponseFinish;
+    } | {
+        readonly seq: Seq;
+        readonly kind: 'concluded';
+        readonly text: string;
+    };
+    /** Steps this turn may still take; a continuation with none left ends the turn `max-steps`. */
+    readonly stepsLeft: number;
+    /** The turn's signal; a slow check should honour it. */
+    readonly signal: AbortSignal;
+    /**
+     * Declares a fact the check's verdict, an abstention included, rests on. `read` returns a token
+     * for it that differs whenever the fact does: synchronous, read-only and cheap, since core calls
+     * it again inside the write that records the judgment, and an answer whose declared facts read
+     * differently then is not judged, whatever the other checks said: the turn ends interrupted and a
+     * later run judges it again. Call it in the same synchronous step that reads the fact, before the
+     * check awaits anything, and before its promise settles at the latest; a call after the judgment
+     * ended throws. A read that throws counts as a change. Only declared facts are covered: what a
+     * check reads from the filesystem or the network stays its own to judge.
+     */
+    observe(read: () => string): void;
+}
+/** A fact a stop check declared, with the token it read when it declared it. */
+export type StopObservation = {
+    readonly read: () => string;
+    readonly value: string | null;
+};
+/** One check's say on an answer. No answer accepts it. */
+export type StopVerdict = {
+    decision: 'continue';
+    message: StepContributionInput;
+} | {
+    decision: 'reject';
+    reason: string;
+    source: ExtensionRecord;
+} | {
+    decision: 'prepare';
+    request: CompletionRequest;
+};
+/** A pure plan. Core owns its durable dispatch after every stop check permits preparation. */
+export type CompletionRequest = {
+    readonly owner: string;
+    readonly key: string;
+    readonly operation: {
+        readonly name: string;
+        readonly arguments: JsonObject;
+    };
+};
+/** What the checks concluded together. */
+export type StopJudgement = {
+    kind: 'accept';
+} | {
+    kind: 'continue';
+    messages: StepContribution[];
+} | {
+    kind: 'reject';
+    rejections: TurnRejection[];
+} | {
+    kind: 'prepare';
+    requests: CompletionRequest[];
+};
+/**
+ * Asks every stop check about an answer. The outcome is independent of registration order: any
+ * rejection ends the turn, otherwise any continuation sends the model back, otherwise a preparation
+ * plan runs before rejudgment, otherwise the answer is accepted. A throwing check, or an invalid
+ * verdict, fails the check without deciding anything.
+ * The facts the checks declare they observed collect in `observations`, which the caller validates
+ * when it records the outcome.
+ */
+export declare function judgeAnswer(runtime: LoopRuntime, stop: Omit<TurnStop, 'observe'>, observations: StopObservation[]): Promise<StopJudgement>;
+/**
+ * Runs `use` with the confinement operation of one tool execution, opened for it and ended when it
+ * settles, whatever it did: the file access its tool was given dies with the call, and what it still
+ * had open is closed.
+ */
+export declare function withOperation<T>(runtime: LoopRuntime, threadId: string, signal: AbortSignal, use: (operation: InvocationContext['operation']) => Promise<T>): Promise<T>;
+/** Runs middleware and binds its final result to the dispatched call, for every execution path. */
+export declare const executeTool: (runtime: LoopRuntime, invocation: ToolInvocation, run: () => Promise<ToolOutcome>) => Promise<ToolOutcome>;
+/**
+ * A model request as `lagent/llm/request` middleware sees it. The turn's route is fixed, so `model`
+ * and `thinkingEffort` are read-only: assigning or deleting either throws, as it does for the
+ * correlation ids, `purpose` and `signal`. On an auxiliary request
+ * (`purpose: 'auxiliary'`) the caller's `toolChoice` and `maxOutputTokens` are fixed the same way,
+ * which the type cannot say.
+ */
+export type ModelRequestDraft = Omit<ModelRequest, 'model' | 'thinkingEffort'> & {
+    readonly model: string;
+    readonly thinkingEffort?: ThinkingEffort;
+};
+/** Fields of a draft a caller may fix beside the route; see {@link modelSend}. */
+export type FixedRequestField = 'toolChoice' | 'maxOutputTokens';
+/** The rows that record a model request before it is sent. */
+type RequestRowType = 'llm/request' | 'auxiliary/request';
+/** What a caller says of its request row: where it was made and why; the terminal adds what was sent, and the tools. */
+type RequestRowFields<K extends RequestRowType> = Omit<JournalEventInput[K], 'llm_call_id' | 'model' | 'message_count'>;
+/** One model call's send, from {@link modelSend}: what the terminal recorded and how far the client got. */
+export interface ModelSend<K extends RequestRowType> {
+    /** Sends `request`, once. The stream is the client's; see {@link modelSend}. */
+    call(request: ModelRequest): Promise<StreamingLLMResponse>;
+    /** The request row the terminal recorded; none while it has not, or when middleware answered without calling `next()`. */
+    readonly row: JournalEvent<K> | undefined;
+    /** The attempts the client made, kept before its call is awaited so a refusal or cancellation still has them; 0 until one starts. */
+    readonly attempts: number;
+}
+/**
+ * The fields every model request of a thread's agent carries the same way, a step's and an
+ * auxiliary call's alike: the route's model and effort, the tools the agent is granted now, the
+ * thread's recorded prompt, and the correlation. A caller adds what differs: its `messages`, its
+ * `toolChoice`, an output cap.
+ */
+export declare function baseRequest(runtime: LoopRuntime, call: {
+    readonly threadId: string;
+    readonly agentName: string;
+    readonly route: ModelRoute;
+    readonly signal: AbortSignal;
+    readonly llmCallId: string;
+    readonly purpose: RequestPurpose;
+}): Omit<ModelRequest, 'messages' | 'toolChoice' | 'maxOutputTokens'>;
+/**
+ * The send of one model request, which a step's call and an auxiliary call share; they differ in the
+ * row they record (`type`, with the `fields` they say of it) and in how they read the stream.
+ *
+ * Middleware gets a draft of its own whose fields it may replace, never the data in them, and never
+ * the route: the model and effort the step was told are the ones sent, and never what the caller
+ * fixed beside it. The builder's data is frozen where it is made (surface messages, registry specs,
+ * prompt rows, auxiliary instructions); the fields the builder made for this call are frozen here, so
+ * the draft shares all of it without a copy. The terminal takes the {@link snapshot} that the journal
+ * recorder, the observers and the provider all receive.
+ *
+ * The terminal records the request row, with a `thread/tools` row before it when the tools differ
+ * from the thread's latest, shows it to `lagent/llm/sent` listeners and starts the call,
+ * and it checks for cancellation twice: before it records anything, so a cancel during middleware
+ * leaves no row, and after the row is recorded and observed, so a cancel there leaves the row and
+ * sends nothing.
+ */
+export declare function modelSend<K extends RequestRowType>(runtime: LoopRuntime, client: ModelCallClient, type: K, fields: RequestRowFields<K>, fixed?: readonly FixedRequestField[]): ModelSend<K>;
+/** A model request as it was sent: the prepared request, with no signal. */
+export type SentModelRequest = Omit<ModelRequest, 'signal'>;
+/** What `lagent/llm/sent` listeners see: the request as sent, and the row that recorded it. */
+export interface SentRequest {
+    readonly request: SentModelRequest;
+    readonly row: JournalEvent<'llm/request'> | JournalEvent<'auxiliary/request'>;
+}
+/**
+ * Hands a problem that does not fail the turn to `internal/error` listeners, or the console. Kept
+ * here rather than inlined so `hooks.ts` stays the loop's only use of cordis (architecture test).
+ */
+export declare function reportError(runtime: LoopRuntime, error: unknown): void;
+export {};

package/dist/loop/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What the rest of the package may use from the loop: live execution against an activation. A live
+ * thread activation drives execution through TurnRunner; plugins extend it through tools and hooks.
+ * What the journal records, without a runtime, is `state/`.
+ */
+export * from './chunks.js';
+export * from './errors.js';
+export * from './runtime.js';
+export * from './hooks.js';
+export type { AuxiliaryCall, AuxiliaryReply } from './auxiliary.js';
+export * from './agent.js';
+export * from './strategy.js';
+export * from './tool.js';
+export { declarePolicyState } from './authorization.js';
+export { TurnRunner } from './runner.js';
+export type { CompactOptions, ServedRun } from './runner.js';

package/dist/loop/runner.d.ts

@@ -0,0 +1,134 @@
+import type { Seq, TurnEndReason } from '../records/journal.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 TurnRunner {
+    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/runtime.d.ts

@@ -0,0 +1,76 @@
+import type { Context, Scoped } from '@leuduan/cordis';
+import type { ModelCallClient } from '../llm/failure.js';
+import type { ModelRoute, ModelSelection } from '../llm/provider.js';
+import type { ToolSpec } from '../llm/primitives.js';
+import type { DeepReadonly } from '../util/json.js';
+import type { Journal } from '../journal/index.js';
+import type { AgentDefinition } from './agent.js';
+import type { ChunkChannel } from './chunks.js';
+import type { TurnLimits } from '../state/index.js';
+import type { SurfaceStrategy } from './strategy.js';
+import type { Tool } from './tool.js';
+/** Anything advertised to the model — a registered tool or a sub-agent. */
+export type ToolEntry = {
+    readonly name: string;
+    readonly tool: Tool;
+    /**
+     * `tool.buildSpec()` with `name` forced to the registered name: the registry's own deep copy,
+     * frozen, shared by every request that advertises the tool.
+     */
+    readonly spec: DeepReadonly<ToolSpec>;
+};
+/**
+ * What the loop runs against.
+ *
+ * The journal says what happened; the registries say what a thread can do right now. Every lookup
+ * here is live — resolved when the loop asks, never captured at start — which is the whole of how a
+ * registry change reaches a running conversation. There is no turn signal: it is carried by
+ * value on each turn, so two concurrent turns cannot see each other's.
+ */
+export interface LoopServices {
+    readonly journal: Journal;
+    /** The model's output as it streams. Ephemeral — see {@link ChunkChannel}. */
+    readonly chunks: ChunkChannel;
+    readonly limits: TurnLimits;
+    /** The registered definition, or a thrown `UnknownAgentError`. */
+    agent(name: string): AgentDefinition;
+    /** What `agentName` may call, in grant order, as the registries stand right now. */
+    toolsFor(agentName: string): ToolEntry[];
+    /** One tool `agentName` may call, or `undefined` when it is unknown or not granted. */
+    tool(agentName: string, toolName: string): ToolEntry | undefined;
+    /** Why `route` cannot run now, its provider not registered, or `null`. Registry lookup only. */
+    unavailable(route: ModelRoute): string | null;
+    /** `selection` folded over `base`; throws `RouteUnavailableError` when its provider is not registered. */
+    resolveRoute(selection: ModelSelection, base: ModelRoute): ModelRoute;
+    /** A client for a resolved route; throws when its provider is gone or the client cannot be built. */
+    client(route: ModelRoute): ModelCallClient;
+    /** Whether a constraint registration under `owner` is live now: what a call's wait may name. */
+    waitOwner(owner: string): boolean;
+    /**
+     * The constraint registrations `threadId`'s run needs, its own `requires` and every thread's above
+     * it by origin, as a token equal only for the same registrations, all ready; `null` while one is
+     * missing. A judgment is fenced on it: a required owner may be a checker of the answer.
+     */
+    requiredRegistrations(threadId: string): string | null;
+}
+/** Only a live activation can supply an execution runtime. There is no passive/no-op runtime. */
+export interface LoopRuntime extends LoopServices {
+    readonly ctx: Context;
+    readonly target: Scoped;
+    readonly signal: AbortSignal;
+    /**
+     * Whether the activation's plugins have changed since it was ready: the loop dispatches nothing
+     * new once they have, and ends the turn as `interrupted` at its next boundary.
+     */
+    stale(): boolean;
+    /** The strategy that prepares the thread's surface, if one is provided (`registerSurfaceStrategy`). */
+    strategy(): SurfaceStrategy | undefined;
+}
+/**
+ * A thread's exclusive execution lease, as one holder holds it: a run, or a request to prepare the
+ * surface. `held` is read on every use of something the holder handed out, so a callback that
+ * escapes its holder does nothing under a later one's lease.
+ */
+export interface Lease {
+    readonly held: boolean;
+}