@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/testing/helpers.d.ts

@@ -0,0 +1,362 @@
+import { Context, type Plugin } from '@leuduan/cordis';
+import { Journal, type CoreFold, type JournalStore, type PluginJournal, type Summarizer } from '../journal/index.js';
+import type { ConfirmationState, RouteStatement, RowRef, SendOutcome, TurnLimits } from '../state/index.js';
+import type { InvocationContext, ResolvedWait, Tool } from '../loop/index.js';
+import type { ConversationMessage, ThinkingEffort } from '../llm/primitives.js';
+import type { FailureClassification } from '../llm/failure.js';
+import type { LLMClient, ModelCapacity } from '../llm/client.js';
+import type { ModelRequest } from '../llm/request.js';
+import type { ModelRoute } from '../llm/provider.js';
+import type { PromptBlock } from '../llm/prompt.js';
+import type { DeepReadonly, ReadonlyJsonValue } from '../util/json.js';
+import type { AgentDefinitionInput } from '../loop/index.js';
+import type { ExtensionRecord, JournalEvent, Seq, ThreadOrigin, ThreadSummary, TurnEndReason } from '../records/journal.js';
+import { type TrustedPrograms } from '../sys/environment.js';
+import type { ConfinementService, Launched, LaunchOptions, LaunchRequest } from '../services/confinement/service.js';
+import { MemoryJournalStore } from '../stores/memory.js';
+import { type PromptContribution } from '../services/prompts.js';
+import { type RetryPolicy } from '../services/llm.js';
+import type { Thread } from '../services/threads/index.js';
+import type { BirthInput, CreateThreadOptions, Opening } from '../services/threads/index.js';
+import type { InitialInstallationInput } from '../services/presets/installations.js';
+import type { OwnerHandle, StartOptions } from '../services/threads/index.js';
+import type { DelegationsConfig } from '../plugins/delegations/service.js';
+import type { ThreadView } from '../services/threads/index.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 `threadDirs` keeps thread directories: a temporary directory, removed with the
+     * root, when omitted; `null` mounts no thread directories, as on a host with no file system.
+     */
+    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 file 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 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>;
+/** One shell launch for `request.threadId` as its own operation: a snapshot, then the launch under it. */
+export declare function launchOnce(service: ConfinementService, { threadId, ...request }: LaunchRequest & {
+    threadId: string;
+    program: {
+        shell: string;
+    };
+}, options: LaunchOptions): Promise<Launched>;
+/** Makes every launch through `confinement` report that its stop could not be confirmed, as a launcher that cannot confirm the group ended. */
+export declare function failStops(confinement: ConfinementService): void;

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';

package/dist/testing/index.js

