@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/services/threads/thread.d.ts

@@ -0,0 +1,268 @@
+import type { Context } from '@leuduan/cordis';
+import type { AppendEntry, Journal } from '../../journal/index.js';
+import type { PromptBlock } from '../../llm/prompt.js';
+import type { CompactOptions, StreamedChunk, SurfacePrepareOutcome } from '../../loop/index.js';
+import type { RouteStatement, RowRef, SendOptions, SendOutcome, WithdrawOptions, WithdrawOutcome } from '../../state/index.js';
+import type { CancelIntent, JournalEvent, ThreadInput, ThreadOrigin, ThreadSummary, TurnEndReason } from '../../records/journal.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 './service.js';
+import type { ThreadView } from './view.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/threads/view.d.ts

@@ -0,0 +1,93 @@
+import type { ConversationMessage, ToolSpec } from '../../llm/primitives.js';
+import type { PromptBlock } from '../../llm/prompt.js';
+import type { ConfirmationState, ForkPoint, InputFate, InstallationRecord, RowRef, RunOutcome, Target, WaitEntry } from '../../state/index.js';
+import type { JournalEvent, QueuedInput, Seq } from '../../records/journal.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[];
+}

package/dist/services/tools.d.ts

@@ -0,0 +1,118 @@
+import { Context, Service, type ScopeKey } from '@leuduan/cordis';
+import { z } from 'zod';
+import { type AgentSelector } from './agents.js';
+import { type Tool, type ToolEntry, type InvocationContext, type ToolExecutionMode, type WaitRequest } from '../loop/index.js';
+import { type InterruptionPolicy } from '../records/journal.js';
+import { type ParsedToolCall, type ToolCall } from '../llm/primitives.js';
+import { type ToolResult, type ToolResultPayloadInput } from '../records/toolResult.js';
+import type { JsonValue } from '../util/json.js';
+/**
+ * The tools this process can offer, and who may call them. Live: a tool or a grant lasts
+ * exactly as long as the plugin that registered it, and an agent's reachable set is resolved when a
+ * request is built, never captured earlier. Untagged registrations are global; scoped registrations
+ * are visible from that scope and its descendants. The closest definition of a name wins.
+ *
+ * What an agent may call is exactly what it is granted. A grant holds the selector it was made
+ * with and is matched against the agent asking, so a grant to `'global'` or `'all'` keeps up with
+ * agents registered after it, and a grant may name a tool or an agent that does not exist yet; it
+ * simply resolves to nothing until they do. A scoped agent is reached only by grants naming it or
+ * by `'all'` (`selects`).
+ */
+export declare class ToolsService extends Service {
+    static inject: string[];
+    private readonly layers;
+    constructor(ctx: Context);
+    /** Registered tool names visible from `scope`, sorted and deduplicated. */
+    names(scope: ScopeKey | undefined): string[];
+    has(scope: ScopeKey | undefined, name: string): boolean;
+    /** The closest registered definition of `name`, then the global fallback. */
+    get(scope: ScopeKey | undefined, name: string): ToolEntry | undefined;
+    /**
+     * Adds a tool to one layer; returns the unregister function. Duplicates fail within that layer,
+     * and so does a tool that does not say what a re-dispatch after an interruption may do: the
+     * declaration has no default, and a missing one would surface as a schema error mid-turn.
+     */
+    register(scope: ScopeKey | undefined, name: string, tool: Tool): () => void;
+    /** Lets the agents `agents` selects call `toolName` in one layer; returns the revoke function. */
+    grant(scope: ScopeKey | undefined, agents: AgentSelector, toolName: string): () => void;
+    /**
+     * What `agentName` may call right now: its global-to-local grants in registration order, each name
+     * once, names nothing answers to skipped. Throws for an agent unknown from `scope`.
+     */
+    toolsFor(scope: ScopeKey | undefined, agentName: string): ToolEntry[];
+    /** One tool `agentName` may call, or `undefined` when it is unknown or not granted. */
+    toolFor(scope: ScopeKey | undefined, agentName: string, toolName: string): ToolEntry | undefined;
+    mayCall(scope: ScopeKey | undefined, agentName: string, toolName: string): boolean;
+}
+/**
+ * Parameters described elsewhere, as JSON schema: advertised as given and handed to `execute`
+ * unvalidated, for a tool whose real validator is someone else's, such as an MCP server.
+ */
+export type JsonSchemaParameters = {
+    readonly jsonSchema: Record<string, JsonValue>;
+};
+type ParametersOf<P> = P extends z.ZodType ? z.output<P> : Record<string, unknown>;
+/** What `execute` returns: a result with `is_error`, `notes` and `metadata` optional, or a wait (`waitFor`). */
+export type ToolReply = ToolResultPayloadInput | WaitRequest;
+/** One tool, as {@link defineTool} takes it. */
+export type ToolDefinition<P extends z.ZodType | JsonSchemaParameters> = {
+    /** The name it is registered under, and advertised to the model by. */
+    readonly name: string;
+    /** One paragraph advertised to the model. */
+    readonly description: string;
+    /** A zod schema the arguments are validated against and advertised from, or JSON schema. */
+    readonly parameters: P;
+    /**
+     * What a re-dispatch may do with a call that may have begun when its turn was interrupted; see
+     * `Tool.onInterrupted`. Every tool says which; there is no default.
+     */
+    readonly onInterrupted: InterruptionPolicy;
+    /** Whether a call may overlap its batch's others; see `Tool.executionMode`. No default either. */
+    readonly executionMode: ToolExecutionMode;
+    /** Runs one call. A throw becomes an `is_error` result: a tool never fails a turn. */
+    execute(parameters: ParametersOf<P>, context: InvocationContext, call: ParsedToolCall): Promise<ToolReply>;
+};
+/**
+ * Defines a tool: the one way to write one. Arguments are validated against `parameters` when it is
+ * a zod schema, and a validation failure or a throw from `execute` becomes an `is_error` result, so
+ * a tool can never crash a turn; the result is timed. A tool that needs configuration closes over it.
+ *
+ * ```ts
+ * const echo = defineTool({
+ *   name: 'echo',
+ *   description: 'Repeat the text.',
+ *   parameters: z.strictObject({ text: z.string() }),
+ *   onInterrupted: 'rerun',
+ *   executionMode: 'parallel',
+ *   execute: async ({ text }) => ({ output: text }),
+ * })
+ * ```
+ */
+export declare function defineTool<P extends z.ZodType | JsonSchemaParameters>(definition: ToolDefinition<P>): Tool;
+/**
+ * Offers `tool` in the calling plugin's scope for the life of its fiber, and grants it to the agents
+ * `agents` selects when given; without them it is registered for a grant elsewhere, a preset's say.
+ * Returns the disposer.
+ */
+export declare function registerTool(ctx: Context, tool: Tool, options?: {
+    readonly agents?: AgentSelector;
+}): () => void | Promise<void>;
+/**
+ * {@link registerTool} for each of `tools`, then a prompt instruction under `tag` for every agent that
+ * is granted one of them: the `guidance` of each granted tool, in tool order, and nothing when none
+ * is granted or none has any.
+ */
+export declare function registerTools(ctx: Context, tools: readonly Tool[], options: {
+    readonly tag: string;
+    readonly guidance: ReadonlyMap<string, string>;
+}): void;
+/** A tool's result for `call`, its defaults applied and its duration recorded. */
+export declare function toToolResult(call: ToolCall, reply: ToolResultPayloadInput, startedAt: number): ToolResult;
+export { errorResult } from '../loop/index.js';
+/**
+ * Grants `toolName` to the agents `agents` selects, for the life of the calling plugin's fiber, or
+ * until the returned disposer runs. The selector is stored as given: registries are live, so
+ * a grant to `'global'` or `'all'` is matched against each agent when it asks, agents registered
+ * later included.
+ */
+export declare function grantTool(ctx: Context, toolName: string, agents: AgentSelector): () => void | Promise<void>;

