@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/records/toolResult.d.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import type { ContentPart } from '../llm/content.js';
+export declare const ToolResultPayloadSchema: z.ZodObject<{
+    output: z.ZodString;
+    content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        detail: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            low: "low";
+            high: "high";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>], "type">>>;
+    is_error: z.ZodDefault<z.ZodBoolean>;
+    notes: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    concludes_turn: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+export type ToolResultPayload = z.infer<typeof ToolResultPayloadSchema>;
+/** A payload as a tool writes one: `is_error`, `notes` and `metadata` may be left out. */
+export type ToolResultPayloadInput = z.input<typeof ToolResultPayloadSchema>;
+export declare const ToolResultSchema: z.ZodObject<{
+    output: z.ZodString;
+    content: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        text: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"image">;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        detail: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            low: "low";
+            high: "high";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"file">;
+        file_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        data: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        filename: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        media_type: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>], "type">>>;
+    is_error: z.ZodDefault<z.ZodBoolean>;
+    notes: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    concludes_turn: z.ZodOptional<z.ZodLiteral<true>>;
+    call_id: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strip>;
+export type ToolResult = z.infer<typeof ToolResultSchema>;
+export declare function toolResultMessageContent(result: ToolResult): ContentPart[];

package/dist/services/agents.d.ts

@@ -0,0 +1,62 @@
+import { Context, Service, type ScopeKey } from '@leuduan/cordis';
+import { z } from 'zod';
+import { type AgentDefinition, type AgentDefinitionInput } from '../loop/index.js';
+/** A definition and the layer that registered it: `undefined` for the global one. */
+export type AgentResolution = {
+    readonly agent: AgentDefinition;
+    readonly layer: ScopeKey | undefined;
+};
+/**
+ * The agents this process can run. Live: a registration lasts exactly as long as the plugin
+ * that made it, and a thread resolves its agent from the scope it runs in, not when it was created.
+ *
+ * Layered by Cordis scope like tools: an untagged registration is global, a scoped one is visible
+ * from that scope and its descendants, and the closest definition of a name wins. Global and scoped
+ * names are disjoint (`isScopedAgentName`): a scoped name contains a dot and a global one does not,
+ * so a scoped agent can never answer to a name a global one has, or will have.
+ */
+export declare class AgentsService extends Service {
+    private readonly layers;
+    constructor(ctx: Context);
+    /** Agent names visible from `scope`, sorted and deduplicated. */
+    names(scope: ScopeKey | undefined): string[];
+    /**
+     * Every agent visible from `scope`, each name once with its closest definition: the global
+     * layer's first, then each closer layer's, each in registration order.
+     */
+    all(scope: ScopeKey | undefined): AgentDefinition[];
+    has(scope: ScopeKey | undefined, name: string): boolean;
+    get(scope: ScopeKey | undefined, name: string): AgentDefinition | undefined;
+    /** The definition, or a thrown `UnknownAgentError`. */
+    require(scope: ScopeKey | undefined, name: string): AgentDefinition;
+    /** The closest definition of `name` visible from `scope`, with the layer that registered it. */
+    resolve(scope: ScopeKey | undefined, name: string): AgentResolution | undefined;
+    /** Adds an agent to one layer; returns the unregister function. Duplicates fail within that layer. */
+    register(scope: ScopeKey | undefined, agent: AgentDefinitionInput): () => void;
+}
+/** Registers an agent in the calling plugin's layer for the lifetime of its fiber. */
+export declare const registerAgent: (ctx: Context, agent: AgentDefinitionInput) => (() => void | Promise<void>);
+/**
+ * The agents a plugin's `agents` option selects. Required wherever it appears: which agents a
+ * composition has is the host's to say, so none of the shipped plugins defaults it. `'global'` is
+ * every globally registered agent, those registered later included; `'all'` is every thread's agent,
+ * scoped ones included; a list names agents, global or scoped.
+ */
+export declare const AgentSelectorSchema: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"global">, z.ZodLiteral<"all">]>;
+export type AgentSelector = readonly string[] | 'global' | 'all';
+/**
+ * Whether `selector` selects `agentName`. One meaning wherever a selector appears, whether the plugin
+ * equips (a grant, a prompt section, a notice) or restricts (a mode, a stop check). `'global'` never
+ * selects a scoped agent (`isScopedAgentName`), so a role child gets only what names it or says
+ * `'all'`; a gate that must cover role children says `'all'`.
+ *
+ * Registries are live, so a selector is a predicate evaluated when the plugin acts — granting,
+ * rendering a prompt section, authorizing a call — rather than a list resolved once at mount.
+ */
+export declare const selects: (selector: AgentSelector, agentName: string) => boolean;
+/**
+ * Whether `name` is an agent name for a scoped registration: one containing a dot, such as
+ * `codex.explore`. Global agent names never contain one, so the two kinds cannot collide, and the
+ * agents registry refuses a registration of the wrong kind.
+ */
+export declare const isScopedAgentName: (name: string) => boolean;