@@ -0,0 +1 @@
+import{a as B}from"../chunks/W57RW55W.js";import{a as E,b as I,c as N,f as J,h as m}from"../chunks/B4FXK5ER.js";import"../chunks/SS3B5W34.js";import"../chunks/IAAEP6VL.js";import"../chunks/OCBPT7KE.js";import"../chunks/2P47AHNK.js";import"../chunks/MHC6VPB4.js";import"../chunks/EMRB4KCN.js";import"../chunks/RCIHV3KG.js";import"../chunks/2GCIWSOA.js";import{a as z}from"../chunks/GGSVIIWJ.js";import{c as L,d as M}from"../chunks/CANPZYTH.js";import"../chunks/VYMT4TXD.js";import"../chunks/MNJ4SRF7.js";import"../chunks/JFZZXVWD.js";import{c as F,e as W}from"../chunks/N6IXG2VL.js";import"../chunks/6DRCKZ2C.js";import"../chunks/7LI64H5X.js";import"../chunks/3UMZMPWW.js";import{a as A}from"../chunks/Q75FUN7D.js";import"../chunks/PUSUPTAT.js";import"../chunks/34KW6VNQ.js";import"../chunks/KUZCL2SH.js";import"../chunks/CQEVREBT.js";import{b as $}from"../chunks/HK6ZSONF.js";import"../chunks/7VAPNE3L.js";import{b as C}from"../chunks/EPYQ5M3B.js";import{a as b,c as R}from"../chunks/5IRF47YB.js";import"../chunks/OL5A6ITQ.js";import{b as D,e as j}from"../chunks/JFX2MXBA.js";import"../chunks/S34ZA2R6.js";import"../chunks/6FRNHMCV.js";import{b as P}from"../chunks/CUK7CGC7.js";import{H as S,s as q}from"../chunks/BPRCULZH.js";import"../chunks/FJLU4UH3.js";import{f as O}from"../chunks/DDANMY45.js";import{w as v}from"../chunks/BBCW2FZK.js";import"../chunks/MMNNZCBO.js";import"../chunks/G44LG6VL.js";import{o as T,q as p,r as w}from"../chunks/D4PQP5MA.js";var u=class{claimed=!1;ledger=new A;failure;chunks;settled;options;constructor(e,n,r={}){this.chunks=e,this.settled=n,this.options=r}[Symbol.asyncIterator](){if(this.claimed)throw new Error("A response is read once: it has been claimed already");this.claimed=!0;let e=this.read();return{next:()=>this.ledger.operation(()=>e.next()),return:n=>this.ledger.operation(()=>e.return(n),!0),throw:n=>this.ledger.operation(()=>e.throw(n),!0)}}async*read(){try{for await(let n of this.chunks)yield T.parse(n);let e=this.options.readFailure===!0?this.settlement():void 0;if(e instanceof Error)throw e}catch(e){throw this.failure={error:e},e}finally{this.ledger.finish()}}settlement(){return typeof this.settled=="function"?this.settled():this.settled}async completed(){if(this.claimed){if(!this.ledger.ended)throw new Error("A response is settled before its read or after it, not while the read is under way")}else for await(let n of this);if(this.failure!==void 0)throw this.failure.error;let e=this.settlement();if(e instanceof Error)throw e;return"finish"in e?e:{message:e,finish:this.options.finish??"completed",provider_metadata:{}}}},g=class t{providerName="fake";requests=[];handler;constructor(e){this.handler=e}static scripted(...e){let n=0;return new t(()=>{let r=e[n];if(r===void 0)throw new Error(`Unexpected LLM call #${n+1}`);return n+=1,r})}async chat(e){if(this.requests.push(e),e.signal?.aborted)throw e.signal.reason instanceof Error?e.signal.reason:new Error("aborted");let n=await this.handler(e.messages,e);return"failure"in n?new u(n.chunks,n.failure):"chunks"in n?new u(n.chunks,n.message):new u([],n)}},ie=(t,e={})=>p({role:"assistant",content:t,...e}),le=(t,e=null)=>p({role:"assistant",content:e,tool_calls:t.map(n=>n.arguments===void 0?{...n,arguments:{}}:n)});var y=class{request;queue=[];ended=null;text="";wake=null;constructor(e){this.request=e,e.signal?.addEventListener("abort",()=>{this.ended??={cutOff:!0},this.wake?.()},{once:!0})}push(e){this.queue.push(e),this.wake?.()}finish(e,n={}){this.ended??={message:p({role:"assistant",content:e,...n})},this.wake?.()}fail(e){this.ended??={error:e},this.wake?.()}stream=new u(this.feed(),()=>this.ended!==null&&"cutOff"in this.ended?{message:p({role:"assistant",content:this.text||null}),finish:"other",provider_metadata:{}}:this.ended!==null&&"message"in this.ended?this.ended.message:new Error("The stream did not finish"));async*feed(){for(;;){let e=this.queue.shift();if(e!==void 0){this.text+=e.text_delta??"",yield e;continue}if(this.ended!==null){if("error"in this.ended)throw this.ended.error;return}await new Promise(n=>this.wake=n),this.wake=null}}},x=class{providerName="fake";calls=[];waiting=[];taken=0;async chat(e){let n=new y(e);return this.calls.push(n),this.waiting.shift()?.(n),n.stream}next(){let e=this.taken++,n=this.calls[e];return n!==void 0?Promise.resolve(n):new Promise(r=>this.waiting.push(r))}};import{randomUUID as _}from"node:crypto";import{resolve as me}from"node:path";import{Context as he,scopeOf as we}from"@leuduan/cordis";import{onTestFinished as ge,vi as tt}from"vitest";import{z as Q}from"zod";import{mkdtempSync as de,rmSync as ce}from"node:fs";import{tmpdir as ue}from"node:os";import{join as pe}from"node:path";import{onTestFinished as fe}from"vitest";var U=new Set;function H(t){let e=de(pe(ue(),t));return U.add(e),e}function V(t){U.delete(t),ce(t,{recursive:!0,force:!0})}function Y(t="lagent-test-"){let e=H(t);return fe(()=>V(e)),{root:e}}function G(t,e="lagent-test-"){let n=H(e);return t.effect(()=>()=>V(n)),n}var Z=(t,e="fake")=>({name:`test:provider:${e}`,inject:["llm"],apply:(n,r)=>I(n,{name:e,defaultModel:"test-model",...r?.thinkingEffort===void 0?{}:{defaultThinkingEffort:r.thinkingEffort},capacity:r?.capacity??(()=>({contextWindow:null,providerTools:!1,toolResultImages:!1})),createClient:()=>t,classify:r?.classify??(()=>({kind:"other"}))},{retry:r?.retry??xe})}),ye=Object.freeze({provider:"fake",model:"test-model",thinking_effort:null}),xe={maxAttempts:1,baseDelayMs:0,maxDelayMs:0},_e=10,K={resume:"all",startLimit:64};function ee(t={}){return{from:"defaults",route:ye,...t}}async function ke(t){let e=new he;t.disposal!=="manual"&&ge(()=>e.fiber.dispose()),await e.plugin(N,{store:t.store??new m,cwd:t.cwd??process.cwd(),retention:t.retention??"keep",chainLimit:t.chainLimit??_e,...t.limits===void 0?{}:{limits:t.limits}});let n=t.dataDir===void 0?G(e,"lagent-data-"):t.dataDir;return n!==null&&await e.plugin(B,{dataDir:n}),await e.plugin(Z(t.llm),{...t.capacity===void 0?{}:{capacity:t.capacity},...t.classify===void 0?{}:{classify:t.classify},...t.retry===void 0?{}:{retry:t.retry}}),await e.plugin(te(t.agents??ne())),await e.plugin({name:"test:tools",inject:["tools"],apply(r){for(let{name:s,tool:o}of t.tools??Se())r.effect(()=>r.tools.register(we(r),s,o))}}),e.appended=[],e.journal.subscribe(r=>e.appended.push(r)),e.newThread=({id:r=_(),agent:s="main_agent",...o}={})=>e.threads.create(s,{id:r,...o.birth===void 0?{reuse:"identity",birth:ee()}:{},...o}),t.start!=="defer"&&await e.threads.start(K),e}var Te=()=>{let t=F(process.env,J);for(let e of z)delete t[e];return t},ve=()=>W(process.env.PATH??""),qe=Q.strictObject({path:Q.string()}),Ee=D({name:"read_file",description:"Read a file from the workspace.",parameters:qe,onInterrupted:"rerun",executionMode:"parallel",async execute(t,e){let n=await e.operation.files.open(me(e.environment.cwd,t.path));try{return{output:(await n.readAll()).toString("utf8")}}finally{await n.close()}}}),Se=()=>[{name:"read_file",tool:Ee}],te=t=>({name:"test:agents",inject:["agents","tools"],apply(e){for(let{tools:n=[],...r}of t){P(e,r);for(let s of n)j(e,s,[r.name])}}}),X=(t={})=>({name:"main_agent",tools:["read_file"],...t}),ne=(...t)=>t.length>0?t.map(e=>X(e)):[X()];async function be(t,e={}){let{route:n,signal:r,untilWait:s=!1}=e,o=()=>t.cancel(r===void 0?"Turn cancelled":O(r.reason),{intent:"user"});if(r?.aborted)return await o(),{thread_id:t.id,ended:"cancelled",reason:null,pending_confirmations:null};let a,i=()=>{a=o(),a.catch(()=>{})};r?.addEventListener("abort",i,{once:!0});let d=t.service,h=t.summary.through_seq;try{let f=await t.resume(n===void 0?{}:{route:n});if(a!==void 0)return await a,{thread_id:t.id,ended:"cancelled",reason:null,pending_confirmations:null};let c=await L(d,t.id,f,l=>M(l)&&(s||l.state!=="held"||l.hold.reason!=="wait"));await a;let k=await t.read(l=>l.replay().filter(oe=>oe.seq>h)),se=r?.aborted===!0||c.state==="held"&&c.hold.reason==="shutdown"||c.state==="settled"&&(c.outcome==="cancelled"||c.outcome==="superseded");return{thread_id:t.id,ended:se?"cancelled":k.some(l=>l.type==="turn/start")?"turns":"none",reason:k.some(l=>l.type==="turn/end")?t.lastOutcome():null,pending_confirmations:await t.read(l=>l.pendingConfirmations())}}finally{r?.removeEventListener("abort",i)}}var Oe=(t={})=>({maxOpenTasks:8,clock:$,...t});async function Pe(t,e,n,r,s={}){let o=t,[a]=await S(o,e,{trigger:"request",turn:null,step:null},[{kind:"span",stand_in:{role:s.role??"user",content:r},source:s.source??{plugin:"test:strategy",kind:"checkpoint",version:1,data:null},source_seqs:n.map(i=>i.seq)}]);return o.eventAt(a.seq)}var Re=t=>t===void 0?"":w(t);var Ae=t=>{let e=[...t].reverse().find(n=>n.role==="tool");return e===void 0?null:w(e)},Ie=t=>t.service.view(t.id);function Ce(t=new m,e={}){return new v(t,{summarize:e.summarize??((n,r)=>b(n,r,E())),...e.onListenerError===void 0?{}:{onListenerError:e.onListenerError},coreFolds:e.coreFolds??(e.summarize===void 0?[q]:[])})}async function Le(t){let e=t;return await Promise.all(t.summaries().map(n=>e.load(n.thread_id))),t.summaries().flatMap(n=>t.rows(n.thread_id)).sort((n,r)=>n.seq-r.seq)}async function re(t){let e=t.isOpen;e||await t.open();try{let n=await t.threads();return(await Promise.all(n.map(({threadId:s})=>t.read(s)))).flat().sort((s,o)=>s.seq-o.seq)}finally{e||await t.close()}}async function ae(t,e,n){let r=await t.acquireWriter();try{for(let s of e)await t.append({id:_(),baseHead:await t.head(),writer:r.acquisitionId,rows:[s]});await t.putSummaries(n,r.acquisitionId)}finally{await r.release()}}async function Me(t){let e=new m;await e.open();let n=t.isOpen;n||await t.open();try{await ae(e,await re(t),await t.summaries())}finally{n||await t.close()}return e}async function De(t){let e=new m;await e.open(),await ae(e,t,[]);let n=Ce(e);return await n.open(),await n.close(),e}async function je(t,e){let n=await R(t).append("tool/call",{turn:1,step:1,call_id:`call-${_()}`,name:"test_call"},{threadId:e});return{caller_thread_id:e,source_seq:n.seq,cause:{kind:"call"}}}var Ne=t=>({name:`test:prompt:${t.tag}`,inject:["prompts"],apply:e=>C(e,t)});function Fe(t=Date.parse("2026-01-05T09:00:00Z")){let e=t,n=0,r=0,s=new Map,o=(a,i)=>{for(;;){let d;for(let c of s)c[1].due<=a&&(d===void 0||c[1].due<d[1].due)&&(d=c);if(d===void 0)break;let[h,f]=d;i&&(e+=f.due-n),n=f.due,s.delete(h),f.fire()}i&&(e+=a-n),n=a};return{now:()=>e,setTimer(a,i){let d=r++;return s.set(d,{due:n+Math.max(0,a),fire:i}),()=>{s.delete(d)}},advance:a=>o(n+a,!0),jump(a){e+=a},elapse:a=>o(n+a,!1),pending:()=>[...s.values()].map(a=>a.due-n).sort((a,i)=>a-i)}}export{g as FakeLLMClient,x as FedLLM,K as TEST_START,ie as assistant,je as callOrigin,Me as copyStore,ke as createTestRoot,be as drive,Z as fakeProvider,Le as journalRows,Ae as lastToolMessage,Fe as manualClock,Pe as replaceSpan,De as replayStore,re as storeRows,ne as testAgents,te as testAgentsPlugin,ee as testBirth,Oe as testDelegations,Te as testEnvironment,ve as testPrograms,Ne as testPromptPlugin,Re as textOf,Y as tmpWorkspace,Ie as viewOf,le as withToolCalls};

