@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/loop/hooks.d.ts

@@ -0,0 +1,241 @@
+import type { AgentDefinition, ExtensionRecord, JournalEvent, JournalEventInput, QueuedInput, Seq, StepContribution, StepContributionInput, TurnRejection } from '../models/index.js';
+import type { ModelCallClient, ModelRequest, ModelRoute, ParsedToolCall, RequestPurpose, ResponseFinish, StreamingLLMResponse, ThinkingEffort } from '../llm/index.js';
+import type { LoopRuntime } from './runtime.js';
+import type { RowRef } from './surface.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;
+}
+/** 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;
+};
+/** What the checks concluded together. */
+export type StopJudgement = {
+    kind: 'accept';
+} | {
+    kind: 'continue';
+    messages: StepContribution[];
+} | {
+    kind: 'reject';
+    rejections: TurnRejection[];
+};
+/**
+ * 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 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 a tool through its listeners. One that does not call `next()` has answered the call itself. */
+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/inbox.d.ts

@@ -0,0 +1,188 @@
+import type { ExtensionRecord, InboxTarget, QueuedInput, Seq, ThreadInput } from '../models/index.js';
+import type { AppendEntry, Journal } from '../journal/index.js';
+import type { DeepReadonly, ReadonlyJsonValue } from '../util/json.js';
+import type { RouteAuthority } from './route.js';
+import type { FreshOpening, ForkOpening } from './opening.js';
+import { type Wake } from './wake.js';
+/**
+ * Why a write-time callback refused its write, as data a host or plugin can act on without parsing
+ * `message`: the text a person is shown, an optional `code` for the cause when a reader branches on
+ * one, and optional `data` for its facts.
+ */
+export type Refusal = {
+    readonly message: string;
+    readonly code?: string;
+    readonly data?: ReadonlyJsonValue;
+};
+/**
+ * What a write-time callback returns: the plugin rows to add to the write's group, or `{ refuse }`,
+ * its explicit veto, which writes nothing and gives the {@link Refusal} to whoever asked. Anything
+ * the callback throws is a failure, not a veto: it propagates as it was thrown.
+ */
+export type RowsResult = readonly AppendEntry<'ext'>[] | {
+    readonly refuse: Refusal;
+};
+/** Whether a callback vetoed its write. */
+export declare const isVeto: (result: RowsResult) => result is {
+    readonly refuse: Refusal;
+};
+/** What every write that queues input tells its callback: the thread, where the input waits, and the run its cause joins. */
+type WriteBase = {
+    readonly threadId: string;
+    /** Where the input waits, which `send` decides inside the write; a creation always queues for `next-turn`. */
+    readonly target: InboxTarget;
+    /** The run request the write's cause joins or opens; `null` when it brings none. */
+    readonly runId: string | null;
+};
+/**
+ * What a write-time callback is told, by the write it runs in. A creation or a fork carries the
+ * resolved opening it records, a frozen copy, so a callback reads what core records and cannot
+ * change it; `inputId` is the first input's id, `null` when the write queues none. A `send`
+ * carries the id it queues.
+ */
+export type RowsWrite = (WriteBase & {
+    readonly kind: 'create';
+    readonly inputId: string | null;
+    readonly opening: DeepReadonly<FreshOpening>;
+}) | (WriteBase & {
+    readonly kind: 'fork';
+    readonly inputId: string | null;
+    readonly opening: DeepReadonly<ForkOpening>;
+}) | (WriteBase & {
+    readonly kind: 'send';
+    readonly inputId: string;
+});
+/**
+ * A write-time callback on a write that queues input — `create`, `fork` or `send`: run inside the
+ * write's transaction, once the write's own rows are built and before anything is stored, it returns
+ * plugin rows for the same group, or vetoes the write by returning `{ refuse }` (see
+ * {@link RowsResult}). Synchronous, as every `transact` callback is.
+ */
+export type WriteRows = (write: RowsWrite) => RowsResult;
+/**
+ * What `send` returns for input it accepted: the input's id and `queuedAt`, the seq of the row that
+ * queued it. The id is the one the caller passed or the one `send` made.
+ */
+export type InputReceipt = {
+    readonly inputId: string;
+    readonly queuedAt: Seq;
+};
+/**
+ * What a `send` did: queued the input, with the run request its wake joined or opened in the same
+ * write (`runId`, `null` when it had no wake; see `waitForRun`); found its id already known and
+ * wrote nothing, its receipt naming the row that queued it the first time; or wrote nothing because
+ * its `rows` callback vetoed, for `refusal`.
+ */
+export type SendOutcome = ({
+    readonly status: 'queued';
+    readonly runId: string | null;
+} & InputReceipt) | ({
+    readonly status: 'known';
+} & InputReceipt) | {
+    readonly status: 'refused';
+    readonly refusal: Refusal;
+};
+/**
+ * How `send` queues: under `id`, attributed to `source`, with `rows` added to its write, and with
+ * `wake`, a cause in the same write that asks the thread to run (`{}` for a person's). A sourced
+ * input needs its `id`.
+ */
+export type SendOptions = {
+    readonly id?: string;
+    readonly source?: ExtensionRecord;
+    readonly rows?: WriteRows;
+    readonly wake?: Wake;
+    /**
+     * Where the input waits; omitted, admission places it (a running turn's next step, else a turn of
+     * its own). `next-turn` waits for a turn of its own even while a run holds the thread. `next-step`
+     * joins the next model step whichever turn takes it: a running turn's, a resumed turn's once its
+     * parked calls are answered, or a new turn's first step together with what waits for that turn.
+     */
+    readonly target?: InboxTarget;
+};
+/**
+ * A write-time callback on a `withdraw`: run inside its transaction, told whether the input was
+ * still queued and is withdrawn by this write, it returns plugin rows for the same group, written
+ * either way, or vetoes the withdrawal by returning `{ refuse }` (see {@link RowsResult}).
+ */
+export type WithdrawRows = (write: {
+    readonly threadId: string;
+    readonly withdrawn: boolean;
+}) => RowsResult;
+export type WithdrawOptions = {
+    readonly rows?: WithdrawRows;
+};
+/**
+ * What a `withdraw` did: took the input out of the queue (`withdrawn`); found it not queued, being
+ * claimed, discarded or unknown (`not-queued`), writing only what `rows` returned; or wrote nothing
+ * because `rows` vetoed, with its `refusal`.
+ */
+export type WithdrawOutcome = {
+    readonly status: 'withdrawn' | 'not-queued';
+} | {
+    readonly status: 'refused';
+    readonly refusal: Refusal;
+};
+/**
+ * Input waiting for a boundary, held in the journal rather than in memory.
+ *
+ * Every mutation is an `inbox/spliced` event, so a message queued while the agent was busy survives
+ * a crash exactly like the conversation does. `next-turn` is claimed only by a turn's first step,
+ * when that step asks the model: a turn that opens by answering calls an earlier turn left leaves it
+ * for the next turn. `next-step` joins the next model step of whichever turn takes it: the turn in
+ * flight, which is what makes steering possible, a resumed turn once its calls are answered, or the
+ * first step of the next turn.
+ */
+export declare class Inbox {
+    private readonly journal;
+    private readonly threadId;
+    constructor(journal: Journal, threadId: string);
+    private get queues();
+    private get state();
+    get nextTurn(): readonly QueuedInput[];
+    get nextStep(): readonly QueuedInput[];
+    /** The row that queued input `id`, or `undefined` when this thread was never handed that id. */
+    private queuedAt;
+    /** Everything waiting for a step to claim it, in the order it was sent. */
+    get pending(): QueuedInput[];
+    /**
+     * Idempotent durable input. The target is the sender's when it names one; otherwise execution
+     * admission chooses it (`target`), asked inside the write, as is whether the id was queued
+     * before: two sends of one id queue it once, and a known id calls no `rows`. Input attributed to
+     * a plugin (`source`) needs the id the plugin derived, since a redelivery must find it. `routes`
+     * checks a wake's route statement.
+     */
+    send(input: ThreadInput, target: () => InboxTarget, options?: SendOptions, routes?: RouteAuthority): Promise<SendOutcome>;
+    /**
+     * Discards one queued input by id, wherever it waits, deciding inside the write whether it is still
+     * queued; `rows` adds a plugin's rows to the same write either way (see {@link WithdrawRows}).
+     */
+    withdraw(id: string, options?: WithdrawOptions): Promise<WithdrawOutcome>;
+    /**
+     * The rows that discard everything pending, `next-step` first so a drained turn cannot pick it
+     * up: none when nothing waits. Built inside the write that carries them, a cancel's.
+     */
+    clearRows(): AppendEntry<'inbox/spliced'>[];
+    /**
+     * The batch one step will consume: everything queued for the next step, plus, when this boundary
+     * opens a turn, the head of what waits for one: a single unsourced input, or every consecutive
+     * sourced input at the head. The batch is ordered by seq; order holds within a batch, not across
+     * the whole queue, so `next-step` input sent after something still waiting for a turn can enter
+     * before it. A person's message is never skipped to collect plugin input waiting for a turn behind
+     * it, so sourced input left at `next-turn` (notice, notice, person, notice) opens three turns:
+     * `[N, N]`, `[U]`, `[N]`; with the notices at `next-step`, it opens one: `[N, N, U, N]`. With
+     * `sentBack`, a later step takes the next such batch too: a turn that opened by answering calls
+     * claimed nothing that waited for a turn, and once a stop check sent its answer back, what waits
+     * could be what the check holds the answer for.
+     *
+     * Reading only. The input leaves the queue when its `input/message` is appended, so recording it
+     * and claiming it are the same event and a crash between them is not a thing that can happen.
+     */
+    peek(target: InboxTarget, sentBack?: boolean): QueuedInput[];
+    /**
+     * Array-splice semantics, normalized against the inbox as it stands: the row that records it, or
+     * nothing to record. Built inside a write, so the indices are the ones the row lands on.
+     */
+    private spliceEntry;
+}
+export {};

