@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/loop/projections.d.ts

@@ -0,0 +1,307 @@
+import type { InboxTarget, InstallationLifetime, InterruptionPolicy, JournalEvent, QueuedInput, Seq, ThreadEnvironment, ThreadFork, ThreadOrigin, TurnEndReason } from '../models/index.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import type { DeepReadonly, JsonValue, ReadonlyJsonValue } from '../util/json.js';
+import type { ConversationMessage, ModelRoute, ParsedToolCall, PromptBlock, ResponseFinish, ToolCall, ToolSpec } from '../llm/index.js';
+import type { Journal } from '../journal/index.js';
+import type { Reducer } from './threadState.js';
+/**
+ * Where a thread is in its turns: the highest one opened, how many steps it has taken, how it ended,
+ * and whether a tool asked it to stop.
+ *
+ * `step` counts `step/start` since the last `turn/start`, so it is only meaningful while that turn
+ * is in flight — a finished turn's count says nothing about the next one. It is folded rather than
+ * counted in memory so the loop's decision stays a function of the journal across a restart.
+ * `turnOpen` holds while a turn is in flight — including one whose process died, which the thread
+ * closes as `interrupted` before it opens another.
+ *
+ * A fork continues the turn numbering and inherits `concludedTurn`, so a fork taken after a
+ * concluding result is not owed a reply either. Everything else here describes the source's
+ * execution and resets: a fork has no turn in flight and no outcome of its own, even when it was cut
+ * inside one of its source's turns.
+ */
+export declare const turnBoundary: Reducer<{
+    lastTurn: number;
+    step: number;
+    /** How this thread's own last turn ended; `null` before its first ends, or while one is open. */
+    lastReason: TurnEndReason | null;
+    turnOpen: boolean;
+    /**
+     * The turn in which a tool result asked for the turn to end, until input arrives. Holds across
+     * the turn boundary: the concluding result is not a reply the model owes, so nothing happens until
+     * someone sends something new — but only the turn it landed in is cut short by it.
+     */
+    concludedTurn: number | null;
+}>;
+/** Whether a thread's latest answer has been judged by its stop checks. */
+export type AnswerCheck = {
+    status: 'none';
+} | ({
+    status: 'pending' | 'accepted' | 'rejected';
+    seq: Seq;
+    text: string;
+} & ({
+    kind: 'reply';
+    finish: ResponseFinish;
+} | {
+    kind: 'concluded';
+}));
+/**
+ * The conversation's latest answer — a reply with no tool calls, or a result that concluded the
+ * turn — and whether a stop check has judged it.
+ *
+ * An answer is `pending` from the moment it is recorded until its turn ends `completed` (accepted)
+ * or `rejected`. Every other ending leaves it pending, so a check a crash, an abort or a failing
+ * listener cut short is still owed; new input supersedes the answer altogether. Folded from rows
+ * the loop writes anyway, so there is no marker for a crash to fall in front of.
+ *
+ * A fork resets it (see `threadState`'s fork table); a fork is never cut where a check is still owed,
+ * so nothing is lost.
+ */
+export declare const answerCheck: Reducer<AnswerCheck>;
+/**
+ * Calls dispatched and not yet answered, and the row that recorded the dispatch.
+ *
+ * Bookkeeping, not truth: what a turn still owes answers for is {@link unansweredToolCalls}, read
+ * off the conversation. This exists so a re-dispatched call can cite its original `tool/call` rather
+ * than recording a second one.
+ */
+export declare const dispatchedCalls: Reducer<Map<string, Seq>>;
+/** One dispatch attempt of a call: its `tool/authorization` row, and what became of it. */
+export type DispatchAttempt = {
+    /** The `tool/authorization` row: the attempt itself. */
+    seq: Seq;
+    /** The `tool/call` row the attempt dispatched. */
+    call_seq: Seq;
+    turn: number;
+    decision: JournalEvent<'tool/authorization'>['data']['decision'];
+    /** What the tool declared, at this attempt, a re-dispatch may do if the attempt is interrupted. */
+    policy: InterruptionPolicy;
+};
+/**
+ * The latest dispatch attempt of every call that has no result yet, by call id.
+ *
+ * An attempt is written immediately before the tool is invoked, so an allowed attempt with no
+ * result, from a turn that has since closed, of a call that did not suspend, is a call the process
+ * was cut off in: the tool may have begun. {@link abandonedAttempt} reads that; the policy recorded with the attempt
+ * decides what a re-dispatch may do. A new `tool/call` under a reused provider id starts a new call
+ * with no attempt; a result clears the call's attempt.
+ */
+export declare const dispatchAttempts: Reducer<Map<string, DispatchAttempt>>;
+/**
+ * The attempt of `callId` that was abandoned, if any: allowed, so the tool may have begun;
+ * unanswered; of the `tool/call` row being dispatched now, not of an earlier call that reused the
+ * provider's id; of a call that is not suspended (`waits`), since a waiting call returned on purpose
+ * and one whose wait resolved is dispatched again from its recorded value, however often a crash
+ * cuts that dispatch off; and from a turn before `currentTurn`, so the process that made it is gone —
+ * every earlier turn is closed before a new one opens. Read before a new attempt is recorded, so the
+ * judgment is about the attempt that was cut off.
+ */
+export declare function abandonedAttempt(state: ReadonlyMap<string, DispatchAttempt>, waits: ReadonlyMap<Seq, WaitEntry>, callId: string, callSeq: Seq, currentTurn: number): DispatchAttempt | undefined;
+/** A call's `wait/declared` row, as the waits fold keeps it. */
+export type WaitDeclaration = {
+    /** The `wait/declared` row. */
+    readonly seq: Seq;
+    readonly turn: number;
+    readonly step: number;
+    readonly call_id: string;
+    readonly call_seq: Seq;
+    readonly owner: string;
+    readonly dependency: {
+        readonly [key: string]: ReadonlyJsonValue;
+    };
+    readonly deadline_at: number | null;
+    readonly reason: string;
+};
+/** One declared wait: its declaration, the value it resolved with, and whether its call was answered. */
+export type WaitEntry = {
+    readonly declaration: WaitDeclaration;
+    value: {
+        readonly [key: string]: ReadonlyJsonValue;
+    } | null;
+    /** The call's `tool/result` landed: by its dispatch from the value, or by a cancel. */
+    answered: boolean;
+};
+/**
+ * Every wait the thread declared, by `call_seq`, kept after its call is answered, so answer-once can
+ * report a value recorded before. A fork starts with none: it is never cut with a call unanswered.
+ */
+export declare const waits: Reducer<Map<Seq, WaitEntry>>;
+/** Declared, with no value and no answer: what holds the thread, and what its owner still resolves. */
+export declare const isUnresolved: (entry: WaitEntry | undefined) => boolean;
+/** Declared and unanswered, resolved or not: the waiting call's authority, which a cancel answers. */
+export declare const isSuspended: (entry: WaitEntry | undefined) => boolean;
+/** The thread's suspended waits, in declaration order. */
+export declare const suspendedWaits: (state: ReadonlyMap<Seq, WaitEntry>) => WaitEntry[];
+/**
+ * Tool calls on the last assistant message that have no result yet.
+ *
+ * Derived from the conversation, not from `tool/call` rows, because the conversation is what a
+ * provider validates: a message holding calls must be followed by a result for each one. Calls are
+ * recorded one row at a time, so a hard kill part-way through that burst leaves a thread with fewer
+ * `tool/call` rows than the model asked for — nothing "pending", and a conversation nothing could
+ * answer. Reading the assistant message instead makes the two agree by construction.
+ */
+export declare function unansweredToolCalls(messages: readonly DeepReadonly<ConversationMessage>[]): DeepReadonly<ToolCall>[];
+export type ConfirmationState = {
+    request_id: string;
+    thread_id: string;
+    /** The `tool/call` row this request was raised for — the dispatch it belongs to. */
+    call_seq: Seq | null;
+    tool_call: ParsedToolCall;
+    reason: string;
+    resolution: {
+        approved: boolean;
+        rejection_message: string | null;
+    } | null;
+};
+/**
+ * A thread's confirmation requests and their answers, keyed by request id. Thread-scoped: an answer
+ * is written on the thread that asked, so a thread's confirmations are a function of its own rows.
+ * A fork starts with none: a fork is never cut with a request still open, and an inherited answer
+ * belongs to a call the source already finished.
+ */
+export declare const confirmations: Reducer<Map<string, ConfirmationState>>;
+/** Requests still waiting on the user on one thread. */
+export declare const outstandingConfirmations: (state: ReadonlyMap<string, ReadonlyState<ConfirmationState>>, threadId: string) => ReadonlyState<ConfirmationState>[];
+/**
+ * Calls one thread must not dispatch now, by call id: those waiting on a user's answer, and those
+ * whose wait has not resolved. Neither is turn-bound: dispatching again before the answer or the
+ * value would only raise a second request, or declare the wait twice.
+ */
+export declare const parkedCallIds: (confirmationState: ReadonlyMap<string, ReadonlyState<ConfirmationState>>, waitState: ReadonlyMap<Seq, WaitEntry>, threadId: string) => Set<string>;
+/**
+ * How a dispatch was answered, if it was ever asked about. `undefined` means nobody has been asked —
+ * which is what tells a re-dispatched call to go through authorization again rather than assume.
+ *
+ * Matched on the `tool/call` row rather than the provider's call id: two threads, or two turns of
+ * one thread, may legitimately see the same id, and an approval must not carry across.
+ */
+export declare const approvalFor: (state: Map<string, ConfirmationState>, dispatch: {
+    threadId: string;
+    callId: string;
+    callSeq: Seq | null;
+}) => {
+    approved: boolean;
+    rejection_message: string | null;
+} | undefined;
+export type ThreadRecord = {
+    thread_id: string;
+    agent_name: string;
+    metadata: JournalEvent<'thread/spawned'>['data']['metadata'];
+    /** The source thread and row this thread was forked at; `null` unless it is a fork. */
+    fork: ThreadFork | null;
+    origin: ThreadOrigin | null;
+    environment: ThreadEnvironment;
+    /** The constraint owners the thread's runs are under. */
+    requires: readonly string[];
+    /** The `thread/spawned` row. */
+    seq: Seq;
+};
+/**
+ * A thread's identity, lineage and environment, from its spawn row. A fork's lineage replays its
+ * source's spawn row first and its own after it, so the fork's record is its own. The set of all
+ * threads is the journal's catalog, not a fold.
+ */
+export declare const threadRecord: Reducer<ThreadRecord | null>;
+/** The thread's latest `confirm/resolved` row, or `null`: what tells a parked caller an answer landed under it. */
+export declare const lastAnswer: Reducer<Seq | null>;
+/**
+ * The thread's route: the one its spawn row was born with, replaced by each cause that changed it.
+ * A lineage fold: a fork, born with none of its own, goes on with the route its inherited rows fold
+ * to at the cut, which keeps it on the model whose cache holds its history. Nothing else changes it:
+ * not turns, settlements, cancels or compaction. `null` only before a spawn row, which no thread lacks.
+ */
+export declare const threadRoute: Reducer<ModelRoute | null>;
+/**
+ * The system prompt a thread sends: the latest `thread/prompt` row, or none yet. A fork inherits
+ * it and never renders its own, so it sends its source's exact prompt.
+ */
+export declare const threadPrompt: Reducer<PromptBlock[] | null>;
+/**
+ * The tool specifications a thread's requests send: the latest `thread/tools` row, or none before
+ * its first request. Read at a request's seq, what that request sent. A fork inherits it.
+ */
+export declare const threadTools: Reducer<readonly ToolSpec[] | null>;
+/**
+ * Whether a fork has yet to claim the task it was created with. A fork cut at a request inherits a
+ * conversation that ends on input its source is answering. Created to regenerate that answer, the
+ * fork owes it; created with a task, it owes only the task. So a task discarded before it was
+ * claimed — by `cancel()` — leaves the fork with nothing to do, rather than answering its source's
+ * request. Any input the fork records settles it.
+ */
+export declare const forkTask: Reducer<{
+    spawnSeq: Seq | null;
+    unclaimed: boolean;
+}>;
+export type InboxState = Record<InboxTarget, QueuedInput[]>;
+/**
+ * Input waiting for a turn or a step boundary. Durable, so a crash does not lose a queued message.
+ * A fork starts with nothing queued: its source's queued input is not the fork's.
+ */
+export declare const inbox: Reducer<InboxState>;
+/** Where one input id's life is recorded: the row that queued it, and the step's row that claimed it. */
+export type InputRows = {
+    readonly queuedAt: Seq;
+    readonly claimedAt: Seq | null;
+};
+/**
+ * Every input id this thread was ever handed: the row that queued it and, once a step took it, the
+ * `input/message` that claimed it. Never forgets: this is what makes `send` with an explicit id
+ * idempotent across a re-dispatch or a restart, and why a withdrawn or cancelled id stays
+ * spent. A fork starts over: the ids its source was handed are the source's.
+ */
+export declare const inputs: Reducer<Map<string, InputRows>>;
+/**
+ * How the run that began after a row ended, and what it answered, read from the thread's events
+ * after that row. A run's outcome, not a delegation task's: an `aborted` turn ends a run, while a
+ * task stays open across it (the delegations plugin's own fold).
+ */
+export type RunOutcome = {
+    /** The last turn ending seen for this run, if any. */
+    reason: TurnEndReason | null;
+    /**
+     * The accepted answer: the reply, or the output of the tool result that concluded the turn. Empty
+     * until the run has answered — a provisional or rejected answer is not one.
+     */
+    output: string;
+    /** Whether the conversation has reached an answer: a complete reply, or a result that concluded the turn. */
+    answered: boolean;
+};
+/**
+ * How the run that began after `fromSeq` ended, and what it answered.
+ *
+ * The `answerCheck` reducer folded over the rows after `fromSeq`: the same rule the loop and its stop
+ * checks read, so an answer is a complete reply with nothing left to call, or a tool result that
+ * concluded the turn, and it becomes the run's answer only at the `turn/end(completed)` that
+ * accepted it. A process that died before that ending leaves it unaccepted, and the scan goes on to
+ * the turn that checks it. Scanning stops at the first turn ending that settles the run, answered or
+ * failed outright, so a later turn of the same thread is never mistaken for this run's.
+ */
+export declare function outcomeSince(journal: Journal, threadId: string, fromSeq: Seq): RunOutcome;
+/** A turn ending after which the run will not produce an answer without new input. */
+export declare const isRunFailure: (reason: TurnEndReason | null) => boolean;
+/** One installation a thread holds, as its folds read it. */
+export type InstallationRecord = {
+    readonly installationId: string;
+    readonly presetId: string;
+    /** The validated configuration, defaults included: exactly what `setup` receives. */
+    readonly config: JsonValue;
+    /**
+     * `defining` for one recorded as such in its thread's spawn row, on this thread or on the one a
+     * fork inherited it from, which cannot be removed; `configurable` for any other, one applied
+     * later included.
+     */
+    readonly lifetime: InstallationLifetime;
+};
+/** A thread's installations: the current ones in application order, and every id it ever used. */
+export type InstallationsState = {
+    readonly current: Map<string, InstallationRecord>;
+    readonly used: Set<string>;
+};
+/**
+ * The preset installations that define a thread's plugins. A fork inherits its source's
+ * installations and reserved ids at the cut: its own spawn row carries none, and the source's spawn
+ * row, which it folds through lineage, keeps a defining installation defining on every fork.
+ * Installations never move, so application order is also the order they are restored in.
+ */
+export declare const installations: Reducer<InstallationsState>;