package/dist/testing/processes.d.ts

@@ -0,0 +1,13 @@
+import { type ChildProcess } from 'node:child_process';
+/** The URL of a source module, such as `sys/spawn.ts`, for a {@link lagentProcess} script to import. */
+export declare const sourceModule: (path: string) => string;
+/**
+ * Another lagent process, running `script` as an ES module against the TypeScript sources, for
+ * tests of what happens when a process ends — which a test cannot do to its own. Only for tests
+ * run from the sources. The caller kills it.
+ */
+export declare function lagentProcess(script: string): {
+    child: ChildProcess;
+    line: () => Promise<string>;
+    exited: () => Promise<number | null>;
+};

package/dist/testing/settlement.d.ts

@@ -0,0 +1,6 @@
+import type { StreamingLLMResponse } from '../llm/client.js';
+/**
+ * Asks `stream` to settle at every turn of the microtask queue while `closing` is pending, and fails
+ * when one settles with `closing` still pending at the moment it was asked: the read is not over.
+ */
+export declare function settlementNeverEarly(stream: StreamingLLMResponse, closing: Promise<unknown>): Promise<void>;

package/dist/testing/tmpDirs.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from '@leuduan/cordis';
+/**
+ * A temporary directory that lives as long as the test that made it, in its body or a
+ * `beforeEach`: removed once that test finishes, after any root made after it is disposed.
+ */
+export declare function tmpWorkspace(prefix?: string): {
+    root: string;
+};
+/** A temporary directory removed when `ctx` is disposed. */
+export declare function ownedTmpDir(ctx: Context, prefix?: string): string;
+/**
+ * Removes every temporary directory made by `tmpWorkspace` or `ownedTmpDir` that nothing cleaned
+ * up, such as the data directory of a root a test never disposed. The vitest setup file calls it
+ * after each test file, so no directory outlives the file that made it. Kept apart from the
+ * helpers so that setup file imports nothing else.
+ */
+export declare function removeLeftoverTmpDirs(): void;

