@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/services/birth.d.ts

@@ -0,0 +1,220 @@
+import { type ModelRoute } from '../llm/index.js';
+import type { Journal } from '../journal/index.js';
+import { type BirthConflict, type BirthSpec, type ForkOpening, type FreshOpening, type RowRef, type WriteRows } from '../loop/index.js';
+import type { InitialInstallation, Installation, JournalEventInput, Seq, ThreadEnvironment, ThreadInput, ThreadOrigin, ThreadSummary } from '../models/index.js';
+import type { Wake } from '../loop/index.js';
+import { type DeepReadonly, type ReadonlyJsonValue } from '../util/json.js';
+import type { InitialInstallationInput, PresetsService } from './presets.js';
+/**
+ * What must match when a creation or fork finds its id taken: `identity` is the thread's agent,
+ * origin and whether it is a fork, and for a fork its cut; `configuration` also compares the
+ * birth the request resolves to with the one recorded.
+ */
+export type Reuse = 'identity' | 'configuration';
+/**
+ * What a new thread's opening write carries beside its spawn row, the same for `create` and `fork`:
+ * one group, so the thread never exists without them. All of it is creation-only: a thread found
+ * again under its id gets none, whichever {@link Reuse} the request names.
+ */
+export type Opening = {
+    /** The caller chooses the id once per creation and reuses it on retries. */
+    id: string;
+    /** Never inherited by a fork: application markers belong to the thread they were written on. */
+    metadata?: Readonly<Record<string, ReadonlyJsonValue>>;
+    /**
+     * The thread's first input, queued for a turn of its own. A fork created with one owes only it,
+     * not a reply to the conversation it inherited, until a step claims it.
+     */
+    input?: ThreadInput;
+    /** The first input's id, for idempotent re-dispatch; a fresh one when omitted. */
+    inputId?: string;
+    /** Plugin rows for the same group, or a veto that rejects the creation with its refusal; see {@link WriteRows}. */
+    rows?: WriteRows;
+    /**
+     * A cause in the same group asking the new thread to run, naming its first input, as `send`'s
+     * `wake`: how a delegation authorizes a new child's task in the write that opens it. It states no
+     * route: the thread is born on its own.
+     */
+    wake?: Wake;
+};
+/**
+ * What a fresh thread is born with, as a request states it. Each field `defaults` or `caller`
+ * leaves out is filled from that source; `exact` states a whole {@link BirthSpec} instead.
+ */
+export type BirthInput<I> = {
+    /**
+     * The route the thread is born on, complete: required, since which model a conversation runs on
+     * is the caller's choice. A later change travels with a cause's route statement.
+     */
+    route: ModelRoute;
+    /**
+     * Where the thread's work happens, field by field. An omitted field is the default: the root's
+     * `cwd` and no read roots, or with `caller` the caller's. The cwd and every read root must be absolute.
+     */
+    environment?: Partial<DeepReadonly<ThreadEnvironment>>;
+    /**
+     * Preset installations the thread is born with, recorded in its spawn row, so the thread never
+     * exists without them and a fork cut anywhere inherits them, each with its lifetime: a `defining`
+     * one is never removed, a `configurable` one changes through `Thread.configure` as one applied
+     * later does. Validated as a configuration change validates, a preset that defines its thread's
+     * agent must define this one, and a creation preset must be `defining`. With `caller`, the
+     * installations the caller's live scope hands down follow these, as defining ones.
+     */
+    installations?: readonly I[];
+    /**
+     * The constraint owners, by plugin name, that every run of the thread is under: a run waits while
+     * one is not registered and repaired, and so does a run of every thread created under it by
+     * origin, which records only its own. A set: sorted and deduplicated when recorded.
+     */
+    requires?: readonly string[];
+};
+/**
+ * Where a fresh thread's configuration comes from, and its origin: where the thread came from, in
+ * the shape a summary records it, immutable once recorded; creation refuses one whose cited row is
+ * not the caller's (`origins.validate`).
+ *
+ * - `defaults`: fields left out come from core's configuration.
+ * - `caller`: fields left out come from the caller, plus what its live scope hands down; the caller
+ *   must have a live activation, whatever the origin's cause.
+ * - `exact`: reads nothing from the caller or core: the spec is the birth.
+ */
+export type BirthChoice<I> = {
+    origin?: ThreadOrigin;
+    birth: {
+        from: 'defaults';
+    } & BirthInput<I>;
+} | {
+    origin: ThreadOrigin;
+    birth: {
+        from: 'caller';
+    } & BirthInput<I>;
+} | {
+    origin?: ThreadOrigin;
+    birth: {
+        from: 'exact';
+        spec: BirthSpec;
+    };
+};
+/**
+ * How `create` starts a thread: its {@link Opening}, a {@link BirthChoice} and a {@link Reuse},
+ * both required, with no default. `caller` goes with `identity` only: comparing a birth that came
+ * from the caller's live hand-downs would not be a comparison of birth facts. Under `configuration`
+ * installations must be named, since generated ids cannot compare.
+ */
+export type CreateThreadOptions = Opening & (({
+    reuse: 'identity';
+} & BirthChoice<InitialInstallationInput>) | ({
+    reuse: 'configuration';
+} & Exclude<BirthChoice<InitialInstallationInput & {
+    installationId: string;
+}>, {
+    birth: {
+        from: 'caller';
+    };
+}>));
+/**
+ * Where a fork is cut. `at` names the row itself: a `thread/spawned`, `turn/start`, `llm/request`
+ * or `turn/end` row of the source's lineage, as a bare seq or as the `{ threadId, seq }` pair the
+ * thread helpers return. `atTurn` names any row of the lineage and cuts at the end of the turn
+ * holding it, or with `before`, just ahead of the turn, at its `turn/start`: edit and resend, with
+ * `input` in the turn's place, which `before` therefore requires. A turn that has not ended cannot
+ * be cut at its end.
+ */
+export type ForkCut = {
+    at: Seq | RowRef;
+    atTurn?: never;
+    before?: never;
+} | {
+    atTurn: Seq | RowRef;
+    before?: boolean;
+    at?: never;
+};
+/**
+ * How to fork a thread; see {@link ThreadsService.fork}. A fork inherits its route and installations
+ * at the cut; `reuse` is required: `identity` is the cut, agent and origin, `configuration` also
+ * the fork's own environment and `requires`.
+ */
+export type ForkOptions = Opening & ForkCut & {
+    reuse: Reuse;
+    /** Set by a delegating tool; a fork someone asks for directly has none and is a root. */
+    origin?: ThreadOrigin;
+    /**
+     * The environment of the thread `fork` is called on, field by field, where omitted — also when the
+     * cut is redirected to an ancestor, whose working directory may differ.
+     */
+    environment?: Partial<DeepReadonly<ThreadEnvironment>>;
+    /** The constraint owners the fork's runs are under, as {@link BirthInput.requires}. None when omitted. */
+    requires?: readonly string[];
+};
+/** What resolving a birth reads from outside its options. */
+export type BirthContext = {
+    readonly journal: Journal;
+    readonly presets: PresetsService;
+    /** The `environment.cwd` a thread created without one gets. */
+    readonly defaultCwd: string;
+    /**
+     * The installations the live scope of caller `callerId` hands down to a child on `agent`, refused
+     * when the caller has no live activation: its plugins could not say what the child is born with.
+     */
+    readonly handedDown: (agent: string, own: readonly Installation[], callerId: string) => InitialInstallation[];
+};
+/**
+ * A resolved opening: what a creation or fork records, built once and used for validation,
+ * comparison, a write-time callback's payload and the spawn row.
+ */
+export type ResolvedOpening = {
+    readonly kind: 'fresh';
+    readonly opening: FreshOpening;
+} | {
+    readonly kind: 'fork';
+    readonly opening: ForkOpening;
+};
+/** Read roots as a spawn row records them: each normalized, once, in the order given. A relative one is refused. */
+export declare function readRoots(roots: readonly string[]): string[];
+/** Constraint owners as a spawn row records them: a set, sorted and without repeats. */
+export declare const canonicalRequires: (requires: readonly string[] | undefined) => string[];
+/**
+ * Resolves a fresh creation's birth, validated before anything is appended. `origin` is the
+ * validated one (`null` for a root). Under `configuration` reuse every installation must name its
+ * id: a generated one could never compare.
+ */
+export declare function resolveFresh(context: BirthContext, args: {
+    agent: string;
+    origin: ThreadOrigin | null;
+    birth: CreateThreadOptions['birth'];
+    reuse: Reuse;
+}): FreshOpening;
+/**
+ * Resolves a fork's own configuration: its environment, field by field from `options`, else from the
+ * thread `fork` was called on (`named`, even when the cut redirects to an ancestor), and its
+ * constraint owners. The route and installations are the cut's, never stated.
+ */
+export declare function resolveForkOwn(named: ThreadSummary, options: Pick<ForkOptions, 'environment' | 'requires'>): {
+    environment: ThreadEnvironment;
+    requires: string[];
+};
+/** What a fork goes on with from its cut and does not record: the route and installations as the lineage folds to there. */
+export declare function inheritsAt(journal: Journal, cut: RowRef): ForkOpening['inherits'];
+/** The spawn row a resolved opening records. */
+export declare function spawnRow(resolved: ResolvedOpening, metadata: NonNullable<Opening['metadata']>): JournalEventInput['thread/spawned'];
+/** What a request must match of an existing thread by identity: its agent, origin and kind, and for a fork its cut. */
+export type Identity = {
+    readonly kind: 'fresh' | 'fork';
+    readonly agent: string;
+    readonly origin: ThreadOrigin | null;
+    readonly cut?: RowRef;
+};
+/**
+ * What differs between an existing thread and the identity a request asks for: its agent, its
+ * origin, whether it is a fork, and for a fork its cut. The origin is compared as the request states it.
+ */
+export declare function identityConflicts(summary: ThreadSummary, requested: Identity): BirthConflict[];
+/**
+ * What differs between a fresh birth's recorded spawn row and the birth requested: route,
+ * environment, installations and `requires`, the last as a set. Installation order is significant.
+ */
+export declare function specConflicts(spawn: JournalEventInput['thread/spawned'], requested: BirthSpec): BirthConflict[];
+/** What differs between a fork's recorded own configuration and the one requested. */
+export declare function forkConflicts(summary: ThreadSummary, requested: Pick<ForkOpening, 'environment' | 'requires'>): BirthConflict[];
+/** Throws {@link BirthConflictError} when `conflicts` is not empty. */
+export declare function requireNoConflicts(threadId: string, conflicts: readonly BirthConflict[]): void;

