@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/services/owner.d.ts

@@ -0,0 +1,367 @@
+import type { JsonValue, Seq, ThreadSummary } from '../models/index.js';
+import type { ReadonlyJsonValue } from '../util/json.js';
+import { type Continuation, type ConstraintAnswer, type DecisionTurn, type Hold, type HoldBasis, type TurnLimits, type WaitDeclaration } from '../loop/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;
+}

package/dist/services/preset.d.ts

@@ -0,0 +1,154 @@
+import { type Context, type Fiber, type Inject, type Plugin } from '@leuduan/cordis';
+import type { z } from 'zod';
+import type { InstallationLifetime } from '../models/index.js';
+import { type JsonValue } from '../util/json.js';
+import { type AgentSelector } from '../kit/scope.js';
+import type { Thread } from './thread.js';
+/** What a preset's setup is told when it is mounted as one thread's recorded installation. */
+export type PresetInstallation = {
+    readonly kind: 'installation';
+    readonly thread: Thread;
+    readonly installationId: string;
+    /**
+     * `defining` when the thread's spawn row recorded it so (`create`'s `installations`, or a
+     * hand-down), on this thread or on the one a fork inherited it from, and it can never be removed;
+     * `configurable` otherwise. Read from the record.
+     */
+    readonly lifetime: InstallationLifetime;
+    /**
+     * Aborts when this run of `setup` is unloaded, before its cleanups: when the thread's activation
+     * is released, which every application or removal on the thread does, when the application shuts
+     * down, and when an injected service goes away once `setup` has returned, after which `setup` runs
+     * again with a new signal. A `setup` still pending when a service goes away is not interrupted:
+     * it is unloaded, and run again, once it returns. A setup that rejects with the reason it was
+     * aborted with, or with an error whose `cause` is that reason, as Node's abortable APIs do, is not
+     * a failure, since the installation is going away; any other error is reported.
+     */
+    readonly signal: AbortSignal;
+};
+/**
+ * What a preset's setup is told when a root mount for an agent selector runs it on a thread whose
+ * agent it selects: the thread, never recorded. A selected setup hands nothing down: a hand-down
+ * belongs to a thread's recorded installation, so a setup that hands down checks its place first.
+ */
+export type PresetSelection = {
+    readonly kind: 'selected';
+    readonly thread: Thread;
+    /**
+     * Aborts when this run of `setup` is unloaded, before its cleanups: when the activation goes,
+     * when the root mount is disposed, and when an injected service goes away. A setup that rejects
+     * with the reason it was aborted with is not a failure, as for an installation.
+     */
+    readonly signal: AbortSignal;
+};
+/**
+ * Where a setup runs: a thread's installation, or a thread a root mount for an agent selector chose.
+ * Every setup runs in its thread's scope, where the agent it equips is `[place.thread.agentName]`.
+ * A preset mounted from a setup is told the same place, with a signal that also aborts when that
+ * setup is unloaded.
+ *
+ * A setup still pending is not interrupted by its own unload: cordis defers a `dispose`, `update`
+ * or `restart` until the setup returns, and only then aborts its signal and runs its cleanups. So a
+ * setup that waits for its signal ends only on an abort from outside: the activation going, or an
+ * enclosing setup that has returned being unloaded.
+ */
+export type PresetPlace = PresetInstallation | PresetSelection;
+/**
+ * Where a preset may be placed. `thread`: applied to one thread at any time, or mounted on the root
+ * for an agent selector, once per installation or selected activation, so only for members safe to mount many times
+ * (agents with scoped names, tools, grants, prompt contributions and listeners; no services,
+ * installers or nested scopes). `creation`: recorded only with a thread's spawn row as a defining
+ * installation, never mounted or applied later, and never removable.
+ */
+export type PresetPlacement = 'thread' | 'creation';
+/**
+ * A preset: a named, configurable set of plugins, as plain data and a `setup`. `mountPreset`
+ * mounts it directly, and the presets service mounts it as a thread's recorded installation;
+ * declare it with `definePreset`, which checks it.
+ */
+export type Preset<Schema extends z.ZodType = z.ZodType> = {
+    /**
+     * What a thread's installation records and is restored by. Give the preset a new id (convention:
+     * a `#N` suffix, `codex#2`) when the configuration it records changes shape or meaning, so an
+     * old installation is refused as an unknown preset; behaviour and prompt changes keep the id.
+     */
+    readonly id: string;
+    /**
+     * JSON in and JSON out: validate strictly (`z.strictObject`), apply defaults, and leave runtime
+     * transformations to `setup`. The parsed result is what a thread records, and restoring parses it
+     * again, so it must parse back to itself. An omitted configuration parses as `{}`, so give fields
+     * defaults rather than the schema a top-level `.default()`.
+     */
+    readonly schema: Schema;
+    readonly placement: PresetPlacement;
+    /**
+     * For a creation preset that defines the agent its thread runs on: the agent name its
+     * configuration defines. A creation checks it against the thread's agent before anything is
+     * recorded. Refused on any other placement, where nothing would check it.
+     */
+    readonly definesAgent?: (config: z.output<Schema>) => string;
+    /** The services `setup` uses directly, as for any plugin; members declare their own. */
+    readonly inject?: Inject;
+    /**
+     * Mounts the preset's members through `ctx`, in the scope of the thread `place` names: one
+     * thread's recorded installation, or a thread a root mount for an agent selector chose. A preset
+     * mounted from another's setup is told that one's place.
+     */
+    setup(ctx: Context, config: z.output<Schema>, place: PresetPlace): void | Promise<void>;
+};
+/** A preset whatever its schema, where presets of every schema are kept or passed through. */
+export type AnyPreset = Preset<any>;
+/** Checks `preset`, which is otherwise used as it is given. */
+export declare function definePreset<Schema extends z.ZodType>(preset: Preset<Schema>): Preset<Schema>;
+/** Where a mount places a preset. */
+export type PresetMountOptions = {
+    /**
+     * Runs the setup in the scope of each activation whose agent this selects, from then on;
+     * disposing the mount disposes it on live threads too. Required on the untagged application
+     * context, and refused anywhere else.
+     */
+    readonly agents?: AgentSelector;
+};
+/** Optional exactly when the schema accepts an empty object, which is what an omitted one parses as. */
+type MountArguments<Schema extends z.ZodType> = {} extends z.input<Schema> ? [config?: z.input<Schema>, options?: PresetMountOptions] : [config: z.input<Schema>, options?: PresetMountOptions];
+/**
+ * Mounts `preset` with `config`, validated by its schema. With `agents`, on the root for those
+ * agents: the setup runs in each selected activation's scope, told the thread (`PresetSelection`),
+ * the one way to put a per-thread capability on every thread of some agents. Without, from another
+ * preset's setup, beside its members: told that setup's place, it serves the same thread for as long
+ * as that setup runs. Refused anywhere else, since a setup always serves one thread. Nothing is
+ * recorded either way; a thread keeps a preset across reopening and forks only through
+ * `thread.configure`. A creation preset cannot be mounted. Resolves like `ctx.plugin`, and fails the
+ * same way when the configuration is refused or the setup throws.
+ */
+export declare function mountPreset<Schema extends z.ZodType>(ctx: Context, preset: Preset<Schema>, ...[config, options]: MountArguments<Schema>): Fiber & PromiseLike<Fiber>;
+declare const kInstalled: unique symbol;
+/**
+ * How the presets service mounts a thread's installation through {@link presetPlugin}: the recorded
+ * configuration with the installation, under a key no caller's configuration carries, so a direct
+ * mount's configuration stays the caller's own, `fiber.update()` included.
+ */
+export declare const installedMount: (config: JsonValue, installation: Omit<PresetInstallation, "kind">) => {
+    [kInstalled]: {
+        config: z.core.util.JSONType;
+        installation: Omit<PresetInstallation, "kind">;
+    };
+};
+/**
+ * The one plugin that mounts `preset`, as a thread's installation, for a selected thread, or from
+ * another preset's setup: one per preset, named after it, injecting what its setup declares.
+ */
+export declare function presetPlugin(preset: AnyPreset): Plugin.Object<unknown>;
+/**
+ * Validates `input` with the preset's schema, defaults applied, and returns the result as frozen
+ * JSON: the value both a direct mount and a thread installation hand to `setup`, and the one a
+ * thread records. Throws when the schema rejects the input or its result is not JSON.
+ */
+export declare function parsePresetConfig(preset: AnyPreset, input: unknown): JsonValue;
+/**
+ * Throws `message` unless `config`, a configuration the schema produced, parses back to itself: all
+ * that restoring a recorded installation relies on. Checked before recording, so a schema that
+ * transforms its output fails when applied rather than every time the thread reopens.
+ */
+export declare function assertRereadable(preset: AnyPreset, config: JsonValue, message: string): void;
+export {};

