@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/state/continuation.d.ts

@@ -0,0 +1,167 @@
+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 './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`;
+ * 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/state/decide.d.ts

@@ -0,0 +1,72 @@
+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.
+ *
+ * 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;
+/**
+ * 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/state/forks.d.ts

@@ -0,0 +1,61 @@
+import type { Journal } from '../journal/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
+ * 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/state/holds.d.ts

@@ -0,0 +1,104 @@
+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';
+/**
+ * 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;