package/dist/state/birth.d.ts

@@ -0,0 +1,62 @@
+import type { ModelRoute } from '../llm/provider.js';
+import type { InitialInstallation, JournalEvent, Seq, ThreadEnvironment, ThreadFork, ThreadOrigin } from '../records/journal.js';
+import type { DeepReadonly } from '../util/json.js';
+import type { RowRef } from './surface.js';
+import type { Reducer } from './thread.js';
+/**
+ * What a fresh thread is born with, as its spawn row records it: the one value `create` resolves a
+ * birth to, whichever source it came from, and the one a reused thread is compared on. `installations`
+ * holds all of them, handed down ones included, each with its lifetime; `requires` is a set, kept
+ * sorted and without repeats.
+ */
+export type BirthSpec = DeepReadonly<{
+    route: ModelRoute;
+    environment: ThreadEnvironment;
+    installations: InitialInstallation[];
+    requires: string[];
+}>;
+/**
+ * A fresh thread as a write-time callback sees it: the agent it is born on, the origin it records
+ * (`null` for a root) and its {@link BirthSpec}.
+ */
+export type FreshOpening = {
+    agent: string;
+    origin: ThreadOrigin | null;
+    spec: BirthSpec;
+};
+/**
+ * A fork as a write-time callback sees it: its agent (the cut's thread's), the origin it records
+ * and the cut it continues from, its own environment and constraint owners as its spawn row records
+ * them, and `inherits`, what it goes on with from the cut and does not record: the route and the
+ * installations at that row.
+ */
+export type ForkOpening = {
+    agent: string;
+    origin: ThreadOrigin | null;
+    cut: RowRef;
+    environment: ThreadEnvironment;
+    requires: string[];
+    inherits: {
+        route: ModelRoute;
+        installations: InitialInstallation[];
+    };
+};
+export type ThreadRecord = {
+    thread_id: string;
+    agent_name: string;
+    metadata: JournalEvent<'thread/spawned'>['data']['metadata'];
+    /** The source thread and row this thread was forked at; `null` unless it is a fork. */
+    fork: ThreadFork | null;
+    origin: ThreadOrigin | null;
+    environment: ThreadEnvironment;
+    /** The constraint owners the thread's runs are under. */
+    requires: readonly string[];
+    /** The `thread/spawned` row. */
+    seq: Seq;
+};
+/**
+ * A thread's identity, lineage and environment, from its spawn row. A fork's lineage replays its
+ * source's spawn row first and its own after it, so the fork's record is its own. The set of all
+ * threads is the journal's catalog, not a fold.
+ */
+export declare const threadRecord: Reducer<ThreadRecord | null>;