package/dist/util/async.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `task`, or the signal's reason once it aborts: stops waiting, not the work, which keeps running.
+ * A signal aborted already rejects at once, even when `task` has settled: the abort is raced first.
+ * `task` is always observed, so its later failure is never an unhandled rejection.
+ */
+export declare function abortable<T>(task: Promise<T>, signal: AbortSignal): Promise<T>;
+/** The longest delay a Node timer honours; a longer one fires at once. The bound of every timer setting. */
+export declare const MAX_TIMER_MS: number;

package/dist/util/diff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A line diff between two texts, as unified diff text.
+ *
+ * Myers' algorithm over the lines left once the common head and tail are set aside, which is all
+ * that differs when an edit changed a few places. Its search is bounded: past
+ * {@link MAX_EDIT_DISTANCE} differing lines, or work proportional to it, the middle is given as
+ * removed and added whole, which is still a correct diff, only not the shortest.
+ */
+export type UnifiedDiff = {
+    /** The diff, with `---`/`+++` headers; empty when the texts have the same lines. */
+    readonly text: string;
+    readonly added: number;
+    readonly removed: number;
+};
+/**
+ * The unified diff from `before` to `after`, with `context` lines around each change. Lines split
+ * on `\n`, a carriage return right before it dropped, and a last line without a newline is marked
+ * as git marks it.
+ */
+export declare function unifiedDiff(before: string, after: string, labels: {
+    readonly from: string;
+    readonly to: string;
+}, context?: number): UnifiedDiff;
+/** How many lines a text has: a last line without a newline counts. */
+export declare function lineCount(text: string): number;

