@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/loop/chain.d.ts

@@ -0,0 +1,46 @@
+import type { RunChain, Seq } from '../models/index.js';
+import type { Reducer } from './threadState.js';
+/** An inputless cause not yet consumed: the run whose next turn it classifies, `null` once carried. */
+type InputlessCause = {
+    readonly seq: Seq;
+    readonly runId: string | null;
+    readonly chain: RunChain;
+};
+/**
+ * A thread's chain of unattended work, folded from its causes, claims and turns: core's
+ * {@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
+ * 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.
+ */
+export type ChainState = {
+    /** The chain a cause with an input named, by input id, until a step claims that input or it is discarded. */
+    readonly byInput: Map<string, RunChain>;
+    /**
+     * Inputless causes not consumed yet, in order. Each is consumed once, by the first turn on its
+     * run that opens after it; a settlement carries the ones it names as residual to the successor,
+     * and the rest retire.
+     */
+    inputless: readonly InputlessCause[];
+    /** The turn open, if any, and the strongest class it received. */
+    open: {
+        readonly turn: number;
+        readonly class: RunChain | null;
+    } | null;
+    /** Reactive turns in a row since the last `person` or `fresh` authority, committed ones only. */
+    count: number;
+};
+export declare const chain: Reducer<ChainState>;
+/** Where a thread's chain stands, as `ctx.threads.chain` reads it. */
+export type ChainStanding = {
+    /** Whether the turn open now has received a person's authority; `false` between turns. */
+    readonly personTurn: boolean;
+    /** Reactive turns in a row, the open one counted if it is reactive. */
+    readonly turns: number;
+    /** Whether `turns` has reached the limit: a producer of more unattended work is refused. */
+    readonly atLimit: boolean;
+};
+export declare function chainStanding(state: ChainState, limit: number): ChainStanding;
+export {};

package/dist/loop/chunks.d.ts

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

package/dist/loop/continuation.d.ts