package/dist/loop/replace.d.ts

@@ -0,0 +1,33 @@
+import type { Journal } from '../journal/index.js';
+import type { JournalEventInput, ReplacementTrigger, Seq } from '../models/index.js';
+import type { RowRef } from './surface.js';
+type ReplacedData = JournalEventInput['surface/replaced'];
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+/**
+ * One replacement as a strategy offers it: what a `surface/replaced` row records that the strategy
+ * decides — its kind, stand-in and `source` — and the rows it replaces, in surface order. The
+ * engine fills in the rest.
+ */
+export type ReplacementInput = DistributiveOmit<ReplacedData, 'trigger' | 'turn' | 'step' | 'auxiliary_request_seq'> & {
+    /** The rows replaced: a contiguous run of the current surface for a `span`, one row for a `rewrite`. */
+    readonly source_seqs: readonly Seq[];
+    /** The `auxiliary/request` row the stand-in was made from, when a model call made it. */
+    readonly auxiliary_request_seq?: Seq | null;
+};
+/** Where a replacement is recorded: what caused it, and the turn and step, both `null` between turns. */
+export type ReplacementContext = {
+    readonly trigger: ReplacementTrigger;
+    readonly turn: number | null;
+    readonly step: number | null;
+};
+/**
+ * The one way a replacement reaches the journal: appends `replacements` as one atomic group on
+ * `threadId`, each with the context filled in. The group is judged inside the write, against the
+ * durable surface, each row against the surface the previous one left, and refused whole with a
+ * {@link ReplacementRefusedError} when one breaks a rule; nothing of it is written then. Counts
+ * nothing and judges nothing of its own: the rules are the surface's (`judgeGroup`).
+ *
+ * The caller holds the thread's lease; `runSurfacePrepare` checks it before recording.
+ */
+export declare function replaceSurface(journal: Journal, threadId: string, context: ReplacementContext, replacements: readonly ReplacementInput[]): Promise<RowRef[]>;
+export {};