package/dist/util/dispatch.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Calls every listener with `event`, synchronously and in order, and never awaits one. A throw, or
+ * the rejection of anything a listener returns with a `then`, is reported, and the other listeners
+ * still run. A returned thenable is adopted, so its `then` is called once. The one rule for "a
+ * listener failed"; the caller owns the event, freezing it when the listeners must not change what
+ * the others see.
+ */
+export declare function dispatch<T>(listeners: Iterable<(event: T) => unknown>, event: T, report: (error: unknown) => void): void;

package/dist/util/errors.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export declare const formatError: (error: unknown) => string;
+/**
+ * `formatError` followed by the `cause` chain. A transport failure's own message says nothing (the
+ * OpenAI SDK's is just `Connection error.`); what actually broke is in its causes.
+ */
+export declare function formatErrorWithCauses(error: unknown): string;
+/** The Node system-error code of `error`, such as `ENOENT`, when it has one. */
+export declare const errnoCode: (error: unknown) => string | undefined;
+/** Whether `error` is a Node system error with one of `codes`. */
+export declare const hasErrnoCode: (error: unknown, ...codes: string[]) => boolean;
+/** A zod failure as one line per bad field, in the form the calling model is told about. */
+export declare function formatValidationError(error: z.ZodError): string;
+/** What a failure says in the journal: a validation error as its fields, anything else with its causes. */
+export declare const failureText: (error: unknown) => string;
+/**
+ * Whether `error` is how work stops on `signal`: its reason, or one wrapping it as Node's abortable
+ * APIs do (`cause`), possibly again (`Promise.any` over them), a few levels down. A failure that only
+ * coincided with the abort is not.
+ */
+export declare function stoppedOn(signal: AbortSignal, error: unknown, depth?: number): boolean;
+/**
+ * Whether `error` is the cancellation of work on `signal`, not a failure that coincided with it: its
+ * reason (see {@link stoppedOn}), or the `AbortError` a platform transport (`fetch`, a stream) throws
+ * when the signal it was handed fired. Either needs the signal to have fired. An adapter whose SDK
+ * throws an abort error of its own turns it into the signal's reason.
+ */
+export declare function isCancellation(signal: AbortSignal, error: unknown): boolean;

