@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/sys/spawn.d.ts

@@ -0,0 +1,176 @@
+import type { Readable, Writable } from 'node:stream';
+/**
+ * Process containment for everything lagent runs: one process group per command, a bounded stop,
+ * and cleanup however lagent ends. POSIX only.
+ *
+ * Every command is spawned detached, so it leads a new session and process group whose id is its
+ * pid, with no controlling terminal. A short `/bin/sh` wrapper holds it at a startup gate until the
+ * group is registered with the exit listener and the reaper, joins stderr into stdout unless the
+ * streams are wired as separate pipes, and then `exec`s the command, so the leader keeps the pid
+ * and therefore the group. If lagent dies before the gate opens, the wrapper reads EOF and runs
+ * nothing. Nothing is inherited implicitly: every spawn names its whole environment.
+ *
+ * Process-wide, because process exit is: the exit listener and the reaper are installed with the
+ * first spawn and shared by every root in the process. Stopping commands while the process lives
+ * is their owners' job, through the signal every spawn requires.
+ */
+/** How long SIGTERM gets before SIGKILL, and SIGKILL before a stop is reported failed. */
+export declare const DEFAULT_KILL_GRACE_MS = 3000;
+/**
+ * A process's whole environment; an `undefined` value leaves the variable unset. lagent never
+ * builds one from its own: a host does (`sys/environment`), and every spawn passes one.
+ */
+export type SpawnEnvironment = Readonly<Record<string, string | undefined>>;
+/**
+ * How the command's standard streams are wired. `joined`: no input, and stderr joined into stdout
+ * as one `output` stream, in exact order. `pipes`: a writable stdin and separate stdout and stderr,
+ * for a process that speaks a protocol on its standard streams.
+ */
+export type SpawnStdio = 'joined' | 'pipes';
+export type SpawnOptions = {
+    /** A shell command line, run by `/bin/sh -c`, or an argv run without a shell. */
+    command: string | readonly [string, ...string[]];
+    cwd: string;
+    /**
+     * The command's whole environment, passed as it is. An argv's program is resolved through its
+     * `PATH`, or the shell's default search path when it has none.
+     */
+    env: SpawnEnvironment;
+    /** Defaults to `joined`. */
+    stdio?: SpawnStdio;
+    /** The owner: aborting it stops the command's group within the bound. */
+    signal: AbortSignal;
+    /** Stops the group when this elapses; omitted for a command meant to outlive its call. */
+    timeoutMs?: number;
+    killGraceMs?: number;
+    /**
+     * Awaited after the group is registered and before the gate opens, with the group's id: what a
+     * caller must have durable before the command runs — a record that it may have started, say — goes
+     * here. A rejection kills the group, which has run nothing, and rejects the spawn.
+     */
+    beforeRelease?: (pgid: number) => void | Promise<void>;
+};
+/** Why lagent stopped a group: its deadline, its owner's signal, or an explicit `stop()`. */
+export type StopCause = 'timeout' | 'abort' | 'stop';
+export type SpawnResult = {
+    /** `null` when the leader never exited, or was killed by a signal. */
+    exitCode: number | null;
+    exitSignal: NodeJS.Signals | null;
+    /** `null` when the leader exited on its own. */
+    stoppedBy: StopCause | null;
+    /** The leader exited leaving processes in its group, and they were stopped. */
+    leftoversStopped: boolean;
+    /**
+     * A live process remained in the group when the bound ran out. The group stays tracked by the
+     * exit listener and the reaper, and is polled until it empties.
+     */
+    stopFailed: boolean;
+    durationMs: number;
+};
+/** A spawned process group, whichever way its streams are wired. */
+export interface SpawnedGroup {
+    readonly pid: number;
+    /**
+     * Settles within `2 × killGraceMs` of the deadline, the abort, `stop()`, or the leader exiting
+     * with processes left behind, and sooner once the leader, the group and the pipe are all done.
+     * Never rejects.
+     */
+    readonly result: Promise<SpawnResult>;
+    /** Stops the group, as an abort would, and resolves with `result`. */
+    stop(): Promise<SpawnResult>;
+}
+/** A group spawned with `stdio: 'joined'`. */
+export interface SpawnedCommand extends SpawnedGroup {
+    /** stdout with stderr joined, in exact order. Destroyed once the command settles. */
+    readonly output: Readable;
+}
+/**
+ * A group spawned with `stdio: 'pipes'`. Every stream is destroyed once the command settles.
+ *
+ * Read stdout and stderr continuously, from the start, even when only one matters. A child blocks
+ * on a write once that pipe's buffer fills, so an unread stderr eventually hangs a process that
+ * only logs to it. Keep a bounded tail if the content is not needed.
+ */
+export interface SpawnedPipes extends SpawnedGroup {
+    readonly stdin: Writable;
+    readonly stdout: Readable;
+    readonly stderr: Readable;
+}
+/**
+ * Spawns a command in a process group of its own. Resolves once the group is registered,
+ * `beforeRelease` has settled and the command released; rejects, having run nothing, when it cannot
+ * be spawned or registered, when `beforeRelease` rejects, or when `signal` aborts first.
+ */
+export declare function spawnCommand(options: SpawnOptions & {
+    stdio?: 'joined';
+}): Promise<SpawnedCommand>;
+export declare function spawnCommand(options: SpawnOptions & {
+    stdio: 'pipes';
+}): Promise<SpawnedPipes>;
+export declare function spawnCommand(options: SpawnOptions): Promise<SpawnedCommand | SpawnedPipes>;
+/**
+ * Runs a command to completion and collects its output: for tools that need a command's answer,
+ * not its stream. Output is held in memory, so use it only for commands whose output is bounded.
+ */
+export declare function runToCompletion(options: SpawnOptions & {
+    stdio?: 'joined';
+}): Promise<SpawnResult & {
+    output: string;
+}>;
+/** How {@link runLines} hands a command's stdout over. */
+export type LineReader = {
+    /**
+     * Called with each line of stdout, without its delimiter, as it arrives. Returning `false` stops the
+     * group: no later line is delivered, and the result reports `stoppedBy: 'stop'`.
+     */
+    onLine: (line: string, clipped: boolean) => boolean | void;
+    /**
+     * What ends a line: a newline, or NUL for output whose records may hold a newline, such as paths
+     * printed with `--null`.
+     */
+    delimiter: '\n' | '\0';
+    /** A longer line reaches `onLine` cut to this many characters, with `clipped` set; the rest is never held. */
+    maxLineChars: number;
+};
+/**
+ * Runs a command and hands its stdout to `onLine` line by line, holding at most one line: for
+ * output whose size is not bounded, such as a search's, where the caller stops the command once it
+ * has what it needs. The command gets no input. stderr is read separately and kept as a bounded
+ * tail, for diagnostics.
+ */
+export declare function runLines(options: Omit<SpawnOptions, 'stdio' | 'beforeRelease'> & LineReader): Promise<SpawnResult & {
+    stderr: string;
+}>;
+/** Whether any process remains in the group; a zombie still counts. */
+export declare function groupAlive(pgid: number): boolean;
+/** Live groups, as the exit listener and the reaper know them. One per process. */
+declare class Containment {
+    private readonly groups;
+    private readonly stuck;
+    private reaper;
+    private exitListener;
+    private watcher;
+    /**
+     * Adds a group to the exit listener's set and the reaper's. A reaper that died is replaced and
+     * given every live group; this fails only when its replacement fails too.
+     */
+    register(pgid: number): Promise<void>;
+    /** Forgets a group proven empty. A reaper that misses the line is replaced from `groups` anyway. */
+    unregister(pgid: number): void;
+    /** Keeps a group whose stop failed tracked, polling it until it empties. */
+    watchUntilEmpty(pgid: number): void;
+    /** The groups currently tracked, for tests and diagnostics. */
+    tracked(): number[];
+    /** The current reaper's pid, for tests. */
+    reaperPid(): number | undefined;
+    /** Kills the current reaper, as the OOM killer might, for tests. */
+    killReaper(): void;
+    private ensureReaper;
+    /** A reaper that died while lagent lives is replaced at once, seeded with every live group. */
+    private onReaperExit;
+    /** Node runs nothing asynchronous in `exit`, so this is a synchronous SIGKILL of every live group. */
+    private installExitListener;
+}
+/** The process's containment state; exported for tests. */
+export declare const containment: Containment;
+export {};