package/dist/loop/requests.d.ts

@@ -0,0 +1,129 @@
+import type { CancelIntent, RunChain, RunOutcomeKind, RunSettledReason, Seq } from '../models/index.js';
+import type { InputFate } from './state.js';
+import type { Reducer } from './threadState.js';
+/** One `run/cause` row as the request fold keeps it. */
+export type RunCause = {
+    readonly seq: Seq;
+    /** The row's timestamp: how old the cause is, which the startup policy judges. */
+    readonly at: string;
+    readonly inputId: string | null;
+    readonly releases: boolean;
+    readonly chain: RunChain;
+};
+/** The request a thread is authorized to run, with every cause it holds, residual ones first. */
+export type PendingRun = {
+    readonly runId: string;
+    /** The `run/requested` row. */
+    readonly requestedAt: Seq;
+    readonly causes: readonly RunCause[];
+};
+/** One `run/settled` row as the request fold keeps it. */
+export type RunSettlement = {
+    readonly runId: string;
+    readonly seq: Seq;
+    readonly outcome: RunOutcomeKind;
+    readonly reason: RunSettledReason;
+    readonly errorText: string | null;
+    readonly through: Seq;
+    readonly residual: readonly Seq[];
+};
+/** One `thread/cancel` row as the request fold keeps it. */
+export type CancelRecord = {
+    readonly seq: Seq;
+    readonly cancelId: string;
+    readonly intent: CancelIntent;
+    readonly runId: string | null;
+    readonly reason: string;
+};
+/**
+ * A thread's run requests, folded from its `run/*` and `thread/cancel` rows: the pending request,
+ * the first cancel that captured it, the latest settlement and user cancel, the latest releasing
+ * cause, and every request it ever
+ * opened with its settlement, so a waiter can read any run by id. A row that breaks the request
+ * rules (a cause or settlement for a run that is not pending, a request opened over a pending one)
+ * is kept in `inconsistencies` rather than thrown: core's fold is fatal, and a bad row must not
+ * stop the thread from being read.
+ */
+export type RequestsState = {
+    pending: PendingRun | null;
+    /**
+     * The first cancel row naming the pending request's execution, whichever its intent: what a
+     * recovery settles that request by when the process died before its execution's finalization did.
+     * The first capture fixes the intent; a later cancel joining it changes nothing here.
+     */
+    pendingCancel: CancelRecord | null;
+    latestSettlement: RunSettlement | null;
+    latestUserCancel: CancelRecord | null;
+    /** The seq of the latest cause that releases holds, on any request. */
+    latestReleasing: Seq | null;
+    /** Every request by id: its `run/requested` row, and its settlement once it has one. */
+    readonly runs: Map<string, {
+        readonly requestedAt: Seq;
+        settlement: RunSettlement | null;
+    }>;
+    /**
+     * The latest `turn/start`: the run it served and the attempt cutoff of the execution that opened
+     * it, which a recovery settles a failure recorded before a crash with.
+     */
+    latestTurn: {
+        readonly seq: Seq;
+        readonly runId: string;
+        readonly attemptCutoff: Seq;
+    } | null;
+    /**
+     * The turns of the pending request in a row, since its latest releasing cause, that ended
+     * `interrupted` with the activation or the judgment as the cause; an abandonment by recovery leaves
+     * the count as it was. What an
+     * entry decision spends its repairs against: a request held on an interrupted turn that was
+     * already repaired is not repaired again until a releasing cause releases it.
+     */
+    interruptions: number;
+    /** The causes a settlement carried over, until the successor request it opened takes them. */
+    carried: readonly RunCause[];
+    readonly inconsistencies: string[];
+};
+/**
+ * The request fold: core's {@link RequestsState} concern of `threadState`. A fork starts with none
+ * of its source's requests.
+ */
+export declare const requests: Reducer<RequestsState>;
+/** Where a run stands from its rows alone: pending, settled with its settlement, or unknown on this thread. */
+export type DurableRunState = {
+    readonly state: 'pending';
+} | {
+    readonly state: 'settled';
+    readonly settlement: RunSettlement;
+} | {
+    readonly state: 'unknown';
+};
+export declare function durableRunState(state: RequestsState, runId: string): DurableRunState;
+/**
+ * What a settlement decided, and where its execution's cutoffs fall, for {@link residualOf}: the
+ * attempt cutoff, the position the execution was admitted at, and the cancel's write, when a cancel
+ * settled the request and its write landed.
+ */
+export type ResidualRule = {
+    readonly outcome: RunOutcomeKind;
+    readonly reason: RunSettledReason;
+    readonly attemptCutoff: Seq;
+    readonly cancelSeq: Seq | null;
+};
+/**
+ * The causes of `pending` a settlement carries over to a successor request, by seq. A cause whose
+ * input a step claimed, or that left the queue unclaimed, carries nothing whatever its position;
+ * of the rest:
+ *
+ * - `completed` carries the causes recorded after the attempt cutoff: a wake that landed while the
+ *   execution was finishing runs once more;
+ * - `failed` carries only the releasing ones recorded after the cutoff: a person's message that
+ *   arrived during the attempt runs, while the cause that started it, and a notice or a fire, does
+ *   not retry a failure;
+ * - a cancel's carries those recorded after its write, which it did not clear, or, when that write
+ *   failed and cleared nothing, those after the attempt cutoff;
+ * - an `obsolete` request carries nothing: its authority is gone, and a successor comes with causes
+ *   of its own.
+ *
+ * `fate` reads an input's fate on the thread (`inputFate`). Input left queued with no cause runs
+ * again only when a new cause arrives.
+ */
+export declare function residualOf(pending: PendingRun, rule: ResidualRule, fate: (inputId: string) => InputFate['state']): Seq[];

