@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/services/prompts.d.ts

@@ -0,0 +1,67 @@
+import { Context, Service, type ScopeKey } from '@leuduan/cordis';
+import type { PromptBlock } from '../llm/index.js';
+import type { ToolEntry } from '../loop/index.js';
+import type { AgentDefinition, ThreadSummary } from '../models/index.js';
+import { type AgentSelector } from '../kit/scope.js';
+export type PromptSlot = 'base' | 'instruction' | 'context';
+/**
+ * What a contribution is rendered against: the agent, where the thread works, and the tools it
+ * reaches.
+ *
+ * Deliberately not the thread's id or metadata. A recorded prompt is the head of every request a
+ * provider caches, so it must not depend on which thread it is: threads of one agent in one
+ * workspace then render the same prompt. Anything thread-specific belongs in the conversation, as
+ * a step contribution (see `workspaceContext`).
+ */
+export type PromptRenderInput = {
+    readonly agent: AgentDefinition;
+    readonly thread: {
+        readonly environment: ThreadSummary['environment'];
+    };
+    /** What the agent may call from the rendering scope, as the registries stand at render time. */
+    readonly tools: readonly ToolEntry[];
+};
+/**
+ * One section a plugin adds to an agent's prompt.
+ *
+ * `render` is synchronous and pure in its inputs: anything needing IO reads it when the plugin
+ * mounts, and returns the cached value here. Returning `null` contributes nothing — or, for a tag
+ * that already exists, removes it.
+ */
+export type PromptContribution = {
+    readonly tag: string;
+    readonly slot: PromptSlot;
+    /** Which agents get it; see `AgentSelector`. */
+    readonly agents: AgentSelector;
+    /** Render order within the slot; ties break on `tag`. Default 0. */
+    readonly order?: number;
+    render(input: PromptRenderInput): string | null;
+};
+/**
+ * Prompt contributions, live like the other registries and layered by Cordis scope like tools:
+ * an untagged contribution is global, a contribution registered through a thread's context belongs
+ * to that thread's layer. The prompt itself is rendered once, when a thread first runs and every
+ * activation plugin is ready, and recorded on it; this service only says what that render
+ * would be right now.
+ */
+export declare class PromptsService extends Service {
+    static inject: string[];
+    private readonly layers;
+    constructor(ctx: Context);
+    /** Adds a contribution to one layer; returns the function that removes it. */
+    contribute(scope: ScopeKey | undefined, contribution: PromptContribution): () => void;
+    /**
+     * The prompt `agentName` would send on a thread rendered now from `scope`: the agent's base
+     * prompt, then the global layer's contributions, then each closer layer outward-in, each in
+     * declared order, never mount order. A contribution whose tag is already present replaces that
+     * section in place — so the closest layer wins a tag — and `null` removes it.
+     *
+     * The base prompt is seeded at the layer that defines the agent, so only that layer and closer
+     * ones can replace or remove it with a `base` contribution: for a global agent every layer can,
+     * while a scoped agent's own base prompt outranks every layer farther out. Instruction and context
+     * contributions apply from every layer. Throws for an agent unknown from `scope`.
+     */
+    render(scope: ScopeKey | undefined, agentName: string, thread: PromptRenderInput['thread']): PromptBlock[];
+}
+/** Registers a contribution in the calling plugin's layer for the lifetime of its fiber. */
+export declare const contributePrompt: (ctx: Context, contribution: PromptContribution) => (() => void | Promise<void>);

package/dist/services/runEvents.d.ts