@@ -0,0 +1,166 @@
+import type { CancelIntent, InterruptionCause, JsonValue, RunOutcomeKind, RunSettledReason, Seq, TurnEndReason } from '../models/index.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';
+/**
+ * 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`;
+ * or `obsolete`, the request's authority gone for good: it settles `superseded` once nothing of it is
+ * left to drain.
+ */
+export type ConstraintAnswer = {
+    readonly kind: 'allow';
+} | {
+    readonly kind: 'hold';
+    readonly reason: string;
+    readonly code?: string;
+    readonly data?: JsonValue;
+} | {
+    readonly kind: 'obsolete';
+    readonly reason: string;
+};
+/** An answer as the decision reads it: core stamps the registration's `owner` onto a hold. */
+export type OwnedAnswer = Exclude<ConstraintAnswer, {
+    readonly kind: 'hold';
+}> | (Extract<ConstraintAnswer, {
+    readonly kind: 'hold';
+}> & {
+    readonly owner: string;
+});
+/** What the work on a thread looks like to the decision: the folds' answers, read as it decides. */
+export type WorkSnapshot = {
+    /** Whether a run would find something to do (`hasThreadWork`). */
+    readonly hasWork: boolean;
+    /**
+     * Whether input waits for the next step: steering that arrived during the turn just ended, or a
+     * report its sender queued for the next step, which a turn that ran out answering calls left.
+     */
+    readonly nextStepQueued: boolean;
+    /** Whether any input waits, for a step or a turn. */
+    readonly anyQueued: boolean;
+    /** Whether the conversation holds calls with no answer. */
+    readonly unanswered: boolean;
+};
+/** How a turn ended, as a continuation decision reads it: its kind, and for an interruption its cause. */
+export type Ending = {
+    readonly kind: Exclude<TurnEndReason['kind'], 'interrupted'>;
+} | {
+    readonly kind: 'interrupted';
+    readonly cause: InterruptionCause;
+};
+/** Everything one continuation decision reads. No clock, I/O or callback. */
+export type ContinuationInput = {
+    readonly pending: PendingRun;
+    /** How the execution's last turn ended; `null` at the execution's entry, or for an idle thread. */
+    readonly ending: Ending | null;
+    /**
+     * The repairs the request may still spend on interrupted turns, read from its durable count
+     * (`repairsLeft`), so a crash, a hold or a new execution neither grants nor loses one.
+     */
+    readonly repairsLeft: number;
+    readonly work: WorkSnapshot;
+    /**
+     * Whether a confirmation on the thread or under it was answered since its last turn began: what
+     * the next turn carries to the call that parked on it.
+     */
+    readonly answeredUnder: boolean;
+    /** The derived holds on the request, as `deriveHolds` orders them. */
+    readonly holds: readonly DerivedHold[];
+    /** What the constraints the thread is under say, combined; `allow` with none. */
+    readonly constraint: OwnedAnswer;
+    /** The intent of the cancel that captured this execution, if one did. */
+    readonly cancel: CancelIntent | null;
+};
+/**
+ * What a thread does next with its pending request: run another turn (`advance`); end the
+ * execution with the request still pending (`hold`, `shutdown` when an abort that no cancel
+ * captured ended it); settle the request with an outcome; or rerun the interrupted turn (`repair`),
+ * when plugins, or what its judgment was fenced on, changed under it.
+ */
+export type Continuation = {
+    readonly kind: 'advance';
+} | {
+    readonly kind: 'hold';
+    readonly hold: Hold;
+} | {
+    readonly kind: 'settle';
+    readonly outcome: RunOutcomeKind;
+    readonly reason: RunSettledReason;
+} | {
+    readonly kind: 'repair';
+};
+/** How a cancel settles the run it reaches: a person's `cancelled`, a feature's cleanup `superseded`. */
+export declare const cancelOutcome: (intent: CancelIntent) => RunOutcomeKind;
+/** The repairs left to a request whose rows fold to `requests`: one, less one per interrupted turn since a releasing cause, after the first. */
+export declare const repairsLeft: (requests: {
+    readonly interruptions: number;
+}) => number;
+/** A constraint's hold as the hold on the request: its answer, the owner that gave it stamped. */
+export declare function constraintHold(answer: Extract<OwnedAnswer, {
+    readonly kind: 'hold';
+}>): Hold;
+/**
+ * The one continuation decision, at an idle thread and at every turn boundary of an execution. It
+ * replaces the loop's own branch after a turn, and every host's rule for running a thread again;
+ * the turn and step decider underneath (`nextAction`) is unchanged. In order:
+ *
+ * 1. A cancel that captured the execution settles it by its intent; a constraint that calls the
+ *    request obsolete settles it `superseded`.
+ * 2. How the last turn ended: an abort no cancel captured is a shutdown, leaving the request
+ *    pending; an interrupted turn holds for any current hold (a repair would run the turn again
+ *    under it), and otherwise is repaired while the execution has a repair left. Once none is, a
+ *    turn whose activation changed fails the request, and one whose judgment was invalidated (a
+ *    transient race with the facts it judged) leaves it held until the next releasing cause, the
+ *    answer still owed its checks; a turn recovery closed goes on as at an entry. An error fails the
+ *    request, as a failure before any turn does (`setup`); out of steps or a rejected answer goes
+ *    on only for input waiting for the next step (`nextStep`), and fails otherwise; a blocked
+ *    turn holds on an approval still waiting unless an answer under the thread landed since it
+ *    began, and otherwise decides as below; a completed turn goes on while input waits, and settles
+ *    `completed` otherwise.
+ * 3. Going on, or at the entry: the derived holds (past an approval hold when an answer landed
+ *    since the last turn began; a wait holds whatever landed), then the constraint's own hold, then
+ *    whether a run would find work at all. One that would not still holds on an approval waiting,
+ *    and otherwise settles as its last turn ended, or `completed` with nothing done. A blocked turn
+ *    whose calls nothing holds and none can be dispatched breaks the rules the holds keep: the
+ *    decision throws.
+ */
+export declare function continuation(input: ContinuationInput): Continuation;
+/**
+ * The run a cancel's own write settles, by its intent: the request pending when the write lands,
+ * unless it is the run of the execution the cancel captured, whose finalization settles it. That is
+ * the pending run of an idle thread, or a successor the captured execution's finalization already
+ * opened from residual causes.
+ */
+export declare function cancelWriteSettles(pending: PendingRun | null, capturedRunId: string | null): string | null;
+/** A turn a run served: how it ended, its `turn/start`, and the attempt cutoff of the execution that opened it. */
+export type ServedTurn = {
+    readonly ending: DeepReadonly<TurnEndReason>;
+    readonly start: Seq;
+    readonly attemptCutoff: Seq;
+};
+/** The thread's last turn when it served `runId` and has ended. */
+export declare function lastTurn(state: ThreadState, runId: string): ServedTurn | null;
+/**
+ * The thread's last turn when it served `runId` and ended, as a resumed run re-enters from it: a
+ * crash between a failed turn and its settlement fails the run, carrying the causes that release
+ * the failure to a successor, rather than retry it under the failed run. A turn that a shutdown
+ * aborted, or that recovery abandoned, is no ending to decide from: the run goes on. Nor is a turn that did not fail when a releasing cause came after it: a person who asked
+ * since would have opened a request of their own, had the run settled first. That includes an
+ * interrupted turn, its activation changed or its judgment invalidated: until a releasing cause
+ * lands, it is the ending the run is repaired from, held on or failed by, as its spent repairs say.
+ */
+export declare function resumedTurn(state: ThreadState, runId: string): ServedTurn | null;
+/** Where a continuation decision reads the last turn from: how it ended (`null` before any) and where it began. */
+export type DecisionTurn = {
+    readonly ending: Ending | null;
+    readonly start: Seq | null;
+};
+/**
+ * The turn the decision at an execution's entry, or one made before admitting a run, reads: the
+ * ending of a turn that served the pending run when a crash or a hold left it there (`resumed`),
+ * and otherwise where the thread's last turn began, so an answer since counts.
+ */
+export declare function entryTurn(state: ThreadState): DecisionTurn & {
+    readonly resumed: ServedTurn | null;
+};

