@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/services/extensionEvents.d.ts

@@ -0,0 +1,181 @@
+import type { Context } from '@leuduan/cordis';
+import type { z } from 'zod';
+import type { AppendOptions, PluginJournal, PluginProjection } from '../journal/index.js';
+import type { ContentPartInput } from '../llm/content.js';
+import { type ModelStep } from '../loop/index.js';
+import { type RowRef } from '../state/index.js';
+import { type AgentSelector } from './agents.js';
+import type { ExtensionRecord, InputRole, JournalEvent, Seq, StepContribution } from '../records/journal.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import type { DeepReadonly } from '../util/json.js';
+export declare class ExtensionVersionError extends Error {
+    readonly record: ExtensionRecord;
+    readonly supportedVersion: number;
+    constructor(record: ExtensionRecord, supportedVersion: number);
+}
+/**
+ * One plugin-owned event schema. A row of another version is refused with
+ * {@link ExtensionVersionError}: the journal is not migrated, and neither are a plugin's rows.
+ *
+ * `policyState` says a `lagent/tool/authorize` listener decides from these rows: one that lands
+ * while a call is authorized sends the decision round again. Rows of an event that does not say so
+ * never do, so diagnostics and notices cost an authorization nothing.
+ */
+export declare function defineExtensionEvent<Schema extends z.ZodType>(definition: {
+    plugin: string;
+    instanceId?: string;
+    kind: string;
+    version: number;
+    schema: Schema;
+    policyState?: boolean;
+}): {
+    /** A validated record carrying `value`: what an `ext` row holds, and a contribution's `source`. */
+    record: (value: z.input<Schema>) => ExtensionRecord;
+    /** `value` validated as this event's payload, its defaults applied. */
+    parse: (value: z.input<Schema>) => z.output<Schema>;
+    /** A validated row for an atomic `journal.appendAll` batch; every row names its thread. */
+    entry: (value: z.input<Schema>, options: AppendOptions) => {
+        type: "ext";
+        data: {
+            plugin: string;
+            instance_id: string;
+            kind: string;
+            version: number;
+            data: z.core.util.JSONType;
+        };
+        options: AppendOptions;
+    };
+    /** Appends one row carrying `value`; resolves once it is durable. */
+    append(journal: PluginJournal, value: z.input<Schema>, options: AppendOptions): Promise<JournalEvent<"ext">>;
+    read(event: JournalEvent): z.output<Schema> | undefined;
+    /** A validated `lagent/llm/step` contribution whose `source` is this event carrying `value`. */
+    contribution(message: {
+        role?: InputRole;
+        content: string | readonly ContentPartInput[];
+    }, value: z.input<Schema>, options?: {
+        sourceSeqs?: readonly Seq[];
+    }): StepContribution;
+    /** Whether `record` — a contribution's or a rejection's `source` — is one of this event's. */
+    matchesSource(record: DeepReadonly<ExtensionRecord>): boolean;
+    /** A `lagent/turn/stop` rejection whose `source` is this event carrying `value`. */
+    rejection(reason: string, value: z.input<Schema>): {
+        decision: "reject";
+        reason: string;
+        source: ExtensionRecord;
+    };
+    /** The value a contributed `input/message` carries, when this event is its source. */
+    readContribution: (event: JournalEvent) => z.output<Schema> | undefined;
+    /**
+     * The value `source` carries — a queued input's or a contribution's — when it is one of this
+     * event's; `undefined` for any other. Another version is refused, as for a row.
+     */
+    readSource: (source: DeepReadonly<ExtensionRecord> | null) => z.output<Schema> | undefined;
+    /**
+     * What a thread was told through this event's contributions: every notice row, with the value
+     * it carried and whether it is still on the thread's surface. Read it with {@link latestNotice}
+     * and {@link latestVisible}.
+     *
+     * A thread was told something only while the notice is on its surface. A `surface/replaced`
+     * row that cites a notice row clears that row's visibility, for good; nothing else does. So a
+     * plugin that tells a thread a fact compares it with what the model can still see, and tells it
+     * again once a replacement took it away, with no scan of the surface at any step. Thread-scoped
+     * and inherited: a fork, and `stateAt`, see what was visible at their row of the lineage.
+     */
+    told: PluginProjection<ToldNotices<z.output<Schema>>>;
+    /**
+     * Unrelated events are ignored. Failure makes this projection unavailable, not the journal.
+     *
+     * A fork inherits a thread-scoped state by default; `onFork: 'reset'` starts each fork from
+     * `init()` instead, for state that describes what the source did rather than its conversation.
+     * `apply` also gets the `ext` row that carried the value.
+     */
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: z.output<Schema>, event: JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): PluginProjection<State>;
+};
+/**
+ * One notice a thread was told: the row that told it, the value its `source` carried, and whether
+ * the model can still see it.
+ */
+export type ToldNotice<Value> = {
+    readonly row: RowRef;
+    readonly value: Value;
+    /**
+     * Whether the notice is still on the thread's surface: cleared by the first `surface/replaced`
+     * row that cites it. What was recorded is one fact; whether the model can still see it, another.
+     */
+    readonly visible: boolean;
+};
+/** Every notice of one kind a thread was told, oldest first: the state of an event's `told` fold. */
+export type ToldNotices<Value> = {
+    readonly notices: readonly ToldNotice<Value>[];
+};
+/**
+ * The latest notice told, visible or not; `null` when none was ever told. For recorded text: a
+ * notice whose latest telling is no longer visible is told again from that row, as recorded.
+ */
+export declare function latestNotice<Value>(told: ToldNotices<Value>): ToldNotice<Value> | null;
+/**
+ * What the latest notice the model can still see says; `null` when none is visible. For live facts:
+ * compare the fact as it stands with this, and tell it when they differ, rendered against this
+ * value, as a first telling when it is `null` and as a change from it otherwise.
+ *
+ * Not the latest notice's value: an earlier notice can outlive a later one. A restriction told
+ * early and lifted by a later notice that a replacement took away is still what the model sees, so
+ * the lift has to be told again.
+ */
+export declare function latestVisible<Value>(told: ToldNotices<Value>): Value | null;
+/** What {@link tellOnStep} uses of an event `defineExtensionEvent` declared, `Input` and `Output` its payload's. */
+export type NoticeEvent<Input, Output> = {
+    parse(value: Input): Output;
+    readonly told: PluginProjection<ToldNotices<Output>>;
+    contribution(message: {
+        content: string;
+    }, value: Input): StepContribution;
+};
+/** One fact a thread is told at its model steps; see {@link tellOnStep}. */
+export type StepNotice<Input, Output> = {
+    /** The event each notice is recorded as, whose `told` fold says what the model can still see. */
+    readonly event: NoticeEvent<Input, Output>;
+    /** Whose threads are told; without it, every thread this plugin's listener reaches. */
+    readonly agents?: AgentSelector;
+    /**
+     * Where the notice is recorded among the step's contributions: lower first, equal ranks in
+     * listener order, 0 when omitted. See {@link ModelStep.contribute}.
+     */
+    readonly rank?: number;
+    /** What is true for this step, or `undefined` to tell nothing at it. */
+    current(step: ModelStep): Input | undefined;
+    /**
+     * The notice's text: `value` as a first telling when `told`, the latest notice the model can still
+     * see, is `null`, and as a change from it otherwise; `null` to tell nothing. `notices` is every
+     * notice of the event, for a plugin whose rule needs more than the latest visible one. What was
+     * told is read from the journal's fold, so it is the read-only view of `Output`.
+     */
+    render(value: Output, told: ReadonlyState<Output> | null, at: {
+        readonly step: ModelStep;
+        readonly notices: ToldNotices<ReadonlyState<Output>>;
+    }): string | null;
+};
+/**
+ * Tells a thread a fact as a conversation message at its model steps: at each step already due,
+ * `current` says what is true, and when it differs from the latest notice the model can still see
+ * the step carries the rendered notice, recorded as the event. So a fact is told on the first step,
+ * again when it changes, and again after a replacement took the notice off the surface; several
+ * changes between two steps are one notice, and a change back is none. A plugin whose notice one
+ * plugin's failure must not silence keeps its own event, as every notice does. The event's schema
+ * must give the same value parsed twice, since the notice is recorded from `current` and compared
+ * after it is read back.
+ *
+ * ```ts
+ * tellOnStep(ctx, {
+ *   event: routeNotice,
+ *   current: (step) => step.route,
+ *   render: (route, told) => (told === null ? `You run on ${route.model}.` : `You now run on ${route.model}.`),
+ * })
+ * ```
+ */
+export declare function tellOnStep<Input, Output>(ctx: Context, notice: StepNotice<Input, Output>): void;

