@leuduan/lagent 0.0.0-stage → 44.0.0

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

@@ -0,0 +1,633 @@
+import { z } from 'zod';
+import { type PluginJournal } from '../../journal/index.js';
+import { type AnswerCheck } from '../../state/index.js';
+import type { JournalEvent, Seq, ThreadOrigin, ThreadSummary, TurnEndReason } from '../../records/journal.js';
+import type { ToolResult, ToolResultPayloadInput } from '../../records/toolResult.js';
+import type { DeepReadonly } from '../../util/json.js';
+import { type AssignmentOutcome } from './request.js';
+import type { ReadonlyState } from '../../util/foldState.js';
+/**
+ * What the journal keeps of every delegation, on the child: the task was opened, stopped for good,
+ * and quiet after its stop. Written by the delegations service as `ext` rows of its own identity.
+ *
+ * `started` rides in the write that queues the task's input, the child's creation group or the
+ * `send` that continues it, so no child holds a task without its row. `stopped` is the durable intent
+ * of a stop; `stop_cleaned` says the stopped task's work went quiet, and changes no outcome.
+ */
+declare const DelegationRowSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"started">;
+    task_id: z.ZodString;
+    origin: z.ZodObject<{
+        caller_thread_id: z.ZodString;
+        source_seq: z.ZodNumber;
+        cause: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"call">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"assignment">;
+            owner: z.ZodString;
+            key: z.ZodJSONSchema;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>;
+    background: z.ZodBoolean;
+    notice: z.ZodBoolean;
+    run_id: z.ZodString;
+    task: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"stopped">;
+    task_id: z.ZodString;
+    by: z.ZodEnum<{
+        caller: "caller";
+        host: "host";
+        ancestor: "ancestor";
+    }>;
+    reason: z.ZodString;
+    call_seq: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"stop_cleaned">;
+    task_id: z.ZodString;
+}, z.core.$strict>], "op">;
+export type DelegationRow = z.output<typeof DelegationRowSchema>;
+/** A task's origin as its `started` row is written: the shape a start builds, before a fold holds it read-only. */
+export type StartedOrigin = Extract<DelegationRow, {
+    op: 'started';
+}>['origin'];
+export type TaskStarted = DeepReadonly<Extract<DelegationRow, {
+    op: 'started';
+}>>;
+export type TaskStopped = Extract<DelegationRow, {
+    op: 'stopped';
+}>;
+export declare const delegationRow: {
+    record: (value: {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    }) => import("../../records/journal.js").ExtensionRecord;
+    parse: (value: {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    }) => {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    };
+    entry: (value: {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: 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: PluginJournal, value: {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    }, options: import("../../journal/journal.js").AppendOptions): Promise<JournalEvent<"ext">>;
+    read(event: JournalEvent): {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    } | undefined;
+    contribution(message: {
+        role?: import("../../records/journal.js").InputRole;
+        content: string | readonly import("../../llm/content.js").ContentPartInput[];
+    }, value: {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    }, options?: {
+        sourceSeqs?: readonly Seq[];
+    }): import("../../records/journal.js").StepContribution;
+    matchesSource(record: DeepReadonly<import("../../records/journal.js").ExtensionRecord>): boolean;
+    rejection(reason: string, value: {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    }): {
+        decision: "reject";
+        reason: string;
+        source: import("../../records/journal.js").ExtensionRecord;
+    };
+    readContribution: (event: JournalEvent) => {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    } | undefined;
+    readSource: (source: DeepReadonly<import("../../records/journal.js").ExtensionRecord> | null) => {
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    } | undefined;
+    told: import("../../journal/projection.js").PluginProjection<import("../../services/extensionEvents.js").ToldNotices<{
+        op: "started";
+        task_id: string;
+        origin: {
+            caller_thread_id: string;
+            source_seq: number;
+            cause: {
+                kind: "call";
+            } | {
+                kind: "assignment";
+                owner: string;
+                key: z.core.util.JSONType;
+            };
+        };
+        background: boolean;
+        notice: boolean;
+        run_id: string;
+        task: string;
+    } | {
+        op: "stopped";
+        task_id: string;
+        by: "caller" | "host" | "ancestor";
+        reason: string;
+        call_seq: number | null;
+    } | {
+        op: "stop_cleaned";
+        task_id: string;
+    }>>;
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: {
+            op: "started";
+            task_id: string;
+            origin: {
+                caller_thread_id: string;
+                source_seq: number;
+                cause: {
+                    kind: "call";
+                } | {
+                    kind: "assignment";
+                    owner: string;
+                    key: z.core.util.JSONType;
+                };
+            };
+            background: boolean;
+            notice: boolean;
+            run_id: string;
+            task: string;
+        } | {
+            op: "stopped";
+            task_id: string;
+            by: "caller" | "host" | "ancestor";
+            reason: string;
+            call_seq: number | null;
+        } | {
+            op: "stop_cleaned";
+            task_id: string;
+        }, event: JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): import("../../journal/projection.js").PluginProjection<State>;
+};
+/**
+ * What decided a task, from the first settling row on: an accepted answer, a failure, or a stop. A
+ * failure says why: the turn ending that failed it, or the run serving it that failed without one.
+ */
+export type TaskSettlement = {
+    readonly kind: 'completed';
+    readonly output: string;
+} | {
+    readonly kind: 'failed';
+    readonly why: string;
+    readonly latestText: string | null;
+} | {
+    readonly kind: 'stopped';
+    readonly reason: string;
+};
+export type TaskState = 'open' | TaskSettlement['kind'];
+/**
+ * Who stopped a task: one of the `stopped` row's, or `person`, a person's cancel of an owner's
+ * child, which the fold derives from the cancel row itself.
+ */
+export type StopBy = TaskStopped['by'] | 'person';
+/** One task, as its child's rows record it. */
+export type TaskRecord = {
+    readonly started: TaskStarted;
+    /** The `started` row: a call addresses the latest task whose row precedes its own `tool/call` row. */
+    readonly startedSeq: Seq;
+    /**
+     * The run request serving the task: its assignment's, then each one the thread opens while the
+     * task is open, since every run of a delegated thread serves its open task; fixed once it settles.
+     */
+    runId: string;
+    /** The `input/message` row that claimed the task's input, once a step has. */
+    claimSeq: Seq | null;
+    settlement: TaskSettlement | null;
+    /** The task's stop: its `stopped` row, or a person's cancel of an owner's child; whether or not it settled the task. */
+    stop: {
+        readonly by: StopBy;
+        readonly reason: string;
+        readonly call_seq: Seq | null;
+    } | null;
+    cleaned: boolean;
+    /** The answer under check since the claim, read as core's stop checks read it. */
+    answer: AnswerCheck;
+    /** The latest assistant text since the claim. */
+    latestText: string | null;
+    /** How the latest turn since the task started ended, claimed or not: what a failed run that settles it reports. */
+    ending: TurnEndReason | null;
+};
+/** A task as a reader of the fold sees it. */
+export type ReadTask = ReadonlyState<TaskRecord>;
+/** A thread's tasks as its child: every one by id, and the latest, the only one that can be open. */
+export type DelegationTasks = {
+    readonly byId: Map<string, TaskRecord>;
+    latest: TaskRecord | null;
+};
+/**
+ * The caller's `tool/call` row that opened a task of `origin`, or `null` for one an owner's
+ * assignment opened: what a path about calls (a call's result, receipt or wait) reads, so no
+ * granting row is ever taken for a call.
+ */
+export declare const openingCall: (origin: ThreadOrigin) => Seq | null;
+/**
+ * The owner's assignment that opened a task of `origin`, or `null` for one a call opened: what a
+ * path about owners (their authority, their outcome) reads.
+ */
+export declare const openingAssignment: (origin: ThreadOrigin) => Extract<ThreadOrigin["cause"], {
+    kind: "assignment";
+}> | null;
+/** The latest task whose opening row strictly precedes a call, stable across re-dispatches. */
+export declare function taskBeforeCall(tasks: ReadonlyState<DelegationTasks>, callSeq: Seq): ReadTask | null;
+/**
+ * Whether a turn ending settles a delegated thread's work: `completed`, at which its pending answer is
+ * accepted, or a failure, `error`, `max-steps` or `rejected`. An `aborted`, `interrupted` or `blocked`
+ * ending settles nothing, since the next admission runs the thread again. The task fold reads it
+ * after its task's claim, and the backstop that stops what a delegated thread left open at every one.
+ */
+export declare const settlingEnding: (reason: Pick<TurnEndReason, "kind">) => boolean;
+/**
+ * The tasks a thread was given, read forward from each `started` row: the task's claim, then the
+ * answers and turn endings after it, until the first settling row: an accepted answer, a failure
+ * at a `settlingEnding`, or the failed settlement of the run serving it with no successor, which
+ * may have opened no turn at all. Any other ending settles nothing, so a task re-driven after a shutdown or a cancel
+ * settles on its next turn's answer. Raw rather than an `ext` fold because it reads core rows beside its own;
+ * resets at a fork's spawn row, so a fork owns none of its source's tasks.
+ */
+export declare const delegationTasks: import("../../journal/projection.js").PluginProjection<DelegationTasks>;
+/** The caller's result for its call at `callSeq`, from its loaded rows; `null` while the call has none. */
+export declare function callResult(journal: PluginJournal, callerId: string, callSeq: Seq): ToolResult | null;
+/**
+ * A background call's reply once its task is open: a non-error result whose metadata carries the
+ * receipt marker, the one result that does not end the task it cites. `toolName` is the start tool
+ * that opened it, or `null` for a continuation.
+ */
+export declare function receiptReply(toolName: string | null, childId: string, taskId: string): ToolResultPayloadInput;
+/** Whether `result` is task `taskId`'s receipt: a non-error result carrying the marker, which ends no task. */
+export declare function isReceipt(result: ToolResult, taskId: string): boolean;
+/**
+ * Whether the loaded thread's last turn left work behind: it ended `blocked`, or calls have no
+ * results. A task queued on it would wait behind an approval or calls that are not its own.
+ */
+export declare function stoppedMidWork(journal: PluginJournal, threadId: string): boolean;
+/** A task, by its id and the child it was given to. */
+export type TaskRef = {
+    readonly taskId: string;
+    readonly childId: string;
+};
+/**
+ * Task `task.taskId` as its loaded child `task.childId` records it, for the owner that assigned it:
+ * how it settled, if it has, who stopped it, if anyone did, and its latest prose; `null` when that
+ * owner assigned no such task there. Synchronous, so an owner can read it inside a write of its own while it holds
+ * the child loaded.
+ */
+export declare function assignmentOutcome(journal: PluginJournal, owner: string, task: TaskRef): AssignmentOutcome | null;
+/**
+ * What opened task `task.taskId` on child `task.childId`, as its `started` row records it: a call, or
+ * an owner's assignment, whichever opened it, creation or continuation; `null` when the child records
+ * no such task, as for a steer's input, which opens none. Read while the child is loaded, as a host
+ * draws the task's input.
+ */
+export declare function taskOrigin(journal: PluginJournal, task: TaskRef): ThreadOrigin | null;
+/**
+ * The row that opened the latest task of the loaded child `childId` (its `started` row), or `null`
+ * while it records none: a journal seq, comparable with any other thread's. Read from its rows, so it
+ * holds across a restart.
+ */
+export declare function latestTaskOpenedAt(journal: PluginJournal, childId: string): Seq | null;
+declare const LatestTaskSchema: z.ZodObject<{
+    task_id: z.ZodString;
+    origin: z.ZodObject<{
+        caller_thread_id: z.ZodString;
+        source_seq: z.ZodNumber;
+        cause: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"call">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"assignment">;
+            owner: z.ZodString;
+            key: z.ZodJSONSchema;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>;
+    run_id: z.ZodString;
+    background: z.ZodBoolean;
+    notice: z.ZodBoolean;
+    state: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        open: "open";
+        stopped: "stopped";
+    }>;
+    cleanup_pending: z.ZodBoolean;
+    first_line: z.ZodString;
+}, z.core.$strip>;
+/** A child's latest task, as its catalog entry carries it. */
+export type LatestTask = DeepReadonly<z.output<typeof LatestTaskSchema>>;
+/**
+ * What a thread's catalog entry says of its latest task: `null` for none, or for a thread
+ * delegations does not manage (`taskManaged`); `unavailable` when the entry cannot be read: the
+ * contribution failed or never ran for the thread, which nothing reads as "no task".
+ */
+export type TaskReading = LatestTask | null | {
+    readonly state: 'unavailable';
+    readonly error: string;
+};
+/** The constraint owner a delegated child requires, recorded at its creation. */
+export declare const DELEGATIONS_OWNER = "lagent:delegations";
+/**
+ * Whether delegations governs the thread: it requires {@link DELEGATIONS_OWNER}, which every child a
+ * task opens records at creation. Origin alone says only where a thread sits in its tree: a thread
+ * made by hand under another takes no task and runs when its host wakes it, as a root does.
+ */
+export declare const taskManaged: (summary: Pick<ThreadSummary, "requires">) => boolean;
+/** A managed thread's latest task, contributed to its catalog entry while delegations is mounted. */
+export declare const latestTask: import("../../services/catalogContributions.js").ContributionDefinition<{
+    task_id: string;
+    origin: {
+        caller_thread_id: string;
+        source_seq: number;
+        cause: {
+            kind: "call";
+        } | {
+            kind: "assignment";
+            owner: string;
+            key: z.core.util.JSONType;
+        };
+    };
+    run_id: string;
+    background: boolean;
+    notice: boolean;
+    state: "completed" | "failed" | "open" | "stopped";
+    cleanup_pending: boolean;
+    first_line: string;
+} | null>;
+/**
+ * Whether the thread's latest task settled while the run that served it still drains input it
+ * accepted before it settled: still work, though settled.
+ */
+export declare function taskDraining(journal: PluginJournal, child: ThreadSummary): boolean;
+/**
+ * What `threadId`'s latest task is, from its folds when it is loaded and its catalog entry
+ * otherwise: `null` for none or a thread delegations does not manage, `unavailable` for a managed
+ * thread whose entry has no valid value.
+ */
+export declare function readTask(journal: PluginJournal, threadId: string): TaskReading;
+/**
+ * Whether an approval holds up `childId`'s task, from the catalog: an unanswered confirmation on the
+ * child, or on a thread under it reached through the open tasks each thread above waits on. A thread
+ * waits on its open blocking tasks, whose calls run in its turn, and, once its own last turn ended
+ * `blocked`, on every open task it started, since it is parked on whatever it waits for. So a
+ * background grandchild's approval holds up the child's task only while the child is parked; and a
+ * parked thread whose approvals were all answered holds nothing up, and is driven again.
+ */
+export declare function blockedUnder(journal: PluginJournal, childId: string): boolean;
+export {};