@@ -0,0 +1,79 @@
+import type { RunOutcomeKind, RunSettledReason } from '../models/index.js';
+import type { DurableRunState, Hold, HoldBasis } from '../loop/index.js';
+/**
+ * Where one run request stands, as its waiters see it: waiting to be admitted (`requested`), with
+ * an execution serving it (`running`, finalization included), held with the request still pending,
+ * or settled. A held run carries its structured `hold` and the `basis` it was read on, an immutable
+ * observation at publication, not a snapshot of the thread. `{ reason: 'shutdown' }` is what a
+ * waiter is told when the application closes under it.
+ */
+export type RunState = {
+    readonly state: 'requested';
+} | {
+    readonly state: 'running';
+} | {
+    readonly state: 'held';
+    readonly hold: Hold;
+    readonly basis: HoldBasis;
+} | {
+    readonly state: 'settled';
+    readonly outcome: RunOutcomeKind;
+    readonly reason: RunSettledReason;
+    readonly errorText: string | null;
+};
+/**
+ * One change of a run's state, published as it happens: `requested` once its cause is durable,
+ * `running` at admission, and `held` or `settled` only after the execution's finalization and its
+ * release of the thread, so nothing that reads it can still find the execution running.
+ */
+export type RunEvent = {
+    readonly threadId: string;
+    readonly runId: string;
+} & RunState;
+/**
+ * The read rule, the same as the events': a run an execution serves is `running` until that
+ * execution releases the thread, even when its settlement row is already durable; a settled run
+ * with no live execution is its settlement; a pending one is what the owner's current decision for
+ * it says, `held` with its hold or `requested`, since holds have no rows to read. `null` for a
+ * run the reader does not know: one the thread never had, or, on a thread out of memory, one older
+ * than its pending run and its latest settlement, which its catalog entry does not keep.
+ */
+export declare function readRunState(facts: {
+    readonly durable: DurableRunState;
+    /** Whether an execution serving this run holds the thread now. */
+    readonly executing: boolean;
+    /** The hold the owner currently reads on the thread's pending request, `null` when it has none to say. */
+    readonly held: {
+        readonly hold: Hold;
+        readonly basis: HoldBasis;
+    } | null;
+}): RunState | null;
+/** Where a waiter reads runs from: the event stream, and the read that follows the same rule. */
+export type RunSource = {
+    onRunEvent(listener: (event: RunEvent) => void): () => void;
+    runState(threadId: string, runId: string): RunState | null;
+};
+/**
+ * A run a waiter named is unknown to the catalog: the thread never had it, or the thread is out of
+ * memory and the run is older than its pending run and its latest settlement. A read or a hold
+ * loads the thread, which knows its every run.
+ */
+export declare class UnknownRunError extends Error {
+    readonly threadId: string;
+    readonly runId: string;
+    constructor(threadId: string, runId: string);
+}
+/**
+ * Waits until run `runId` on `threadId` reaches a state `until` accepts, and resolves with it, where
+ * `source` is `ctx.threads`. The wait is for that run: not for the input that asked for it to be
+ * answered, nor for the thread to go quiet, since a cause that lands while an execution finishes is
+ * carried to a successor request. `queued.runId` of a `send` names the run to wait for. It
+ * subscribes first and reads the state after, so a change that happened before the call is read,
+ * not missed; on each event of the run it reads again rather than trust the event, which may be
+ * stale by the time it is delivered. Rejects with the signal's reason when aborted (the run goes on),
+ * with {@link UnknownRunError} for a run unknown to the catalog, and with whatever the read or
+ * `until` threw; unsubscribes however it ends.
+ */
+export declare function waitForRun(source: RunSource, threadId: string, runId: string, until: (state: RunState) => boolean, signal?: AbortSignal): Promise<RunState>;
+/** What a caller waiting for a run's work to stop waits for: the run held or settled, as `waitForRun`'s `until`. */
+export declare const heldOrSettled: (state: RunState) => boolean;

package/dist/services/thread.d.ts