package/dist/services/journal.d.ts

@@ -0,0 +1,26 @@
+import type { Context, Plugin } from '@leuduan/cordis';
+import { Journal, type JournalStore } from '../journal/index.js';
+import { type TurnLimits } from '../state/index.js';
+export type JournalConfig = {
+    /** Durable backing. A store that is already open stays caller-owned. */
+    store: JournalStore;
+    /** What a thread's summary asks of the folds: whether a run would find work depends on them. */
+    limits: TurnLimits;
+};
+/**
+ * Opens the one journal this process runs against and provides it as `ctx.journal`.
+ *
+ * The journal takes the store's writer lease before reading: another process may hold this journal.
+ *
+ * Core's one fold, `threadState`, is registered before the journal opens and never removed: it
+ * holds every row before the first write, which `replaceSurface` judges against its surface.
+ * The loop's summary is what the journal writes to the catalog with every group; `journal/` knows
+ * only its shape. A journal that can no longer be written is announced as `lagent/journal/revoked`;
+ * it has already refused every later write, and the host must exit.
+ */
+export declare const journalPlugin: Plugin.Object<JournalConfig>;
+/**
+ * The journal with core's writes, for the engine's own services: the same journal `ctx.journal`
+ * holds, which types it for plugins as one that appends `ext` rows only.
+ */
+export declare const engineJournal: (ctx: Context) => Journal;