package/dist/loop/decide.d.ts

@@ -0,0 +1,64 @@
+import type { QueuedInput, Seq, TurnEndReason } from '../models/index.js';
+import type { ToolCall } from '../llm/index.js';
+import type { TurnLimits } from './limits.js';
+/**
+ * What one thread looks like at a decision point. Not the public `ThreadView` read.
+ *
+ * Every field is a fold of the journal but one input: which queue the boundary reads and whether a
+ * stop check sent back the answer of a turn that opened by answering calls (`decisionView`'s
+ * `target` and `sentBack`), which the loop remembers for the turn. A crash closes the turn, and a new
+ * turn starts both afresh, so a journal that stops anywhere still decides the same way.
+ */
+export type DecisionView = {
+    /** Input waiting at this boundary. */
+    readonly queued: readonly QueuedInput[];
+    /** Calls the conversation has no answer for. */
+    readonly unanswered: readonly ToolCall[];
+    /** Of those, the ones that cannot be dispatched now: waiting on a confirmation, or on a wait not resolved. */
+    readonly parked: readonly ToolCall[];
+    /** Whether the conversation ends on something the model has not replied to. */
+    readonly owed: boolean;
+    /** Whether a tool result asked for this turn to stop. */
+    readonly concluded: boolean;
+    /** The answer the conversation ends on, while no stop check has accepted or rejected it. */
+    readonly provisional: Seq | null;
+    /** Steps already taken in this turn. */
+    readonly step: number;
+};
+export type Action = 
+/** Run these, then decide again. */
+{
+    kind: 'answer-calls';
+    calls: readonly ToolCall[];
+}
+/** Record this input, ask the model, then decide again. */
+ | {
+    kind: 'ask-model';
+    claim: readonly QueuedInput[];
+}
+/** Ask the stop checks to judge the provisional answer. */
+ | {
+    kind: 'check';
+}
+/** Stop, for this reason. */
+ | {
+    kind: 'end';
+    reason: TurnEndReason;
+};
+/**
+ * What a thread does next.
+ *
+ * A pure function of the view, so the whole of the loop's control flow is a truth table rather than
+ * something you need a model, a store and a clock to exercise. The loop is then: decide, do it,
+ * append what happened, decide again — which is why resuming needs no separate path. A journal that
+ * stops mid-turn produces a view like any other, and the same decision picks it up.
+ *
+ * Deliberately absent: what to do when a model call *fails*. A transient failure before any output
+ * is retried beneath the loop, by `ctx.llm`'s client under the provider's policy; one that still
+ * fails ends the turn, reported with its kind, and whether to run it again is the host's. Request
+ * middleware cannot retry: it may call `next()` once. A decider that could see a failure and ask
+ * again would spin on a provider outage, since the conversation it reads is unchanged by one.
+ */
+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;

