@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/sys/git.d.ts

@@ -0,0 +1,47 @@
+/** Variables that select a repository, an index or an object store other than the working directory's. */
+export declare const GIT_REPOSITORY_VARIABLES: readonly ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_NAMESPACE"];
+/**
+ * Where a repository keeps its metadata, as found from a path in its working tree. Read from the
+ * filesystem alone, without running git, so it costs a few `stat`s and runs nothing the repository
+ * configures.
+ */
+export type RepositoryLocation = {
+    /** The working tree's top directory: the one holding `.git`. */
+    readonly worktree: string;
+    /**
+     * The `.git` entry itself, with its symbolic links resolved: the git directory, or the pointer
+     * file a linked worktree or a submodule has, under whatever name it really has.
+     */
+    readonly dotGit: string;
+    /** The git directory: `.git` itself, or the `gitdir:` target its pointer file names. */
+    readonly gitDir: string;
+    /**
+     * The shared git directory the git directory's `commondir` names, as a linked worktree's does;
+     * else `null`.
+     */
+    readonly commonDir: string | null;
+};
+/**
+ * The repository containing `path`: the nearest directory at or above it holding a `.git` entry,
+ * so a nested repository is found before the one around it. `path` need not exist. The walk starts
+ * from `path` with its symbolic links resolved, as git's own discovery does from the physical
+ * working directory, so a workspace reached through a link is found in the repository it lives in,
+ * not among the link's own parents; the worktree, git and common directories are given resolved
+ * too. A `.git` file that names no git directory is taken as its own, so it still marks the
+ * repository. `null` outside every repository.
+ */
+export declare function findRepository(path: string): RepositoryLocation | null;
+/** What a repository's `HEAD` names: a branch, or a commit it is detached at. */
+export type GitHead = {
+    readonly kind: 'branch';
+    readonly name: string;
+} | {
+    readonly kind: 'detached';
+    readonly commit: string;
+};
+/**
+ * The `HEAD` of the worktree `repository` locates, read from its git directory without running git:
+ * a branch by its short name (`ref: refs/heads/main` is `main`, another ref its full name), a commit
+ * id as a detached head at its first seven digits; `null` when it cannot be read or says neither.
+ */
+export declare function readHead(repository: RepositoryLocation): GitHead | null;

package/dist/sys/paths.d.ts

@@ -0,0 +1,9 @@
+/** Whether `candidate` is `root` or a path inside it, by whole segments: `/a/bc` is not inside `/a/b`. Both normalized. */
+export declare const isWithin: (candidate: string, root: string) => boolean;
+/** A path as results show it: relative to the cwd inside it, absolute outside it. */
+export declare function displayPath(cwd: string, path: string): string;
+/**
+ * `path` normalized, refused when relative: a relative path would mean the process's directory,
+ * which is the host's to choose. `what` names the setting in the error.
+ */
+export declare function absolutePath(path: string, what: string): string;

package/dist/sys/spawn.d.ts

@@ -0,0 +1,186 @@
+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 command never passed its startup gate; a wrapper group may still need cleanup. */
+export declare class CommandStartFailure extends Error {
+    readonly stopFailed: boolean;
+    readonly code: string | undefined;
+    constructor(cause: unknown, cleanup: {
+        readonly stopFailed: boolean;
+    });
+}
+/**
+ * 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.
+ * Each rejection owns a `CommandStartFailure` recording cleanup of its gated wrapper, with the
+ * original failure as its cause.
+ */
+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 readLines} 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;
+};
+/**
+ * Hands a spawned command's stdout to `onLine` line by line, holding at most one line, and waits for
+ * the command to end: 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 readLines(command: SpawnedPipes, reader: 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 '../util/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,76 @@
+import type { z } from 'zod';
+import type { ConversationMessage, LLMStreamChunk, MalformedToolCall, ModelResponse, ResponseFinish } from '../llm/primitives.js';
+import type { LLMClient, StreamingLLMResponse } from '../llm/client.js';
+import type { ModelRequest } from '../llm/request.js';
+import { LLMStreamChunkSchema } from '../llm/primitives.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,34 @@
+import type { ConversationMessage } from '../llm/primitives.js';
+import type { LLMClient, StreamingLLMResponse } from '../llm/client.js';
+import type { ModelRequest } from '../llm/request.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>;
+}