package/dist/services/llm.d.ts

@@ -0,0 +1,82 @@
+import { Context, Service } from '@leuduan/cordis';
+import { z } from 'zod';
+import { type ModelCallClient } from '../llm/failure.js';
+import { type LLMProvider, type ModelRoute } from '../llm/provider.js';
+import { type ModelCapacity } from '../llm/client.js';
+import { type ModelSelection } from '../llm/provider.js';
+/**
+ * How `ctx.llm` retries a provider's failed call, required at registration. `maxAttempts` counts the
+ * first request, so `1` retries nothing. The wait before a retry is exponential from `baseDelayMs`
+ * with full jitter, capped at `maxDelayMs`; a wait the provider asked for (`retryAfterMs`) at or below
+ * `maxDelayMs` is the wait, and one above it stops retrying.
+ */
+export declare const RetryPolicySchema: z.ZodObject<{
+    maxAttempts: z.ZodNumber;
+    baseDelayMs: z.ZodNumber;
+    maxDelayMs: z.ZodNumber;
+}, z.core.$strict>;
+export type RetryPolicy = z.input<typeof RetryPolicySchema>;
+/** The service's own registration, reachable only through {@link registerProvider}. */
+declare const register: unique symbol;
+/**
+ * Offers `provider` to route selection and to the agents told about routes, for the life of the
+ * calling fiber, with `retry` the policy its calls are retried by. Register only what should be
+ * offered. Returns the disposer, as `registerAgent` does.
+ */
+export declare const registerProvider: (ctx: Context, provider: LLMProvider, options: {
+    retry: RetryPolicy;
+}) => (() => void | Promise<void>);
+/**
+ * Provider registry, route resolution and client construction.
+ *
+ * One client per provider, built when first asked for and kept until the provider is withdrawn: a
+ * client is asked for on every model call, and rebuilding a transport each time would be waste. The
+ * model and the effort travel on each request, so neither is part of the key. A route's effort is
+ * the route's to resolve (`resolveRoute`, `routeOn`); the client only supplies the provider's own
+ * default when a request carries none.
+ */
+export declare class LlmService extends Service {
+    private readonly providers;
+    private readonly policies;
+    /** By provider name. */
+    private readonly clients;
+    constructor(ctx: Context);
+    get providerNames(): string[];
+    /**
+     * Offers `provider` until the returned disposer runs (see {@link registerProvider}, the one way in).
+     * The disposer withdraws it and its client at once, so a provider registered again under the name
+     * never reaches the old one, and resolves once it is disposed, rejecting with what its cleanup threw.
+     */
+    [register](provider: LLMProvider, retry: z.output<typeof RetryPolicySchema>): () => Promise<void>;
+    /** The provider registered under `name`; throws `RouteUnavailableError` when none is. */
+    provider(name: string): LLMProvider;
+    /** Why `route` cannot run now: its provider is not registered; `null` when it can. */
+    unavailable(route: Pick<ModelRoute, 'provider'>): string | null;
+    /**
+     * `selection` folded over `base`, the route it changes: a named model or effort replaces that
+     * field, and a named different provider takes that provider's defaults for whatever it leaves
+     * unnamed, since a model or an effort means nothing on another provider. Throws
+     * `RouteUnavailableError` when the resulting provider is not registered. Registry lookup only; no
+     * client is built. Resolved once, as the route is written, so a recorded route is always complete.
+     */
+    resolveRoute(selection: ModelSelection, base: ModelRoute): ModelRoute;
+    /**
+     * What the route's provider declares for its model: the usable context window, `null` when it
+     * declares none, whether its requests may carry provider-executed tools, and whether its tool
+     * results may carry images. Registry lookup only; throws when the provider is not registered.
+     */
+    capacity(route: Pick<ModelRoute, 'provider' | 'model'>): ModelCapacity;
+    /**
+     * The client a resolved route's provider sends through, the same for every model and effort: the
+     * provider's own, wrapped so a failed call is retried by its policy and otherwise throws a
+     * `ModelCallError` with its kind and attempt count (see {@link RetryingClient}). The route's effort
+     * is not applied here: a request carries it, or leaves the provider's own default. Throws when its
+     * provider is not registered.
+     */
+    clientFor(route: ModelRoute): ModelCallClient;
+    /** Removes the clients of the providers `owned` names, synchronously. */
+    private detachClients;
+    /** Disposes each provider client, once: the one that owns its transport owns its cleanup. */
+    private disposeClients;
+}
+export {};