package/dist/testing/clock.d.ts

@@ -0,0 +1,17 @@
+import type { Clock } from '../kit/timers.js';
+/**
+ * A {@link Clock} a test moves by hand. Wall time and elapsed time move apart: `advance` moves
+ * both, as time passing does; `jump` sets the wall clock forward or back without any timer
+ * noticing, as a clock change does; `elapse` lets timers run without the wall clock moving.
+ */
+export type ManualClock = Clock & {
+    /** Lets `ms` pass: the wall clock moves, and every timer due by then fires, in order. */
+    advance(ms: number): void;
+    /** Moves the wall clock by `ms`, either way; no timer fires. */
+    jump(ms: number): void;
+    /** Lets `ms` of timer time pass with the wall clock standing still. */
+    elapse(ms: number): void;
+    /** The delay of each pending timer from now, soonest first. */
+    pending(): number[];
+};
+export declare function manualClock(start?: number): ManualClock;

package/dist/testing/fakeLlm.d.ts

@@ -0,0 +1,74 @@
+import type { z } from 'zod';
+import type { ConversationMessage, LLMClient, LLMStreamChunk, MalformedToolCall, ModelRequest, ModelResponse, ResponseFinish, StreamingLLMResponse } from '../llm/index.js';
+import { LLMStreamChunkSchema } from '../llm/index.js';
+/** A chunk as a test writes one: anything the schema defaults may be left out. */
+export type FakeChunk = z.input<typeof LLMStreamChunkSchema>;
+/** Every request the fake was handed, exactly as the loop built it. */
+export type FakeChatRequest = ModelRequest;
+/**
+ * A canned reply: a message, a message streamed as `chunks`, or `chunks` followed by a `failure`
+ * that `completed()` throws, as an adapter throws a `ResponseSettlementError` for a response it
+ * could not settle.
+ */
+export type FakeChatReply = ConversationMessage | {
+    chunks: FakeChunk[];
+    message: ConversationMessage;
+} | {
+    chunks: FakeChunk[];
+    failure: Error;
+};
+export type FakeChatHandler = (messages: ModelRequest['messages'], request: ModelRequest) => FakeChatReply | Promise<FakeChatReply>;
+/** How a {@link FakeStream} settles: with the message, with a whole response, or by throwing the failure. */
+type FakeSettlement = ConversationMessage | ModelResponse | Error;
+export interface FakeStreamOptions {
+    readonly finish?: ResponseFinish;
+    readonly readFailure?: boolean;
+}
+/**
+ * A response stream that keeps the reader rules a real adapter does (see `StreamingLLMResponse`): it
+ * is read once, `completed()` drains it when unread, reports the outcome of a read that ended (a
+ * failed read throws its failure again) and throws while a read is under way. `chunks` is any
+ * source, so a test can feed one live; `settled` is what `completed()` gives for a read that ran
+ * through or was left early, read when asked so it can depend on the source: a message (or a whole
+ * response, finish included), or an error thrown as an adapter throws a `ResponseSettlementError`. `options.readFailure` makes the error be
+ * thrown by the read, after the chunks, as a transport failure is; `options.finish` is the reply's
+ * finish, `completed` otherwise. Unlike a real adapter, a reader that left early still gets the whole
+ * message.
+ */
+export declare class FakeStream implements StreamingLLMResponse {
+    private claimed;
+    private readonly ledger;
+    private failure;
+    private readonly chunks;
+    private readonly settled;
+    private readonly options;
+    constructor(chunks: Iterable<FakeChunk> | AsyncIterable<FakeChunk>, settled: FakeSettlement | (() => FakeSettlement), options?: FakeStreamOptions);
+    [Symbol.asyncIterator](): AsyncIterator<LLMStreamChunk>;
+    private read;
+    private settlement;
+    completed(): Promise<ModelResponse>;
+}
+/** Scripted stand-in for an LLM provider: the handler inspects the conversation and picks a canned reply. */
+export declare class FakeLLMClient implements LLMClient {
+    readonly providerName = "fake";
+    readonly requests: FakeChatRequest[];
+    private readonly handler;
+    constructor(handler: FakeChatHandler);
+    /** Replies in order; an extra call throws so unexpected loops fail loudly. */
+    static scripted(...responses: ConversationMessage[]): FakeLLMClient;
+    chat(request: ModelRequest): Promise<StreamingLLMResponse>;
+}
+export declare const assistant: (content: string, extra?: Partial<ConversationMessage>) => ConversationMessage;
+/** A reply asking for `toolCalls`; omitted arguments are `{}`, and a malformed call stays malformed. */
+export declare const withToolCalls: (toolCalls: ({
+    call_id: string;
+    name: string;
+    arguments?: Record<string, unknown>;
+} | MalformedToolCall)[], content?: string | null) => ConversationMessage;
+/**
+ * A response that streams one chunk, calls `streamed`, and then waits until `request` is aborted
+ * without ending: a connection that goes quiet mid-response. A test that restarts the host while it
+ * waits finds the model request unanswered.
+ */
+export declare function stallingStream(request: ModelRequest, streamed: () => void): FakeStream;
+export {};

