@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/sandbox/policy.d.ts

@@ -0,0 +1,86 @@
+import type { SpawnEnvironment } from '../sys/spawn.js';
+import type { CallConfig, PathEntry } from './protocol.js';
+export declare function refuseStartupInjection(environment: SpawnEnvironment): void;
+/** The most command text one launch carries, which travels in the environment of the process that starts it. */
+export declare const MAX_COMMAND_BYTES: number;
+/** `path` with every link in its existing part resolved, so containment is judged on real locations. */
+export declare function canonical(path: string): string;
+/**
+ * The root a command's protected names are rebuilt for, canonical. sandbox-runtime substitutes the
+ * real prefix before it compiles a pattern, and cannot anchor one this module hands it, so a root
+ * whose real path holds glob characters or its compiler's placeholders would turn the patterns
+ * below into something else: it is refused, not escaped.
+ */
+export declare function canonicalRoot(root: string): string;
+/**
+ * sandbox-runtime's mandatory write denies, rebuilt for `root`: its own set anchors at the host's
+ * working directory and only ever adds denies there. Each name once as the path at the root and
+ * once as a pattern for the same name anywhere beneath it. `root` is canonical and holds no glob
+ * characters (`canonicalRoot`).
+ */
+export declare function mandatoryDenies(root: string): PathEntry[];
+/**
+ * The programs a launch runs before confinement, as the search path finds them: the directories
+ * searched, since a program dropped into an earlier one would win, and the real file of every
+ * candidate for each program, wherever its link leads.
+ */
+export declare function helperLocations(searchPath: string): string[];
+/**
+ * Refuses roots a command could use against the sandbox itself: one overlapping, either way, what
+ * a launch runs before confinement, or the temporary root, whose directories the host creates
+ * unconfined. `roots` are canonical.
+ */
+export declare function refuseUnsafeRoots(roots: readonly string[], trusted: readonly string[], tmpRoot: string): void;
+/** What a command's filesystem policy is made of, besides its root and scratch directory. */
+export type HostFacts = {
+    readonly allowWrite: readonly string[];
+    readonly denyWrite: readonly string[];
+    readonly denyRead: readonly string[];
+    readonly dataDir: string;
+    /** The paths under the home directory sandbox-runtime keeps writable for itself, as its worker reported them. */
+    readonly conveniences: readonly string[];
+    readonly privateDirectory: string;
+};
+/**
+ * A command's complete filesystem lists, which replace the initialized ones for the call: writes
+ * only in the root, the host's roots and the scratch directory, and never in what the host or
+ * sandbox-runtime keeps for itself or in the root's protected names. Every path is literal.
+ */
+export declare function callPolicy(facts: HostFacts, root: string, scratchDirectory: string): CallConfig['filesystem'];
+/**
+ * The script the sandbox runs: restores the command's `PATH`, sets its temporary directory and runs
+ * it with `/bin/sh -c`. Everything it needs arrives in variables, never spliced into the script.
+ */
+export declare const BOOTSTRAP: string;
+/**
+ * The environment of the process that starts the sandbox: the command's own, but with the trusted
+ * `PATH` until the sandbox holds, since the wrapped line runs `env` and `sandbox-exec` before
+ * confinement. The bootstrap restores the rest.
+ */
+export declare function launchEnvironment(environment: SpawnEnvironment, searchPath: string, scratchDirectory: string, command: string): SpawnEnvironment;
+/** What the name and version say in a command's recorded launch. */
+export declare const LAUNCHER = "lagent-srt";
+export declare const versionOf: (runtime: string) => string;
+/** Everything enforcement depends on, digested: recorded with a launch as its policy. */
+export declare function policyDigest(facts: {
+    readonly filesystem: CallConfig['filesystem'];
+    readonly network: unknown;
+    readonly searchPath: string;
+    readonly cwd: string;
+    readonly home: string;
+    readonly conveniences: readonly string[];
+    readonly javaAgent: string;
+    readonly version: string;
+}): string;
+/** What the model is told about sandboxed commands. */
+export declare function instructionsFor(config: {
+    readonly filesystem: {
+        readonly allowWrite: readonly string[];
+    };
+    readonly network: {
+        readonly mode: 'allowlist';
+        readonly allowedDomains: readonly string[];
+    } | {
+        readonly mode: 'unrestricted';
+    };
+}): string;