package/dist/services/modes.d.ts

@@ -0,0 +1,65 @@
+import type { Context } from '@leuduan/cordis';
+import type { PluginJournal } from '../journal/index.js';
+import type { WriteRows } from '../state/index.js';
+/** One set of durable modes, as {@link defineModes} takes it. */
+export type ModesDefinition<Mode extends string> = {
+    /** Names the modes in the journal, so two sets never mix. */
+    readonly name: string;
+    /**
+     * Where a thread's mode is recorded and read: on the thread itself, or on its origin root
+     * (`Thread.originRoot`), so a delegated thread is in its conversation's mode and switching the
+     * conversation switches every thread it started.
+     */
+    readonly authority: 'thread' | 'conversation';
+    /** The mode before one is recorded. */
+    readonly initial: NoInfer<Mode>;
+    /** Every mode the set has; what each one means belongs to the feature that reads it. */
+    readonly modes: readonly Mode[];
+};
+/**
+ * A set of durable modes: the state a feature reads to decide what a thread may do, and the host's
+ * way to set it. Each read and write takes a context that injects `journal` and `threads`.
+ */
+export type Modes<Mode extends string = string> = ModesDefinition<Mode> & {
+    /** The mode in force on `threadId`: its authority's latest recorded mode, or `initial`. */
+    of(ctx: Context, threadId: string): Mode;
+    /** Records `mode` on `threadId`'s authority, only when it changes it, decided inside the write. */
+    set(ctx: Context, threadId: string, mode: Mode): Promise<void>;
+    /**
+     * The rows that record `mode` in the write that creates or forks a thread (`Opening.rows`),
+     * so the thread never exists in another mode: always one row, `initial` included, so an opening
+     * leaves evidence of the choice (a fork would otherwise go on in the mode it inherits). The mode
+     * is validated here, before anything is written. Refused inside the write, which then records
+     * nothing, anywhere but an opening write, and for a thread with an `origin` under `conversation`
+     * authority, which is in its conversation's mode.
+     */
+    opening(mode: Mode): WriteRows;
+    /**
+     * The thread a mode is recorded on for `threadId`: itself, or for `conversation`, its
+     * `originRoot`. Throws {@link MissingAuthorityError} when that root cannot be found, so no thread
+     * part-way up is taken for it; a thread the catalog does not hold is its own.
+     */
+    authorityOf(ctx: Context, threadId: string): string;
+    /** The mode recorded on `threadId` itself, or `null`: what a catalog contribution computes. */
+    recorded(journal: PluginJournal, threadId: string): Mode | null;
+};
+/** A conversation mode asked for a thread whose caller chain does not reach its origin root. */
+export declare class MissingAuthorityError extends Error {
+    constructor(threadId: string, modes: string);
+}
+/**
+ * Defines a set of durable modes, once per `name` in a process. A mode is an `ext` row on the
+ * authority thread, declared policy state, so a switch while a call is authorized decides it again.
+ * The set owns that state only: what a mode means, and what the model is told about it, belong to
+ * the feature that reads it (see `toolPolicy`).
+ *
+ * ```ts
+ * const permissions = defineModes<'ask' | 'auto'>({
+ *   name: 'app:permission',
+ *   authority: 'conversation',
+ *   initial: 'ask',
+ *   modes: ['ask', 'auto'],
+ * })
+ * ```
+ */
+export declare function defineModes<Mode extends string>(definition: ModesDefinition<Mode>): Modes<Mode>;