package/dist/services/catalogContributions.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/confinement/files.d.ts

@@ -0,0 +1,118 @@
+import { type Stats } from 'node:fs';
+import type { FileAccess, FilePolicy } from './service.js';
+/**
+ * The scoped file facade: how file tools touch the file system. One implementation, owned by the
+ * operation (`ConfinementOperation.files`), which applies the operation's `FilePolicy` to every
+ * path and ends with the operation. With no policy it authorizes everything but keeps the same
+ * lifetime rules, so a tool cannot tell which it has.
+ *
+ * Every check covers the path as requested (absolute and normalized) and the path it resolves to,
+ * resolved natively so it carries the volume's own spelling, and a path is refused when either is.
+ * A file is opened by its resolved path without following a final link, and the handle is verified
+ * (the file opened is the file approved, and the requested path still leads to it) before any byte
+ * is read through it. This narrows the race between check and use to the revalidation window; it does
+ * not close it, and hard links are not detected.
+ *
+ * Changes are primitives on regular files, never a write of a whole file: a file is created exclusively
+ * (never opened for writing over what exists, and never truncated), and committed by `link` or
+ * `rename`, which the caller owns. A directory is never renamed or removed, and nothing is changed
+ * through a link: the target of a change is refused when it is itself a symbolic link, naming where it
+ * leads. Each primitive judges its paths at the moment it runs, so a path swapped after the caller's
+ * own checks is judged as it is then.
+ */
+/** A refusal by the file policy, whose message is for the model. */
+export declare class FileAccessError extends Error {
+    constructor(message: string);
+}
+/** An open file as a tool may use it: reads only, through the handle the facade verified. */
+export type ReadHandle = {
+    /** Up to `length` bytes from `position`; fewer only at the end of the file. */
+    read(position: number, length: number): Promise<Buffer>;
+    /** All of the file from its start. */
+    readAll(): Promise<Buffer>;
+    /** The opened file's own metadata. */
+    stat(): Promise<Stats>;
+    close(): Promise<void>;
+};
+/** A new file as a tool may fill it: writes only, through the handle the facade created. */
+export type WriteHandle = {
+    /** Appends all of `data`. */
+    write(data: Uint8Array): Promise<void>;
+    /** Flushes what was written to the device. */
+    sync(): Promise<void>;
+    /** The created file's own metadata. */
+    stat(): Promise<Stats>;
+    close(): Promise<void>;
+};
+/** Which access a call judges its paths for: a read unless the caller says what it intends. */
+export type PathOptions = {
+    readonly access?: readonly FileAccess[];
+};
+/** One entry of a directory the policy lets through. */
+export type DirEntry = {
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly isSymbolicLink: boolean;
+};
+/** A directory's allowed entries, and how many the policy hid. */
+export type DirListing = {
+    readonly entries: readonly DirEntry[];
+    readonly hidden: number;
+};
+/**
+ * What a tool does to files, within one operation. Paths are absolute. Every method rejects with a
+ * {@link FileAccessError} for a path the policy refuses, and with an ordinary error once the
+ * operation has ended or was aborted: a reference that outlives its call is dead.
+ */
+export type FileScope = {
+    /**
+     * Names how this facade judges reads (`FilePolicy.identity`, or `unrestricted` with no policy): taking
+     * it takes the operation's snapshot, so a refused operation rejects here. What a reader that keeps
+     * its result for another thread to use keys it by.
+     */
+    identity(): Promise<string>;
+    /** Opens a file for reading, where links resolve and are checked. Never a raw descriptor. */
+    open(path: string): Promise<ReadHandle>;
+    /** The entries of a directory, with every entry the policy refuses (or a link resolving to one) left out and counted. */
+    readdir(path: string): Promise<DirListing>;
+    /** Metadata of the file a path leads to. */
+    stat(path: string, options?: PathOptions): Promise<Stats>;
+    /** Metadata of a path itself, not of what a final link leads to. */
+    lstat(path: string, options?: PathOptions): Promise<Stats>;
+    /**
+     * The path with every link resolved, as the checks see it; a missing tail stays as named, after the
+     * nearest existing ancestor's real path. `options.access` names what the caller means to do with it.
+     */
+    realpath(path: string, options?: PathOptions): Promise<string>;
+    /**
+     * Creates a new file that must not exist, with `mode` as given, for writing; never replaces or truncates.
+     * A `temporary` file is the caller's scratch: it may be removed with `unlink` even after a cancellation,
+     * and is removed when the operation ends unless the caller has put it elsewhere.
+     */
+    create(path: string, options?: {
+        readonly mode?: number;
+        readonly temporary?: boolean;
+    }): Promise<WriteHandle>;
+    /** Creates a directory and any missing parents. */
+    mkdir(path: string): Promise<void>;
+    /** Hard-links the regular file `existing` as `created`, which must not exist. */
+    link(existing: string, created: string): Promise<void>;
+    /** Renames a regular file over `to`, which is absent or a regular file; a directory is never renamed. */
+    rename(from: string, to: string): Promise<void>;
+    /** Removes a regular file; a directory is never removed. A `temporary` file this operation created goes even after a stop. */
+    unlink(path: string): Promise<void>;
+    /** Sets the mode of a regular file. */
+    chmod(path: string, mode: number): Promise<void>;
+};
+/** What the operation hands its facade. */
+export type FileScopeHost = {
+    /** The operation's policy, which the first call takes; `null` for no path policy. Rejects when the operation is refused. */
+    policy(): Promise<FilePolicy | null>;
+    /** Aborts when the call is cancelled, the operation ends or its handler is released: checked between file system calls. */
+    signal(): AbortSignal;
+};
+/** The facade's lifetime: `end` closes what it opened and kills its methods. */
+export type EndableFileScope = FileScope & {
+    end(): Promise<void>;
+};
+export declare function fileScope(host: FileScopeHost): EndableFileScope;

