@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/plugins/delegations/service.d.ts

@@ -0,0 +1,563 @@
+import { Service, type Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { InvocationContext, WaitRequest } from '../../loop/index.js';
+import type { ThreadSummary } from '../../records/journal.js';
+import type { ToolResultPayloadInput } from '../../records/toolResult.js';
+import type { AppendEntry, PluginJournal } from '../../journal/index.js';
+import type { ToolReply } from '../../services/tools.js';
+import { type StopOptions, type StopOutcome } from './cleanup.js';
+import { type TaskRef, type TaskState } from './record.js';
+import { type AdmissionRefused, type AssignmentOwner, type DelegationRequest, type AssignmentOwnerHandle } from './request.js';
+import { type TaskStanding } from './standing.js';
+declare module '@leuduan/cordis' {
+    interface Context {
+        /** Every delegation: the tasks children are given, their drives, waits and stops (optional plugin). */
+        delegations: DelegationsService;
+    }
+}
+export declare const DelegationsConfigSchema: z.ZodObject<{
+    maxOpenTasks: z.ZodNumber;
+    clock: z.ZodCustom<import("../../util/timers.js").Clock, import("../../util/timers.js").Clock>;
+}, z.core.$strict>;
+export type DelegationsConfig = z.input<typeof DelegationsConfigSchema>;
+/**
+ * One thread's latest task, as `tasks()` reads it from the catalog: the thread and the thread that
+ * gave it the task, then the task, or why its state cannot be read.
+ */
+export type TaskEntry = {
+    readonly childId: string;
+    readonly callerId: string;
+} & ({
+    readonly taskId: string;
+    readonly background: boolean;
+    /** Whether its caller is owed a notice once it completes or fails. */
+    readonly notice: boolean;
+    readonly state: TaskState;
+    /**
+     * Open, and an approval under it waits: asked by the child, by a descendant it waits on through
+     * blocking tasks, or, while the child is parked, through any of its open tasks.
+     */
+    readonly blocked: boolean;
+    readonly cleanupPending: boolean;
+    readonly firstLine: string;
+    /** Settled, while the run that served it still drains input accepted before it settled. */
+    readonly draining: boolean;
+} | {
+    readonly state: 'unavailable';
+    readonly error: string;
+});
+/** Which threads' tasks `tasks()` lists: those under a thread, its own excluded, or those it created. */
+export type TaskFilter = {
+    readonly under: string;
+} | {
+    readonly callerThreadId: string;
+};
+/** What `read_agent` asks of its named tasks: how long to wait at most, and for what. */
+export type ReadRequest = {
+    readonly tasks: readonly TaskRef[];
+    /** `settled` returns once any named task settles; `activity` also once any named child records anything. */
+    readonly until: 'settled' | 'activity';
+    /** The longest the read waits; zero reads at once. */
+    readonly waitSeconds: number;
+};
+/**
+ * What a read returns: each named task as it stands; when nothing can advance a named open task,
+ * why each stands still (`noProgress`); and when the caller's chain kept the read from waiting, a
+ * note saying so.
+ */
+export type ReadOutcome = {
+    readonly tasks: readonly TaskStanding[];
+    readonly noProgress: readonly string[] | null;
+    readonly note: string | null;
+};
+/**
+ * Every delegation, from the call that opens a task to the stop that ends one: the one way a tool
+ * delegates (`delegate`), the one way an owner's assignment does (`registerOwner`), both through
+ * one admission, the task constraint core runs every delegated child under, the one read
+ * (`read`), the one stop, and the catalog read of the tasks under a thread (`tasks`). A task is
+ * recorded on its child (`record.ts`) and its state is the child's catalog contribution, so every
+ * question about it is a catalog read.
+ *
+ * Every start, a call's or an owner's, takes one of its origin root's `maxOpenTasks` slots before
+ * anything is created, and its opening write queues the child's input with the assignment's cause,
+ * so core's owner runs the child once the task constraint (`evaluate`) allows. An owner's task runs
+ * on its live owner's say, with no call, receipt or wait, and owes no notice. A blocking call suspends on a
+ * durable wait (`waitFor`) that this service resolves with the task's answer; a background call
+ * returns a receipt and `read_agent` waits the same way. The waits, slots and constraint are
+ * described in `docs/records/delegation.md`. A call's task ends no later than its opening call's result, unless
+ * that result is its receipt:
+ * the service watches `tool/result` rows, and one citing a task's opening call ends the task if it
+ * is still open, however core answered the call, a deny, an unregistered tool, an aborted turn or a
+ * cancel of the waiting caller included. The constraint's repair, before anything runs at startup,
+ * mends what a crash left: stops whose cleanup is pending, tasks whose calls were answered, stop
+ * obligations, owed notices, and waits satisfied while the process was down.
+ *
+ * A stop and its cleanup over the stopped thread's subtree have their own owner (`cleanup.ts`); so
+ * has the notice that tells a caller a background task completed or failed (`notices.ts`). This
+ * service decides when each is asked for. A steer (`steer`) queues a correction into a task only for
+ * the next step of a run serving its child, never into an owner's. A call from a caller whose chain
+ * of unattended work is at core's limit (`ctx.threads.chain`) is refused, blocking or background.
+ *
+ * The ordering it keeps beside its owners': the result listener asks for the stop of a task whose
+ * call was answered synchronously, inside the write that answered it, so the stop's write lands
+ * before any work the caller's later writes start; and shutdown joins the calls in flight, then the
+ * stops and cleanups, while the journal still takes their rows.
+ */
+export declare class DelegationsService extends Service<DelegationsConfig> {
+    static inject: string[];
+    readonly config: z.output<typeof DelegationsConfigSchema>;
+    /** Resolves once the contribution refresh registration queued has completed: nothing is served before. */
+    private readonly ready;
+    private refreshed;
+    private obligationsRefreshed;
+    /** Task slots taken by calls whose `started` row is not durable yet, by task id. */
+    private readonly reservations;
+    /**
+     * Tasks whose opening call runs in this process and has no result yet, from before the write that
+     * opens the task: a background task's authority until its receipt is durable, and a blocking
+     * task's until its call's wait is declared, which the caller's catalog then shows.
+     */
+    private readonly openingCalls;
+    /**
+     * Opening calls' results by task id, as far as this process has read them: a receipt, or the result
+     * that answered the call otherwise while its task was open. Built for a caller by its repair, the
+     * one scan of its rows (`indexCaller`), and kept by the result listener from then on. Only what
+     * the task's eligibility needs: an entry lives while its task is the child's latest and open or
+     * draining (the only states that read it), or while its state cannot be read, and goes with the
+     * child's next task row or run settlement (`evictOpening`); a result that arrives for a task
+     * that is not eligible is not kept (`rememberOpening`).
+     */
+    private readonly openingResults;
+    /** Callers whose rows were read into `openingResults` in this process. */
+    private readonly indexedCallers;
+    /** Stop obligations being carried out, by id: each is carried out once at a time. */
+    private readonly carrying;
+    /** Every stop and its subtree cleanup (`cleanup.ts`), handed the drives on a thread. */
+    private readonly cleanup;
+    /** Every notice's delivery and withdrawal (`notices.ts`). */
+    private readonly notices;
+    /**
+     * Starts in flight, delegating calls and owners' starts alike, by their caller, which shutdown
+     * lets finish before it drains.
+     */
+    private readonly starts;
+    /**
+     * Owners' admissions in flight by task id, with what they start: an identical start joins the one
+     * in flight; a different one waits for it, then replays or conflicts with what it wrote.
+     */
+    private readonly admitting;
+    /** The live registration of each owner of assignment-origin tasks, by its name. */
+    private readonly owners;
+    /** Owners' tasks whose settling their owner was told of in this process. */
+    private readonly settledTold;
+    /** The task constraint's registration with the owner, through which the wait resolver resolves delegation waits. */
+    private constraint;
+    /** Every delegation wait, from its declaration to its call's answer, and when and with what it resolves (`waitResolver.ts`). */
+    private readonly waits;
+    private closing;
+    constructor(ctx: Context, config: DelegationsConfig);
+    [Service.init](): Promise<void>;
+    /**
+     * Runs one delegating call: the one way a tool delegates, adapting the call into the one admission
+     * every task opens through, with the call as its authority. In order: a call dispatched again with
+     * its resolved wait returns the answer recorded there; a continued child is checked to be one this
+     * thread created; a task this call already opened is waited for, or its recorded answer or receipt
+     * returned, before anything else is decided; otherwise the route is checked, a new role child
+     * refused if its role names a tool that is not registered, a start refused at the chain limit, a
+     * task slot taken, and the task opened by one write that queues its input with its `started` row
+     * and the request's own `rows`, creating the child on its target or continuing it. Then a blocking
+     * call suspends on the task (`waitFor`), and a background call returns its receipt. Never throws: a
+     * failure becomes an error reply. A reply about a child that exists names its `thread_id`; a
+     * refusal before one exists names none.
+     */
+    delegate(context: InvocationContext, request: DelegationRequest): Promise<ToolReply>;
+    /** Keeps `start` among the starts in flight until it settles, for shutdown to join. */
+    private track;
+    /**
+     * Registers an owner of assignment-origin tasks: the one way an owner's assignment opens a task
+     * on a child and is let run, through the same admission, slots and checks as a call. Its
+     * `authorize` is asked inside every write that opens one of its tasks and whenever core asks
+     * whether such a task may run; a task whose owner has no live registration is held. Its
+     * `settled` is told when one of its tasks settles. One live registration per name; disposing the
+     * handle withdraws it, refusing its starts still in flight inside their writes.
+     */
+    registerOwner(owner: AssignmentOwner): AssignmentOwnerHandle;
+    /** Asks core to evaluate again every child whose latest task `owner` assigned. */
+    private ownerChanged;
+    /**
+     * An owner's start, adapted into the one admission with its registration as the authority: the
+     * task and child ids derive from the request, so a repeat finds what it opened. Refused (`hold`)
+     * once the registration is withdrawn or shutdown has begun; a start already in flight then is
+     * joined by shutdown.
+     */
+    private startAssignment;
+    /** Task `task.taskId` as its child records it, for the owner that assigned it; `null` when that owner assigned no such task. */
+    private outcome;
+    /**
+     * The latest task of each thread the filter names, from the catalog, in spawn order. `under` names every thread created under
+     * that one at any depth, and never that one itself, unlike `ctx.threads.list({ under })`: its own
+     * task is its caller's to read. `callerThreadId` names the threads that one created. A thread with
+     * no task is not listed. An older task than a thread's latest has settled, and is read from its
+     * child's rows.
+     */
+    tasks(filter: TaskFilter): TaskEntry[];
+    /**
+     * The tasks a stop of everything under `threadId` stops: those open, still draining a late turn
+     * after they settled, or still being cleaned up after a stop. A task whose state cannot be read is
+     * not one, since what to stop of it is unknown.
+     */
+    stopTargets(threadId: string): TaskRef[];
+    /**
+     * The rows of a stop obligation over everything under the thread a `cancel` is written on, for
+     * that cancel's `rows`: its targets, `stopTargets` read inside the write, and from that write no
+     * target, nothing under one, and no call of the run the cancel cuts short opens new work. The
+     * service then stops each target, and acknowledges the obligation once they are all quiet; one a
+     * crash left outstanding is carried out again by the next startup's repair. No rows when
+     * there is nothing to stop.
+     */
+    stopObligationRows(reason: string): (threadId: string) => AppendEntry<'ext'>[];
+    /**
+     * Carries out again every stop obligation still outstanding on `threadId`, resuming each target's
+     * cleanup, as the startup repair does: what a host that composed one into a cancel asks for when
+     * it retries that stop, since an obligation whose targets were not yet quiet when it was carried
+     * out stays outstanding until something drives it again. Resolves once the stops have landed; the
+     * acknowledgement follows once every target is quiet.
+     */
+    retryStops(threadId: string): Promise<void>;
+    /**
+     * `read_agent`'s read of tasks the calling thread started: where each stands now, or a durable
+     * wait for the first of these: a named task ended (`settled`); with `activity`, a named child
+     * recorded anything; nothing can advance a named open task (`no_progress`, saying why each stands
+     * still); the deadline. It reads at once with no wait asked, when one of them holds already, or
+     * when the caller's chain is at core's limit, since each resolution would open another reactive
+     * turn. Dispatched again with its resolved wait, it reads the tasks it named. A read that finds a
+     * background task ended returns once the notice its settle queued, or an owed one a crash left
+     * unsent, is durable on its caller.
+     */
+    read(context: InvocationContext, request: ReadRequest): Promise<ReadOutcome | WaitRequest>;
+    /** What a read returns of `tasks`, once the notices of those that ended are durable. */
+    private readOutcome;
+    /**
+     * The startup repair of everything delegations owns, the task constraint's: before any thread
+     * runs, every stop whose cleanup a crash left pending is resumed, every task whose call was
+     * answered other than by its receipt is ended, the opening results of every caller with an open
+     * task are indexed, every stop obligation still outstanding is carried out, every notice owed
+     * and unsent is queued, and every delegation wait is tracked again, resolved now when what it
+     * waits on happened while the process was down. Resolves once those decisions and writes have
+     * landed, not once a cleanup's walk has ended. What cannot be read or written is reported and the
+     * rest goes on.
+     */
+    private repair;
+    /**
+     * The repair of what delegations owns at and under `under`, without running anything: resumes
+     * every stop whose cleanup is pending there, and walks once more under a stopped task this
+     * process has not seen quiet; ends every task whose call was answered other than by its receipt;
+     * carries out `under`'s stop obligations; queues every notice owed and unsent. At startup over
+     * every root, and again as a caller is admitted, since a cleanup acknowledged before it covered
+     * the subtree can have left work beneath. Resolves once those writes have landed.
+     */
+    private repairUnder;
+    /**
+     * Stops a task for good: one write on its child appends `stopped` if the task is still open, and
+     * resolves once that is durable; a settled task is left as it settled, and its outcome reported.
+     * A run of the child still serving the task is cancelled either way. When the child's latest task is stopped, by
+     * this call or before, its cleanup then quiets the child and every thread under it, and writes
+     * `stop_cleaned` bottom-up; nobody awaits that, a later stop of the same thread joins it, and a
+     * stop of a task whose cleanup a crash left pending resumes it, with no run.
+     */
+    stop(taskId: string, options: StopOptions): Promise<StopOutcome>;
+    /**
+     * One `message_agent` steer: queues `message` into task `taskId` of `childId`, the task the call
+     * addresses, for the next step of the run that holds the child, and returns at once; `null` when
+     * the call addresses no task. Plugin-facing, as `delegate` is. The steer's input id derives from
+     * the call, so a re-dispatch first reports what became of a steer the child already knows, and
+     * decides nothing live. One write decides, inside it, that the task is open and that a run of the
+     * child takes the input at its next step, and refuses otherwise, naming the outcome or the state.
+     * Nothing waits for a run to start: a child whose run is only requested, or still being
+     * prepared for admission, is refused, since the caller's own run slot may be what it waits for. A
+     * steer never opens a task or asks for a run, and never reaches a child an owner's assignment
+     * created: only its owner gives it work.
+     */
+    steer(context: InvocationContext, request: {
+        readonly childId: string;
+        readonly taskId: string | null;
+        readonly message: string;
+    }): Promise<ToolResultPayloadInput>;
+    /**
+     * The steer's check, run inside the `send` that queues it, with the inbox target decided: the
+     * addressed task is open, which also means its input is queued or claimed, since a discarded one
+     * settles it; and the input joins the next step of the run serving the child. A `next-turn`
+     * target, which no run takes now, is refused.
+     */
+    private steerRows;
+    /** Why no run of an open task's child takes a steer now, and what its caller can do. */
+    private notRunning;
+    /** `delegate`'s call path: the tool invocation adapted into `admit`, and the call answered from what it decided. */
+    private runCall;
+    /**
+     * A recorded background task's call hands it to the owner again, which runs it once the task
+     * constraint allows: while the call runs here, which stands in for its receipt until that is
+     * durable, and after.
+     */
+    private handOff;
+    /** The tool the call at `callSeq` named, from its loaded `tool/call` row; `null` when it cannot be read. */
+    private toolNameOf;
+    /**
+     * The one admission and opening of a task, whatever its authority; each outcome is typed by what
+     * the starter does next (`Admission`), a cancelled start's a `discard`, checked last inside its
+     * write. An
+     * owner's start identical to one in flight for the same task joins it, so concurrent starts of
+     * one assignment coalesce; a different one waits for it to finish, then replays or conflicts with
+     * what it wrote. A call is dispatched once at a time, and its re-dispatch replays.
+     */
+    private admit;
+    /**
+     * One admission. An owner's start whose registration was withdrawn is held. A start whose task
+     * its child already records replays it (`replay`): nothing is judged again and no slot is taken.
+     * Otherwise its authority decides how the child is reached (`callReach`, `ownerReach`), a call is
+     * refused at its caller's chain limit, one of the origin tree's slots is taken (`reserveSlot`), an
+     * existing child's last task's notice is queued or found no longer owed, and one write (`open`)
+     * creates or continues the child.
+     */
+    private admitOnce;
+    /**
+     * A start finding its task recorded: replayed, taking no slot and reopening nothing, when the
+     * recorded origin is the start's own, and for an owner's, its task input and its child's pinned
+     * configuration too; a conflict otherwise, never adopted. A call's replay compares its origin
+     * alone: the effect the call recorded decides, whatever its arguments would decide now.
+     */
+    private replay;
+    /**
+     * How a call reaches its child, or why it does not: a start's child must not exist yet; a new child
+     * is born on the call's fields folded over the route of the turn making the call, resolved here
+     * once, a fork on the route at its cut, which must run; a continued child's change is checked here
+     * and decided by the write that makes it, against the route it reads then. A new role child is
+     * refused if its role names a tool that is not registered.
+     */
+    private callReach;
+    /**
+     * Why what an owner pinned cannot be bound now, or `null`: its route's provider cannot run, a
+     * preset it installs or the global agent it names is not registered. A binding that comes back
+     * lets the same start through, so each is a `hold`, never a refusal.
+     */
+    private unbound;
+    /**
+     * How an owner's start reaches its participant's child, or why it does not, with no caller route
+     * and no chain limit: its assignment's turns are fresh. Its pinned route must run now, else it is
+     * held. A child that does not exist is created on exactly the pinned configuration; one that
+     * exists is continued only when it is this owner's conversation for this generation under this
+     * caller, born exactly so (`birthConflicts`): anything else is a conflict. A pin whose installations
+     * are not all defining and named is refused before either.
+     */
+    private ownerReach;
+    /** What an owner's child is born with: its pin, under delegations' own constraint owner. */
+    private pinnedSpec;
+    /**
+     * Why `childId` was not born as `configuration` pins it, or `null` when it was: its agent, that it
+     * is not a fork, and the birth fields core names. The recorded origin is the caller's to check.
+     */
+    private birthConflicts;
+    /** Task `taskId` as `childId` records it, read while the child is loaded, with its `started` row; `null` when it records none. */
+    private recordedTask;
+    /**
+     * Opens the task: one write queues its input with its `started` row, the assignment's cause and
+     * the start's own rows, creating the child with `create`, or continuing it with `send`, a call's
+     * fields its route statement. Every check runs inside that write (`admissionCheck`, then for an
+     * owner's start its live owner's `authorize`), then the start's rows; any of them vetoing leaves
+     * nothing, and the admission says which refused and why. A write that found the task already
+     * written, by another start meanwhile, replays it.
+     */
+    private open;
+    /**
+     * The one creation of a call's child, by its target: on a global agent; on a role, recorded as
+     * the child's defining installation of the `role` preset; or a fork of the calling thread cut at
+     * the request that produced the call. A replayed start never gets here: it finds the task it
+     * opened first, whatever its target has become.
+     */
+    private createChild;
+    /**
+     * An owner's recheck inside the write that opens its task, `null` for a call's start: its
+     * registration is still live, what its pin names is still registered (`unbound`), and its
+     * `authorize` allows the assignment, typed as it says otherwise. Its starts still in flight when it is withdrawn are held here.
+     */
+    private ownerCheck;
+    /** An owner's task as its owner judges it, from the origin it records or will record. */
+    private assignmentTask;
+    /**
+     * The checks of the write that opens a task, run inside it, `null` when the task may open, else
+     * the admission refused: no thread above the caller is being stopped (`discard`) or unreadable
+     * (`hold`); no stop obligation covers the start (`discard`); a delegated caller's own task is
+     * still open; and a child that exists can take another task ({@link continuation}). A new child
+     * has no folds yet, so its creation reads the caller and the catalog only.
+     */
+    private admissionCheck;
+    /**
+     * Whether `threadId`, a thread that exists, can take another task now, as the write that would open
+     * one decides it (`admissionCheck`): `null` when it can; a `refusal`, durable for this thread, when
+     * it is not one delegations manages, a person's cancel holds it, it stopped mid-work, or something
+     * it or a thread under it started has an unknown end; a `wait` on the predecessor while its own task
+     * is open or being cleaned up after, a stop's walk holds it, an earlier run of it is still pending
+     * or a command is still ending; a `hold` while its task state cannot be read. What an owner reads,
+     * before asking for a continuation, to know whether its participant's conversation can be continued
+     * or must be replaced. Reads the thread's folds: the caller holds it loaded.
+     */
+    continuation(threadId: string): AdmissionRefused | null;
+    /**
+     * Why nothing may start or be driven under `threadId`: it has a stop still being cleaned up after,
+     * or a thread above it has, or a thread above it has its latest task stopped, cleaned up after or
+     * not, since nothing under a stopped task is anyone's to run, whatever a cleanup acknowledged
+     * before it covered the subtree, or a thread above it has a task state that cannot be read.
+     */
+    private stoppedAbove;
+    /**
+     * Why a stop obligation keeps a task that the row at `seq` of `callerId` opens from opening, or
+     * `null`: the caller is a target of an obligation outstanding on its origin root, or under one; or
+     * the caller is that root and the row (a call, or the row granting an assignment) came before the
+     * obligation, in the run it cancelled. A call a later message brings opens independently.
+     */
+    private obligationOver;
+    /** Whether `obligation` names `threadId`, or a thread above it. */
+    private covers;
+    /** Whether a stop obligation outstanding on `childId`'s origin root names it, or a thread above it. */
+    private obligated;
+    /**
+     * Takes one of the task slots of the caller's origin root for a task until its `started` row is
+     * durable, or says why none is free: a `wait` on capacity, never queued, so a tree of tasks
+     * waiting on each other cannot deadlock on capacity; one pool, whatever a task's authority. Each origin tree has its own `maxOpenTasks`, so conversations
+     * in one journal never take each other's. Decided synchronously, so parallel calls in one step are
+     * admitted up to the limit exactly. Fails closed: while a task state under the root cannot be
+     * read, or the root cannot be found, how many slots are in use is unknown, and nothing new is
+     * admitted (a `hold`).
+     */
+    private reserveSlot;
+    /**
+     * Every task holding a slot of the origin tree under `rootId`, blocking or background: one
+     * reserved by a call whose `started` row is not durable yet; an open one, blocked ones included; a
+     * settled one whose run still drains; and a stopped one whose cleanup is pending, since its old
+     * work may still run. Also the threads under it whose task state cannot be read, whose slots are
+     * unknown. A task belongs to the tree its caller is in.
+     */
+    private slotHolders;
+    /** The latest task of each thread among `summaries` that has one, as `tasks()` lists it. */
+    private entriesOf;
+    /**
+     * The task constraint's verdict on a delegated child's pending run, read synchronously from the
+     * catalog and this process: the task predicate (`constraint.ts`) over the child's latest task,
+     * under the authority its origin records: a call's, where its opening call stands; an owner's
+     * assignment's, its live owner's verdict (`ownerVerdict`). Every child takes a start slot of its own.
+     */
+    private evaluate;
+    /**
+     * Whether an owner's task may run, by its live owner: its `authorize` in `running`, anything but
+     * `allow` a hold; held too while no owner is registered under the name its origin records, or
+     * when the owner cannot judge it, which is reported.
+     */
+    private ownerVerdict;
+    /** What answered the task's opening call, as far as the index knows. */
+    private openingOf;
+    /**
+     * Whether the opening result of `taskId` can still be read: the task is `childId`'s latest and open
+     * or draining, or its state cannot be read, so nothing says it is not.
+     */
+    private openingNeeded;
+    /** Keeps `result` for `taskId`, which any of `childIds` may hold, unless none of them still reads it. */
+    private rememberOpening;
+    /** Drops `childId`'s results its rows made unneeded: its task ended, was succeeded, or its run settled. */
+    private evictOpening;
+    /**
+     * The repair half of the index: reads the loaded caller's rows from its oldest open task's call,
+     * once per process, recording each open task's receipt or other result. Rows written after it
+     * reach the index through the result listener.
+     */
+    private indexCaller;
+    /** The child whose latest task is `taskId`, from the catalog. */
+    private childHolding;
+    /**
+     * The child holding an older task, whose rows record it: one of its caller's children, for a
+     * call's task; for any other, one of the children an owner's assignment created, a persistent
+     * participant's earlier tasks included.
+     */
+    private findChild;
+    /**
+     * Carries out a stop obligation of `threadId`, once at a time: stops each target as the host, which
+     * aborts its drive and starts or joins the walk over its subtree, then acknowledges it. Each stop's
+     * write is queued before this returns. Resolves once the stops are durable; the acknowledgement
+     * follows, unawaited.
+     */
+    private carryOut;
+    /**
+     * Writes `stop_completed` once every target is quiet: its drive ended and the walk over its subtree
+     * finished with its stop acknowledged. A target left being cleaned up after, by a walk that failed,
+     * leaves the obligation outstanding for the next `resume` over the thread.
+     */
+    private acknowledgeObligation;
+    /** Resolves once the run that served `task`, if still pending, is held or settled. */
+    private runStopped;
+    /**
+     * Hands every row to the wait resolver, a turn's end and a receipt to the notice owner, and ends a task whose opening call was
+     * answered other than by its receipt. The stop is asked for here, synchronously, and the cleanup
+     * owner queues its write before returning, so it lands before anything the caller writes after its
+     * result.
+     */
+    private onRow;
+    /**
+     * A person's cancel of an owner's child: the task fold stopped its task from the cancel row itself
+     * (`delegationTasks`), its cleanup pending. Here, in the cancel's listener, that cleanup starts,
+     * through the one stop, which finds the task stopped and writes nothing; a crash before it leaves
+     * the cleanup pending, which repair resumes (`StopCleanup.resume`). A call's task is held for its
+     * caller instead.
+     */
+    private personCancelled;
+    /**
+     * Tells the owner of `threadId`'s latest task that it settled, once in this process, when it was
+     * an owner's assignment that has: the owner reads its outcome, a stop through `stop_agent` or a
+     * host's included, which its own scheduling would otherwise never learn of.
+     */
+    private tellSettled;
+    /**
+     * The children that may hold the task the call at `callSeq` opened, still open or settled with its
+     * run still draining (a cancel answered the call waiting on that run), matched by the call, never by its provider's id: a start tool's child, named after the call; or, only for a `message_agent` call, read from the loaded
+     * caller, the caller's child whose latest task it is, or, when none reads so, every child whose
+     * task state cannot be read, which the stop's own write then checks. A result of any other tool
+     * costs one catalog lookup.
+     */
+    private childrenHolding;
+    private onRunEvent;
+    /**
+     * One caller's repair at startup: indexes its opening calls' results with one scan of its rows,
+     * and ends every task whose call has a result other than its receipt, what a crash between a
+     * result and its stop left behind. Resolves once the stops it wrote landed.
+     */
+    private reconcile;
+    /**
+     * The caller's children's open tasks, and settled ones whose run still drains, by the call that
+     * opened each, from the catalog or their rows: those a result of their opening call ends.
+     */
+    private openTasksOf;
+    /**
+     * A child's latest task from its own rows, while it is open or settled with the run serving it
+     * still pending, draining; `null` otherwise.
+     */
+    private openTaskOf;
+    /**
+     * Stops the wait resolver deciding and lets each decision under way land; lets each call in flight,
+     * opening its task, be answered on its aborted turn, so a result other than its receipt or its
+     * wait stops its task, and each owner's start in flight finish, a new one being refused; then
+     * waits for the stops and their cleanups while the journal still takes their rows. Tasks whose calls wait durably stay open, as
+     * background tasks do, their runs pending for the next startup, which decides by its policy. What
+     * it cannot finish waits for the next startup's repair.
+     */
+    private shutdown;
+}
+/**
+ * The latest task of each of `summaries`' threads, read without loading any (`readTask`), in their order:
+ * what `tasks()` lists, readable whether or not the service is mounted. A thread with no task is
+ * not listed; one delegations governs whose task state the catalog lacks is `unavailable`.
+ */
+export declare function taskEntries(journal: PluginJournal, summaries: readonly ThreadSummary[]): TaskEntry[];
+/**
+ * Every task under `threadId` at any depth, never its own, from the catalog alone: `tasks({ under })`,
+ * the read a quiescence or cleanup check makes before it certifies the thread quiet, whether or not
+ * the service is mounted, so a task it cannot read is never taken for none.
+ */
+export declare function tasksUnder(journal: PluginJournal, threadId: string): TaskEntry[];

package/dist/plugins/delegations/standing.d.ts

@@ -0,0 +1,19 @@
+import type { Context } from '@leuduan/cordis';
+import { type TaskRef, type TaskState } from './record.js';
+import { type DelegationOutcome } from './request.js';
+/** Where one task stands when a wait returns, and once it settled, what its caller is told. */
+export type TaskStanding = TaskRef & {
+    readonly state: TaskState | 'unavailable';
+    readonly outcome: DelegationOutcome | null;
+};
+/** A named task's state from the catalog: a task that is not its child's latest has settled. */
+export declare function taskState(ctx: Context, task: TaskRef): TaskState | 'unavailable' | 'superseded';
+/** The named tasks that are not open, with their state. */
+export declare function endedTasks(ctx: Context, tasks: readonly TaskRef[]): {
+    task: TaskRef;
+    state: "superseded" | "unavailable" | TaskState;
+}[];
+/** Where a task stands as a read returns it, with what its caller is told once it settled. */
+export declare function taskStanding(ctx: Context, task: TaskRef, state: TaskState | 'unavailable' | 'superseded'): Promise<TaskStanding>;
+/** Why a task's child is not running, for a caller told that nothing advances it. */
+export declare function whyStill(ctx: Context, task: TaskRef): string;

package/dist/plugins/delegations/stopCheck.d.ts

@@ -0,0 +1,21 @@
+import type { Context } from '@leuduan/cordis';
+import type { DelegationsService } from './service.js';
+/**
+ * The sub-agent-waits rule: a delegated thread cannot answer while tasks it started are open, and
+ * what it leaves open when its turn settles is stopped, since its caller cannot see those tasks and
+ * may never follow up.
+ *
+ * A settled background task whose notice is still owed, unspent and unclaimed counts as open, so a
+ * child that settles just before the check sends the caller round once to read its notice.
+ *
+ * The check sends the model back at once, naming the open tasks, and never waits: waiting and
+ * any-of belong to `read_agent`. A child whose task state cannot be read rejects
+ * the answer with the error. The backstop stops the thread's open tasks at every turn ending that
+ * would settle a task (`settlingEnding`), and at a failed run with no successor, since after either
+ * its caller may never follow up on what it started; any other ending keeps them, since the next
+ * admission drives them again. It keys off the
+ * ending, not off the thread's own task: the task fold ignores endings before its input is claimed.
+ * A thread delegations does not manage (a root, or one made by hand), which no caller waits on,
+ * keeps its tasks across its answers.
+ */
+export declare function waitForOwnTasks(ctx: Context, service: DelegationsService): void;