package/dist/services/plugins.d.ts

@@ -0,0 +1,34 @@
+import { type Context } from '@leuduan/cordis';
+/**
+ * Claims `key`, a thread by its id or by its activation's scope, for the calling plugin within
+ * `kind`, for as long as the calling plugin's fiber lives: for a behaviour a thread runs at most
+ * once, such as an `AGENTS.md` briefing. `holder` is
+ * how a later refusal names this claim. Throws `refusal(holder)` with the holder of a live claim of
+ * the same kind on the same key, so the plugin that claimed later fails, and with it the
+ * activation, rather than running beside the first. Claims of different kinds never meet.
+ *
+ * Synchronous: the check and the claim are one step, and the claim is an effect of the caller's
+ * fiber, so a release, an unload or a failed setup frees the thread for the next activation.
+ */
+export declare function claimThread(ctx: Context, kind: string, key: unknown, holder: string, refusal: (holder: string) => string): void;
+/**
+ * Runs `drain` before any owner of `ctx` starts its cleanup, and before the journal's owner does:
+ * as an unload guard on every fiber from `ctx` up to the root, and on the fiber that provides the
+ * journal. Guards on one fiber run together before its disposers, so every service draining this
+ * way is signalled before any of them is awaited, and the journal is still writable for their final
+ * rows. `drain` must be idempotent, since several owners can unload, and must not await its own
+ * owner's teardown, which waits for the guard.
+ */
+export declare function drainBeforeUnload(ctx: Context, drain: () => Promise<void>): void;
+/**
+ * The root service `name`, or a refusal naming `user`, the plugin or tool that depends on it, when
+ * it is not mounted. Checked where a plugin mounts, so a composition without the service fails
+ * there rather than leaving the plugin silently inactive, and looked up again at each call.
+ */
+export declare function requireService<K extends string & keyof Context>(ctx: Context, name: K, user: string): NonNullable<Context[K]>;
+/**
+ * Refuses a plugin mounted in a thread's scope when `name`, the thing mounted, serves every thread
+ * from the application root. The predicate is `scopeOf(ctx) === undefined`: an untagged application
+ * context passes, so this is not a root-identity check.
+ */
+export declare function requireUnscoped(ctx: Context, name: string): void;

package/dist/services/presets/definition.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 '../../records/journal.js';
+import { type JsonValue } from '../../util/json.js';
+import { type AgentSelector } from '../agents.js';
+import type { Thread } from '../threads/index.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 {};