package/dist/loop/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * What the rest of the package may use from the loop.
+ *
+ * Journal operations (projections, inbox, recovery) need no execution runtime. A live thread
+ * activation drives execution through LoopAgent; plugins extend it through tools and hooks.
+ */
+export * from './projections.js';
+export * from './surface.js';
+export * from './threadState.js';
+export * from './chunks.js';
+export * from './errors.js';
+export * from './limits.js';
+export * from './runtime.js';
+export { Inbox } from './inbox.js';
+export { isVeto } from './inbox.js';
+export type { BirthSpec, ForkOpening, FreshOpening } from './opening.js';
+export type { Refusal, RowsResult, RowsWrite, InputReceipt, SendOptions, SendOutcome, WithdrawOptions, WithdrawOutcome, WithdrawRows, WriteRows, } from './inbox.js';
+export { closeInterruptedTurn, hasThreadWork, inputFate, lastAssistantMessage, refusedReplacement, unfinishedConfirmations, } from './state.js';
+export type { InputFate } from './state.js';
+export * from './summary.js';
+export * from './requests.js';
+export { chainStanding } from './chain.js';
+export type { ChainStanding } from './chain.js';
+export * from './wake.js';
+export * from './route.js';
+export * from './holds.js';
+export * from './continuation.js';
+export * from './forks.js';
+export * from './hooks.js';
+export type { AuxiliaryCall, AuxiliaryReply } from './auxiliary.js';
+export { replaceSurface } from './replace.js';
+export type { ReplacementContext, ReplacementInput } from './replace.js';
+export * from './strategy.js';
+export * from './tool.js';
+export { declarePolicyState, errorResult } from './toolCalls.js';
+export { LoopAgent } from './agent.js';
+export type { CompactOptions, ServedRun } from './agent.js';