package/dist/services/contributions.d.ts

@@ -0,0 +1,73 @@
+import type { Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { PluginJournal, ThreadSummaryCore } from '../journal/index.js';
+import type { DeepReadonly, JsonValue } from '../util/json.js';
+/** What one thread's contribution says, as {@link ContributionDefinition.read} reports it. */
+export type ContributionReading<T> = 
+/** The thread's value: computed from its folds when it is loaded, else the catalog's cached copy. */
+{
+    readonly status: 'available';
+    readonly value: DeepReadonly<T>;
+}
+/** The contribution is not about this thread: its `applies` says no. */
+ | {
+    readonly status: 'not-applicable';
+}
+/** It applies, but there is no valid value to read: nothing nor no one computed it, or it fails its schema or version. Never read as an empty value. */
+ | {
+    readonly status: 'unavailable';
+    readonly reason: string;
+};
+export type ContributionDefinitionInput<T extends JsonValue> = {
+    /** Where the value sits in a thread's catalog entry; one definition per key. */
+    key: string;
+    /** The shape of what is cached; a changed shape is recomputed, never migrated. */
+    schema: z.ZodType<T>;
+    /** An integer that changes when the value's meaning does, though its shape does not: entries with another one are recomputed. */
+    version: number;
+    /** Whether the thread has a value. Decided from the catalog entry alone, so a reader needs nothing loaded. */
+    applies(summary: ThreadSummaryCore): boolean;
+    /**
+     * The value from the thread's folds, synchronously. Total for a thread that applies: a failure
+     * throws, and the entry is then missing and reads `unavailable`, never an empty value. It
+     * must return JSON, and may return what a fold holds read-only: the result is validated and copied.
+     */
+    compute(journal: PluginJournal, threadId: string): NoInfer<DeepReadonly<T>>;
+};
+/** A summary contribution: define it once at module level, register it from a service, read it where it is needed. */
+export type ContributionDefinition<T extends JsonValue> = {
+    readonly key: string;
+    /**
+     * Computes the value into every thread's catalog entry with each write group, for the lifetime of
+     * `ctx`, and queues the refresh of the entries that are missing, fail the schema or carry another
+     * version. `refreshed` settles when it has run, with the threads whose repair failed: they keep
+     * an entry without the key and read `unavailable`. A service waits for it before it serves from
+     * the catalog.
+     */
+    register(ctx: Context): {
+        readonly refreshed: Promise<string[]>;
+    };
+    /**
+     * What `threadId` says. A loaded thread computes from its folds, so it reads the same with the
+     * contributing service unmounted; any other validates the cached entry. Never loads a thread and
+     * never queues a repair.
+     */
+    read(journal: PluginJournal, threadId: string): ContributionReading<T>;
+};
+/**
+ * Defines a typed, versioned contribution to every thread's catalog entry: what is read of a thread
+ * that is not loaded, as after a restart, or by a listing that loads nothing.
+ *
+ * ```ts
+ * const openTasks = defineContribution({
+ *   key: 'app:open-tasks',
+ *   version: 1,
+ *   schema: z.number(),
+ *   applies: (summary) => summary.origin !== null,
+ *   compute: (journal, threadId) => journal.state(tasks, threadId).size,
+ * })
+ * openTasks.register(ctx) // in a service
+ * openTasks.read(ctx.journal, threadId) // { status: 'available', value: 2 }
+ * ```
+ */
+export declare function defineContribution<T extends JsonValue>(input: ContributionDefinitionInput<T>): ContributionDefinition<T>;

package/dist/services/core.d.ts

@@ -0,0 +1,34 @@
+import type { Plugin } from '@leuduan/cordis';
+import type { JournalStore } from '../journal/index.js';
+import { type TurnLimits } from '../loop/index.js';
+export type CoreConfig = {
+    /** The journal's backing, constructed by the application. */
+    store: JournalStore;
+    /** Default `environment.cwd` for new threads; absolute. */
+    cwd: string;
+    /**
+     * Absolute application data directory holding each thread's own directory, or `null` for none:
+     * plugins that need directories then refuse to mount. Required: where to keep files is the
+     * application's choice.
+     */
+    dataDir: string | null;
+    limits?: Partial<TurnLimits>;
+    /**
+     * What becomes of a thread the owner loaded to run once its run lets go: `retire` takes it out of
+     * memory, `keep` leaves it loaded. Required: what to cache is the application's choice.
+     */
+    retention: 'retire' | 'keep';
+    /**
+     * How many reactive turns in a row a thread may run (turns its own work woke, such as notices)
+     * before a producer of more unattended work refuses: `ctx.threads.chain(threadId).atLimit`. A
+     * person's or an assignment's authority resets the count. Required: how much unattended work to
+     * allow is the application's choice.
+     */
+    chainLimit: number;
+};
+/**
+ * Mounts the core services on one root: `ctx.journal`, `ctx.llm`, `ctx.agents`, `ctx.tools`,
+ * `ctx.prompts`, `ctx.threadDirs`, `ctx.launches`, `ctx.presets` and `ctx.threads`. Providers, tools, agents and
+ * capability plugins mount beside it.
+ */
+export declare const core: Plugin.Object<CoreConfig>;

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 '../loop/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/launches.d.ts

@@ -0,0 +1,104 @@
+import { Service, type Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import { type SpawnedCommand, type SpawnEnvironment } from '../sys/spawn.js';
+/**
+ * How a model-driven process becomes a local launch: the one place `run_command`, and later other
+ * model-driven processes such as MCP stdio servers, start a process, so a host's confinement sees
+ * every one. Not `sys/spawn`: lagent's own spawns (`rg`, git, the shell probe, stop-check hooks) call
+ * `spawnCommand` directly and are never intercepted.
+ */
+/** Which launch a process got, recorded with it: never secrets, ids or ports. */
+export declare const LaunchProvenanceSchema: z.ZodObject<{
+    launcher: z.ZodString;
+    version: z.ZodString;
+    policy: z.ZodString;
+}, z.core.$strict>;
+export type LaunchProvenance = z.output<typeof LaunchProvenanceSchema>;
+/** The `policy` of a launch a handler chose to run unconfined: what a host or a listing marks as such. */
+export declare const UNCONFINED_LAUNCH = "unconfined";
+/**
+ * What to launch: the geometry to confine (`root`, `scratch`) and the thread the launch is for, the
+ * subject a handler's per-thread policy is decided on.
+ */
+export type LaunchRequest = {
+    /** The thread the launch serves: the policy subject, never a place to confine. */
+    readonly threadId: string;
+    /** What runs. */
+    readonly program: {
+        readonly shell: string;
+    };
+    /** Absolute: where it starts. */
+    readonly workdir: string;
+    /** The writable root the protected names are rebuilt for: the thread's working directory for commands. */
+    readonly root: string;
+    /** Keys the process's temporary directory: `thread:<id>` for commands. Equal keys share one directory. */
+    readonly scratch: string;
+    /** The process's environment: the caller's. */
+    readonly environment: SpawnEnvironment;
+    /** Aborting it stops the launch: preparation at once, and the process within its stop bound. */
+    readonly signal: AbortSignal;
+};
+export type LaunchOptions = {
+    readonly timeoutMs?: number;
+    readonly killGraceMs: number;
+    /** Awaited before the process is released, as `spawnCommand`'s, with the launch it got. */
+    readonly beforeRelease?: (pgid: number, launch: LaunchProvenance | null) => Promise<void>;
+};
+/** A local process to spawn in place of `/bin/sh -c <command>`. */
+export type PreparedLaunch = {
+    readonly argv: readonly [string, ...string[]];
+    readonly cwd: string;
+    readonly env: SpawnEnvironment;
+    readonly provenance: LaunchProvenance;
+    /** After the process ended: bounded report lines, or `null`. Never rejects the process's outcome. */
+    violations(): Promise<string | null>;
+};
+/** What confines launches, such as the OS sandbox of `@leuduan/lagent/sandbox`. */
+export type LaunchHandler = {
+    /** Rejects, with a message for the model, to refuse the launch. */
+    prepare(request: LaunchRequest): Promise<PreparedLaunch>;
+};
+export type LaunchHandle = {
+    /**
+     * Stops admitting through the handler, aborts every launch it prepared, and waits for each one's
+     * preparation, process and report within `timeoutMs`. Resolves `true` only when every group was
+     * confirmed stopped: no `stopFailed` result, ever, and nothing still running at the bound.
+     * Idempotent: every caller shares the first call's result.
+     */
+    release(timeoutMs: number): Promise<boolean>;
+};
+/** A launched process: its group, what it was launched as, and the handler's report once it ends. */
+export type Launched = {
+    readonly spawned: SpawnedCommand;
+    readonly launch: LaunchProvenance | null;
+    /** Settles after `spawned.result`, within {@link DIAGNOSTICS_MS}; `null` for nothing to report. Never rejects. */
+    readonly diagnostics: Promise<string | null>;
+};
+/** How long after a process ended its report may take. */
+export declare const DIAGNOSTICS_MS = 1000;
+/**
+ * The launch seam. With no handler, a launch is `/bin/sh -c <command>`. The first {@link handle}
+ * declares for the root's lifetime that launches go through a handler, which decides what each one
+ * gets (confinement, or refusal): from then on a launch with no live handler, because it was
+ * released, failed or never mounted again, is refused, and nothing falls back to a plain spawn. A
+ * host mounts the handler before anything launches.
+ *
+ * A handler is told nothing about consumers. It is released as a whole: core aborts what it
+ * prepared and reports whether every group stopped, so the handler may then free what confined them.
+ */
+export declare class LaunchesService extends Service {
+    private readonly root;
+    constructor(ctx: Context);
+    /**
+     * Registers the one handler. Throws while another is live. Afterwards, until the root ends, a
+     * launch with no live handler is refused.
+     */
+    handle(handler: LaunchHandler): LaunchHandle;
+    /** One launch: through the handler when one was registered, else `/bin/sh -c`. */
+    launch(request: LaunchRequest, options: LaunchOptions): Promise<Launched>;
+    private spawnPlain;
+    private spawnThrough;
+    private release;
+    /** Whether every operation settled within `timeoutMs` and no stop ever failed. */
+    private settle;
+}

package/dist/services/llm.d.ts

@@ -0,0 +1,80 @@
+import { Context, Service } from '@leuduan/cordis';
+import { z } from 'zod';
+import { type LLMProvider, type ModelCallClient, type ModelCapacity, type ModelRoute } from '../llm/index.js';
+import { type ModelSelection } from '../loop/index.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 {};