@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/services/threads/runOwner.d.ts

@@ -0,0 +1,368 @@
+import type { Seq, ThreadSummary } from '../../records/journal.js';
+import type { JsonValue } from '../../util/json.js';
+import type { ReadonlyJsonValue } from '../../util/json.js';
+import { type Continuation, type ConstraintAnswer, type DecisionTurn, type Hold, type HoldBasis, type TurnLimits, type WaitDeclaration } from '../../state/index.js';
+import type { Journal, OriginBreak } from '../../journal/index.js';
+import type { Admission, AdmittedOperation, OperationKind } from './admission.js';
+import { type RunEvent, type RunState } from './runEvents.js';
+/**
+ * Which run requests pending at boot `start` runs, judged by the age of each request's newest
+ * cause: every one, none, or those newer than `newerThanMs`. The rest are held (`startup`) until a
+ * releasing cause.
+ */
+export type StartupPolicy = 'all' | 'none' | {
+    readonly newerThanMs: number;
+};
+export type StartOptions = {
+    readonly resume: StartupPolicy;
+    /** How many runs execute at once; the rest wait in memory, in order, for one to end. */
+    readonly startLimit: number;
+};
+/**
+ * A feature's registration as an owner: its say over when the threads it applies to run, and its
+ * part in startup. `owner` is the
+ * name a thread's `requires` lists; such a thread, and every thread created under it by origin, is
+ * held `missing` while no registration under it is ready. What a thread records in `requires` stays
+ * its own: a constraint's `applies` reads it, and only readiness passes down. `repair` runs at
+ * `start`, awaited before the startup policy classifies what is pending, so the causes it writes are
+ * judged with the rest; registered once started, it runs at once, and its causes are admitted like
+ * any later one. The owner's threads stay `missing` until it resolves, held with its error if it
+ * rejects; a rejection is reported and never fails `start`.
+ * `constraint`'s `applies` and `evaluate` are synchronous; a throw is a hold on that thread with the
+ * error as its reason. A registration with no `constraint` constrains no thread: one carrying only a
+ * `repair` is a startup participant, such as a feature firing the work that fell due while the
+ * process was down, or the owner of waits, whose repair resolves what was satisfied while the
+ * process was down.
+ *
+ * The registration is also what a call's wait names (`waitFor`'s `owner`): a call may declare one
+ * only while a registration under that owner is live, and only its handle resolves it.
+ */
+export type OwnerRegistration = {
+    readonly owner: string;
+    /** Which threads the registration governs, and what it says of each; none when omitted. */
+    readonly constraint?: {
+        applies(summary: ThreadSummary): boolean;
+        /** What it says about a thread it applies to. */
+        evaluate(threadId: string): ConstraintAnswer;
+    };
+    repair?(): Promise<void>;
+};
+/**
+ * What `build` resolves a wait with: its `value`, a JSON object the owner versions and the waiting
+ * tool reads; the `chain` of the turn it asks for, `person` for a person's answer and `reactive`
+ * otherwise; and the rows the resolution cites as `evidence` beside the declaration.
+ */
+export type WaitValue = {
+    readonly value: {
+        readonly [key: string]: JsonValue;
+    };
+    readonly chain?: 'person';
+    readonly evidence?: readonly Seq[];
+};
+/**
+ * What `resolveWait` did: `resolved`; `declined` when `build` returned `null`; `resolved-before`
+ * with the value recorded first, which an answer-once check reports; `closed` when the call was
+ * answered without a value (cancelled, denied, aborted); `unknown` when no wait is declared for the
+ * call (yet), or one is, under another owner.
+ */
+export type WaitResolution = {
+    readonly status: 'resolved';
+} | {
+    readonly status: 'declined';
+} | {
+    readonly status: 'resolved-before';
+    readonly value: {
+        readonly [key: string]: ReadonlyJsonValue;
+    };
+} | {
+    readonly status: 'closed';
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * An owner registration's handle: `changed` asks for the thread to be evaluated again; `dispose` withdraws
+ * it. `resolveWait` resolves a wait a call of `threadId` declared under this registration's owner,
+ * in one write on that thread: `build`, run inside it with the declaration, gives the value, and the
+ * write records it with an inputless cause that releases nothing, so the call is dispatched again
+ * once nothing else holds the thread. Racing resolutions serialize: the first wins. A disposed
+ * handle refuses it.
+ */
+export type OwnerHandle = {
+    changed(threadId: string): void;
+    resolveWait(wait: {
+        readonly threadId: string;
+        readonly callSeq: Seq;
+    }, build: (declaration: WaitDeclaration) => WaitValue | null): Promise<WaitResolution>;
+    dispose(): void;
+};
+/**
+ * A constraint owner a thread's run needs that is not ready: `absent` when no registration serves
+ * it, `repairing` until its repair finishes, `failed` with why when that repair failed.
+ * `introducedBy` is the threads that require it: the thread itself, or callers above it.
+ */
+export type OwnerReadiness = {
+    readonly owner: string;
+    readonly state: 'absent' | 'repairing' | {
+        readonly failed: string;
+    };
+    readonly introducedBy: readonly string[];
+};
+/** What stands behind a `missing` hold: the owners not ready, and whether the callers above it could be read. */
+export type MissingDetail = {
+    readonly owners: readonly OwnerReadiness[];
+    readonly chain: 'complete' | OriginBreak;
+};
+/**
+ * Where a thread stands, from `threads.inspect`: `idle` with no run pending; `requested` while its
+ * pending run waits to be admitted, a failed attempt to prepare it included, which backs off before
+ * the next; `running` while an execution serves it; `held` with `hold`. `operation` names an
+ * exclusive operation other than a run holding the thread now. `missing` says what is behind a
+ * `missing` hold and is `null` for any other. `approvalBlocked` is a screening read from the
+ * catalog whatever the state: the thread's last turn ended blocked and a confirmation waits on it
+ * or on a thread created under it. The run's actual hold (`approval`) is decided from the thread's
+ * folds, which can pass an answer the screening still counts. `basis` is the look it was computed on.
+ */
+export type ThreadInspection = {
+    readonly state: 'idle' | 'requested' | 'running' | 'held';
+    readonly operation: Exclude<OperationKind, 'run'> | null;
+    readonly hold: Hold | null;
+    readonly missing: MissingDetail | null;
+    readonly approvalBlocked: boolean;
+    readonly basis: HoldBasis;
+};
+/**
+ * One execution of a run request, the owner's record of it from admission to the publication of
+ * where the run stands: what its finalization settles the run by, and the decision it asks as it
+ * goes. `execute` records on it as it decides; the finalization and the publication read it.
+ */
+export type RunExecution = {
+    readonly runId: string;
+    /**
+     * The journal's head as the execution was admitted; a recovered ending's execution's, when the run
+     * settles from that ending.
+     */
+    attemptCutoff: Seq;
+    /** The last continuation decision: what the finalization settles by, unless a cancel captured it. */
+    final: Continuation | null;
+    /** Why the run failed in setup, for its settlement. */
+    errorText: string | null;
+    /**
+     * The continuation decision for the run, for the cancel that captured the operation serving it:
+     * asked at the execution's entry, after every turn and when an abort ends it.
+     */
+    readonly decide: (turn: DecisionTurn) => Continuation;
+};
+/** What the owner needs of the threads service. */
+export type OwnerHost = {
+    readonly journal: Journal;
+    readonly admission: Admission;
+    /** Aborts once lagent is closing. */
+    readonly signal: AbortSignal;
+    /**
+     * The execution of `run` under its admitted `operation`: the entry decision, the turns it opens
+     * and the decision after the last, recorded on `run`. A failure before it opens a turn is its
+     * setup's, which settles the run failed and resolves; only a failure past its setup rejects.
+     */
+    execute(run: RunExecution, operation: AdmittedOperation): Promise<void>;
+    /**
+     * The operation's cleanup, still under its admission: releases the activation a failed or stale
+     * setup left, which could not be released while the operation held the thread.
+     */
+    cleanup(operation: AdmittedOperation): Promise<void> | undefined;
+    /** Loads what an execution of the thread reads and keeps it held, under the application's retention policy. */
+    retain(threadId: string): Promise<{
+        release(): void;
+    }>;
+    report(error: unknown): void;
+};
+/**
+ * The one owner of when threads run: it admits a thread's pending run request once nothing holds
+ * it, runs the request's envelope (the execution through the threads service, its finalization
+ * under the same admission) and publishes each run's state. It makes every continuation decision,
+ * from the folds and the registered constraints. Nothing is admitted before `start`. A committed
+ * write, an operation settling or a constraint's `changed` re-evaluates the threads it touches,
+ * coalesced on a microtask, reading the catalog first and loading a thread only when it may be
+ * eligible; the decision is made again, authoritatively and with nothing awaited before admission,
+ * once the thread is loaded. A thread that failed to load backs off before the next try.
+ */
+export declare class RunOwner {
+    private started;
+    private starting;
+    private limit;
+    /** Runs executing that count against the limit. */
+    private counted;
+    /** Threads the startup policy declined, until a releasing cause lands on them. */
+    private readonly startupDeclined;
+    private readonly owners;
+    /** The serial the next registration gets. */
+    private nextSerial;
+    private readonly dirty;
+    private scheduled;
+    /** Threads being loaded for admission. */
+    private readonly admitting;
+    /** Every admission from its entry to the end of its cleanup, which shutdown waits for. */
+    private readonly preparations;
+    /** The execution serving each executing thread's run. */
+    private readonly executing;
+    /** Threads waiting for a slot under the limit, in order. */
+    private readonly waiting;
+    /** The hold last decided for each thread's pending run, which its state reads and its events say. */
+    private readonly holds;
+    private readonly listeners;
+    /** The threads whose pending run failed to be prepared for admission, and their backoff. */
+    private readonly preparation;
+    private readonly host;
+    private readonly limits;
+    constructor(host: OwnerHost, limits: TurnLimits);
+    /** Starts admitting; see `Threads.start`. */
+    start(options: StartOptions): Promise<void>;
+    registerOwner(registration: OwnerRegistration): OwnerHandle;
+    private repair;
+    /**
+     * Decides again every thread requiring `owner`, itself or through a thread above it by origin, or
+     * with a call waiting on it, resolved or not, whose registration or repair changed: a resolved call
+     * waiting to be dispatched again is not stranded. A change worth a new look does not wait out a
+     * preparation's backoff.
+     */
+    private scheduleRequiring;
+    /** Whether a registration under `owner` is live now. */
+    isRegistered(owner: string): boolean;
+    /** `OwnerHandle.resolveWait` for a live registration under `owner`. */
+    private resolveWait;
+    /**
+     * Re-evaluates the thread a row landed on, and the threads above it, whose holds can read it. A
+     * releasing cause re-authorizes the subtree the startup policy declined under the thread: each
+     * thread in it is decided again, which never overrides a person's stop of a child, a cancellation
+     * hold or a stopped task, neither of which is the startup decline. A releasing cause on the
+     * thread, and the release of a descendant's decline, forget a preparation's backoff: a person
+     * asked, or what held the thread is gone. Any other row waits it out.
+     */
+    onRow(threadId: string, row: {
+        readonly type: string;
+        readonly data: unknown;
+    }): void;
+    /**
+     * An operation on the thread settled, published as it released the thread: a run an execution
+     * served is held or settled to its waiters from this moment; and the thread is looked at again.
+     */
+    onSettled(threadId: string, kind: OperationKind): void;
+    /** Resolves once every admission begun has finished, its cleanup included; none begins once closing. */
+    whenIdle(): Promise<void>;
+    /** Tells every waiter on a pending run that lagent is closing. */
+    close(): void;
+    onRunEvent(listener: (event: RunEvent) => void): () => void;
+    runState(threadId: string, runId: string): RunState | null;
+    /**
+     * Where the thread stands, `null` for a thread the catalog does not hold. Admits nothing, changes
+     * no backoff and publishes nothing. On the `loaded` basis the thread and the callers above it must
+     * be loaded, and the hold is decided from their folds; otherwise it throws.
+     */
+    inspect(threadId: string, basis: HoldBasis): ThreadInspection | null;
+    /** The `loaded` basis needs what a run reads: the thread and every caller above it, in memory. */
+    private requireLoaded;
+    /**
+     * The hold admission would record for the thread's pending run now: the entry continuation
+     * decision, from the folds, that `admit` asks. A decision that advances, repairs or settles the
+     * run is no hold; none either while the run is being admitted.
+     */
+    private loadedHold;
+    /**
+     * Whether the thread's last turn ended blocked and a confirmation waits on it or under it: the
+     * one rule of the approval screening, from the catalog, which `inspect` reports and the owner's
+     * look at a pending run applies. It scans the thread's subtree only for a blocked ending.
+     */
+    private approvalBlocked;
+    /**
+     * Where the idle pending run `runId` stands, the one rule `runState` and `inspect` read: the hold
+     * decided for it; none while it is being loaded to be admitted, or is about to be decided whatever
+     * the catalog holds (obsolete, or captured by a cancel a crash left unsettled); otherwise the hold
+     * the catalog shows, then the constraint's, as `consider` would record them; or none, requested.
+     */
+    private idleHold;
+    /** Whether the startup policy declined the thread's pending run, and nothing released it since. */
+    private declined;
+    /**
+     * The constraint owners the thread's run needs that are not registered and repaired, with why: what
+     * its own `requires` names and what every thread above it by origin requires, read from the
+     * catalog. Only readiness is inherited, never a caller's holds or what its constraints say. A
+     * caller chain that stops short of its root, at a caller the catalog does not hold or a cycle,
+     * cannot say what is required, and holds the thread.
+     */
+    private missing;
+    /** The owners `missing` counts, not ready, with the threads that require each, and the chain read. */
+    private missingDetail;
+    /**
+     * The registrations the thread's run needs, as one token: every owner its own `requires` names
+     * or a thread above it by origin requires, each with the registration serving it. Equal tokens
+     * mean the same registrations, all ready; `null` while one is missing. What a judged turn ending
+     * is fenced on (`LoopServices.requiredRegistrations`): a registration that left or was replaced
+     * during the judgment may be a checker that did not judge the answer.
+     */
+    requiredRegistrations(threadId: string): string | null;
+    /**
+     * What the registered constraints that apply to the thread say, combined, a hold stamped with the
+     * owner that gave it; `allow` with none.
+     */
+    private verdict;
+    /**
+     * The continuation decision for the thread's pending run, from its folds and catalog as they
+     * stand: how the last turn ended (`ending`, opened at `start`), the holds derived on it, what the
+     * registered constraints say, and the cancel that captured the execution (`cancel`), or that a
+     * crash left recorded against the run. The one place a run's next step is decided: before
+     * admitting it, at an execution's entry, after each turn and as it lets go.
+     */
+    private decide;
+    /** The decision for the thread's pending run as no execution serves it, from where its last turn stands. */
+    private entryDecision;
+    /** The holds on the thread's pending request, derived from its folds as `deriveHolds` orders them. */
+    private derivedHolds;
+    private schedule;
+    /** From the catalog: leaves the thread, holds it, queues it for a slot, or loads it to admit it. */
+    private consider;
+    /**
+     * The first hold the catalog alone shows, by the order the folds' decision reads them
+     * (`deriveHolds`), or `null` when the thread may be eligible.
+     */
+    private catalogHold;
+    /**
+     * Loads what the thread's run reads, decides again from the folds, and admits the pending run
+     * with nothing awaited between that decision and the admission; then serves it, finalizes it
+     * under its admission and, once the execution has let the thread go, publishes where the run
+     * stands and looks at the thread again. The reads stay held until all of that is done.
+     */
+    private admit;
+    /**
+     * An execution's finalization, under its admission: settles the run as its last decision said,
+     * in one write with the successor request its residual causes open. The settlement is built
+     * inside the write, which is the irrevocable boundary: a cancel that captured the execution before
+     * then settles it by the cancel's intent, whatever was decided, a hold included; after, what was
+     * built stands, and a cancel that captures it later has admission finalize it again, which settles
+     * a run the build left pending. A run settled meanwhile, or left pending (a hold, a shutdown),
+     * writes nothing.
+     */
+    private finalize;
+    /**
+     * Records a failed preparation of the thread's pending run and looks at the thread again once its
+     * backoff is due, from half a second to a minute, so a store that fails to read is neither given
+     * up on nor hammered. Until then `consider` admits nothing: no row retries it, but the causes
+     * listed at `forgetPreparation`'s callers.
+     */
+    private retryLater;
+    /** Forgets the thread's preparation failures and its pending retry: the next look may admit it at once. */
+    private forgetPreparation;
+    /** Publishes where a run stands once its execution let the thread go. */
+    private afterExecution;
+    /**
+     * Records a hold, and publishes it unless it is the one already published (`always` publishes it
+     * again). Published as read from the folds (`loaded`) when it stands as decided or `basis` says
+     * so, from the catalog otherwise.
+     */
+    private hold;
+    /** Forgets a decided hold of `reason` on the thread, so the next look decides again. */
+    private forgetDecided;
+    /** Starts what waits for a slot, in order, while slots are free. */
+    private drain;
+    private durable;
+    private publishState;
+    private publish;
+}