package/dist/loop/errors.d.ts

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

package/dist/loop/forks.d.ts

@@ -0,0 +1,61 @@
+import type { Journal } from '../journal/index.js';
+import type { Seq, TurnEndReason } from '../models/index.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
+ * reads only: forking never activates, leases or waits on the thread it forks.
+ */
+/**
+ * Where "fork from here" cuts, along a thread's lineage: a turn's ending, or a replacement recorded
+ * between turns, such as a `compact()`, which a `turn/end` alone would miss. A replacement point
+ * carries the turn it followed, `null` when no turn had ended before it.
+ */
+export type ForkPoint = (RowRef & {
+    readonly kind: 'turn/end';
+    readonly turn: number;
+    readonly reason: TurnEndReason;
+}) | (RowRef & {
+    readonly kind: 'surface/replaced';
+    readonly afterTurn: number | null;
+});
+/**
+ * Resolves `at` on `sourceId` to the row a fork is cut at, and the thread that owns it.
+ *
+ * The row must be of a cut kind and belong to the source's lineage; a row the source inherited is
+ * redirected to the thread that owns it, so the fork becomes that thread's. A pair must name the
+ * owner. The cut must also be settled (see {@link unsettled}).
+ */
+export declare function resolveCut(journal: Journal, sourceId: string, at: Seq | RowRef): RowRef;
+/**
+ * The cut for forking at the turn that contains `anchor`: that turn's `turn/end`, or with `before`
+ * its `turn/start` — after what the turn started with was recorded, such as the prompt of a first
+ * turn, a mode switch and the turn's route, and before any of its input.
+ *
+ * An anchor inside a turn that has not ended is rejected rather than clipped back to the turn
+ * before; `before` has no such problem, since it cuts ahead of the turn's input.
+ */
+export declare function turnCut(journal: Journal, threadId: string, anchor: Seq | RowRef, before: boolean): RowRef;
+/**
+ * Every `turn/end` along a thread's lineage that a fork can be cut at, and every replacement recorded
+ * between turns, oldest first, with the thread that owns each. A turn that ended with a call
+ * unanswered, or with an answer still owed its stop checks, is left out. A replacement recorded
+ * inside a turn is not listed: its turn's ending follows it. One pass: the two folds are replayed
+ * along the lineage as they go.
+ */
+export declare function forkPoints(journal: Journal, threadId: string): ForkPoint[];
+/**
+ * The `llm/request` that produced the reply recorded at `row`: the request with the same
+ * `llm_call_id`, searched on the thread that owns the reply. `null` for a row that is not a reply.
+ */
+export declare function requestBehind(journal: Journal, row: RowRef): RowRef | null;
+/**
+ * The request behind the conversation's latest reply — the one whose tool calls a step is
+ * answering, and so the row a tool that forks this thread cuts at. `null` before any reply. A
+ * stand-in in the assistant role is not a reply: no request is behind it.
+ */
+export declare function latestReplyRequest(journal: Journal, threadId: string): RowRef | null;
+/**
+ * The row of the conversation's latest reply: the `assistant/message` whose tool calls a step is
+ * answering, on a fork's source when the fork inherited it. `null` before any reply.
+ */
+export declare function latestReply(journal: Journal, threadId: string): RowRef | null;

package/dist/loop/holds.d.ts