@@ -0,0 +1,267 @@
+import type { Context } from '@leuduan/cordis';
+import type { AppendEntry, Journal } from '../journal/index.js';
+import type { PromptBlock } from '../llm/index.js';
+import type { CompactOptions, RouteStatement, RowRef, SendOptions, SendOutcome, StreamedChunk, SurfacePrepareOutcome, WithdrawOptions, WithdrawOutcome } from '../loop/index.js';
+import type { CancelIntent, JournalEvent, ThreadInput, ThreadOrigin, ThreadSummary, TurnEndReason } from '../models/index.js';
+import type { DeepReadonly } from '../util/json.js';
+import type { AdmissionView } from './admission.js';
+import type { ForkOptions } from './birth.js';
+import type { ConfigurationChange, ConfigurationResult, ThreadsService } from './threads.js';
+import type { ThreadView } from './threadView.js';
+/** One answer to a parked confirmation. */
+export type ConfirmationAnswer = {
+    request_id: string;
+    approved: boolean;
+    rejection_message?: string | null;
+};
+/**
+ * How `cancel()` cancels: a person's stop (`user`), which holds the thread until a releasing cause,
+ * or a feature's `cleanup`, which holds nothing; `rows`, extension rows built inside the cancel's
+ * write for the same group, or a refusal of it by throwing; and `until`, the milestone the call
+ * settles at: `released` (the default) once the write has landed and what the cancel captured has
+ * released the thread, `recorded` once the write alone has landed.
+ */
+export type CancelOptions = {
+    readonly intent: CancelIntent;
+    readonly rows?: (threadId: string) => readonly AppendEntry<'ext'>[];
+    readonly until?: 'recorded' | 'released';
+};
+/**
+ * One conversation in the journal. Threads are independent: their own transcript, their own
+ * exclusive admission while the owner runs them, their own confirmations. Two may run at once. A
+ * thread runs for a recorded request: `send` or `answer` with `wake`, or `resume`.
+ *
+ * Durable accessors read the journal; execution status and ctx belong to the current activation.
+ * The handle never owns plugin lifetime and survives replacement of that activation.
+ */
+export declare class Thread {
+    private readonly inbox;
+    private readonly service;
+    private readonly admission;
+    readonly id: string;
+    private readonly journal;
+    constructor(service: ThreadsService, 
+    /** The admission owner's reads and cancel, given by the service that owns it. */
+    admission: AdmissionView, id: string, 
+    /** The journal with core's writes, which only the thread owner hands out. */
+    journal: Journal);
+    /**
+     * Reads what this thread's folds say through `reader`, which is synchronous: the thread is loaded
+     * and held for the call (a `keep` retention), so nothing drops it meanwhile: how a caller that
+     * holds nothing reads a thread's conversation, where one that holds it already reads
+     * `ctx.threads.view`. The catalog reads (`summary`, `status`, `lastOutcome`) need neither.
+     */
+    read<T>(reader: (view: ThreadView) => T): Promise<T>;
+    /** Lazily activates this thread. Its plugins are fixed once ready: mount them from activate listeners or presets. */
+    get ctx(): Context;
+    /**
+     * The current activation's signal, the one its `lagent/thread/activate` listeners receive: it
+     * aborts when the activation is released or stopped, not when one turn is cancelled. Activates
+     * the thread, as `ctx` does, and like `ctx` throws `ThreadBusyError` while the activation is being
+     * released, since a getter cannot wait; a read after the release starts a new activation; and once
+     * `ctx.threads` has shut down it throws.
+     */
+    get signal(): AbortSignal;
+    /**
+     * Activates this thread if it is not live, after any release in progress, and resolves once its
+     * plugins are ready: the barrier a run waits at, so a plugin that cannot mount, such as a recorded
+     * preset installation that no longer restores, rejects here with its error and nothing runs. A
+     * host that changes a thread's installations and wants the failure now awaits this.
+     */
+    whenReady(): Promise<void>;
+    /**
+     * Changes this thread's preset installations as one operation: validates the whole change,
+     * releases the live activation, records every installation applied or removed in one write, and
+     * restores a thread that was live from the record, rebuilding its recorded prompt when asked
+     * (which restores a thread at rest too); a thread at rest otherwise stays at rest, and its next run
+     * or `whenReady()` restores it. Removals go first, then
+     * applications, which are restored in that order. A given `installationId` makes a retry a no-op,
+     * and a removed id is never accepted again; removing an id not installed is no change, and a
+     * defining installation is never removed. Refused busy while an operation holds the thread, and
+     * refused with `ThreadActivatingError` while its activation is still getting ready, with
+     * `ThreadUnsettledError` for an unfinished confirmation (open, or approved and not yet run), and
+     * once lagent is closing. The record is the boundary: a cancel before it records nothing, a cancel
+     * after it ends only the restoration, and a setup that fails after it rejects with
+     * `RestoreFailedError`, the change standing, so a change that removes a broken installation
+     * always goes through.
+     */
+    configure(change: ConfigurationChange): Promise<ConfigurationResult>;
+    /**
+     * Takes this thread out of the working set: releases an idle activation and drops the rows and
+     * folds, under one admission; the catalog entry stays. Refused busy while an operation holds it.
+     */
+    close(): Promise<void>;
+    /**
+     * This thread's catalog entry: its identity and lineage, how its last turn ended, whether it has
+     * work, what it waits on, and what plugins and hosts contributed — everything a listing shows,
+     * read without a row of the thread in memory, exact as of the thread's last group.
+     */
+    get summary(): ThreadSummary;
+    get agentName(): string;
+    /** App-owned annotations the engine never reads. */
+    get metadata(): ThreadSummary['metadata'];
+    /** Where this thread came from: its caller, the caller's row and the cause; `null` for a root thread. */
+    get origin(): ThreadOrigin | null;
+    /**
+     * How many delegation hops separate this thread from its origin root: one for each thread
+     * of its caller chain that has a caller, a caller the catalog does not hold included.
+     */
+    get depth(): number;
+    /**
+     * The thread at the top of this one's origin tree, the caller chain's thread with no caller:
+     * itself for a thread created without an `origin`. `null` when the chain does not reach one, at a
+     * caller the catalog does not hold or a cycle, which only a journal that broke its rules has; a
+     * reader that decides by the root then decides nothing, rather than take a thread part-way up for
+     * it. From the catalog, loading nothing; fork lineage is {@link lineageRoot}'s.
+     */
+    get originRoot(): string | null;
+    get environment(): ThreadSummary['environment'];
+    /** The thread and row this one was forked at, or `null` unless it is a fork. */
+    get forkedFrom(): RowRef | null;
+    /**
+     * The thread at the start of this one's fork lineage: itself unless it is a fork. Forks of one
+     * root share its history, and so the provider cache that holds it.
+     */
+    get lineageRoot(): string;
+    /** How this thread's own last turn ended, from the catalog; `null` before its first ends, or while one is open. */
+    lastOutcome(): DeepReadonly<TurnEndReason> | null;
+    /** Forks this thread at a row, or at the turn holding one; see `ctx.threads.fork`. */
+    fork(options: ForkOptions): Promise<Thread>;
+    /**
+     * Re-renders the prompt from the registries as they stand — the thread's own plugins included,
+     * which is why it activates the thread and waits for them — and records it; later turns send the
+     * new one. The deliberate exception to a prompt being frozen at first run.
+     */
+    rebuildPrompt(): Promise<PromptBlock[]>;
+    /**
+     * This thread's events as they are appended: `ctx.journal.subscribe` filtered to the thread, so a
+     * promise the listener returns is reported if it rejects, as any subscriber's is. Returns the
+     * unsubscribe function.
+     */
+    on(listener: (event: JournalEvent) => void): () => void;
+    /** The model's output as it streams on this thread. Returns the unsubscribe function. */
+    onChunk(listener: (chunk: StreamedChunk) => void): () => void;
+    /**
+     * Queues durable input without driving, and resolves once it is durable with what the write did:
+     * `queued`, with the row that recorded it; `known`, when this thread was already handed `id`, which
+     * queues nothing and names the original row; or `refused`, with the reason `rows` vetoed it for.
+     *
+     * `rows` runs inside the write once the input's target is decided, and adds a plugin's rows to the
+     * same group or vetoes the input by returning `{ refuse }` (see `WriteRows`); a callback that
+     * throws fails the send with that error instead. A known id never calls it.
+     * `source` attributes the input to a plugin, as on a step contribution, and needs the `id` the
+     * plugin derived: the claimed `input/message` keeps both, and input waiting for a turn is claimed
+     * as one unsourced input or every consecutive sourced input at the head of the queue.
+     *
+     * Text is the common case and stays a string; `{ role: 'developer', content }` queues a message
+     * that speaks as the harness rather than as the person, and content parts carry what text cannot.
+     *
+     * Where input waits is the sender's `target` when it names one, and admission's choice otherwise.
+     * Admission joins a running turn at its next step; the caller that started the turn owns its
+     * result. On an idle thread it waits for a turn of its own, behind input sent before it, and is
+     * claimed only by that turn's first step: a turn that opens by answering calls an earlier turn
+     * left leaves it for the next turn, which the same run opens once that work completed.
+     * `target: 'next-turn'` asks for a turn of its own even while a run holds the thread, as a new
+     * assignment does; `target: 'next-step'` joins the next model step of whichever turn takes it,
+     * including a turn that resumes parked calls, as a report on work already set going does.
+     * Sending never interrupts: an in-flight model call or tool is never cut off. Interruption is
+     * `cancel()`, then `send()` with a wake, deliberately two visible steps.
+     *
+     * A wake may state the route it runs on (`RouteStatement`), checked inside the write: an `expect`
+     * that no longer matches the thread's route is refused with `RouteConflictError`, one whose route
+     * cannot run with `RouteUnavailableError`; a `select` changes the route, which reauthorizes all the
+     * thread's unfinished work on it, only while no request is pending or the route cannot run, and no
+     * run serving the pending request holds the thread. A refusal writes nothing.
+     */
+    send(input: ThreadInput, options?: SendOptions): Promise<SendOutcome>;
+    /**
+     * Takes back one queued input that no step has claimed yet, by the id it was sent with, and
+     * resolves with what the write did: `withdrawn`, `not-queued` (claimed, discarded or unknown), or
+     * `refused` by a `rows` veto, which adds a plugin's rows to the same write either way and is told whether
+     * the input was withdrawn. The id stays known, so `send` with it queues nothing again.
+     */
+    withdraw(inputId: string, options?: WithdrawOptions): Promise<WithdrawOutcome>;
+    /**
+     * Records answers to confirmations parked on this thread, all of them or none. Does not drive: the
+     * run the answer's cause asks for re-dispatches them, through authorization again. A request that
+     * already has a decision — answered before, or approved and then revoked — is refused with
+     * `ConfirmationAnsweredError`, carrying the decision on record; a batch naming one request twice
+     * is refused outright.
+     */
+    answer(decisions: readonly ConfirmationAnswer[], options?: {
+        readonly wake?: boolean;
+    }): Promise<void>;
+    /**
+     * Asks the thread to run again, as a person or a host does: a cause that releases the failure,
+     * cancellation and startup holds, recorded in one write and resolving once durable. A `route`
+     * statement is checked as `send` checks a wake's. Resolves with the run the cause joined or opened.
+     */
+    resume(options?: {
+        readonly route?: RouteStatement;
+    }): Promise<string>;
+    /**
+     * A cancel's answer to each call the thread suspended, read inside its write: an error result in
+     * the declaration's turn and step, citing the call and the declaration.
+     */
+    private closeWaitRows;
+    /** The thread's pending run request, read inside a write. */
+    private pendingRun;
+    /**
+     * Takes back approvals of calls without a result. Each becomes a rejection, so the call does not run
+     * again: its next dispatch ends it with an error. A call that already started, and then waits or
+     * was cut off, keeps what it did, and a child thread it started keeps running. Refused while a run
+     * holds the thread, since that run may be executing one. A batch with any id that does not qualify
+     * records nothing. Writes only to the journal, so it also works on a thread that cannot activate,
+     * which is how a host gets such a thread out of an approval it cannot run.
+     */
+    revokeApprovals(requestIds: readonly string[], rejectionMessage?: string | null): Promise<void>;
+    /**
+     * Asks the thread's strategy to prepare its surface now, between turns, with the `request`
+     * trigger and `options`, which the engine passes on and never reads. This is how a host offers a `/compact` command.
+     *
+     * Holds the thread's admission, as a run does, but accepts no input: `send()` meanwhile queues for the
+     * next turn unless its sender names `next-step`, a run waits for it, and `activity` names the compaction. Requires a
+     * settled thread — no tool call without a result, no open confirmation, no answer its stop checks
+     * still owe — and rejects with `ThreadUnsettledError` otherwise; an interrupted open turn is closed
+     * first, as a run closes it. The route is resolved as a turn's would be. Opens no turn, runs no
+     * step hook and claims no queued input. Aborts on `signal`, on `cancel()` and on shutdown, and then
+     * resolves `cancelled` rather than rejects, with whatever the dispatch committed; cancelled before
+     * it began, it resolves `cancelled` with nothing dispatched. A strategy that failed on its own while
+     * the signal aborted resolves `failed`.
+     *
+     * Resolves with the one outcome record: the replacement rows committed and how the dispatch ended;
+     * `skipped` with a reason when no strategy answered.
+     */
+    compact(options?: CompactOptions): Promise<SurfacePrepareOutcome>;
+    /**
+     * Cancels the thread, whatever its state: captures the operation admitted now, if any, and aborts
+     * only it, then records one write: the `thread/cancel` row, the clear of everything queued, an
+     * error result answering each call the thread suspended on a wait, resolved or not, the rows
+     * `options.rows` adds, and the settlement, by the cancel's intent, of a pending run no execution is
+     * still to settle. So a cancelled thread never holds a waiting call, and a feature watching the
+     * call learns of the cancel from its result. The run the captured execution serves settles in that execution's
+     * finalization, unless the finalization built its settlement before this write and left it pending. A `user` cancel (a person's stop) holds the thread until a releasing cause; a
+     * `cleanup` one holds nothing. From the call until its write has landed and what it captured has
+     * released the thread, the cancel holds the thread, so a run meanwhile is refused busy; a cancel
+     * made meanwhile joins it. With `until: 'released'`, the default, resolves then, or rejects with its
+     * own write's failure, which records nothing — so a `send` after `cancel()` never races the
+     * cancelled operation. With `until: 'recorded'` it settles with that write alone, resolving once
+     * it has landed and rejecting with its failure, without waiting for what was captured to wind down:
+     * a run's drain and finalization are the engine's, and a failure of theirs goes to `reportError`,
+     * so a caller that needs the thread free awaits `released`. Each joined call gets its own write's
+     * outcome.
+     */
+    cancel(reason: string, options: CancelOptions): Promise<void>;
+}
+/** The answers as journal rows on the thread that asked, appended as one group. */
+export declare const confirmationRows: (threadId: string, decisions: readonly ConfirmationAnswer[]) => {
+    type: "confirm/resolved";
+    data: {
+        request_id: string;
+        approved: boolean;
+        rejection_message: string | null;
+    };
+    options: {
+        threadId: string;
+    };
+}[];