package/dist/sandbox/protocol.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The messages between the sandbox service on the host's main thread and its worker thread
+ * (`worker.ts`), which holds sandbox-runtime. Types only, so the worker, which runs from the sources
+ * under Node's type stripping as from `dist`, imports nothing of lagent.
+ */
+/** A path as sandbox-runtime takes it: a pattern when it reads as one, or a name marked literal. */
+export type PathEntry = string | {
+    readonly path: string;
+    readonly literal: true;
+};
+export type ParentProxy = {
+    readonly http?: string;
+    readonly https?: string;
+    readonly noProxy?: string;
+};
+/** The configuration sandbox-runtime is initialized with, once, for the worker's life. */
+export type SrtConfig = {
+    readonly network: {
+        readonly allowedDomains: readonly string[];
+        readonly deniedDomains: readonly string[];
+        /** Absent without a configured proxy: sandbox-runtime then reads its environment, which carries none. */
+        readonly parentProxy?: ParentProxy;
+    }
+    /** No `allowedDomains`: sandbox-runtime restricts the network only when it is defined. */
+     | {
+        readonly allowedDomains?: never;
+        readonly deniedDomains: readonly [];
+        readonly parentProxy?: never;
+    };
+    readonly filesystem: {
+        readonly denyRead: readonly PathEntry[];
+        readonly allowWrite: readonly PathEntry[];
+        readonly denyWrite: readonly PathEntry[];
+    };
+    /** The private copy of its JVM proxy agent: an existing explicit path ends sandbox-runtime's own search. */
+    readonly javaAgentJarPath: string;
+};
+/** A command's filesystem policy: complete lists, which replace the initialized ones for the call. */
+export type CallConfig = {
+    readonly filesystem: {
+        readonly allowWrite: readonly PathEntry[];
+        readonly denyWrite: readonly PathEntry[];
+        readonly denyRead: readonly PathEntry[];
+    };
+};
+/** What the worker found when it started sandbox-runtime. */
+export type InitReport = {
+    readonly version: string;
+    readonly supported: boolean;
+    readonly errors: readonly string[];
+    readonly warnings: readonly string[];
+    /** The paths under the home directory that sandbox-runtime keeps writable for its own uses. */
+    readonly conveniences: readonly string[];
+    /** How many JVM agent flags a wrapped command carries, and whether the one is the private copy. */
+    readonly javaAgent: {
+        readonly flags: number;
+        readonly isCopy: boolean;
+    };
+};
+export type WorkerRequest = {
+    readonly type: 'init';
+    readonly id: number;
+    readonly config: SrtConfig;
+    /** What the worker's own environment must say: its private temporary directory and its home. */
+    readonly expect: {
+        readonly tmpdir: string;
+        readonly home: string;
+    };
+} | {
+    readonly type: 'wrap';
+    readonly id: number;
+    readonly command: string;
+    readonly commandId: string;
+    /** The command the wrap stands for, bounded, for sandbox-runtime's reports. */
+    readonly commandText: string;
+    readonly config: CallConfig;
+}
+/** Abandons the wrap sent with the same id; handled on arrival, not behind queued wraps. */
+ | {
+    readonly type: 'cancel';
+    readonly id: number;
+} | {
+    readonly type: 'violations';
+    readonly id: number;
+    readonly commandId: string;
+} | {
+    readonly type: 'reset';
+    readonly id: number;
+};
+/** A request as a caller writes it: the client assigns the id. */
+export type WorkerMessage = WorkerRequest extends infer R ? (R extends WorkerRequest ? Omit<R, 'id'> : never) : never;
+/** What each request's reply carries. */
+export type WorkerValues = {
+    init: InitReport;
+    wrap: string;
+    violations: readonly string[];
+    reset: null;
+};
+export type WorkerReply = {
+    readonly id: number;
+} & ({
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly error: string;
+});

