@leuduan/lagent 0.0.0-stage → 44.0.0

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

@@ -0,0 +1,261 @@
+import type { Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import { type PluginJournal } from '../../journal/index.js';
+import type { ExtensionRecord, Seq } from '../../records/journal.js';
+import { type TaskRef, type TaskState } from './record.js';
+import type { DeepReadonly } from '../../util/json.js';
+/** The most a notice quotes of what a blocking call would have returned; its closing hint comes on top. */
+export declare const NOTICE_TEXT_CHARS = 8000;
+declare const NoticeDataSchema: z.ZodObject<{
+    task_id: z.ZodString;
+    thread_id: z.ZodString;
+    status: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+    }>;
+    summary: z.ZodString;
+}, z.core.$strict>;
+/** What a notice's source carries. */
+export type NoticeData = z.output<typeof NoticeDataSchema>;
+/**
+ * The source of a completion notice: the input the delegations service queues on a caller when one
+ * of its background tasks completes or fails. Its `summary` is one bounded line, such as
+ * `explore t1/42/0 completed`, for a host to show collapsed and for compaction to read.
+ */
+export declare const noticeEvent: {
+    record: (value: {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    }) => ExtensionRecord;
+    parse: (value: {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    }) => {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    };
+    entry: (value: {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        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: PluginJournal, value: {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    }, options: import("../../journal/journal.js").AppendOptions): Promise<import("../../records/journal.js").JournalEvent<"ext">>;
+    read(event: import("../../records/journal.js").JournalEvent): {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    } | undefined;
+    contribution(message: {
+        role?: import("../../records/journal.js").InputRole;
+        content: string | readonly import("../../llm/content.js").ContentPartInput[];
+    }, value: {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    }, options?: {
+        sourceSeqs?: readonly Seq[];
+    }): import("../../records/journal.js").StepContribution;
+    matchesSource(record: DeepReadonly<ExtensionRecord>): boolean;
+    rejection(reason: string, value: {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    }): {
+        decision: "reject";
+        reason: string;
+        source: ExtensionRecord;
+    };
+    readContribution: (event: import("../../records/journal.js").JournalEvent) => {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    } | undefined;
+    readSource: (source: DeepReadonly<ExtensionRecord> | null) => {
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    } | undefined;
+    told: import("../../journal/projection.js").PluginProjection<import("../../services/extensionEvents.js").ToldNotices<{
+        task_id: string;
+        thread_id: string;
+        status: "completed" | "failed";
+        summary: string;
+    }>>;
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: {
+            task_id: string;
+            thread_id: string;
+            status: "completed" | "failed";
+            summary: string;
+        }, event: import("../../records/journal.js").JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): import("../../journal/projection.js").PluginProjection<State>;
+};
+/** What a notice's source carries, when `source` is one; `undefined` for any other. For a host drawing the notice. */
+export declare const readNotice: (source: DeepReadonly<ExtensionRecord> | null) => NoticeData | undefined;
+/** The notice's input id on the caller, derived from the task, so a redelivery queues nothing. */
+export declare const noticeInputId: (taskId: string) => string;
+/** A notice, ready to send: whom it goes to, for which task, its text and its source's data. */
+export type Notice = {
+    readonly callerId: string;
+    readonly callSeq: Seq;
+    readonly taskId: string;
+    readonly text: string;
+    readonly source: NoticeData;
+};
+/**
+ * The notice for a background task that settled: what a blocking call would have returned, bounded,
+ * framed as an `agent_notification` naming the child, the task, its agent and its status, with a
+ * closing hint naming `message_agent` and the thread when the child can be continued.
+ */
+export declare function composeNotice(task: {
+    readonly callerId: string;
+    readonly callSeq: Seq;
+    readonly childId: string;
+    readonly taskId: string;
+    readonly agent: string;
+    readonly status: 'completed' | 'failed';
+    readonly output: string;
+    readonly continuable: boolean;
+}): Notice;
+/**
+ * Where a background task's notice stands on its caller, by the one notice-debt predicate that
+ * sending, the successor rule, `resume` and the stop check all read. A notice is debt
+ * while it is **owed**, **unspent** and **unclaimed** (`unsent` or `queued`):
+ *
+ * - owed: the task's receipt is durable on the caller, and the caller's task its opening call
+ *   addressed, the latest whose `started` row precedes that call (the receiver), is open; a root
+ *   caller has none and is always owed, and a thread made by hand under another, which has none
+ *   either, is never owed: delegations wakes no thread it does not manage but a root.
+ *   `pending-receipt` while the call has no result yet; `unowed` once its result is not the
+ *   receipt, or the receiver has ended, for good;
+ * - unclaimed and unspent, by its input's fate on the caller (`inputFate`): its id is not known
+ *   there (`unsent`), or it is still queued (`queued`); once a step took it, `claimed`; a notice
+ *   discarded unread, withdrawn or cleared by a cancel, keeps its id known and is `spent`.
+ *
+ * Reads the caller's rows and folds, so the caller must be loaded: inside its own write, its turn,
+ * or a read of it.
+ */
+export type NoticeStanding = 'pending-receipt' | 'unowed' | 'unsent' | 'queued' | 'claimed' | 'spent';
+export declare function noticeStanding(journal: PluginJournal, task: {
+    readonly callerId: string;
+    readonly callSeq: Seq;
+    readonly taskId: string;
+}): NoticeStanding;
+/**
+ * Where the notice of task `taskId` stands on `callerId`, or `null` when that thread did not open
+ * the task by a call of its own: the id names another caller, or no call. The one way a caller asks
+ * about a task it knows by id; the caller must be loaded, as for {@link noticeStanding}.
+ */
+export declare function ownNoticeStanding(journal: PluginJournal, callerId: string, taskId: string): NoticeStanding | null;
+/** Whether a notice that stands so is still debt: owed, unspent and unclaimed. */
+export declare const isNoticeDebt: (standing: NoticeStanding) => boolean;
+/** Whether a notice that stands so can never be debt again. */
+export declare const noticeSettled: (standing: NoticeStanding) => boolean;
+/**
+ * Notice delivery, for the delegations service: the one path a background task's notice takes to
+ * its caller, and the withdrawal of notices no longer owed. Settling a task, its receipt landing,
+ * the successor rule, a wait and `resume` all deliver through `deliver`.
+ *
+ * The ordering it keeps: `afterEnding` runs in the listener of the write that ended a turn or
+ * settled a run, and enqueues there, before a run that goes round again can claim one, the
+ * withdrawal of the notices that write left unowed; and `deliver` enqueues its send synchronously when the child is loaded, as
+ * it is in that listener, with nothing awaited at its entrance, so the notice is ordered ahead of
+ * every write enqueued after the settle.
+ */
+export declare class NoticeDelivery {
+    /**
+     * Background tasks whose notice this process found queued, claimed, discarded or no longer owed:
+     * nothing is left to send for them, so `resume` does not read them again.
+     */
+    private readonly noticed;
+    private readonly ctx;
+    constructor(ctx: Context);
+    /**
+     * A turn ended or a run settled on `threadId`, either of which may have settled its latest task. A background task that
+     * completed or failed has its notice sent to its caller, enqueued here, in the listener of the
+     * write that settled it; and a delegated thread whose own task settled withdraws the notices still
+     * queued on it, which their receiver no longer owes anyone.
+     */
+    afterEnding(threadId: string): void;
+    /**
+     * The one delivery path of a notice: composed from the child, then one `send` on the caller under
+     * the notice's id and source, whose write-time check is the notice-debt predicate, so a notice not
+     * owed is refused inside the write and a redelivery queues nothing. Enqueued synchronously when the
+     * child is loaded, as it is in the listener of the write that settled its task; otherwise once the
+     * child is read.
+     */
+    deliver(childId: string, taskId: string): Promise<void>;
+    /**
+     * The successor rule's half: sends the notice of `childId`'s latest task, and returns where it
+     * stands on the caller then, or `null` when the task gets no notice.
+     */
+    deliverLatest(childId: string): Promise<NoticeStanding | null>;
+    /**
+     * Withdraws the notices queued on `threadId` that are no longer owed: what the live settle does,
+     * for a crash that came between a receiver's settling and that withdrawal. `resume` and a
+     * continuation, before it opens a new task on the thread, both ask for it.
+     */
+    withdrawExpired(threadId: string): Promise<void>;
+    /**
+     * Makes the notices of settled tasks a read returns on durable, through the one delivery path,
+     * which is idempotent and gated on the receipt: it sends the notice a crash left
+     * unsent, and for a live settle, whose send the settling write's listener already enqueued, its
+     * own send queues behind that one and finds it known. A failure is reported, and the read still
+     * returns.
+     */
+    durable(ended: readonly {
+        readonly task: TaskRef;
+        readonly state: TaskState | 'unavailable' | 'superseded';
+    }[]): Promise<void>;
+    /**
+     * `resume`'s notice work under `under`: withdraws the notices no longer owed that a crash between
+     * a settle and its withdrawal left queued, and sends those a crash between a settle and its notice
+     * left unsent, reading a child whose task state the catalog cannot give from its rows. Returns each
+     * write, failures reported.
+     */
+    resume(under: string): Promise<unknown>[];
+    /**
+     * The input queued on the loaded `threadId` that no one is owed any more: notices whose task of
+     * `threadId` they were owed to has settled, by the notice-debt predicate; and its own latest
+     * task's input, when that task failed before a step took it, in its setup say.
+     */
+    private expired;
+    /**
+     * The notice of task `taskId` on the loaded `childId`, or `null` when it gets none: its `started`
+     * row owes none (a blocking call's task, an owner's assignment), or it has not completed or failed. Its text is what a blocking call would have
+     * returned; the hint to continue the child is given unless it stopped mid-work.
+     */
+    private noticeOf;
+    private send;
+}
+export {};

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