package/dist/state/chain.d.ts

@@ -0,0 +1,46 @@
+import type { RunChain, Seq } from '../records/journal.js';
+import type { Reducer } from './thread.js';
+/** An inputless cause not yet consumed: the run whose next turn it classifies, `null` once carried. */
+type InputlessCause = {
+    readonly seq: Seq;
+    readonly runId: string | null;
+    readonly chain: RunChain;
+};
+/**
+ * A thread's chain of unattended work, folded from its causes, claims and turns: core's
+ * {@link ChainState} concern of `threadState`, which a fork starts over.
+ *
+ * The rules, a turn's class and the count of reactive turns in a row, are in
+ * `docs/guides/threads.md#the-chain`. What only this fold fixes: a later weaker claim never lowers a
+ * class, a request extended while it runs is not a claim, and the count is provisional while a
+ * `reactive` turn is open and final at its `turn/end`, by the class it ended with.
+ */
+export type ChainState = {
+    /** The chain a cause with an input named, by input id, until a step claims that input or it is discarded. */
+    readonly byInput: Map<string, RunChain>;
+    /**
+     * Inputless causes not consumed yet, in order. Each is consumed once, by the first turn on its
+     * run that opens after it; a settlement carries the ones it names as residual to the successor,
+     * and the rest retire.
+     */
+    inputless: readonly InputlessCause[];
+    /** The turn open, if any, and the strongest class it received. */
+    open: {
+        readonly turn: number;
+        readonly class: RunChain | null;
+    } | null;
+    /** Reactive turns in a row since the last `person` or `fresh` authority, committed ones only. */
+    count: number;
+};
+export declare const chain: Reducer<ChainState>;
+/** Where a thread's chain stands, as `ctx.threads.chain` reads it. */
+export type ChainStanding = {
+    /** Whether the turn open now has received a person's authority; `false` between turns. */
+    readonly personTurn: boolean;
+    /** Reactive turns in a row, the open one counted if it is reactive. */
+    readonly turns: number;
+    /** Whether `turns` has reached the limit: a producer of more unattended work is refused. */
+    readonly atLimit: boolean;
+};
+export declare function chainStanding(state: ChainState, limit: number): ChainStanding;
+export {};