package/dist/services/presets.d.ts

@@ -0,0 +1,139 @@
+import { Service, type Context, type ScopeKey } from '@leuduan/cordis';
+import type { InitialInstallation, Installation, InstallationLifetime } from '../models/index.js';
+import { type AnyPreset } from './preset.js';
+import type { Thread } from './thread.js';
+/**
+ * An installation a caller asks for, at creation (as an {@link InitialInstallationInput}) or later
+ * (`Thread.configure`).
+ */
+export type InstallationInput = {
+    readonly presetId: string;
+    readonly config?: unknown;
+    /**
+     * Unique within the change or the creation; generated when omitted. Given, it makes a retried
+     * application idempotent. A removed id is never accepted again.
+     */
+    readonly installationId?: string;
+};
+/**
+ * An installation a thread is created with (`create`'s `installations`), with how long it lasts:
+ * `defining` ones are never removed, `configurable` ones are installations like any applied later.
+ * A creation preset is only ever `defining`.
+ */
+export type InitialInstallationInput = InstallationInput & {
+    readonly lifetime: InstallationLifetime;
+};
+/**
+ * An installation a thread's scope hands down to every thread a call there creates; see
+ * {@link handDown}. The id is required: it is what keeps a hand-down from colliding with another in
+ * its layer or with the child's own installations.
+ */
+export type HandDown = {
+    readonly presetId: string;
+    readonly config?: unknown;
+    readonly installationId: string;
+};
+/** What a configuration change records, decided against the thread's installations as they stand. */
+export type ConfigurationPlan = {
+    readonly rows: readonly ({
+        type: 'installation/applied';
+        data: Installation;
+        options: {
+            threadId: string;
+        };
+    } | {
+        type: 'installation/removed';
+        data: {
+            installation_id: string;
+        };
+        options: {
+            threadId: string;
+        };
+    })[];
+    /** Every installation the change applies, an earlier application of the same id included. */
+    readonly applied: readonly string[];
+    /** The installations it takes off; an id not installed is none. */
+    readonly removed: readonly string[];
+};
+/**
+ * What a preset installation means: the registry of presets a thread can install, how an
+ * installation is validated, an agent-defining one against its thread's agent included, which
+ * installations a thread's scope hands down to the children its calls create, and how a thread's
+ * recorded installations are mounted when it activates. A core service: the thread owner
+ * orchestrates creation, configuration and activation, and hands this service the thread, the scope
+ * or the state each question is about. Registrations do not survive a reload.
+ */
+export declare class PresetsService extends Service {
+    static inject: string[];
+    private readonly registry;
+    /** Each thread scope's hand-downs, in declaration order; the global layer stays empty. */
+    private readonly handDowns;
+    constructor(ctx: Context);
+    /** Makes `preset` installable on threads; returns the unregister function. */
+    register(preset: AnyPreset): () => void;
+    /** Whether a preset is registered under `presetId`. */
+    has(presetId: string): boolean;
+    /**
+     * The installations `entries` record, validated before anything is appended: a registered
+     * preset whose placement allows the use, a configuration its schema accepts and parses back to
+     * itself, and ids unique among them. At a creation on `agentName`, a preset that defines its
+     * thread's agent must define that one. Reads no thread state, so it fails only on a composition
+     * bug.
+     */
+    installationsFor(entries: readonly InstallationInput[], use: 'creation' | 'change', agentName?: string): Installation[];
+    /**
+     * The installations a creation on `agentName` records, each with its lifetime: validated as
+     * {@link installationsFor} validates a creation's, and a creation preset refused unless it is
+     * `defining`, since it can never be applied again once removed.
+     */
+    initialInstallations(entries: readonly InitialInstallationInput[], agentName: string): InitialInstallation[];
+    /**
+     * What a change records on `threadId`, decided against its installations as they stand:
+     * removals first, then applications, each id once. Removing an id not installed is no change; a
+     * defining installation is never removed. An application whose id is already this very
+     * installation, compared after defaults, is no change, which makes a retry idempotent; one whose
+     * id names another installation, or a removed one, is refused. The owner calls this before
+     * admitting the change and again inside its write.
+     */
+    plan(threadId: string, apply: readonly Installation[], remove: readonly string[]): ConfigurationPlan;
+    /**
+     * Declares in `scope` that every thread a call there creates is born with `handDown` installed,
+     * as a defining installation; returns the withdraw function. Use {@link handDown}, which ties it
+     * to the declaring plugin. Refused in the global layer, where it would reach the children of every
+     * conversation; for a preset that is not registered, since a child restores it from the registry
+     * whether or not its parent is live; for a configuration its preset would not record; and for an
+     * installation id already handed down in the same layer, so no rule has to choose between two
+     * declarations.
+     */
+    handDown(scope: ScopeKey | undefined, handDown: HandDown): () => void;
+    /**
+     * The installations a new thread on `agentName` is born with because the scope of the call
+     * creating it hands them down, each defining: from the closest layer out, each in declaration
+     * order, a closer declaration winning an id. Validated as the creation's own installations are,
+     * and refused when an id is also one of those: two owners for one installation is a composition
+     * bug, not something to resolve.
+     */
+    handedDown(scope: ScopeKey, threadId: string, agentName: string, own: readonly Installation[]): InitialInstallation[];
+    /**
+     * Mounts every recorded installation of `thread`, one at a time in recorded order so that
+     * registration order is stable across reopening; the owner calls it once the activation's
+     * listeners have settled, so installations follow the listeners' own plugins. Any failure fails
+     * the activation, which a run turns into a rejection with the input kept.
+     */
+    restore(thread: Thread): Promise<void>;
+    private requireRegistered;
+    /**
+     * Whether `installation`'s id is already this very installation. Throws when the id names a
+     * different installation, or one that was removed.
+     */
+    private alreadyApplied;
+}
+/** Makes `preset` installable on threads for the lifetime of the calling plugin. */
+export declare const registerPreset: (ctx: Context, preset: AnyPreset) => (() => void | Promise<void>);
+/**
+ * Hands `handDown` down, for the lifetime of the calling plugin, from the thread scope it is
+ * mounted in to every new thread a call there creates: each child is born with it as a defining
+ * installation, recorded with its spawn row. See {@link PresetsService.handDown} for what is
+ * refused. Looks the service up, so a caller need not inject it.
+ */
+export declare function handDown(ctx: Context, handDown: HandDown): () => void | Promise<void>;