@@ -0,0 +1,210 @@
+import { z } from 'zod';
+import { type AppendEntry, type PluginJournal } from '../../journal/index.js';
+import type { Seq } from '../../records/journal.js';
+import type { TaskRef } from './record.js';
+export declare const stopObligationRow: {
+    record: (value: {
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    }) => import("../../records/journal.js").ExtensionRecord;
+    parse: (value: {
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    }) => {
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    };
+    entry: (value: {
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_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: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    }, options: import("../../journal/journal.js").AppendOptions): Promise<import("../../records/journal.js").JournalEvent<"ext">>;
+    read(event: import("../../records/journal.js").JournalEvent): {
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    } | undefined;
+    contribution(message: {
+        role?: import("../../records/journal.js").InputRole;
+        content: string | readonly import("../../llm/content.js").ContentPartInput[];
+    }, value: {
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    }, options?: {
+        sourceSeqs?: readonly Seq[];
+    }): import("../../records/journal.js").StepContribution;
+    matchesSource(record: import("../../util/json.js").DeepReadonly<import("../../records/journal.js").ExtensionRecord>): boolean;
+    rejection(reason: string, value: {
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    }): {
+        decision: "reject";
+        reason: string;
+        source: import("../../records/journal.js").ExtensionRecord;
+    };
+    readContribution: (event: import("../../records/journal.js").JournalEvent) => {
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    } | undefined;
+    readSource: (source: import("../../util/json.js").DeepReadonly<import("../../records/journal.js").ExtensionRecord> | null) => {
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    } | undefined;
+    told: import("../../journal/projection.js").PluginProjection<import("../../services/extensionEvents.js").ToldNotices<{
+        op: "stop_requested";
+        obligation_id: string;
+        reason: string;
+        targets: {
+            task_id: string;
+            child_id: string;
+        }[];
+    } | {
+        op: "stop_completed";
+        obligation_id: string;
+    }>>;
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: {
+            op: "stop_requested";
+            obligation_id: string;
+            reason: string;
+            targets: {
+                task_id: string;
+                child_id: string;
+            }[];
+        } | {
+            op: "stop_completed";
+            obligation_id: string;
+        }, event: import("../../records/journal.js").JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): import("../../journal/projection.js").PluginProjection<State>;
+};
+/**
+ * The `stop_requested` row of a stop obligation over `targets`, for a write on `threadId`, the thread
+ * whose work they are: the one way an obligation is asked for, by delegations' own stop of everything
+ * under a cancelled thread (`stopObligationRows`) or by an owner stopping exactly its tasks.
+ * Delegations carries it out from the write's listener, and the next startup's repair does once more
+ * while it is outstanding, mounted or not when the row was written.
+ */
+export declare function stopObligation(threadId: string, reason: string, targets: readonly TaskRef[]): AppendEntry<'ext'>;
+/** One outstanding obligation: the row that asked for it, why, and the tasks it stops. */
+export type StopObligation = {
+    readonly id: string;
+    readonly seq: Seq;
+    readonly reason: string;
+    readonly targets: readonly TaskRef[];
+};
+/** A thread's outstanding stop obligations, by id. Resets at a fork's spawn row: a fork owes none. */
+export declare const stopObligations: import("../../journal/projection.js").PluginProjection<Map<string, StopObligation>>;
+/**
+ * A thread's outstanding obligations for its catalog entry, an empty list when it owes none: every
+ * entry carries the value, so one rebuilt without it, after a crash between rows and catalog, is
+ * one the registration's refresh recomputes.
+ */
+export declare const outstandingStops: import("../../services/catalogContributions.js").ContributionDefinition<{
+    obligation_id: string;
+    seq: number;
+    reason: string;
+    targets: {
+        task_id: string;
+        child_id: string;
+    }[];
+}[]>;
+/**
+ * What `threadId` owes: its outstanding obligations, none for a thread whose entry cannot be read
+ * (a refresh that failed leaves it so until its next write) and none for one the journal does not hold.
+ */
+export declare function readObligations(journal: PluginJournal, threadId: string): readonly StopObligation[];