package/dist/services/threadActivation.d.ts

@@ -0,0 +1,100 @@
+import { type Context, type Scope, type Scoped, type ScopeKey } from '@leuduan/cordis';
+import { type CompactOptions, type Lease, type LoopServices, type SurfacePrepareOutcome } from '../loop/index.js';
+import type { ServedRun } from '../loop/index.js';
+import type { Thread } from './thread.js';
+import type { AdmissionView } from './admission.js';
+import type { ThreadsService } from './threads.js';
+/**
+ * One process-local activation: the thread's Cordis scope, the plugins mounted in it, their
+ * readiness, and the loop that runs in it. It owns resources, never admission: which operation
+ * holds the thread, and its cancellation, are the admission owner's, which the threads service
+ * keeps and which hands each run or compaction its signal and lease.
+ */
+export declare class ThreadActivation {
+    readonly scope: Scope;
+    readonly target: Scoped;
+    private readonly runtime;
+    private readonly loop;
+    private readiness;
+    private readonly controller;
+    private failed;
+    private prepared;
+    /** The plugin tree as it was when the activation became ready, which is what it runs with. */
+    private readyTree;
+    private staleBecause;
+    private draining;
+    private closingDone;
+    private readonly service;
+    private readonly admission;
+    readonly thread: Thread;
+    private readonly released;
+    constructor(service: ThreadsService, 
+    /** The admission owner's reads, given by the service that owns it. */
+    admission: AdmissionView, owner: Context, thread: Thread, loopServices: (scope: ScopeKey) => LoopServices, released: () => void);
+    /**
+     * From readiness on, the plugin tree is what the activation runs with. A guard on each of its
+     * plugins marks the activation stale before that plugin's disposers run, whatever unloads it: a
+     * dependency gone, a root mount disposed, a reload. Its own release marks it too, harmlessly.
+     */
+    private watchTree;
+    private markStale;
+    /**
+     * Whether the plugins changed since readiness: one unloaded or reloaded, or one added through
+     * `thread.ctx`, which is reported once. A stale activation dispatches nothing new, and the owner
+     * replaces it once the operation holding the thread settles.
+     */
+    isStale(): boolean;
+    /**
+     * Whether a setup in this activation is still running: its listeners and installations have not
+     * settled, or a plugin of its tree is in transition, one mounted later through `thread.ctx` or one
+     * reloading included. A change that waits for this activation to go, made from one of those
+     * setups, would wait on itself, so it is refused meanwhile. Not a readiness check: readiness is
+     * settled once.
+     */
+    get activating(): boolean;
+    private observe;
+    /** Aborts on release and on stop; what the activate listeners receive. */
+    get signal(): AbortSignal;
+    /** Whether readiness failed: the owner releases such an activation once its operation settles. */
+    get hasFailed(): boolean;
+    /** Set once `release()` has begun: resolves when the scope is disposed. The owner waits for it before activating again. */
+    get closed(): Promise<void> | undefined;
+    private settle;
+    /** One execution of the run `served`, under the admitted operation's signal and lease. */
+    run(options: {
+        signal: AbortSignal;
+        lease: Lease;
+        served: ServedRun;
+    }): Promise<void>;
+    /**
+     * One request to prepare the surface, under the admitted operation's signal and lease; see
+     * `Thread.compact`. Resolves with the outcome, `cancelled` when the signal aborts first.
+     */
+    compact(options: CompactOptions & {
+        signal: AbortSignal;
+        lease: Lease;
+    }): Promise<SurfacePrepareOutcome>;
+    /**
+     * Waits for readiness, settled once when the activation began, then checks the agent and records
+     * the prompt if the thread has none. Only then is the scope complete: the thread's plugins may
+     * define its agent, and an unknown one fails here, before a prompt is recorded or a turn opens,
+     * so input waits for a retry. A stale activation never gets here: the owner replaces it first.
+     */
+    private ready;
+    /**
+     * Resolves once the activation is ready: its listeners and installations settled, every plugin of
+     * its tree active. The same barrier a run uses: a settled but PENDING plugin is not ready, so a
+     * caller never reads a half-configured scope.
+     */
+    whenReady(): Promise<void>;
+    /** The owner releases scopes only after every thread has drained, including failed setup. */
+    stop(reason: Error): void;
+    /** Resolves once setup has ended, however, and every plugin mounted since is settled. */
+    whenIdle(): Promise<void>;
+    /**
+     * Disposes the scope once setup has ended. The owner calls this with no executing operation on
+     * the thread, or from the operation that is settling; the scope's own unload guard is what waits
+     * for a loop when something else disposes the scope.
+     */
+    release(): Promise<void>;
+}