@@ -0,0 +1,104 @@
+import type { Seq } from '../models/index.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import { type ReadonlyJsonValue } from '../util/json.js';
+import type { RequestsState } from './requests.js';
+/**
+ * Why a pending request does not run now. Every one is derived from recorded facts and live
+ * registrations, never stored:
+ *
+ * - `approval`: the thread's last turn ended blocked and a confirmation waits on it or under it;
+ *   the answer releases it.
+ * - `failure`: the latest settlement failed and no releasing cause is pending.
+ * - `cancellation`: a person cancelled the thread, and no releasing cause came after.
+ * - `startup`: the startup policy declined the request at boot; a releasing cause releases it.
+ * - `missing`: a constraint owner the thread or a thread above it by origin requires is not
+ *   registered, or its repair has not finished; or the callers above it cannot be read.
+ * - `wait`: a call of the thread waits on a dependency whose owner has not resolved it; only its
+ *   resolution, or a cancel that answers the call, ends it. `deadline` is the owner's to act on.
+ * - `constraint`: a registered owner's constraint says not now, with the `code` and `data` it
+ *   answered with; core stamps the `owner`.
+ * - `rejudge`: the judgment of the answer's stop checks was invalidated until the repair budget ran
+ *   out; the answer stays owed its checks, and a releasing cause releases it.
+ * - `shutdown`: lagent is closing; the request stays pending for the next start.
+ */
+export type Hold = {
+    readonly reason: 'missing';
+} | {
+    readonly reason: 'wait';
+    readonly callSeq: Seq;
+    readonly owner: string;
+    readonly ownerRegistered: boolean;
+    readonly deadline: number | null;
+    readonly text: string;
+} | {
+    readonly reason: 'constraint';
+    readonly owner: string;
+    readonly code?: string;
+    readonly data?: ReadonlyJsonValue;
+    readonly text: string;
+} | {
+    readonly reason: 'rejudge';
+    readonly text: string;
+} | {
+    readonly reason: 'approval' | 'failure' | 'cancellation' | 'startup' | 'shutdown';
+};
+/** The reasons a hold can be read for while lagent runs: every one but `shutdown`. */
+export type HoldReason = Exclude<Hold['reason'], 'shutdown'>;
+/** The holds the folds and the catalog derive: those that neither a constraint nor a closing lagent made. */
+export type DerivedHold = Exclude<Hold, {
+    readonly reason: 'constraint' | 'shutdown';
+}>;
+/**
+ * Which look a hold was read from: `catalog`, the screening the catalog shows without loading the
+ * thread, or `loaded`, decided from the thread's folds.
+ */
+export type HoldBasis = 'catalog' | 'loaded';
+/** Whether two holds say the same thing. */
+export declare const sameHold: (a: Hold, b: Hold) => boolean;
+/** What a hold says in words, for a reader that prints one: its text, or `null` when its reason says it all. */
+export declare const holdText: (hold: Hold) => string | null;
+/**
+ * What holds are derived from, read from the thread's folds or from its catalog entry, which record
+ * the same facts, and from the owner's registrations.
+ */
+export type HoldFacts = {
+    /** Whether the thread's last turn ended blocked and a confirmation waits on it or on a thread created under it. */
+    readonly approval: boolean;
+    /** Whether the latest settlement failed and no releasing cause is pending (`failureHeld`). */
+    readonly failed: boolean;
+    /** Whether a person's cancel holds the thread (`cancelHeld`). */
+    readonly cancelled: boolean;
+    /**
+     * Whether the startup policy declined this request and no releasing cause landed since boot: the
+     * owner's to say, since a releasing cause recorded before the restart is one the policy judged.
+     */
+    readonly startupDeclined: boolean;
+    /**
+     * The constraint owners the thread or a thread above it by origin requires that are not registered,
+     * or not repaired yet, with why; or that the callers above it cannot be read.
+     */
+    readonly missing: readonly string[];
+    /**
+     * The thread's first wait that has not resolved, if any: its call, why it waits, its owner and
+     * deadline, and whether that owner is registered now.
+     */
+    readonly unresolvedWait: {
+        readonly callSeq: Seq;
+        readonly reason: string;
+        readonly owner: string;
+        readonly deadlineAt: number | null;
+        readonly registered: boolean;
+    } | null;
+};
+/**
+ * The holds on a thread's pending request, in the order a decision reads them: the one rule both
+ * the folds' decision and the owner's catalog reading apply. A request that holds a releasing cause
+ * is past the failure, cancellation and startup holds; the approval hold yields only to the answer
+ * itself, and the wait hold to the resolution. A constraint's own `hold` is not derived here: the
+ * decision reads its verdict.
+ */
+export declare function deriveHolds(facts: HoldFacts): DerivedHold[];
+/** Whether a failure holds the thread: its latest settlement failed and no releasing cause is pending. */
+export declare function failureHeld(requests: ReadonlyState<RequestsState>): boolean;
+/** Whether a person's cancel holds the thread: its latest `user` cancel has no releasing cause after it. */
+export declare function cancelHeld(requests: ReadonlyState<RequestsState>): boolean;