package/dist/testing/fedLlm.d.ts

@@ -0,0 +1,32 @@
+import type { ConversationMessage, LLMClient, ModelRequest, StreamingLLMResponse } from '../llm/index.js';
+import { type FakeChunk } from './fakeLlm.js';
+/** One model call whose stream the test feeds: `push` chunks, then `finish` or `fail`. */
+export declare class FedCall {
+    readonly request: ModelRequest;
+    private readonly queue;
+    private ended;
+    /** The text fed so far, which a cut-off reply carries. */
+    private text;
+    private wake;
+    constructor(request: ModelRequest);
+    push(chunk: FakeChunk): void;
+    finish(content: string, extra?: Partial<ConversationMessage>): void;
+    fail(error: unknown): void;
+    /**
+     * Reads what the test feeds, as a response stream keeps the reader rules: a failure ends the read
+     * and is what `completed()` throws, a cancel ends it quietly with what arrived as a cut-off reply,
+     * and a reader that stops before `finish` gets no answer.
+     */
+    readonly stream: StreamingLLMResponse;
+    private feed;
+}
+/** A provider whose every call is a {@link FedCall}, handed to the test in order. */
+export declare class FedLLM implements LLMClient {
+    readonly providerName = "fake";
+    readonly calls: FedCall[];
+    private readonly waiting;
+    private taken;
+    chat(request: ModelRequest): Promise<StreamingLLMResponse>;
+    /** The next call the loop makes, once it has made it. */
+    next(): Promise<FedCall>;
+}