package/dist/services/threadDirs.d.ts

@@ -0,0 +1,38 @@
+import { Service, type Context } from '@leuduan/cordis';
+export type ThreadDirsConfig = {
+    /**
+     * Absolute application data directory; thread directories live under `<dataDir>/threads`. `null`
+     * turns thread directories off, for a host without a filesystem of its own. Required either way.
+     */
+    dataDir: string | null;
+};
+/**
+ * Where each thread keeps files of its own: `<dataDir>/threads/<thread-id>/`, a scratch space its
+ * file tools may read and write as part of the application's shared data directory. Harness-written
+ * files go in named subdirectories such as `tool-outputs/`.
+ *
+ * The path is derived from the data directory and thread id, but absolute paths are also recorded
+ * in prompts and tool results. Keep the data directory at the same location when reopening a
+ * durable journal. Plugins can use the id supplied by their activation hook to find the directory.
+ *
+ * File tools may read and write the entire data directory, including other threads' scratch files.
+ *
+ * With `dataDir: null` there are no directories: `dataDir` and `root` are `null`, activation creates
+ * nothing, and `dirFor` and `ensure` throw. The service stays mounted either way, because the threads
+ * service injects it. A plugin that needs directories calls {@link ThreadDirsService.require} where it
+ * mounts, so a composition without them fails there.
+ */
+export declare class ThreadDirsService extends Service<ThreadDirsConfig> {
+    readonly dataDir: string | null;
+    readonly root: string | null;
+    constructor(ctx: Context, config: ThreadDirsConfig);
+    /**
+     * The data directory, for the plugin `user` that cannot work without thread directories. Call it
+     * first where the plugin mounts, so a root mounted with `dataDir: null` refuses there.
+     */
+    require(user: string): string;
+    /** The directory of `threadId`, without touching the filesystem. */
+    dirFor(threadId: string): string;
+    /** The directory of `threadId`, created if missing. */
+    ensure(threadId: string): string;
+}