package/dist/util/foldState.d.ts

@@ -0,0 +1,17 @@
+import type { JsonValue, ReadonlyJsonValue } from './json.js';
+/**
+ * A fold's state as a reader sees it: read-only all the way down. Arrays become `readonly`, `Map`
+ * and `Set` their read-only forms, and records map property by property. Fold state is plain data
+ * (primitives, arrays, records, `Map` and `Set`), so a function-typed member becomes `never`: the
+ * state cannot hand a reader a way to change it. A field typed exactly `JsonValue` becomes
+ * {@link ReadonlyJsonValue}, as in `DeepReadonly`, since mapping the recursive alias does not
+ * terminate. This is cooperative authoring, not a sandbox: reducers keep the mutable state and
+ * nothing is copied or frozen on read, so a cast, or a narrowing TypeScript widens, can still reach
+ * the mutable value. `Array.isArray` is the known one: it narrows a read-only array to `any[]`, so
+ * `push` on a JSON array payload compiles. The type does not exclude every cast-free mutation.
+ */
+export type ReadonlyState<S> = [S] extends [JsonValue] ? [JsonValue] extends [S] ? ReadonlyJsonValue : ReadonlyStateOf<S> : [S] extends [ReadonlyJsonValue] ? [ReadonlyJsonValue] extends [S] ? S : ReadonlyStateOf<S> : ReadonlyStateOf<S>;
+type ReadonlyStateOf<S> = S extends (...args: never[]) => unknown ? never : S extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<ReadonlyState<K>, ReadonlyState<V>> : S extends ReadonlySet<infer T> ? ReadonlySet<ReadonlyState<T>> : S extends object ? {
+    readonly [K in keyof S]: ReadonlyState<S[K]>;
+} : S;
+export {};

package/dist/util/freeze.d.ts

@@ -0,0 +1,2 @@
+/** Recursively freezes a tree of data values. Call on an owned copy, never a live service. */
+export declare function freezeData<T>(value: T): T;

package/dist/util/ids.d.ts

