@leuduan/lagent 0.1.2 → 44.0.0

package/dist/services/tools.d.ts

@@ -1,6 +1,11 @@
 import { Context, Service, type ScopeKey } from '@leuduan/cordis';
-import { type AgentSelector } from '../kit/scope.js';
-import type { Tool, ToolEntry } from '../loop/index.js';
+import { z } from 'zod';
+import { type AgentSelector } from './agents.js';
+import { type Tool, type ToolEntry, type InvocationContext, type ToolExecutionMode, type WaitRequest } from '../loop/index.js';
+import { type InterruptionPolicy } from '../records/journal.js';
+import { type ParsedToolCall, type ToolCall } from '../llm/primitives.js';
+import { type ToolResult, type ToolResultPayloadInput } from '../records/toolResult.js';
+import type { JsonValue } from '../util/json.js';
 /**
  * The tools this process can offer, and who may call them. Live: a tool or a grant lasts
  * exactly as long as the plugin that registered it, and an agent's reachable set is resolved when a
@@ -39,3 +44,75 @@ export declare class ToolsService extends Service {
     toolFor(scope: ScopeKey | undefined, agentName: string, toolName: string): ToolEntry | undefined;
     mayCall(scope: ScopeKey | undefined, agentName: string, toolName: string): boolean;
 }
+/**
+ * Parameters described elsewhere, as JSON schema: advertised as given and handed to `execute`
+ * unvalidated, for a tool whose real validator is someone else's, such as an MCP server.
+ */
+export type JsonSchemaParameters = {
+    readonly jsonSchema: Record<string, JsonValue>;
+};
+type ParametersOf<P> = P extends z.ZodType ? z.output<P> : Record<string, unknown>;
+/** What `execute` returns: a result with `is_error`, `notes` and `metadata` optional, or a wait (`waitFor`). */
+export type ToolReply = ToolResultPayloadInput | WaitRequest;
+/** One tool, as {@link defineTool} takes it. */
+export type ToolDefinition<P extends z.ZodType | JsonSchemaParameters> = {
+    /** The name it is registered under, and advertised to the model by. */
+    readonly name: string;
+    /** One paragraph advertised to the model. */
+    readonly description: string;
+    /** A zod schema the arguments are validated against and advertised from, or JSON schema. */
+    readonly parameters: P;
+    /**
+     * What a re-dispatch may do with a call that may have begun when its turn was interrupted; see
+     * `Tool.onInterrupted`. Every tool says which; there is no default.
+     */
+    readonly onInterrupted: InterruptionPolicy;
+    /** Whether a call may overlap its batch's others; see `Tool.executionMode`. No default either. */
+    readonly executionMode: ToolExecutionMode;
+    /** Runs one call. A throw becomes an `is_error` result: a tool never fails a turn. */
+    execute(parameters: ParametersOf<P>, context: InvocationContext, call: ParsedToolCall): Promise<ToolReply>;
+};
+/**
+ * Defines a tool: the one way to write one. Arguments are validated against `parameters` when it is
+ * a zod schema, and a validation failure or a throw from `execute` becomes an `is_error` result, so
+ * a tool can never crash a turn; the result is timed. A tool that needs configuration closes over it.
+ *
+ * ```ts
+ * const echo = defineTool({
+ *   name: 'echo',
+ *   description: 'Repeat the text.',
+ *   parameters: z.strictObject({ text: z.string() }),
+ *   onInterrupted: 'rerun',
+ *   executionMode: 'parallel',
+ *   execute: async ({ text }) => ({ output: text }),
+ * })
+ * ```
+ */
+export declare function defineTool<P extends z.ZodType | JsonSchemaParameters>(definition: ToolDefinition<P>): Tool;
+/**
+ * Offers `tool` in the calling plugin's scope for the life of its fiber, and grants it to the agents
+ * `agents` selects when given; without them it is registered for a grant elsewhere, a preset's say.
+ * Returns the disposer.
+ */
+export declare function registerTool(ctx: Context, tool: Tool, options?: {
+    readonly agents?: AgentSelector;
+}): () => void | Promise<void>;
+/**
+ * {@link registerTool} for each of `tools`, then a prompt instruction under `tag` for every agent that
+ * is granted one of them: the `guidance` of each granted tool, in tool order, and nothing when none
+ * is granted or none has any.
+ */
+export declare function registerTools(ctx: Context, tools: readonly Tool[], options: {
+    readonly tag: string;
+    readonly guidance: ReadonlyMap<string, string>;
+}): void;
+/** A tool's result for `call`, its defaults applied and its duration recorded. */
+export declare function toToolResult(call: ToolCall, reply: ToolResultPayloadInput, startedAt: number): ToolResult;
+export { errorResult } from '../loop/index.js';
+/**
+ * Grants `toolName` to the agents `agents` selects, for the life of the calling plugin's fiber, or
+ * until the returned disposer runs. The selector is stored as given: registries are live, so
+ * a grant to `'global'` or `'all'` is matched against each agent when it asks, agents registered
+ * later included.
+ */
+export declare function grantTool(ctx: Context, toolName: string, agents: AgentSelector): () => void | Promise<void>;