package/dist/sandbox/service.d.ts

@@ -0,0 +1,143 @@
+import { Service, type Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { WriteRows } from '../loop/index.js';
+import { type LaunchHandler, type LaunchRequest, type PreparedLaunch } from '../services/launches.js';
+import { type SandboxMode } from './mode.js';
+export declare const SandboxConfigSchema: z.ZodObject<{
+    worker: z.ZodUnion<readonly [z.ZodCustom<import("url").URL, import("url").URL>, z.ZodString]>;
+    searchPath: z.ZodString;
+    tmpRoot: z.ZodString;
+    javaAgentJar: z.ZodString;
+    unconfined: z.ZodEnum<{
+        refused: "refused";
+        allowed: "allowed";
+    }>;
+    filesystem: z.ZodObject<{
+        allowWrite: z.ZodArray<z.ZodString>;
+        denyRead: z.ZodArray<z.ZodString>;
+        denyWrite: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+    network: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        mode: z.ZodLiteral<"allowlist">;
+        allowedDomains: z.ZodArray<z.ZodString>;
+        deniedDomains: z.ZodArray<z.ZodString>;
+        parentProxy: z.ZodUnion<readonly [z.ZodLiteral<"none">, z.ZodObject<{
+            http: z.ZodOptional<z.ZodURL>;
+            https: z.ZodOptional<z.ZodURL>;
+            noProxy: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>, z.ZodObject<{
+        mode: z.ZodLiteral<"unrestricted">;
+    }, z.core.$strict>], "mode">;
+    drainTimeoutMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type SandboxConfigInput = z.input<typeof SandboxConfigSchema>;
+/** Whether the sandbox can confine a launch now: `failed` once its worker died or its start failed, for good. */
+export type SandboxHealth = 'ready' | 'failed';
+declare module '@leuduan/cordis' {
+    interface Context {
+        /** The OS sandbox for shell commands, the launch handler of `ctx.launches` (optional plugin, `@leuduan/lagent/sandbox`). */
+        sandbox: SandboxService;
+    }
+    interface Events {
+        /**
+         * The sandbox can no longer confine a launch, so it refuses every one, confined or not: its
+         * worker died or it failed to start. For a host that shows conversations' sandbox state.
+         */
+        'lagent/sandbox/health'(health: SandboxHealth): void;
+    }
+}
+/**
+ * The OS sandbox for shell commands, as a service and as the one launch handler of `ctx.launches`.
+ * sandbox-runtime runs on a worker thread of this process (`./worker.ts`), started once, and this
+ * service owns it: the policy built for each command, the worker's messages and deadlines, and the
+ * order of teardown.
+ *
+ * Each conversation is confined or unconfined, as its durable mode says (`mode`, `setMode`, `opening`),
+ * unless the host's `unconfined: 'refused'` confines them all. The mode is read once when a launch
+ * starts preparing: a switch applies to launches that start preparing after it, and a launch already
+ * preparing or running keeps the policy it selected. An unconfined launch is still the sandbox's
+ * handler's, so it stops with it and a failed sandbox refuses it too. The model is told the mode as a
+ * notice, never in the prompt.
+ *
+ * The handler is registered before the worker starts and refuses every launch until the self-check
+ * passed, so a sandbox that fails to start never leaves a window in which launches run plain.
+ * Teardown releases the handle first, so what it confined ends before its proxy does. sandbox-runtime
+ * starts at most once per process, so a failed or disposed service is never restarted. The teardown
+ * order and its failure cases are in `docs/sandbox.md`.
+ */
+export declare class SandboxService extends Service<SandboxConfigInput> implements LaunchHandler {
+    static inject: string[];
+    /** What the model is told about confined commands: part of the notice's fact, so a changed one is told again. */
+    private readonly guidance;
+    private readonly config;
+    private readonly dataDir;
+    private state;
+    private failure;
+    private admitting;
+    private client;
+    private host;
+    private readonly handle;
+    private releasing;
+    constructor(ctx: Context, config: SandboxConfigInput);
+    [Service.init](): Promise<() => Promise<void>>;
+    /** The host's gate: whether any conversation may run its commands unconfined. */
+    get unconfined(): 'allowed' | 'refused';
+    /** Whether the sandbox can confine a launch now. */
+    get health(): SandboxHealth;
+    /**
+     * The mode `threadId` runs its commands in: its conversation's recorded mode, `confined` before
+     * one is recorded, and `confined` whatever was recorded when the host refuses unconfined. The one
+     * value preparation, the notice and a host's display read.
+     */
+    mode(threadId: string): SandboxMode;
+    /**
+     * Records `mode` for `threadId`'s conversation, when it changes it. Refuses a mode the host's gate
+     * refuses, a thread the journal does not hold, and a thread with an origin, which is in its
+     * conversation's mode: switch the conversation.
+     */
+    setMode(threadId: string, mode: SandboxMode): Promise<void>;
+    /**
+     * The rows that record `mode` in the write that creates or forks a conversation (`Opening.rows`),
+     * always one, so an opening leaves evidence of the choice. The mode and the host's gate are judged
+     * here, before anything is written; a thread with an origin is refused inside the write.
+     */
+    opening(mode: SandboxMode): WriteRows;
+    private refuseGated;
+    prepare(request: LaunchRequest): Promise<PreparedLaunch>;
+    /**
+     * An unconfined launch: what core would have run with no handler, with the provenance that says so.
+     * None of the confined machinery runs: no scratch directory, policy, digest, worker request or
+     * violation lookup.
+     */
+    private plain;
+    private start;
+    /** Runs a fixed command through the path every command takes, so a sandbox that cannot confine never serves. */
+    private selfCheck;
+    private requireOpen;
+    /**
+     * A confined launch from its geometry alone, never a thread, so the self-check builds one with none.
+     * `trusted` skips the root checks, for the one launch whose root lies in the temporary root.
+     */
+    private build;
+    /** What sandbox-runtime recorded against one command: best-effort, from its global tail of recent events. */
+    private violationsOf;
+    private onWorkerDeath;
+    /** Tells the host's listeners the sandbox failed; a listener that throws is reported and never interrupts the caller. */
+    private announceFailure;
+    /** The unload guard: closes admission at once, then releases what the handler confined. */
+    private closeAndRelease;
+    /**
+     * Releases the handle once, whoever asks: core stops admitting through the handler, aborts what it
+     * prepared and waits for the groups. `false`, with the error reported, when a group could not be
+     * confirmed stopped, or one still ran at the bound: a confined process may still run, so the worker
+     * stays.
+     */
+    private releaseHandle;
+    /**
+     * Resets sandbox-runtime and ends the worker, once the handle was released: freeing its proxy port
+     * while a confined process may still run would hand the port to a listener without the
+     * allowlist, which that process's profile still permits.
+     */
+    private release;
+}

package/dist/sandbox/worker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The sandbox worker: a message interface over Anthropic's sandbox-runtime (`SandboxManager`) on a
+ * worker thread of the host, and nothing else. It is the one module that loads sandbox-runtime, so
+ * the library's process-wide state, its proxies and its signal handlers live here: signals are not
+ * delivered to worker threads, and the proxy runs on an event loop that does nothing else.
+ *
+ * The service (`./service.ts`) starts it with an explicit environment, sends `init` once, then
+ * `wrap` for each command, and `reset` last. Self-contained: it imports sandbox-runtime and Node
+ * only (types aside), so it runs from the sources under Node's type stripping as from `dist`, and
+ * bundles into a single-file executable as an extra entry point.
+ */
+export {};

package/dist/sandbox/worker.js

@@ -0,0 +1 @@
+import{homedir as c,tmpdir as y}from"node:os";import{sep as u}from"node:path";import{parentPort as P}from"node:worker_threads";import{getDefaultWritePaths as S,NetworkConfigSchema as _,SandboxManager as n}from"@anthropic-ai/sandbox-runtime";import b from"@anthropic-ai/sandbox-runtime/package.json"with{type:"json"};var A=20,E=500,T=2e3,j=["HTTP_PROXY","HTTPS_PROXY","NO_PROXY","http_proxy","https_proxy","no_proxy"],a=P;if(a===null)throw new Error("lagent sandbox worker: started outside a worker thread");var d=new Map;a.on("message",e=>{I(e)});async function I(e){try{switch(e.type){case"init":return i(e.id,await O(e));case"wrap":{let o=new AbortController;d.set(e.id,o);try{let t=await n.wrapWithSandbox(e.command,"/bin/sh",e.config,o.signal,{commandId:e.commandId,commandText:e.commandText});return i(e.id,t)}finally{d.delete(e.id)}}case"cancel":d.get(e.id)?.abort();return;case"violations":{let o=n.getSandboxViolationStore().getViolationsForCommand(e.commandId);return i(e.id,o.slice(-A).map(t=>t.line.slice(0,E)))}case"reset":{let o;return await Promise.race([n.reset().catch(()=>{}),new Promise(t=>{o=setTimeout(t,T)})]),clearTimeout(o),i(e.id,null)}}}catch(o){let t={id:e.id,ok:!1,error:o instanceof Error?o.message:String(o)};a.postMessage(t)}}function i(e,o){let t={id:e,ok:!0,value:o};a.postMessage(t)}async function O(e){let{config:o,expect:t}=e;if(o.network.allowedDomains!==void 0){let r=_.safeParse(o.network);if(!r.success){let v=r.error.issues.map(g=>`${g.path.join(".")}: ${g.message}`);throw new Error(`sandbox-runtime rejects the network configuration: ${v.join("; ")}`)}}if(y()!==t.tmpdir)throw new Error(`the worker's temporary directory is ${y()}, not the private directory ${t.tmpdir}`);if(c()!==t.home)throw new Error(`the worker's home directory is ${c()}, not ${t.home}`);let m=o.network.parentProxy===void 0?j.filter(r=>r in process.env):[];if(m.length>0)throw new Error(`the worker's environment sets ${m.join(", ")} but no parent proxy is configured`);let p=n.isSupportedPlatform(),{errors:l,warnings:x}=n.checkDependencies(),h={version:b.version,supported:p,errors:l,warnings:x,conveniences:[],javaAgent:{flags:0,isCopy:!1}};if(!p||l.length>0)return h;await n.initialize(o);let s=c(),k=S({denyRead:o.filesystem.denyRead}).filter(r=>r.startsWith(s.endsWith(u)?s:s+u)),w=await n.wrapWithSandbox("true","/bin/sh"),f=w.split("-javaagent:").length-1;return{...h,conveniences:k,javaAgent:{flags:f,isCopy:f===1&&w.includes(`-javaagent:${o.javaAgentJarPath}`)}}}

package/dist/services/admission.d.ts

@@ -0,0 +1,174 @@
+import type { Lease } from '../loop/index.js';
+import type { CancelIntent, InboxTarget } from '../models/index.js';
+/**
+ * An exclusive operation on one thread; see `Admission.onOperation`. A `cancel` holds the thread from a
+ * `cancel()` until its write has landed and what it cancelled has released the thread.
+ */
+export type OperationKind = 'run' | 'compact' | 'rebuild' | 'configure' | 'release' | 'cancel';
+/** How an operation ended: as asked, by throwing, or because it was cancelled or lagent closed. */
+export type OperationEnding = 'completed' | 'failed' | 'cancelled';
+/** What holds a thread: the operation's kind, and the run request a run serves (`null` for any other). */
+export type OperationHolder = {
+    readonly kind: OperationKind;
+    readonly runId: string | null;
+};
+/**
+ * What `onOperation` listeners are told: an operation was admitted on a thread, or it settled and
+ * how. Process-local and never a journal row; `settled` is published once admission is released,
+ * so a listener may start the thread's next operation from it.
+ */
+export type OperationEvent = {
+    readonly thread_id: string;
+    readonly kind: OperationKind;
+    readonly phase: 'admitted';
+} | {
+    readonly thread_id: string;
+    readonly kind: OperationKind;
+    readonly phase: 'settled';
+    readonly ended: OperationEnding;
+};
+/**
+ * An admitted operation as the code running it sees it: what it is, and the signal and lease it
+ * hands to the work. Everything else about it is the owner's.
+ */
+export type AdmittedOperation = {
+    readonly threadId: string;
+    readonly kind: OperationKind;
+    /** The run request a run serves; `null` for any other operation. */
+    readonly runId: string | null;
+    readonly signal: AbortSignal;
+    readonly lease: Lease;
+};
+/**
+ * What a thread's handle and its activation ask the owner: whether it runs, where input waits, the
+ * cancel, and the unload guard's wait. Nothing that admits or settles an operation.
+ */
+export type AdmissionView = Pick<Admission, 'isRunning' | 'inputTarget' | 'cancel' | 'whenSettled' | 'isAdmitted'>;
+/**
+ * What one `cancel()` gets back: the run of the execution the thread's cancel captured, if it
+ * captured a run, and the one settlement of that cancel. `wrote` reports the call's own write,
+ * once it is queued, and only then aborts what the call captured, so a cancel an abort listener
+ * makes is written after this one. `capturedSettles` says, read inside that write, whether the
+ * captured execution's finalization is still to build its run's settlement: until then the
+ * finalization settles it by the cancel's intent; after, what it built stands, and a run it left
+ * pending is the cancel's to settle.
+ */
+export type CancelHandle = {
+    readonly capturedRunId: string | null;
+    readonly settled: Promise<void>;
+    capturedSettles(): boolean;
+    wrote(write: Promise<unknown>): void;
+};
+/**
+ * The one owner of which operation holds each thread: admission or refusal, the releasing phase,
+ * cancellation, and the publication of admission and settlement in the order
+ * docs/lifecycle.md#ordering states. It knows nothing of activations; the threads service runs
+ * each operation's work, and disposes activations under it, through `hold`.
+ */
+export declare class Admission {
+    /**
+     * The one operation admitted on each thread, from before its first `await` until its work and
+     * cleanup settled: what `cancel()` aborts and awaits, what refuses a second operation as busy,
+     * and what says whether input joins a run's next step.
+     */
+    private readonly admitted;
+    /** The cancel in progress on each thread, from its first call until it settles. */
+    private readonly cancels;
+    private readonly listeners;
+    private readonly closing;
+    private readonly report;
+    /**
+     * @param closing aborts once lagent is closing: nothing is admitted after, and it is composed
+     *   into every operation's signal.
+     */
+    constructor(closing: AbortSignal, report: (error: unknown) => void);
+    /** Refuses as admission would, without admitting: once lagent is closing, or busy while an operation holds the thread. */
+    requireFree(threadId: string): void;
+    /**
+     * Admits `kind` on the thread, or refuses it busy, synchronously, and publishes `admitted` before
+     * returning. The operation's signal composes shutdown's, `cancel()`'s and the caller's; its lease
+     * says whether it still holds the thread, for a callback that escaped it. A configuration change
+     * is admitted releasing: it starts by releasing the live activation, before anything can see it.
+     */
+    admit(threadId: string, kind: OperationKind, options?: {
+        readonly signal?: AbortSignal | undefined;
+        readonly runId?: string | undefined;
+    }): AdmittedOperation;
+    private operation;
+    /**
+     * Runs `work` as the admitted operation, then the disposal `cleanup` returns, if any, then its
+     * `finalize`, if any, both still under it, then releases admission and publishes `settled` in the
+     * same synchronous step, however `work` ended. `finalize` runs in the releasing phase: the
+     * operation still holds the thread, so nothing else is admitted and nothing mounts, but it executes
+     * nothing more, and input sent meanwhile waits for the next turn. It runs again when a cancel
+     * captured the operation while it ran, so it must be safe to repeat. Without either step nothing is
+     * awaited between the work's end and the release. The value `work` returns is its own, taken
+     * before admission is released. A failing finalization or disposal is reported; the admission is
+     * released all the same.
+     */
+    hold<T>(admitted: AdmittedOperation, work: () => Promise<T>, steps?: {
+        readonly finalize?: () => Promise<void>;
+        readonly cleanup?: () => Promise<void> | undefined;
+    }): Promise<T>;
+    /**
+     * Enters or leaves the operation's releasing phase; entering wakes whatever waits for it to stop
+     * executing. Set by whoever disposes an activation under the operation, before the disposal starts.
+     */
+    setReleasing(admitted: AdmittedOperation, releasing: boolean): void;
+    /**
+     * Starts the thread's cancel, or joins the one in progress, synchronously. The first call captures
+     * the operation admitted now, if any, and marks it with its intent; `wrote` aborts it (a release is
+     * waited for, never aborted). The run that operation serves settles by the intent of the first
+     * cancel that reached it. With nothing
+     * admitted, a `cancel` operation holds the thread at once, closing or not, since a shutdown still
+     * cancels. Either way the cancel holds the thread, refusing a run as busy, until every joined
+     * call's write has finished, landed or failed (`wrote`), and the captured operation has released;
+     * its `settled` then resolves, once for every call.
+     */
+    cancel(threadId: string, reason: string, intent: CancelIntent): CancelHandle;
+    /** The intent of the first cancel that captured `admitted`, or `null`: what the run it serves settles by. */
+    cancelIntent(admitted: AdmittedOperation): CancelIntent | null;
+    /**
+     * Records, inside the finalization's write, that `admitted` built its run's settlement: a cancel
+     * written after it settles a run that build left pending.
+     */
+    settlementBuilt(admitted: AdmittedOperation): void;
+    /** The thread's cancel holds the thread as a `cancel` operation of its own; published by the caller. */
+    private holdForCancel;
+    private wroteCancel;
+    /** Settles the thread's cancel once every joined write finished and what it captured released. */
+    private finishCancel;
+    /** What holds the thread now, or `null`. */
+    holder(threadId: string): OperationHolder | null;
+    /** Whether any operation holds the thread. */
+    isAdmitted(threadId: string): boolean;
+    /** Whether a run or a compaction holds the thread: what `Thread.status()` calls running. */
+    isRunning(threadId: string): boolean;
+    /**
+     * Whether the operation holding the thread is disposing its activation, a release or another in
+     * its releasing phase: nothing of the thread may be mounted meanwhile, and it executes nothing.
+     */
+    isReleasing(threadId: string): boolean;
+    /** Where input sent now waits: a run's next step while a run holds the thread and is not cancelled, else the next turn. */
+    inputTarget(threadId: string): InboxTarget;
+    /** Resolves once the operation holding the thread now, if any, has settled. */
+    settlement(threadId: string): Promise<void>;
+    /**
+     * Resolves once no operation that executes holds the thread: what an activation waits for before
+     * it disposes, so a scope never goes under a running loop. An operation disposing the activation
+     * is not waited for, since that would be the disposal waiting on itself.
+     */
+    whenSettled(threadId: string): Promise<void>;
+    /**
+     * Resolves once no operation holds any thread and no cancel is in progress: what shutdown waits
+     * for before releasing scopes. Read again after each wait, since a cancel takes over a thread its
+     * captured operation releases, and a shutdown still cancels.
+     */
+    drain(): Promise<void>;
+    /** Tells `listener` when an operation is admitted on any thread and when it settled; see {@link OperationEvent}. */
+    onOperation(listener: (event: OperationEvent) => void): () => void;
+    /** The owner's record of `admitted`, which must hold its thread: anything else is a caller bug. */
+    private holding;
+    /** One frozen copy for every listener, so no listener can change what the next one sees. */
+    private publish;
+}

package/dist/services/agents.d.ts

@@ -0,0 +1,37 @@
+import { Context, Service, type ScopeKey } from '@leuduan/cordis';
+import type { AgentDefinition, AgentDefinitionInput } from '../models/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>);