package/dist/state/confirmations.d.ts

@@ -0,0 +1,64 @@
+import type { JournalEvent, Seq } from '../records/journal.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import type { ParsedToolCall } from '../llm/primitives.js';
+import type { Reducer, ThreadState } from './thread.js';
+import { type WaitEntry } from './waits.js';
+export type ConfirmationState = {
+    request_id: string;
+    thread_id: string;
+    /** The exact model `tool/call` or runtime `execution/requested` row being approved. */
+    target: JournalEvent<'confirm/requested'>['data']['target'];
+    tool_call: ParsedToolCall;
+    reason: string;
+    resolution: {
+        approved: boolean;
+        rejection_message: string | null;
+    } | null;
+};
+/**
+ * A thread's confirmation requests and their answers, keyed by request id. Thread-scoped: an answer
+ * is written on the thread that asked, so a thread's confirmations are a function of its own rows.
+ * A fork starts with none: a fork is never cut with a request still open, and an inherited answer
+ * belongs to a call the source already finished.
+ */
+export declare const confirmations: Reducer<Map<string, ConfirmationState>>;
+/** One runtime-owned operation and its authorization/result, reconstructed without redispatch. */
+export type RuntimeExecution = {
+    seq: Seq;
+    request: JournalEvent<'execution/requested'>['data'];
+    authorization: {
+        seq: Seq;
+        data: JournalEvent<'execution/authorization'>['data'];
+    } | null;
+    result: {
+        seq: Seq;
+        value: JournalEvent<'execution/result'>['data']['result'];
+    } | null;
+};
+export declare const executions: Reducer<Map<Seq, RuntimeExecution>>;
+/** Requests still waiting on the user on one thread. */
+export declare const outstandingConfirmations: (state: ReadonlyMap<string, ReadonlyState<ConfirmationState>>, threadId: string) => ReadonlyState<ConfirmationState>[];
+/**
+ * Model dispatches held by a pending confirmation or unresolved wait, by durable sequence.
+ * These holds survive turns: dispatching again before the answer or value would only raise a
+ * second request, or declare the wait twice.
+ */
+export declare const parkedCallSeqs: (confirmationState: ReadonlyMap<string, ReadonlyState<ConfirmationState>>, waitState: ReadonlyMap<Seq, WaitEntry>, threadId: string) => Set<Seq>;
+/**
+ * The confirmation of one durable dispatch, pending or answered. Model and runtime dispatch share
+ * this lookup; a provider's call ID, request ID or source citation never grants approval authority.
+ */
+export declare const confirmationFor: (state: ReadonlyMap<string, ReadonlyState<ConfirmationState>>, dispatch: {
+    threadId: string;
+    target: ConfirmationState["target"];
+}) => ReadonlyState<ConfirmationState> | undefined;
+/** The thread's latest `confirm/resolved` row, or `null`: what tells a parked caller an answer landed under it. */
+export declare const lastAnswer: Reducer<Seq | null>;
+/**
+ * Confirmations on `threadId` whose call has no result yet and was not rejected: still waiting on the
+ * user, or approved. An approval lasts until the call's result: the call runs at the next turn, and
+ * one that waits or is cut off runs again on the same approval, against whatever tool answers to its
+ * name by then. Runtime approval belongs to its pending candidate; once that candidate is rejected
+ * or superseded it no longer blocks configuration. Unknown command cleanup is accounted separately.
+ */
+export declare function unfinishedConfirmations(state: ReadonlyState<Pick<ThreadState, 'confirmations' | 'executions' | 'answerCheck' | 'dispatchedCalls'>>, threadId: string): ReadonlyState<ConfirmationState>[];