package/dist/services/confinement/service.d.ts

@@ -0,0 +1,219 @@
+import { Service, type Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import { type SpawnedCommand, type SpawnedGroup, type SpawnedPipes, type SpawnEnvironment } from '../../sys/spawn.js';
+import { type FileScope } from './files.js';
+/**
+ * How a model-driven process becomes a local launch: the one place `run_command`, the search tools,
+ * 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 (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 runs. `shell` is text for `/bin/sh -c`, launched with stdout and stderr joined in order, as a
+ * command line is. `argv` is a program and its arguments, run without a shell, launched with a
+ * writable stdin and stdout and stderr apart, as a tool that parses a program's output needs them.
+ */
+export type LaunchProgram = {
+    readonly shell: string;
+} | {
+    readonly argv: readonly [string, ...string[]];
+};
+/**
+ * What to launch and the geometry to confine (`root`, `scratch`). The thread it serves, the subject
+ * of a handler's per-thread policy, is the one its operation was opened for.
+ */
+export type LaunchRequest = {
+    readonly program: LaunchProgram;
+    /** 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: `threadScratch(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>;
+};
+/** The program a launch runs when nothing confines it: the argv itself, or `/bin/sh -c` for shell text. */
+export declare function plainArgv(program: LaunchProgram): readonly [string, ...string[]];
+/** A local process to spawn in place of the request's program, from the same stdio form. */
+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 a tool does to a path. */
+export type FileAccess = 'read' | 'write';
+/** A path's verdict: allowed, or refused with a message for the model. */
+export type FileVerdict = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+/**
+ * What a handler lets file tools reach, judged by name over absolute paths and never from the file
+ * system: a tool that follows links asks about the path it was given and about where it resolves,
+ * and needs both allowed.
+ */
+export type FilePolicy = {
+    check(path: string, access: FileAccess): FileVerdict;
+    /**
+     * Names how this policy judges a read: two policies with equal identities answer every read alike.
+     * What a reader that shares its result between threads (a catalog of skills) keys it by, so what
+     * one thread was allowed to read is never handed to another that was not.
+     */
+    readonly identity: string;
+};
+/** The `scratch` key of a thread's own processes, which is also the directory its file tools may write besides its root. */
+export declare const threadScratch: (threadId: string) => string;
+/**
+ * What one operation's launches are prepared under: the handler's decisions for a thread, taken
+ * once, so every launch of the operation gets the same ones whatever changes meanwhile.
+ */
+export type ConfinementSnapshot = {
+    /** The thread's file policy, the one its launches are confined by; `null` for no path policy at all. */
+    readonly files: FilePolicy | null;
+    /** Rejects, with a message for the model, to refuse the launch. */
+    prepare(request: LaunchRequest): Promise<PreparedLaunch>;
+};
+/** What confines launches, such as the OS sandbox of `@leuduan/lagent/plugins/sandbox`. */
+export type ConfinementHandler = {
+    /** Rejects, with a message for the model, to refuse the operation: nothing of it is admitted. */
+    snapshot(threadId: string): Promise<ConfinementSnapshot>;
+};
+export type ConfinementHandle = {
+    /**
+     * Says that what an operation opened from now on would be allowed has changed, such as a thread's
+     * mode: content a reader prepared before (`ConfinementService.epoch` then differs from the one it
+     * noted) was read under what no longer holds, and is not delivered.
+     */
+    changed(): void;
+    /**
+     * 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.
+ * A `shell` program is a joined {@link SpawnedCommand}, an `argv` program {@link SpawnedPipes}.
+ */
+export type Launched<Spawned extends SpawnedGroup = SpawnedCommand> = {
+    /** The actual directory selected for the process, including a confinement handler's choice. */
+    readonly cwd: string;
+    readonly spawned: Spawned;
+    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;
+/**
+ * What one piece of model-driven work does under confinement: its launches and its file access, all
+ * under the one snapshot the operation takes on first use. What `run_command` takes for one command,
+ * and what the execution of one tool call is handed (`InvocationContext.operation`).
+ */
+export type ConfinementOperation = {
+    /** Launches under the operation's snapshot, or plainly when no handler is registered. */
+    launch(request: LaunchRequest & {
+        program: {
+            shell: string;
+        };
+    }, options: LaunchOptions): Promise<Launched>;
+    launch(request: LaunchRequest & {
+        program: {
+            argv: readonly [string, ...string[]];
+        };
+    }, options: LaunchOptions): Promise<Launched<SpawnedPipes>>;
+    /**
+     * File access under the snapshot's {@link FilePolicy}, or none: the one way a tool touches files.
+     * Valid until {@link end}.
+     */
+    readonly files: FileScope;
+    /**
+     * Ends the file access: calls in flight settle, every handle it opened is closed, and every later
+     * use of `files`, or of a handle, fails. Launches are not ended with it: a process has a lifetime
+     * of its own. Idempotent.
+     */
+    end(): Promise<void>;
+};
+/**
+ * The confinement seam. With no handler, a launch is a plain spawn: `/bin/sh -c <command>` for shell
+ * text, the argv itself for an argv. The first {@link handle} declares for the root's lifetime that
+ * launches go through a handler, which decides what each operation gets (confinement, or refusal):
+ * from then on an operation 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
+ * admitted and reports whether every group stopped, so the handler may then free what confined them.
+ */
+export declare class ConfinementService extends Service {
+    private readonly root;
+    private changes;
+    private holdReads;
+    constructor(ctx: Context);
+    /**
+     * Registers the one handler. Throws while another is live. Afterwards, until the root ends, an
+     * operation with no live handler is refused.
+     */
+    handle(handler: ConfinementHandler): ConfinementHandle;
+    /**
+     * A count of the changes to what an operation would be allowed: a handler registered or released,
+     * or one saying so (`ConfinementHandle.changed`). A reader that prepares content ahead of its
+     * delivery notes it before it reads, and delivers only if it still reads the same.
+     */
+    get epoch(): number;
+    /**
+     * Opens one operation for `threadId`. Nothing happens until it is used: its first launch or file
+     * access takes the handler's snapshot, once, which everything the operation does is prepared and
+     * checked under, and a refusal (the handler refuses the operation, or has stopped, or the caller's
+     * `signal` aborts first) rejects that use with a {@link CommandStartFailure}. With no handler
+     * registered the operation launches plainly and its file access has no policy. The caller ends it
+     * (`end`) when its call does.
+     */
+    open(threadId: string, signal: AbortSignal): ConfinementOperation;
+    /** The thread and the callers out to its origin root, held loaded; none for a thread the journal does not hold. */
+    private retainReads;
+    /**
+     * For the threads service, which owns what is loaded: how a thread and the histories a snapshot
+     * of it reads (its callers out to its origin root) are held loaded while the snapshot is taken;
+     * `null` for a thread the journal does not hold. Core's own, so that the dependency runs from
+     * threads to confinement. Returns what takes it back.
+     */
+    holdReadsWith(hold: (threadId: string) => Promise<{
+        release(): void;
+    } | null>): () => void;
+    /** The operation's one snapshot, tracked from before the handler hears of it, or none when no handler is registered. */
+    private takeSnapshot;
+    private requireLive;
+    /** One launch under a snapshot. */
+    private launchThrough;
+    private spawnPlain;
+    private spawnThrough;
+    private release;
+    /** Whether every operation settled within `timeoutMs` and no stop ever failed. */
+    private settle;
+}

package/dist/services/core.d.ts

@@ -0,0 +1,28 @@
+import type { Plugin } from '@leuduan/cordis';
+import type { JournalStore } from '../journal/index.js';
+import { type TurnLimits } from '../state/index.js';
+export type CoreConfig = {
+    /** The journal's backing, constructed by the application. */
+    store: JournalStore;
+    /** Default `environment.cwd` for new threads; absolute. */
+    cwd: string;
+    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.confinement`, `ctx.presets` and `ctx.threads`. Providers, tools, agents and
+ * capability plugins mount beside it.
+ */
+export declare const core: Plugin.Object<CoreConfig>;