package/dist/loop/limits.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What bounds a runaway turn. Each is a number the loop can hand back to the model as a tool result
+ * or a turn ending it can react to; together with the depth cap they bound total spend.
+ */
+export type TurnLimits = {
+    /** Positive finite integer: steps in one thread's turn before it stops with `max-steps`. */
+    maxStepsPerTurn: number;
+    /** Non-negative finite integer: nesting below a root. Zero forbids delegation; each hop is one level. */
+    maxThreadDepth: number;
+    /** Positive finite integer: tool calls dispatched at once within one step; the rest wait for a slot. */
+    maxParallelToolCalls: number;
+};
+export declare const DEFAULT_TURN_LIMITS: TurnLimits;
+export declare const resolveLimits: (overrides?: Partial<TurnLimits>) => TurnLimits;

package/dist/loop/opening.d.ts

@@ -0,0 +1,42 @@
+import type { ModelRoute } from '../llm/index.js';
+import type { InitialInstallation, ThreadEnvironment, ThreadOrigin } from '../models/index.js';
+import type { DeepReadonly } from '../util/json.js';
+import type { RowRef } from './surface.js';
+/**
+ * What a fresh thread is born with, as its spawn row records it: the one value `create` resolves a
+ * birth to, whichever source it came from, and the one a reused thread is compared on. `installations`
+ * holds all of them, handed down ones included, each with its lifetime; `requires` is a set, kept
+ * sorted and without repeats.
+ */
+export type BirthSpec = DeepReadonly<{
+    route: ModelRoute;
+    environment: ThreadEnvironment;
+    installations: InitialInstallation[];
+    requires: string[];
+}>;
+/**
+ * A fresh thread as a write-time callback sees it: the agent it is born on, the origin it records
+ * (`null` for a root) and its {@link BirthSpec}.
+ */
+export type FreshOpening = {
+    agent: string;
+    origin: ThreadOrigin | null;
+    spec: BirthSpec;
+};
+/**
+ * A fork as a write-time callback sees it: its agent (the cut's thread's), the origin it records
+ * and the cut it continues from, its own environment and constraint owners as its spawn row records
+ * them, and `inherits`, what it goes on with from the cut and does not record: the route and the
+ * installations at that row.
+ */
+export type ForkOpening = {
+    agent: string;
+    origin: ThreadOrigin | null;
+    cut: RowRef;
+    environment: ThreadEnvironment;
+    requires: string[];
+    inherits: {
+        route: ModelRoute;
+        installations: InitialInstallation[];
+    };
+};