package/dist/loop/route.d.ts

@@ -0,0 +1,53 @@
+import type { ModelRoute } from '../llm/index.js';
+import type { ModelSelection } from './runtime.js';
+/**
+ * What a wake says about the route it runs on, checked by core inside the write that records it:
+ * `expect`, the route the caller was shown and did not change; `select`, the route to run on,
+ * folded over the thread's route as a creation's fields are, so a complete one is itself. A wake
+ * that states none runs on the thread's route as it is, unchecked.
+ */
+export type RouteStatement = {
+    readonly expect: ModelRoute;
+} | {
+    readonly select: ModelSelection;
+};
+/**
+ * The thread's route as a statement is checked against: the route, why it cannot run here
+ * (its provider is not registered), and whether a route change is accepted now — no run serving the
+ * pending request holds the thread, and no request is pending, the route cannot run, or the
+ * request is held by a failure or a cancellation.
+ */
+export type Target = {
+    readonly route: ModelRoute;
+    readonly blocked: string | null;
+    readonly selectable: boolean;
+};
+/** What checks a route statement inside its write: the thread owner, which knows admission and the registry. */
+export interface RouteAuthority {
+    /** The thread's target as its rows and the process stand now. */
+    target(threadId: string): Target;
+    /** `selection` folded over `base`; throws `RouteUnavailableError` when the provider is not registered. */
+    resolve(selection: ModelSelection, base: ModelRoute): ModelRoute;
+}
+/** A route statement does not match the thread's route as it stands, or would change it when it may not. */
+export declare class RouteConflictError extends Error {
+    readonly threadId: string;
+    readonly route: ModelRoute;
+    constructor(threadId: string, 
+    /** The thread's route when the statement was refused. */
+    route: ModelRoute, reason: string);
+}
+/** A route cannot run here: its provider is not registered. Nothing was written, or no turn opened. */
+export declare class RouteUnavailableError extends Error {
+    readonly route: Pick<ModelRoute, 'provider'> & Partial<ModelRoute>;
+    constructor(route: Pick<ModelRoute, 'provider'> & Partial<ModelRoute>);
+}
+/** Whether two routes are the same tuple; a `null` effort (the provider's own default) is a value like any other. */
+export declare const sameRoute: (a: ModelRoute, b: ModelRoute) => boolean;
+/**
+ * The route a cause records for `statement`, read inside its write: `null` when the cause leaves
+ * the thread's route as it is. `expect` needs the route runnable, then matching; `select` resolves
+ * over it, and a different route is written only while the target is selectable. Refusals throw,
+ * which refuses the whole write.
+ */
+export declare function statedRoute(threadId: string, statement: RouteStatement, routes: RouteAuthority): ModelRoute | null;

package/dist/loop/runtime.d.ts

@@ -0,0 +1,85 @@
+import type { Context, Scoped } from '@leuduan/cordis';
+import type { ModelCallClient, ModelRoute, ThinkingEffort, ToolSpec } from '../llm/index.js';
+import type { DeepReadonly } from '../util/json.js';
+import type { Journal } from '../journal/index.js';
+import type { AgentDefinition } from '../models/index.js';
+import type { ChunkChannel } from './chunks.js';
+import type { TurnLimits } from './limits.js';
+import type { SurfaceStrategy } from './strategy.js';
+import type { Tool } from './tool.js';
+/** Anything advertised to the model — a builtin 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>;
+};
+/**
+ * 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;
+};
+/**
+ * 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 (`provideStrategy`). */
+    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;
+}