@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/plugins/commands/output.d.ts

@@ -0,0 +1,115 @@
+import type { Readable } from 'node:stream';
+import type { SpawnResult } from '../../sys/spawn.js';
+/**
+ * A command's log, capped at `maxBytes` in two segments: `<id>.log`, the current one, and after a
+ * rotation `<id>.1.log`, the one before it. When the current segment reaches half the cap it
+ * replaces the older one, so the latest output is always kept.
+ *
+ * Written through one stream at a time and never awaited by a call: `write` returning `false` asks
+ * the caller to pause its source until `whenWritable()`, which also waits for every rotated
+ * segment to finish flushing. A failed write is reported once, and later output is dropped rather
+ * than held.
+ */
+export declare class CommandLog {
+    readonly path: string;
+    readonly olderPath: string;
+    /** Logical bytes accepted since the command started. */
+    written: number;
+    /** Logical bytes no longer on disk. */
+    rotatedOut: number;
+    private stream;
+    /** Rotated streams that have not closed yet. */
+    private readonly flushing;
+    private segmentBytes;
+    private olderBytes;
+    private opened;
+    private failed;
+    private readonly maxBytes;
+    private readonly onError;
+    constructor(path: string, maxBytes: number, onError: (error: unknown) => void);
+    get rotated(): boolean;
+    /** Where the output is, and what rotation or a failed write removed from it. */
+    describe(): string;
+    /** `false` when the source should pause until {@link whenWritable}. */
+    write(chunk: Buffer): boolean;
+    whenWritable(): Promise<void>;
+    end(): void;
+    private needsDrain;
+    /**
+     * The file is opened synchronously and the stream writes to its descriptor, so a rename during a
+     * rotation never races an open, and writes still pending land in the segment they belong to.
+     * A re-dispatched command appends to its log after a separator line.
+     */
+    private open;
+    private rotate;
+    private fail;
+}
+export type CommandOutputOptions = {
+    /** Characters held for a result's head and for its tail; also the most one result shows. */
+    capacityChars: number;
+    openLog: () => CommandLog;
+    /** A background command logs from the start; a foreground one only once its output overflows. */
+    logFromStart: boolean;
+};
+/**
+ * One command's output: one pipe, in exact order, through one decoder, so a character split across
+ * chunks survives. Memory is bounded by a head and a tail of `capacityChars` each, plus one write
+ * buffer of the log; the log has the rest.
+ *
+ * Reads are relative to a mark. A foreground command's mark stays at the start; a background
+ * command's moves to the end of each read, so the next read shows only newer output.
+ */
+export declare class CommandOutput {
+    private readonly decoder;
+    private log;
+    /** Raw output held until the log opens, so the log starts from the first byte. */
+    private pending;
+    private totalChars;
+    private markChars;
+    /** The first `capacityChars` since the mark, and whether that is everything since it. */
+    private sinceMark;
+    private sinceMarkComplete;
+    /** At least the last `capacityChars`, at most twice that. */
+    private recent;
+    private readonly listeners;
+    private finished;
+    private readonly options;
+    constructor(options: CommandOutputOptions);
+    /** The log's path once it exists. */
+    get logPath(): string | undefined;
+    get logDescription(): string | undefined;
+    get isFinished(): boolean;
+    get hasUnread(): boolean;
+    /** Reads `source` to its end, pausing it while the log's buffer is full. */
+    attach(source: Readable): void;
+    /** Adds text the command did not print, such as a confinement handler's report; before {@link finish}. */
+    note(text: string): void;
+    /** Flushes the decoder and ends the log. Call once the command has settled. */
+    finish(): void;
+    /** Called on new output and on `finish`, after which `finished` holds; returns the unsubscribe function. */
+    onChange(listener: () => void): () => void;
+    /**
+     * Renders the output since the mark and then `trailer`, within `budget` characters. The trailer
+     * is laid out first and its length reserved, so no cut can remove it. What does not fit is cut
+     * from the middle, one part head to four parts tail, around the marker `omission` renders.
+     * `advance` moves the mark to the end, so what was skipped is not shown again.
+     */
+    render(options: {
+        budget: number;
+        trailer: readonly string[];
+        empty: string;
+        omission: (omittedChars: number, log: CommandLog) => string;
+        advance: boolean;
+    }): string;
+    private push;
+    private append;
+    private ensureLog;
+    private notify;
+}
+export declare const capitalize: (text: string) => string;
+/** A duration as a person reads it: `850ms`, `12.4s`, `3m 12s`, `2h 5m`. */
+export declare function formatDuration(ms: number): string;
+/** How the command's leader ended: its exit code, its signal, or that it never exited. */
+export declare function describeExit(result: SpawnResult): string;
+/** The marker for a stop that could not be confirmed. */
+export declare const stopFailedMarker: (graceSeconds: number) => string;