@@ -0,0 +1,2 @@
+/** A prefixed unique id, for things a reader has to tell apart at a glance in a journal. */
+export declare const nextId: (prefix: string) => string;

package/dist/util/json.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+/**
+ * Recursively drops `null` object values, so a field left unset and one set to null compare equal.
+ *
+ * This is for comparing, not for storing: the session journal writes events as they stand, because
+ * a row that read back differently from the event in memory made a live session and a resumed one
+ * disagree about their own history.
+ */
+export declare function stripNone<T>(value: T): T;
+/**
+ * JSON with object keys sorted at every level, so equal values produce equal strings. Like
+ * `JSON.stringify`, it leaves out properties whose value is `undefined`, so a value compares equal
+ * to itself read back from storage.
+ */
+export declare function stableStringify(value: unknown): string;
+export declare const JsonValueSchema: z.ZodJSONSchema;
+export type JsonValue = z.infer<typeof JsonValueSchema>;
+/** A {@link JsonValue} no reader may change: what a frozen fact holds. */
+export type ReadonlyJsonValue = string | number | boolean | null | readonly ReadonlyJsonValue[] | {
+    readonly [key: string]: ReadonlyJsonValue;
+};
+/**
+ * `T` with every property and array readonly, all the way down: the type of a frozen fact. A field
+ * typed exactly `JsonValue` or `ReadonlyJsonValue` becomes {@link ReadonlyJsonValue}, since mapping
+ * the recursive alias itself does not terminate; so a type that is already deeply readonly maps to
+ * itself.
+ */
+export type DeepReadonly<T> = [T] extends [ReadonlyJsonValue] ? [ReadonlyJsonValue] extends [T] ? ReadonlyJsonValue : [JsonValue] extends [T] ? ReadonlyJsonValue : DeepReadonlyObject<T> : DeepReadonlyObject<T>;
+type DeepReadonlyObject<T> = T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/**
+ * A mutable copy of a read-only JSON value: for a payload read from a fold that a row or a public
+ * result is made of, which must not share what the fold holds.
+ */
+export declare function copyJson(value: ReadonlyJsonValue): JsonValue;
+export {};

package/dist/util/jsonSchema.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+/**
+ * JSON Schema for a validation schema, as advertised to the model. Uses the input shape, so
+ * defaulted fields stay optional, and every advertised schema is derived from the one that
+ * actually validates — the two can never drift.
+ */
+export declare function toJsonSchema(schema: z.ZodType): Record<string, unknown>;

package/dist/util/log.d.ts

@@ -0,0 +1,6 @@
+/** Minimal logger: warnings and errors go to stderr, debug output only with LAGENT_DEBUG set. */
+export declare const log: {
+    debug(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+};

package/dist/util/retries.d.ts

@@ -0,0 +1,25 @@
+import { type Clock } from './timers.js';
+/**
+ * Consecutive failures and the retry timer of work whose write failed, by key: what ask, schedules
+ * and delegations each kept beside their deadlines. Owns the counts and one timer queue of retries;
+ * the feature keeps its liveness checks, its deadlines, its reporting and what a retry does. There
+ * is no attempt identity: a retry is the feature's own check, which decides again from current state.
+ */
+export type RetryTracker = {
+    /**
+     * Records one more failure of `key` and arms `retry` after the backoff its count earns, replacing a
+     * retry already pending for it. The retry firing keeps the count: only `succeeded` or `clear`
+     * resets it. Inert once disposed.
+     */
+    failed(key: string, retry: () => void): void;
+    /** `key`'s work went through: its count and pending retry are forgotten. */
+    succeeded(key: string): void;
+    /** `key`'s work is no longer wanted: its count and pending retry are forgotten. */
+    clear(key: string): void;
+    /** Whether `key` has failed since it last succeeded or was cleared, its retry pending or in flight. */
+    pending(key: string): boolean;
+    /** Cancels every retry and forgets every count; later calls do nothing. Whoever creates a tracker disposes it. */
+    dispose(): void;
+};
+/** A {@link RetryTracker} whose retries are timed on `clock`; a retry that throws is handed to `report`. */
+export declare function retryTracker(clock: Clock, report: (error: unknown) => void): RetryTracker;