@leuduan/lagent 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,549 @@
+import { z } from 'zod';
+import { type ExtensionRecord, type Seq } from '../../models/index.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("../../models/index.js").JournalEvent<"ext">>;
+    read(event: import("../../models/index.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("../../models/index.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("../../models/index.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("../../models/index.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("../../kit/extension.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("../../models/index.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("../../models/index.js").JournalEvent<"ext">>;
+    read(event: import("../../models/index.js").JournalEvent): {
+        id: string;
+        exit_code: number | null;
+        exit_signal: string | null;
+        summary: string;
+    } | undefined;
+    contribution(message: {
+        role?: import("../../models/index.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("../../models/index.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("../../models/index.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("../../kit/extension.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("../../models/index.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, so nothing was
+ * launched; once one was, `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';
+/**
+ * A thread's `run_command` calls, by the seq of their `tool/call` row, with how each one's process
+ * group is known to have ended. A foreground command leaves no record of its own: its call, the
+ * dispatch attempt allowed before the tool runs, and its result are the evidence. 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>], "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/contributions.js").ContributionDefinition<({
+    kind: "background";
+    id: string;
+    stop_failed: boolean;
+} | {
+    kind: "foreground";
+    call_seq: number;
+    stop_failed: boolean;
+})[]>;
+export {};