package/dist/plugins/commands/record.d.ts

@@ -0,0 +1,558 @@
+import { z } from 'zod';
+import { type ExtensionRecord, type Seq } from '../../records/journal.js';
+import type { DeepReadonly } from '../../util/json.js';
+/**
+ * What the journal keeps of a background command, so that a lagent process that did not start it
+ * can still say what it knows: that it was started, by whom and where, and whether and how it
+ * ended. Written by the commands plugin as `ext` rows of its own identity.
+ *
+ * The start row is written while the spawned group is still held at its startup gate, before the
+ * command runs, so no command ever runs unlisted; it says the command *may have started*, since the
+ * process can die after the row and before the gate opens. The end row is written when the plugin
+ * sees the command settle, and carries whether the stop succeeded: a settled wait does not prove
+ * the group is gone. A notifying command's natural exit writes its end row in the group of the
+ * notice that tells the thread (`commandNotice`).
+ */
+declare const CommandRowSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"started">;
+    id: z.ZodString;
+    call_seq: z.ZodNumber;
+    command: z.ZodString;
+    cwd: z.ZodString;
+    pgid: z.ZodNumber;
+    started_at: z.ZodString;
+    owner: z.ZodString;
+    notify: z.ZodNullable<z.ZodEnum<{
+        exit: "exit";
+    }>>;
+    launch: z.ZodNullable<z.ZodObject<{
+        launcher: z.ZodString;
+        version: z.ZodString;
+        policy: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"ended">;
+    id: z.ZodString;
+    exit_code: z.ZodNullable<z.ZodNumber>;
+    exit_signal: z.ZodNullable<z.ZodString>;
+    stopped_by: z.ZodNullable<z.ZodEnum<{
+        abort: "abort";
+        timeout: "timeout";
+        stop: "stop";
+    }>>;
+    stop_failed: z.ZodBoolean;
+    stop_reason: z.ZodNullable<z.ZodString>;
+    ended_at: z.ZodString;
+}, z.core.$strict>], "op">;
+export type CommandRow = z.output<typeof CommandRowSchema>;
+export type CommandStarted = Extract<CommandRow, {
+    op: 'started';
+}>;
+export type CommandEnded = Extract<CommandRow, {
+    op: 'ended';
+}>;
+export declare const commandRow: {
+    record: (value: {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    }) => ExtensionRecord;
+    parse: (value: {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    }) => {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    };
+    entry: (value: {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    }, options: import("../../journal/journal.js").AppendOptions) => {
+        type: "ext";
+        data: {
+            plugin: string;
+            instance_id: string;
+            kind: string;
+            version: number;
+            data: z.core.util.JSONType;
+        };
+        options: import("../../journal/journal.js").AppendOptions;
+    };
+    append(journal: import("../../journal/journal.js").PluginJournal, value: {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    }, options: import("../../journal/journal.js").AppendOptions): Promise<import("../../records/journal.js").JournalEvent<"ext">>;
+    read(event: import("../../records/journal.js").JournalEvent): {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    } | undefined;
+    contribution(message: {
+        role?: import("../../records/journal.js").InputRole;
+        content: string | readonly import("../../llm/content.js").ContentPartInput[];
+    }, value: {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    }, options?: {
+        sourceSeqs?: readonly Seq[];
+    }): import("../../records/journal.js").StepContribution;
+    matchesSource(record: DeepReadonly<ExtensionRecord>): boolean;
+    rejection(reason: string, value: {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    }): {
+        decision: "reject";
+        reason: string;
+        source: ExtensionRecord;
+    };
+    readContribution: (event: import("../../records/journal.js").JournalEvent) => {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    } | undefined;
+    readSource: (source: DeepReadonly<ExtensionRecord> | null) => {
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    } | undefined;
+    told: import("../../journal/projection.js").PluginProjection<import("../../services/extensionEvents.js").ToldNotices<{
+        op: "started";
+        id: string;
+        call_seq: number;
+        command: string;
+        cwd: string;
+        pgid: number;
+        started_at: string;
+        owner: string;
+        notify: "exit" | null;
+        launch: {
+            launcher: string;
+            version: string;
+            policy: string;
+        } | null;
+    } | {
+        op: "ended";
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        stopped_by: "abort" | "timeout" | "stop" | null;
+        stop_failed: boolean;
+        stop_reason: string | null;
+        ended_at: string;
+    }>>;
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: {
+            op: "started";
+            id: string;
+            call_seq: number;
+            command: string;
+            cwd: string;
+            pgid: number;
+            started_at: string;
+            owner: string;
+            notify: "exit" | null;
+            launch: {
+                launcher: string;
+                version: string;
+                policy: string;
+            } | null;
+        } | {
+            op: "ended";
+            id: string;
+            exit_code: number | null;
+            exit_signal: string | null;
+            stopped_by: "abort" | "timeout" | "stop" | null;
+            stop_failed: boolean;
+            stop_reason: string | null;
+            ended_at: string;
+        }, event: import("../../records/journal.js").JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): import("../../journal/projection.js").PluginProjection<State>;
+};
+/** One recorded command: how it started, and how it ended if the plugin saw it end. */
+export type CommandRecord = {
+    readonly started: CommandStarted;
+    readonly ended: CommandEnded | null;
+};
+/**
+ * A thread's recorded commands, by id. Resets at a fork's spawn row: a command describes what its
+ * source's execution did, not the conversation a fork continues.
+ */
+export declare const commandRecords: import("../../journal/projection.js").PluginProjection<Map<string, CommandRecord>>;
+declare const CommandNoticeSchema: z.ZodObject<{
+    id: z.ZodString;
+    exit_code: z.ZodNullable<z.ZodNumber>;
+    exit_signal: z.ZodNullable<z.ZodString>;
+    summary: z.ZodString;
+}, z.core.$strict>;
+export type CommandNotice = z.output<typeof CommandNoticeSchema>;
+/**
+ * The source of a command's exit notice: the input the commands plugin queues on the thread that
+ * started a command with `notify: "exit"` when it exits on its own. Its `summary` is one bounded
+ * line, such as `cmd-42 exited (exit code 0)`, for a host to show collapsed.
+ */
+export declare const commandNotice: {
+    record: (value: {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    }) => ExtensionRecord;
+    parse: (value: {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    }) => {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    };
+    entry: (value: {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    }, options: import("../../journal/journal.js").AppendOptions) => {
+        type: "ext";
+        data: {
+            plugin: string;
+            instance_id: string;
+            kind: string;
+            version: number;
+            data: z.core.util.JSONType;
+        };
+        options: import("../../journal/journal.js").AppendOptions;
+    };
+    append(journal: import("../../journal/journal.js").PluginJournal, value: {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    }, options: import("../../journal/journal.js").AppendOptions): Promise<import("../../records/journal.js").JournalEvent<"ext">>;
+    read(event: import("../../records/journal.js").JournalEvent): {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    } | undefined;
+    contribution(message: {
+        role?: import("../../records/journal.js").InputRole;
+        content: string | readonly import("../../llm/content.js").ContentPartInput[];
+    }, value: {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    }, options?: {
+        sourceSeqs?: readonly Seq[];
+    }): import("../../records/journal.js").StepContribution;
+    matchesSource(record: DeepReadonly<ExtensionRecord>): boolean;
+    rejection(reason: string, value: {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    }): {
+        decision: "reject";
+        reason: string;
+        source: ExtensionRecord;
+    };
+    readContribution: (event: import("../../records/journal.js").JournalEvent) => {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    } | undefined;
+    readSource: (source: DeepReadonly<ExtensionRecord> | null) => {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    } | undefined;
+    told: import("../../journal/projection.js").PluginProjection<import("../../services/extensionEvents.js").ToldNotices<{
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    }>>;
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: {
+            id: string;
+            exit_code: number | null;
+            exit_signal: string | null;
+            summary: string;
+        }, event: import("../../records/journal.js").JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): import("../../journal/projection.js").PluginProjection<State>;
+};
+/** What a command notice's source carries, when `source` is one; `undefined` for any other. For a host drawing the notice. */
+export declare const readCommandNotice: (source: DeepReadonly<ExtensionRecord> | null) => CommandNotice | undefined;
+/** The foreground command tool's name. */
+export declare const RUN_COMMAND = "run_command";
+/**
+ * How a `run_command` call's process group is known to have ended, from its rows alone, on
+ * affirmative evidence only: `not-run` while no dispatch attempt of it was allowed, or the runtime
+ * dispatcher records that execution was prevented before entering middleware. Otherwise,
+ * `ended` only when its result carries the tool's own report that the stop
+ * succeeded (`stop_failed: false`), `stop-failed` when that report says the stop failed, and
+ * `unknown` otherwise: no result yet, a call cut off, or a result written by anything but the tool,
+ * such as an error that replaced its report.
+ */
+export type ForegroundEnd = 'not-run' | 'ended' | 'stop-failed' | 'unknown';
+/**
+ * Foreground commands, by their `tool/call` or runtime `execution/requested` row. Authorization
+ * marks a possibly started group; only the executor's result establishes cleanup, or the runtime
+ * dispatcher's unstarted outcome establishes that nothing ran. Resets at a
+ * fork's spawn row, as the background records do.
+ */
+export declare const foregroundCommands: import("../../journal/projection.js").PluginProjection<Map<number, ForegroundEnd>>;
+/**
+ * A command a thread's rows leave without affirmative evidence of its end: a background one with no
+ * end row, or a `run_command` call launched with no report of its end from the tool itself; either
+ * kind with `stop_failed` when the stop it reported failed to end its process group.
+ */
+declare const UnendedCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"background">;
+    id: z.ZodString;
+    stop_failed: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"foreground">;
+    call_seq: z.ZodNumber;
+    stop_failed: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"runtime">;
+    request_seq: z.ZodNumber;
+    stop_failed: z.ZodBoolean;
+}, z.core.$strict>], "kind">;
+export type UnendedCommand = z.output<typeof UnendedCommandSchema>;
+/**
+ * What a thread's catalog entry says of its commands: those without an established end, for every
+ * thread while the commands plugin is mounted. A thread whose records cannot be read reads
+ * `unavailable`, which nothing reads as "none".
+ */
+export declare const commandsContribution: import("../../services/catalogContributions.js").ContributionDefinition<({
+    kind: "background";
+    id: string;
+    stop_failed: boolean;
+} | {
+    kind: "foreground";
+    call_seq: number;
+    stop_failed: boolean;
+} | {
+    kind: "runtime";
+    request_seq: number;
+    stop_failed: boolean;
+})[]>;
+export {};