package/dist/{loop/opening.d.ts → state/birth.d.ts}

@@ -1,7 +1,8 @@
-import type { ModelRoute } from '../llm/index.js';
-import type { InitialInstallation, ThreadEnvironment, ThreadOrigin } from '../models/index.js';
+import type { ModelRoute } from '../llm/provider.js';
+import type { InitialInstallation, JournalEvent, Seq, ThreadEnvironment, ThreadFork, ThreadOrigin } from '../records/journal.js';
 import type { DeepReadonly } from '../util/json.js';
 import type { RowRef } from './surface.js';
+import type { Reducer } from './thread.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`
@@ -40,3 +41,22 @@ export type ForkOpening = {
         installations: InitialInstallation[];
     };
 };
+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>;

package/dist/{loop → state}/chain.d.ts

@@ -1,5 +1,5 @@
-import type { RunChain, Seq } from '../models/index.js';
-import type { Reducer } from './threadState.js';
+import type { RunChain, Seq } from '../records/journal.js';
+import type { Reducer } from './thread.js';
 /** An inputless cause not yet consumed: the run whose next turn it classifies, `null` once carried. */
 type InputlessCause = {
     readonly seq: Seq;
@@ -11,7 +11,7 @@ type InputlessCause = {
  * {@link ChainState} concern of `threadState`, which a fork starts over.
  *
  * The rules, a turn's class and the count of reactive turns in a row, are in
- * `docs/lifecycle.md#the-chain`. What only this fold fixes: a later weaker claim never lowers a
+ * `docs/guides/threads.md#the-chain`. What only this fold fixes: a later weaker claim never lowers a
  * class, a request extended while it runs is not a claim, and the count is provisional while a
  * `reactive` turn is open and final at its `turn/end`, by the class it ended with.
  */

package/dist/state/confirmations.d.ts

@@ -0,0 +1,64 @@
+import type { JournalEvent, Seq } from '../records/journal.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import type { ParsedToolCall } from '../llm/primitives.js';
+import type { Reducer, ThreadState } from './thread.js';
+import { type WaitEntry } from './waits.js';
+export type ConfirmationState = {
+    request_id: string;
+    thread_id: string;
+    /** The exact model `tool/call` or runtime `execution/requested` row being approved. */
+    target: JournalEvent<'confirm/requested'>['data']['target'];
+    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>>;
+/** One runtime-owned operation and its authorization/result, reconstructed without redispatch. */
+export type RuntimeExecution = {
+    seq: Seq;
+    request: JournalEvent<'execution/requested'>['data'];
+    authorization: {
+        seq: Seq;
+        data: JournalEvent<'execution/authorization'>['data'];
+    } | null;
+    result: {
+        seq: Seq;
+        value: JournalEvent<'execution/result'>['data']['result'];
+    } | null;
+};
+export declare const executions: Reducer<Map<Seq, RuntimeExecution>>;
+/** Requests still waiting on the user on one thread. */
+export declare const outstandingConfirmations: (state: ReadonlyMap<string, ReadonlyState<ConfirmationState>>, threadId: string) => ReadonlyState<ConfirmationState>[];
+/**
+ * Model dispatches held by a pending confirmation or unresolved wait, by durable sequence.
+ * These holds survive turns: dispatching again before the answer or value would only raise a
+ * second request, or declare the wait twice.
+ */
+export declare const parkedCallSeqs: (confirmationState: ReadonlyMap<string, ReadonlyState<ConfirmationState>>, waitState: ReadonlyMap<Seq, WaitEntry>, threadId: string) => Set<Seq>;
+/**
+ * The confirmation of one durable dispatch, pending or answered. Model and runtime dispatch share
+ * this lookup; a provider's call ID, request ID or source citation never grants approval authority.
+ */
+export declare const confirmationFor: (state: ReadonlyMap<string, ReadonlyState<ConfirmationState>>, dispatch: {
+    threadId: string;
+    target: ConfirmationState["target"];
+}) => ReadonlyState<ConfirmationState> | undefined;
+/** 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>;
+/**
+ * Confirmations on `threadId` whose call has no result yet and was not rejected: still waiting on the
+ * user, or approved. An approval lasts until the call's result: the call runs at the next turn, and
+ * one that waits or is cut off runs again on the same approval, against whatever tool answers to its
+ * name by then. Runtime approval belongs to its pending candidate; once that candidate is rejected
+ * or superseded it no longer blocks configuration. Unknown command cleanup is accounted separately.
+ */
+export declare function unfinishedConfirmations(state: ReadonlyState<Pick<ThreadState, 'confirmations' | 'executions' | 'answerCheck' | 'dispatchedCalls'>>, threadId: string): ReadonlyState<ConfirmationState>[];

package/dist/{loop → state}/continuation.d.ts

@@ -1,8 +1,9 @@
-import type { CancelIntent, InterruptionCause, JsonValue, RunOutcomeKind, RunSettledReason, Seq, TurnEndReason } from '../models/index.js';
+import type { CancelIntent, InterruptionCause, RunOutcomeKind, RunSettledReason, Seq, TurnEndReason } from '../records/journal.js';
+import type { JsonValue } from '../util/json.js';
 import { type DeepReadonly } from '../util/json.js';
 import type { DerivedHold, Hold } from './holds.js';
 import type { PendingRun } from './requests.js';
-import type { ThreadState } from './threadState.js';
+import type { ThreadState } from './thread.js';
 /**
  * What a registered constraint says of a thread's pending request: `allow`; `hold` with why (`reason`,
  * in words) and, optionally, a machine-readable `code` and `data`, until the feature calls `changed`;

package/dist/{loop → state}/decide.d.ts

@@ -1,6 +1,7 @@
-import type { QueuedInput, Seq, TurnEndReason } from '../models/index.js';
-import type { ToolCall } from '../llm/index.js';
+import { type QueuedInput, type Seq, type TurnEndReason, type InboxTarget } from '../records/journal.js';
+import type { ToolCall } from '../llm/primitives.js';
 import type { TurnLimits } from './limits.js';
+import type { Journal } from '../journal/index.js';
 /**
  * What one thread looks like at a decision point. Not the public `ThreadView` read.
  *
@@ -62,3 +63,10 @@ export type Action =
 export declare function nextAction(view: DecisionView, limits: TurnLimits): Action;
 /** Whether there is anything to do at all — the same decision, asked as a question. */
 export declare const hasWork: (view: DecisionView, limits: TurnLimits) => boolean;
+/**
+ * A journal view, usable without constructing an execution runtime or activating plugins.
+ * `sentBack` says a stop check sent back the answer of a turn that opened by answering calls, so
+ * input waiting for a turn joins it batch by batch (`Inbox.peek`).
+ */
+export declare function decisionView(journal: Journal, threadId: string, target: InboxTarget, step: number, turn: number, sentBack?: boolean): DecisionView;
+export declare function hasThreadWork(journal: Journal, threadId: string, limits: TurnLimits): boolean;

package/dist/state/dispatches.d.ts

@@ -0,0 +1,54 @@
+import type { InterruptionPolicy, JournalEvent, Seq } from '../records/journal.js';
+import type { DeepReadonly } from '../util/json.js';
+import type { ConversationMessage, ToolCall } from '../llm/primitives.js';
+import type { Reducer } from './thread.js';
+import { type WaitEntry } from './waits.js';
+/**
+ * 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;
+/**
+ * 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>[];

package/dist/state/errors.d.ts

@@ -0,0 +1,26 @@
+import type { ReplacementRule } from './surface.js';
+/** No thread has this id. */
+export declare class UnknownThreadError extends ReferenceError {
+    readonly threadId: string;
+    constructor(threadId: string);
+}
+/** A fork was asked for at a row it cannot be cut at; nothing was appended. */
+export declare class ForkCutError extends Error {
+    readonly threadId: string;
+    readonly seq: number;
+    constructor(threadId: string, seq: number, reason: string);
+}
+/**
+ * A replacement `replaceSurface` refused: it breaks a rule of the surface it would land on (see
+ * `judgeReplacement`). Nothing of its group was recorded. Distinct from any other failure, so a
+ * strategy can tell a plan the surface refused from a journal that could not write.
+ */
+export declare class ReplacementRefusedError extends Error {
+    readonly index: number;
+    readonly rule: ReplacementRule;
+    constructor(message: string, 
+    /** The refused replacement's position in the group it was offered with. */
+    index: number, 
+    /** The surface rule it breaks. */
+    rule: ReplacementRule);
+}

package/dist/{loop → state}/forks.d.ts

@@ -1,5 +1,5 @@
 import type { Journal } from '../journal/index.js';
-import type { Seq, TurnEndReason } from '../models/index.js';
+import type { Seq, TurnEndReason } from '../records/journal.js';
 import type { RowRef } from './surface.js';
 /**
  * Where forks may be cut, and the lookups that find such a row from a turn or a reply. Journal

package/dist/{loop → state}/holds.d.ts

@@ -1,4 +1,4 @@
-import type { Seq } from '../models/index.js';
+import type { Seq } from '../records/journal.js';
 import type { ReadonlyState } from '../util/foldState.js';
 import { type ReadonlyJsonValue } from '../util/json.js';
 import type { RequestsState } from './requests.js';

package/dist/{loop → state}/inbox.d.ts

@@ -1,8 +1,8 @@
-import type { ExtensionRecord, InboxTarget, QueuedInput, Seq, ThreadInput } from '../models/index.js';
+import type { ExtensionRecord, InboxTarget, QueuedInput, Seq, ThreadInput } from '../records/journal.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 { FreshOpening, ForkOpening } from './birth.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

package/dist/state/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What the rest of the package may use of recorded state: the folds of a thread's rows, the queries
+ * over them, and the writes that need no activation (the inbox, closing an interrupted turn, the
+ * surface replacement writer). Nothing here runs a turn or imports Cordis; the loop executes against
+ * these and the services read them. The journal substrate itself is `journal/`, imported directly.
+ */
+export * from './thread.js';
+export * from './turns.js';
+export * from './dispatches.js';
+export * from './waits.js';
+export * from './confirmations.js';
+export * from './prompt.js';
+export * from './inputs.js';
+export * from './installations.js';
+export * from './surface.js';
+export * from './requests.js';
+export * from './holds.js';
+export * from './chain.js';
+export * from './route.js';
+export * from './errors.js';
+export * from './limits.js';
+export * from './birth.js';
+export * from './continuation.js';
+export * from './decide.js';
+export * from './forks.js';
+export * from './inbox.js';
+export * from './recovery.js';
+export * from './replace.js';
+export * from './surfaceRead.js';
+export * from './summary.js';
+export * from './wake.js';

package/dist/state/inputs.d.ts

@@ -0,0 +1,58 @@
+import type { InboxTarget, QueuedInput, Seq } from '../records/journal.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import type { Reducer, ThreadState } from './thread.js';
+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>>;
+/**
+ * What became of the input id a thread was handed: `unknown` when it never was; `queued` while it
+ * waits, for `target`; `claimed` once a step took it; `discarded` when it left the queue unclaimed,
+ * withdrawn or cleared by a cancel. Each names the row that queued it, and a claim the
+ * `input/message` that took it. A discarded or claimed id stays spent: it is never queued again.
+ */
+export type InputFate = {
+    readonly state: 'unknown';
+} | {
+    readonly state: 'queued';
+    readonly queuedAt: Seq;
+    readonly target: InboxTarget;
+} | {
+    readonly state: 'claimed';
+    readonly queuedAt: Seq;
+    readonly claimedAt: Seq;
+} | {
+    readonly state: 'discarded';
+    readonly queuedAt: Seq;
+};
+/**
+ * The fate of input `id` from a thread's state: the one answer to "what became of input X", read
+ * inside a write or a contributor from the state the journal folds, or through `ThreadView.input`.
+ * A fork's own ids only: its source's are the source's.
+ */
+export declare function inputFate(state: ReadonlyState<Pick<ThreadState, 'inputs' | 'inbox'>>, id: string): InputFate;
+/**
+ * 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;
+}>;

package/dist/state/installations.d.ts

@@ -0,0 +1,28 @@
+import type { InstallationLifetime } from '../records/journal.js';
+import type { JsonValue } from '../util/json.js';
+import type { Reducer } from './thread.js';
+/** 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/state/prompt.d.ts

@@ -0,0 +1,13 @@
+import type { ToolSpec } from '../llm/primitives.js';
+import type { PromptBlock } from '../llm/prompt.js';
+import type { Reducer } from './thread.js';
+/**
+ * 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>;

package/dist/state/recovery.d.ts

@@ -0,0 +1,7 @@
+import type { Journal } from '../journal/index.js';
+import type { TurnLimits } from './limits.js';
+/**
+ * Close a process-interrupted turn from journal state, including when no new execution is needed.
+ * Decided inside the write, so a turn something else closed meanwhile is not closed twice.
+ */
+export declare function closeInterruptedTurn(journal: Journal, threadId: string, limits: TurnLimits): Promise<void>;

package/dist/{loop → state}/replace.d.ts

@@ -1,6 +1,6 @@
 import type { Journal } from '../journal/index.js';
-import type { JournalEventInput, ReplacementTrigger, Seq } from '../models/index.js';
-import type { RowRef } from './surface.js';
+import { type JournalEventInput, type ReplacementTrigger, type Seq } from '../records/journal.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;
 /**

package/dist/{loop → state}/requests.d.ts

@@ -1,6 +1,6 @@
-import type { CancelIntent, RunChain, RunOutcomeKind, RunSettledReason, Seq } from '../models/index.js';
-import type { InputFate } from './state.js';
-import type { Reducer } from './threadState.js';
+import type { CancelIntent, RunChain, RunOutcomeKind, RunSettledReason, Seq } from '../records/journal.js';
+import type { InputFate } from './inputs.js';
+import type { Reducer } from './thread.js';
 /** One `run/cause` row as the request fold keeps it. */
 export type RunCause = {
     readonly seq: Seq;

package/dist/{loop → state}/route.d.ts

@@ -1,5 +1,6 @@
-import type { ModelRoute } from '../llm/index.js';
-import type { ModelSelection } from './runtime.js';
+import type { ModelRoute } from '../llm/provider.js';
+import type { ModelSelection } from '../llm/provider.js';
+import type { Reducer } from './thread.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,
@@ -51,3 +52,10 @@ export declare const sameRoute: (a: ModelRoute, b: ModelRoute) => boolean;
  * which refuses the whole write.
  */
 export declare function statedRoute(threadId: string, statement: RouteStatement, routes: RouteAuthority): ModelRoute | 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>;

package/dist/state/summary.d.ts

@@ -0,0 +1,16 @@
+import type { Journal, ThreadSummaryCore } from '../journal/index.js';
+import type { TurnLimits } from './limits.js';
+/**
+ * A thread's catalog summary, from its folds as they stand: the spawn row's identity, how its last
+ * turn ended, the thread's route, whether a turn is open, whether a run would find
+ * work, and where its run requests stand — the pending one the run owner picks its candidates by at
+ * `threads.start`, from the catalog, so only those are loaded and run; the latest settlement and person's cancel the holds
+ * derive from; and the latest answer, which tells a parked caller an answer landed under it. The confirmations it waits on and the calls it
+ * suspended are listed as descriptors, enough to find them without the thread's rows; the full
+ * requests and dependencies come from the thread once it is loaded.
+ *
+ * Registered with the journal by the journal plugin, which is how `journal/` never learns what a
+ * turn is. Everything here is a thread-scoped fold, so the summary is a function of the thread's
+ * own lineage and nothing else.
+ */
+export declare function summarizeThread(journal: Journal, threadId: string, limits: TurnLimits): ThreadSummaryCore;

package/dist/{loop → state}/surface.d.ts

@@ -1,7 +1,7 @@
 import type { Journal } from '../journal/index.js';
-import type { Reducer } from './threadState.js';
-import type { ConversationMessage } from '../llm/index.js';
-import type { JournalEvent, ReplacementKind, Seq, SurfaceEventType } from '../models/index.js';
+import type { Reducer } from './thread.js';
+import type { ConversationMessage } from '../llm/primitives.js';
+import type { JournalEvent, ReplacementKind, Seq, SurfaceEventType } from '../records/journal.js';
 import type { ReadonlyState } from '../util/foldState.js';
 /** A journal row, named by the thread that owns it. Inherited rows belong to a fork's source lineage. */
 export type RowRef = {

package/dist/state/surfaceRead.d.ts

@@ -0,0 +1,20 @@
+import type { Journal, PluginJournal } from '../journal/index.js';
+import type { ConversationMessage } from '../llm/primitives.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import { type ReplacementRefusal, type RowRef } from './surface.js';
+/**
+ * The first replacement `threadId`'s surface refused, or `null`: a thread that has one carries
+ * history no execution may continue from, which every entry that executes checks.
+ */
+export declare function refusedReplacement(journal: Pick<Journal, 'state'>, threadId: string): {
+    readonly row: RowRef;
+    readonly refusal: ReplacementRefusal;
+} | null;
+/**
+ * The last thing the model said on a thread, if anything: the message of the last
+ * `assistant/message` row on its lineage that the stream did not cut off. Found through the rows
+ * behind the surface, not by role, so an assistant-role stand-in is never reported as the model's
+ * last word; a reply a replacement took off the surface is still found, through the rows its
+ * stand-in replaced.
+ */
+export declare function lastAssistantMessage(journal: Pick<PluginJournal, 'eventAt' | 'state'>, threadId: string): ReadonlyState<ConversationMessage> | null;