package/dist/loop/prepare.d.ts

@@ -0,0 +1,30 @@
+import type { QueuedInput, ReplacementTrigger } from '../models/index.js';
+import type { JsonValue } from '../util/json.js';
+import { type ModelRoute } from '../llm/index.js';
+import type { SurfacePrepareOutcome } from './hooks.js';
+import type { Lease, LoopRuntime } from './runtime.js';
+/** One request to prepare the surface, as the loop or `thread.compact()` starts it. */
+export type SurfacePrepareDispatch = {
+    readonly threadId: string;
+    readonly agentName: string;
+    readonly turn: number | null;
+    readonly step: number | null;
+    readonly route: ModelRoute;
+    readonly trigger: ReplacementTrigger;
+    readonly queued: readonly QueuedInput[];
+    readonly options: JsonValue | null;
+    readonly signal: AbortSignal;
+    /** The lease the caller holds; checked before the engine records anything for the plan. */
+    readonly lease: Lease;
+};
+/** How a request settled, and the error that ended it when the strategy threw. */
+export type SurfacePrepareSettled = {
+    readonly outcome: SurfacePrepareOutcome;
+    readonly error: unknown;
+};
+/**
+ * Asks the thread's strategy for a plan and carries it out: the one model call it asks for, then the
+ * replacement or the facts its final plan names, all recorded by the engine. Never throws for the
+ * strategy: what a failure means is the trigger's policy, which the caller applies.
+ */
+export declare function runSurfacePrepare(runtime: LoopRuntime, dispatch: SurfacePrepareDispatch): Promise<SurfacePrepareSettled>;