package/dist/testing/helpers.d.ts

@@ -0,0 +1,344 @@
+import { Context, type Plugin } from '@leuduan/cordis';
+import { Journal, type CoreFold, type JournalStore, type PluginJournal, type Summarizer } from '../journal/index.js';
+import type { ConfirmationState, InvocationContext, RouteStatement, ResolvedWait, RowRef, SendOutcome, Tool, TurnLimits } from '../loop/index.js';
+import type { ConversationMessage, FailureClassification, LLMClient, ModelCapacity, ModelRequest, ModelRoute, PromptBlock, ThinkingEffort } from '../llm/index.js';
+import type { DeepReadonly, ReadonlyJsonValue } from '../util/json.js';
+import type { AgentDefinitionInput, ExtensionRecord, JournalEvent, Seq, ThreadOrigin, ThreadSummary, TurnEndReason } from '../models/index.js';
+import { type TrustedPrograms } from '../sys/environment.js';
+import { MemoryJournalStore } from '../plugins/store/memory.js';
+import { type PromptContribution } from '../services/prompts.js';
+import { type RetryPolicy } from '../services/llm.js';
+import type { Thread } from '../services/thread.js';
+import type { BirthInput, CreateThreadOptions, Opening } from '../services/birth.js';
+import type { InitialInstallationInput } from '../services/presets.js';
+import type { OwnerHandle, StartOptions } from '../services/owner.js';
+import type { DelegationsConfig } from '../plugins/delegations/service.js';
+import type { ThreadView } from '../services/threadView.js';
+import { ownedTmpDir, tmpWorkspace } from './tmpDirs.js';
+/**
+ * A provider plugin that hands out one fixed client, for tests and embedding. Like the real ones,
+ * it takes an optional default thinking effort; it declares what `capacity` answers, by default no
+ * window, no provider-executed tools and no images in tool results, and classifies every failure
+ * the engine's typed evidence leaves to it as `classify` says, by default `other`.
+ */
+export declare const fakeProvider: (client: LLMClient, name?: string) => Plugin.Object<{
+    thinkingEffort?: ThinkingEffort;
+    capacity?: (model: string) => ModelCapacity;
+    classify?: (error: unknown) => FailureClassification;
+    retry?: RetryPolicy;
+} | undefined>;
+/** The route of the fake provider a test root registers: what a test thread is born on. */
+export declare const TEST_ROUTE: ModelRoute;
+/** The retry policy a test provider gets unless it asks for one: a call is never sent twice. */
+export declare const NO_RETRY: RetryPolicy;
+export type TestRootOptions = {
+    llm: LLMClient;
+    /** Start from an existing journal, as reopening does. */
+    store?: JournalStore;
+    cwd?: string;
+    /** Where thread directories live; a temporary directory, removed with the root, when omitted; `null` for none. */
+    dataDir?: string | null;
+    limits?: Partial<TurnLimits>;
+    /** Agents to register, each granted its `tools`; one `main_agent` that can read files when omitted. */
+    agents?: readonly TestAgent[];
+    /** Tools to register; just the test reader when omitted. */
+    tools?: readonly TestToolEntry[];
+    /** What the fake provider declares it can carry; no window when omitted. */
+    capacity?: (model: string) => ModelCapacity;
+    /** How the fake provider classifies a failure the engine's typed evidence leaves to it; `other` when omitted. */
+    classify?: (error: unknown) => FailureClassification;
+    /** How the fake provider's calls are retried; never when omitted. */
+    retry?: RetryPolicy;
+    /**
+     * `defer` leaves `ctx.threads.start` to the test, which calls it once after composing what it
+     * mounts beside: a reopened journal's recovered runs would otherwise start before it. Started at
+     * once, with every pending run resumed, when omitted.
+     */
+    start?: 'defer';
+    /**
+     * What the threads service does with a thread nothing holds any more. `keep` when omitted, so a
+     * test reads a thread's rows after its run; a host's test passes what the host configures.
+     */
+    retention?: 'retire' | 'keep';
+    /** How many reactive turns in a row a thread may run; {@link TEST_CHAIN_LIMIT} when omitted. */
+    chainLimit?: number;
+    /**
+     * `manual` leaves disposing the root to the caller, for one that a whole file's tests share, such
+     * as a root holding a process-wide service. Disposed when the test that made it finishes when omitted.
+     */
+    disposal?: 'manual';
+};
+/** The chain limit a test root gets unless it asks for one: room for any test's notices. */
+export declare const TEST_CHAIN_LIMIT = 10;
+/** How a test root starts: every pending run resumed, with room for every thread a test runs. */
+export declare const TEST_START: StartOptions;
+/** `Omit` over each member of a union, which a plain `Omit` would collapse into one object type. */
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+type BirthFields = Partial<BirthInput<InitialInstallationInput>>;
+/**
+ * A fresh thread's `birth` on {@link TEST_ROUTE} from `defaults`, with `fields` beside its route, in
+ * the shape `create` takes. `from: 'caller'` says the birth reads the origin's live caller instead,
+ * which the options then name an `origin` for.
+ */
+export declare function testBirth(fields?: BirthFields): {
+    from: 'defaults';
+} & BirthInput<InitialInstallationInput>;
+export declare function testBirth(fields: BirthFields & {
+    from: 'caller';
+}): {
+    from: 'caller';
+} & BirthInput<InitialInstallationInput>;
+/**
+ * What {@link TestRoot.newThread} takes: `create`'s options, with a fresh id and `main_agent`.
+ * `reuse` and `birth`, given together as `create` takes them, default as a whole to `identity`
+ * reuse of {@link testBirth}`()`.
+ */
+export type TestThreadOptions = Omit<Opening, 'id'> & {
+    /** A fresh id is generated when omitted. */
+    id?: string;
+    /** `main_agent` when omitted. */
+    agent?: string;
+} & ({
+    reuse?: undefined;
+    birth?: undefined;
+    origin?: undefined;
+} | DistributiveOmit<CreateThreadOptions, keyof Opening>);
+export type TestRoot = Context & {
+    /** Every journal event appended since the root was made. */
+    appended: JournalEvent[];
+    /** `threads.create` with a fresh id and test defaults: `main_agent`, born on {@link TEST_ROUTE} (see {@link TestThreadOptions}). */
+    newThread(options?: TestThreadOptions): Promise<Thread>;
+};
+/**
+ * A root with the core, a fake provider, and the given agents and tools mounted. It lives as long
+ * as the test that made it, in its body or a `beforeEach`: disposed once that test finishes, unless
+ * the test disposed it before.
+ */
+export declare function createTestRoot(options: TestRootOptions): Promise<TestRoot>;
+/**
+ * The spawn environment tests run programs with: this process's, filtered as the hosts filter
+ * theirs. Tests are the host here, so they may read `process.env`.
+ */
+export declare const testEnvironment: () => Record<string, string>;
+/** The trusted programs tests run, found on this process's `PATH`. */
+export declare const testPrograms: () => TrustedPrograms;
+/** Minimal file reader so loop tests can exercise the tool path without the builtin tools. */
+export declare const testReadFileTool: Tool;
+export type TestToolEntry = {
+    name: string;
+    tool: Tool;
+};
+/** The default tool set for loop tests: just the reader. */
+export declare const testTools: () => TestToolEntry[];
+/** An agent definition and the tools a fixture grants it, written together for brevity. */
+export type TestAgent = AgentDefinitionInput & {
+    readonly tools?: readonly string[];
+};
+/** Registers each agent and grants it its `tools`, in order, for the life of the plugin. */
+export declare const testAgentsPlugin: (agents: readonly TestAgent[]) => Plugin.Object<undefined>;
+/** One agent that can read files, the shape most loop tests need. */
+export declare const testAgent: (overrides?: Partial<TestAgent>) => TestAgent;
+export declare const testAgents: (...agents: Partial<TestAgent>[]) => TestAgent[];
+/** What a test's {@link drive} asks: a route statement for the cause it writes, and a signal that cancels it. */
+export type DriveOptions = {
+    readonly route?: RouteStatement;
+    readonly signal?: AbortSignal;
+    /** Resolve at a `wait` hold too, rather than follow the run until its waits resolve. */
+    readonly untilWait?: boolean;
+};
+/**
+ * How a driven run ended, as a test reads it: `turns` when it opened a turn, `none` when it opened
+ * none, `cancelled` when it was cancelled or shutdown held it; how the last turn it closed ended;
+ * and the confirmations it left waiting, `null` when cancelled before the run was read. A run held
+ * on an approval ends `turns`, its last turn `blocked`.
+ */
+export type DriveResult = {
+    readonly thread_id: string;
+    readonly ended: 'none' | 'turns' | 'cancelled';
+    readonly reason: DeepReadonly<TurnEndReason> | null;
+    readonly pending_confirmations: DeepReadonly<ConfirmationState[]> | null;
+};
+/**
+ * The testing door into execution: asks `thread` to run as a person does (`resume`, a cause that
+ * releases its holds), drives it once, and resolves when its run is held or settled; a run held on a
+ * call's `wait` goes on once the wait resolves, so it is followed through it unless `untilWait`
+ * says to stop there. Applications
+ * never drive a thread; they send to it. `route` is the cause's route statement; a `signal` that aborts cancels the thread as a person's stop does (`Thread.cancel`, which
+ * also clears its queued input), one already aborted before anything runs.
+ */
+export declare function drive(thread: Thread, options?: DriveOptions): Promise<DriveResult>;
+/** The delegations plugin's configuration for a test: 8 open tasks per origin tree and the system clock unless given. */
+export declare const testDelegations: (overrides?: Partial<DelegationsConfig>) => DelegationsConfig;
+/** The owner `testWaitOwner` registers by default. */
+export declare const TEST_WAIT_OWNER = "test:waits";
+/**
+ * Registers a constraint owner a test's tools may wait on (`waitFor({ owner: TEST_WAIT_OWNER, … })`)
+ * and returns its handle, whose `resolveWait` the test resolves them with. It constrains no thread.
+ */
+export declare function testWaitOwner(root: Context, owner?: string): OwnerHandle;
+/**
+ * Holds `threadIds` from running, as a constraint holding them does, until `release()`: a test that
+ * answers or sends and must look before the owner runs the thread takes this first.
+ */
+export declare function holdRuns(root: Context, ...threadIds: string[]): {
+    release(): void;
+};
+/**
+ * Resolves once nothing on the root runs or waits to run: every pending run held or settled, as a
+ * started root leaves things once the work its causes asked for is done.
+ */
+export declare function untilQuiet(root: Context): Promise<void>;
+/** Starts a thread on `agent` (the first registered agent by default) and drives one turn on `text`. */
+export declare function runTestTurn(root: Context, text?: string, options?: {
+    agent?: string;
+    threadId?: string;
+}): Promise<{
+    thread: Thread;
+    result: DriveResult;
+}>;
+/**
+ * What a turn opened on the fake provider records, for a test that writes `turn/start` itself: the
+ * turn serves run `runId`, whose execution was admitted at `attemptCutoff`.
+ */
+export declare const turnStartData: (turn: number, runId?: string, attemptCutoff?: number) => {
+    turn: number;
+    route: {
+        provider: string;
+        model: string;
+        thinking_effort: "low" | "high" | "none" | "medium" | "max" | null;
+    };
+    run_id: string;
+    attempt_cutoff: number;
+};
+/** An invocation context for calling a tool directly, without a loop around it. */
+export declare function testInvocationContext(root: Context, options?: {
+    threadId?: string;
+    agentName?: string;
+    callId?: string;
+    callSeq?: number;
+    cwd?: string;
+    /** The thread's read roots; none when omitted. */
+    readRoots?: string[];
+    /** The turn's route; the fake provider's when omitted. */
+    route?: ModelRoute;
+    /** The resolved wait of a dispatch again; none when omitted. */
+    wait?: ResolvedWait | null;
+}): InvocationContext;
+export { ownedTmpDir, tmpWorkspace };
+/**
+ * Replaces `rows`, a run of a thread's surface, with one stand-in, between turns, as a manual
+ * compaction records it: through `replaceSurface`, which refuses it with a
+ * `ReplacementRefusedError` where the surface would not take it.
+ */
+export declare function replaceSpan(journal: PluginJournal, threadId: string, rows: readonly RowRef[], text: string, options?: {
+    role?: 'user' | 'assistant';
+    source?: ExtensionRecord;
+}): Promise<JournalEvent<'surface/replaced'>>;
+/** The text of a message that may not exist — the shape an assertion usually wants. */
+export declare const textOf: (message: DeepReadonly<ConversationMessage> | undefined) => string;
+/** A model request with everything defaulted, for a test that cares about one field. */
+export declare const modelRequest: (overrides?: Partial<ModelRequest>) => ModelRequest;
+/** The system prompt a request carried, as one string. */
+export declare const promptTextOf: (request: {
+    systemPrompt: readonly PromptBlock[];
+}) => string;
+/** Content of the last `role: tool` message the model received in a request. */
+export declare const lastToolMessage: (messages: readonly DeepReadonly<ConversationMessage>[]) => string | null;
+/**
+ * A thread's view, read now, for a test that has just run or written to it in this process, which
+ * loaded it: the synchronous counterpart of `thread.read` that tests use for brevity. Throws
+ * `ThreadNotLoadedError` for a thread nothing loaded.
+ */
+export declare const viewOf: (thread: Thread) => ThreadView;
+/** The row a `send` queued its input at, or found it queued at; a refused send fails the test. */
+export declare function sentAt(outcome: SendOutcome): Seq;
+/** A thread's tool results as its conversation holds them, in order. */
+export declare const toolResultsOf: (thread: Thread) => string[];
+/** Every tool result the model saw, across every thread and request. */
+export declare const toolMessages: (requests: readonly ModelRequest[]) => string[];
+/**
+ * A summary from a thread's rows alone, consulting no fold: for tests of `journal/` itself, whose
+ * folds are their own and must not meet the loop's. The identity comes from the spawn row when
+ * there is one; nothing is ever pending.
+ */
+export declare const bareSummary: Summarizer;
+export interface TestJournalOptions {
+    /** How summaries are computed: the loop's `summarizeThread` unless given, `bareSummary` for `journal/` tests. */
+    summarize?: Summarizer;
+    onListenerError?: (error: unknown) => void;
+    /**
+     * Core folds the journal registers at construction. When omitted: `threadState`, which the loop's
+     * summary reads, unless `summarize` is given, as a test of `journal/` alone does, and then none.
+     */
+    coreFolds?: readonly CoreFold<unknown>[];
+}
+/**
+ * A journal over `store` for tests that drive the journal without a root. Not opened.
+ */
+export declare function testJournal(store?: JournalStore, options?: TestJournalOptions): Journal;
+/**
+ * Every row the journal holds, across its threads, in seq order: what a test asserts over a whole
+ * journal. Loads every thread first.
+ */
+export declare function journalRows(journal: PluginJournal): Promise<JournalEvent[]>;
+/** Every row a store holds, across its threads, in seq order; opens and closes a closed store around the read. */
+export declare function storeRows(store: JournalStore): Promise<JournalEvent[]>;
+/**
+ * Writes `rows` into an open `store`, one attempt per row, under a writer lease it takes and gives back:
+ * rows written past the journal, as a test that bypasses its gate needs. No journal may hold the store.
+ */
+export declare function writeRows(store: JournalStore, rows: readonly JournalEvent[], summaries: readonly ThreadSummary[]): Promise<void>;
+/** The value of the contribution under `key` in `summary`'s catalog entry, past its cache envelope; `undefined` without an entry. */
+export declare const contributedValue: (summary: ThreadSummary, key: string) => unknown;
+/** Replaces a store's catalog past the journal, under a writer lease it takes and gives back: damage a test inflicts. */
+export declare function writeCatalog(store: JournalStore, summaries: readonly ThreadSummary[]): Promise<void>;
+/**
+ * A memory store holding exactly what `source` holds — its rows and its catalog, as they are — the
+ * way a process that crashed leaves them for the next one to open. Returned open, its lease free.
+ */
+export declare function copyStore(source: JournalStore): Promise<MemoryJournalStore>;
+/**
+ * A memory store holding exactly `events` — seqs and timestamps as they are, gaps included — with
+ * a catalog rebuilt from them: a journal cut off, or thinned, where a test says. Returned open, its
+ * lease free.
+ */
+export declare function replayStore(events: readonly JournalEvent[]): Promise<MemoryJournalStore>;
+/**
+ * Makes core's fold throw on every row `fails` accepts, as a thread core cannot read behaves: a
+ * thread whose rows it cannot fold does not load. Scoped to the test that calls it, undone when it
+ * finishes or when the returned function is called, whichever comes first.
+ */
+export declare function breakCoreFold(fails: (event: JournalEvent) => boolean): () => void;
+/**
+ * `rows` with the origin rule broken above `threadId`, damage a test inflicts: its caller's rows
+ * dropped (`missing`), or its caller's spawn row naming `threadId` as its own caller (`cycle`).
+ */
+export declare function breakCallerChain(rows: readonly JournalEvent[], threadId: string, damage: 'missing' | 'cycle'): JournalEvent[];
+/**
+ * The origin of a thread a test creates under `callerId`, citing a real `tool/call` row recorded on
+ * the caller now: what `origins.validate` requires of a call cause. The call is not on any turn, so
+ * only a caller that no test drives afterwards should be given one.
+ */
+export declare function callOrigin(root: Context, callerId: string): Promise<{
+    caller_thread_id: string;
+    source_seq: Seq;
+    cause: {
+        kind: 'call';
+    };
+}>;
+/**
+ * The invocation context of a call `threadId` made, named by `label`: a real `tool/call` row recorded
+ * on the thread the first time the label is asked for, so the origin a delegation records cites a row
+ * of its caller (`origins.validate`), and the same label is the same call afterwards, as a
+ * re-dispatch of it is. `options` are {@link testInvocationContext}'s, without the call's identity.
+ */
+export declare function callAt(root: Context, threadId: string, label: string | number, options?: Omit<NonNullable<Parameters<typeof testInvocationContext>[1]>, 'threadId' | 'callSeq' | 'callId'>): Promise<InvocationContext>;
+/**
+ * The origin of a thread an owner's assignment creates under `callerId`: the row that granted it is
+ * the caller's spawn row, a real row of the caller, and `key` is the owner's.
+ */
+export declare function assignmentOrigin(root: Context, callerId: string, owner: string, key: ReadonlyJsonValue): ThreadOrigin;
+/** Mounts one agent as a plugin, for tests that need a registration with a fiber of its own. */
+export declare const testAgentPlugin: (agent: AgentDefinitionInput) => Plugin.Object<undefined>;
+/** Mounts one prompt contribution as a plugin, for tests that need it with a fiber of its own. */
+export declare const testPromptPlugin: (contribution: PromptContribution) => Plugin.Object<undefined>;

package/dist/testing/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Test doubles and helpers, available at `@leuduan/lagent/testing` so they stay out of the engine's
+ * public surface. They are not part of the semver contract the root entry point offers.
+ *
+ * The door lists exactly the names hosts outside this package use. lagent's own tests import the
+ * helper modules by relative path, so a helper only they need stays in its module and off this list.
+ */
+export { FakeLLMClient, assistant, withToolCalls } from './fakeLlm.js';
+export type { FakeChatHandler } from './fakeLlm.js';
+export { FedLLM } from './fedLlm.js';
+export { TEST_START, callOrigin, copyStore, createTestRoot, drive, fakeProvider, journalRows, lastToolMessage, replaceSpan, replayStore, storeRows, testAgents, testAgentsPlugin, testBirth, testDelegations, testEnvironment, testPrograms, testPromptPlugin, textOf, tmpWorkspace, viewOf, } from './helpers.js';
+export type { TestRoot, TestRootOptions } from './helpers.js';
+export { manualClock } from './clock.js';