package/dist/services/threadView.d.ts

@@ -0,0 +1,92 @@
+import type { ConversationMessage, PromptBlock, ToolSpec } from '../llm/index.js';
+import type { ConfirmationState, ForkPoint, InputFate, InstallationRecord, RowRef, RunOutcome, Target, WaitEntry } from '../loop/index.js';
+import type { JournalEvent, QueuedInput, Seq } from '../models/index.js';
+import type { DeepReadonly } from '../util/json.js';
+import type { Journal } from '../journal/index.js';
+import type { ReadonlyState } from '../util/foldState.js';
+/**
+ * What one thread's folds say, read synchronously (`ctx.threads.view`, `thread.read`): valid while
+ * something holds the thread in memory — a journal write or a contributor running for it, a run, a
+ * retention. Reading a thread nothing holds may find it unloaded and throws `ThreadNotLoadedError`.
+ */
+export declare class ThreadView {
+    private readonly inbox;
+    private readonly journal;
+    readonly threadId: string;
+    private readonly targetOf;
+    constructor(journal: Journal, threadId: string, targetOf: (threadId: string) => Target);
+    /**
+     * The thread's route, why it cannot run here (`blocked`), and whether a route change is accepted
+     * now (`selectable`): what a route statement is checked against (`Thread.send`). Never throws.
+     */
+    target(): Target;
+    /**
+     * The conversation as the model sees it, a fork's inherited history included. After a
+     * replacement that is the replaced view, stand-ins included; `replayLineage()` is the record.
+     */
+    transcript(): readonly ConversationMessage[];
+    /**
+     * The row behind each {@link transcript} message, index for index — what a fork anchors on. A
+     * stand-in's is the `surface/replaced` row that put it there.
+     */
+    messageSeqs(): readonly RowRef[];
+    /**
+     * The `llm/request` that produced the reply at `row`, on the thread that owns it; `null` for a
+     * row that is not a reply. Forking there regenerates the reply.
+     */
+    requestBehind(row: RowRef): RowRef | null;
+    /**
+     * The original rows a {@link messageSeqs} row stands for, in transcript order: the row itself
+     * when it is an original, and for a `surface/replaced` row, the originals behind every row it
+     * cites, followed through replacements of replacements — what a stand-in summarizes, on whichever
+     * thread holds `row`.
+     */
+    originalsBehind(row: RowRef): RowRef[];
+    /**
+     * Every turn ending along the thread's lineage, and every replacement recorded between turns,
+     * oldest first: where "fork from here" cuts.
+     */
+    forkPoints(): ForkPoint[];
+    /** The last thing the model said on the thread, if anything; see {@link lastAssistantMessage}. */
+    finalMessage(): ReadonlyState<ConversationMessage> | null;
+    /**
+     * How the run that began after `fromSeq` ended, and what it answered: a run's outcome, which an
+     * `aborted` turn ends. A delegation task is not a run and keeps its own settlement rule.
+     */
+    outcomeSince(fromSeq: Seq): RunOutcome;
+    /** The system prompt the thread sends; empty until its first turn records it. */
+    prompt(): readonly PromptBlock[];
+    /**
+     * The tool specifications `request` sent, as recorded then: thread-local tools and middleware's
+     * changes included, whatever is registered now. The request may be the thread's own or one it
+     * inherits; it is read on the thread that made it.
+     */
+    requestTools(request: JournalEvent<'llm/request'> | JournalEvent<'auxiliary/request'>): readonly ToolSpec[];
+    /** Requests waiting on the user, as owned frozen snapshots that survive later answers. */
+    pendingConfirmations(): DeepReadonly<ConfirmationState[]>;
+    /**
+     * The waits the thread declared, in declaration order, answered ones included, as owned frozen
+     * snapshots that survive later resolutions; with `owner`, only the waits declared under it. The
+     * registration named by an owner resolves its waits; a read never does.
+     */
+    waits(options?: {
+        readonly owner?: string;
+    }): readonly Readonly<WaitEntry>[];
+    /** The thread's own rows so far: what `thread.on` would have delivered. */
+    replay(): readonly JournalEvent[];
+    /**
+     * A fork's inherited rows, then its own, each with its original thread id and seq — what a
+     * frontend replays to show a fork's whole history. The same as `replay()` for a thread that is
+     * not a fork.
+     */
+    replayLineage(): readonly JournalEvent[];
+    /** Input waiting for a step to claim it, in the order it was sent. */
+    queued(): readonly QueuedInput[];
+    /**
+     * What became of the input `inputId`: never handed to this thread, queued, claimed by a step, or
+     * discarded unclaimed; see {@link InputFate}.
+     */
+    input(inputId: string): InputFate;
+    /** The thread's preset installations in recorded order, as readonly snapshots. */
+    installations(): readonly InstallationRecord[];
+}