@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/plugins/workflows/fold.d.ts

@@ -0,0 +1,373 @@
+import { type AnswerCheck } from '../../loop/index.js';
+import type { JournalEvent, Seq } from '../../models/index.js';
+import type { ReadonlyState } from '../../util/foldState.js';
+import type { JsonValue, ReadonlyJsonValue } from '../../util/json.js';
+import type { WorkflowDefinition } from './definition.js';
+import { type Citation, type Decided, type Entered, type InstanceRow, type Observation, type Opened } from './record.js';
+/**
+ * Where an assignment stands: `scheduled` until its activation input is claimed, `active` from that
+ * claim, `candidate` while a submission of it is the answer under check, `accepted` once core
+ * accepts that answer, and `superseded` once its authority closed without acceptance.
+ */
+export type AssignmentState = 'scheduled' | 'active' | 'candidate' | 'accepted' | 'superseded';
+/**
+ * A submitted output, the `tool/result` row that recorded it, and the `tool/call` row of the call
+ * that made it (`null` when the result cites none).
+ */
+export type Submitted = {
+    readonly output: JsonValue;
+    readonly seq: Seq;
+    readonly call: Seq | null;
+};
+/**
+ * The search for a replacement activation input, once the recorded one was removed before its claim
+ * (a Stop's clear, a withdrawal): the unsourced inputs queued on the root since that removal and still
+ * queued, in queue order, each with whether a person's wake brought it.
+ */
+export type Replacement = {
+    readonly queued: {
+        readonly id: string;
+        person: boolean;
+    }[];
+};
+export type AssignmentRecord = {
+    readonly id: string;
+    readonly participant: string;
+    /** Whether the conversation participant works it on the root, or an isolated one on its child. */
+    readonly context: 'conversation' | 'isolated';
+    /** The thread it runs in: the root, or the participant's child. */
+    readonly thread: string;
+    /** Its delegation task on the child; `null` on the root. */
+    readonly task: string | null;
+    /** The participant generation it was pinned to; `null` on the root. */
+    readonly generation: number | null;
+    /** Whether an isolated one's child is the participant's own conversation or its attempt's; `null` on the root. */
+    readonly lifetime: 'instance' | 'attempt' | null;
+    /** The check providers judging an isolated one's answer, as its entry recorded them; none on the root. */
+    readonly checks: readonly string[];
+    /**
+     * The input recorded as its activation: on the root, the host's first input or its transition's
+     * scheduling input; on a child, its task's input.
+     */
+    readonly activation: string;
+    state: AssignmentState;
+    /** Set once its root activation input was removed unclaimed; see {@link activationInput}. */
+    replacement: Replacement | null;
+    /** The root's `input/message` row that claimed its activation input; a child's claim is the child's. */
+    claimSeq: Seq | null;
+    /** The submission under check on the root, while it is the root's answer. */
+    candidate: Submitted | null;
+    /**
+     * Its latest submission, kept whatever became of it: diagnostic history apart from the answer
+     * under check, which a recovery shows its producer and the coordinator, labeled unaccepted.
+     */
+    submitted: Submitted | null;
+    /**
+     * The submission accepted: latched, so later input never takes it back. For an isolated
+     * participant, its output as the root's observation of the child carried it, at that row.
+     */
+    accepted: Submitted | null;
+    /** The epoch of the latest submission reminder it was sent ({@link submissionReminder}). */
+    reminded: Seq | null;
+    /**
+     * The root row at which its authority closed: the turn ending that accepted it, the observation
+     * that carried its child's acceptance, or the row that superseded it. `null` while it is open.
+     */
+    closed: Seq | null;
+};
+export type AttemptRecord = {
+    readonly entered: Entered;
+    readonly seq: Seq;
+    readonly assignments: readonly AssignmentRecord[];
+    /** Its result, once every assignment is accepted; at entry for a pure gate. Never once it recovers. */
+    result: string | null;
+    /** Its recovery, once an isolated participant's task ended without acceptance. */
+    recovery: RecoveryRecord | null;
+};
+/**
+ * An attempt that will produce no result, and the one decision a person owes on it: its assignment
+ * authority closed at its boundary, and what it shows is frozen there, so later events change none
+ * of it. An accepted sibling keeps its history, but never makes a partial result.
+ */
+export type RecoveryRecord = {
+    /** A participant's task ended without acceptance (`failure`), or a person stopped the attempt (`stop`). */
+    readonly cause: 'failure' | 'stop';
+    readonly detail: string;
+    /** The row that opened it: its boundary. */
+    readonly seq: Seq;
+    /** By participant, unaccepted: each one's latest submission, and its partial report. */
+    readonly candidates: Readonly<Record<string, JsonValue>>;
+    readonly reports: Readonly<Record<string, string>>;
+    /** The decision on it, once one is recorded. */
+    decision: string | null;
+};
+/** An accepted result: the outputs of one attempt, by participant, and what happened to it. */
+export type ResultRecord = {
+    readonly revision: string;
+    readonly attempt: string;
+    readonly step: string;
+    readonly outputs: Readonly<Record<string, JsonValue>>;
+    /** The row that completed it: the last acceptance, or a pure gate's entry. */
+    readonly seq: Seq;
+    /** The host decision on it, once one is recorded. */
+    decision: string | null;
+    /** The transition it, or its decision, made. */
+    routed: string | null;
+    /** Retired by its own step's re-entry. Its dependents go stale with it ({@link staleResults}). */
+    retired: boolean;
+};
+export type DecisionRecord = Decided & {
+    readonly seq: Seq;
+};
+/**
+ * The fold's records as a reader holds them from `journal.state`: read-only views of what the
+ * reducer mutates. A function that only reads takes the view, so the reducer and a reader share it.
+ */
+export type AssignmentView = ReadonlyState<AssignmentRecord>;
+export type AttemptView = ReadonlyState<AttemptRecord>;
+export type RecoveryView = ReadonlyState<RecoveryRecord>;
+export type ResultView = ReadonlyState<ResultRecord>;
+/** A cancellation admitted, or a decision recorded, under its operation id: what a replay compares. */
+export type Operation = Extract<InstanceRow, {
+    op: 'decided' | 'cancel-requested';
+}>;
+/**
+ * One workflow instance as its root's rows leave it, recorded facts only: nothing here depends on
+ * which definitions are registered. What is pending, where it goes next and what may run are
+ * derived from it, with the definition, by `routing.ts` and `view.ts`.
+ */
+export type InstanceState = {
+    /** The instance's id: its root thread's, which every identity it derives starts with. */
+    instance: string | null;
+    opened: Opened | null;
+    /** Every attempt by id, in entry order. */
+    readonly attempts: Map<string, AttemptRecord>;
+    /** The latest attempt. */
+    current: AttemptRecord | null;
+    /** Every result by revision, in the order they were accepted. */
+    readonly results: Map<string, ResultRecord>;
+    readonly decisions: Map<string, DecisionRecord>;
+    readonly operations: Map<string, Operation>;
+    /** Each step's entries over the instance's life. */
+    readonly ordinals: Map<string, number>;
+    /** Each step's entries since the latest host decision: what its `maxAttempts` bounds. */
+    readonly counts: Map<string, number>;
+    /** Each restarted participant's conversation generation; see {@link generationOf}. */
+    readonly generations: Map<string, number>;
+    /** Every acceptance or ending observed of a child, by its task: one per task, the first; later ones are kept nowhere. */
+    readonly observed: Map<string, Observation & {
+        readonly seq: Seq;
+    }>;
+    /**
+     * The latest person's Stop of the instance (its `stopped` row and why): the boundary a transition
+     * owed by a result ready before it is judged against ({@link stopOwed}).
+     */
+    stop: {
+        readonly seq: Seq;
+        readonly reason: string;
+    } | null;
+    cancellation: Extract<InstanceRow, {
+        op: 'cancel-requested';
+    }> | null;
+    terminal: null | {
+        readonly kind: 'completed';
+        readonly transition: string;
+    } | {
+        readonly kind: 'cancelled';
+    };
+    /** The thread's answer under check, as core's stop checks fold it. */
+    answer: AnswerCheck;
+    /** The root's latest response and its calls, which the response fence orders a call by. */
+    readonly calls: Map<Seq, number>;
+    response: ResponseCalls['response'];
+    /** The root's latest unsourced input: a person's. */
+    personAt: Seq | null;
+};
+/**
+ * A thread's latest response that asked for calls, and its `tool/call` rows by seq, each with the
+ * call's position in that response: what the response fence orders a call by, on the root and on a
+ * participant's child alike.
+ */
+export type ResponseCalls = {
+    readonly calls: Map<Seq, number>;
+    /** The latest `assistant/message` that asked for calls, and their ids in order. */
+    response: {
+        readonly seq: Seq;
+        readonly ids: readonly string[];
+    } | null;
+};
+/**
+ * Whether the call recorded at `callSeq` comes after the submission whose call is `submittedCall` in
+ * the response that asked for both: core does not stop the rest of a batch after a concluding
+ * result, and records every call of it before any runs, so the calls after a submission under check
+ * are fenced by their position in that response, never by row order. The submission's own call is
+ * not after itself, so its replay stands.
+ */
+export declare function fencedCall(thread: ReadonlyState<ResponseCalls>, submittedCall: Seq | null, callSeq: Seq | undefined): boolean;
+/** What {@link live} reads of an instance's state. */
+type Liveness = {
+    readonly opened: unknown;
+    readonly terminal: unknown;
+    readonly cancellation: unknown;
+};
+/** Whether the instance can still take work: opened, not ending and not ended. */
+export declare const live: (state: Liveness) => boolean;
+/**
+ * The instance a root thread holds, folded from this plugin's rows and core's. The root's own
+ * assignment activates when a step claims its activation input (`input/message.input_id`), or the
+ * person's input replacing it once it was removed unclaimed ({@link activationInput}); its
+ * submission is a candidate while it is the answer under check; and it is accepted, latched, when
+ * core accepts that exact answer: the turn ending `completed` with the submission's result as the
+ * pending answer, read with core's own `answerCheck`. So nothing is written to accept, and core's
+ * answer check resetting on later input takes nothing back. An isolated participant's assignment
+ * is accepted, or its attempt recovers, by the root's observation of its child (`observed`), which
+ * carries the child's facts across, since this fold cannot read them; a person's Stop (`stopped`)
+ * recovers an attempt whose isolated work is still open. Submissions, claims, endings and
+ * observations outside the current attempt's open assignments are evidence only and advance
+ * nothing.
+ *
+ * Resets at a fork's spawn row: a fork inherits no workflow state.
+ */
+export declare const instanceFold: import("../../journal/projection.js").PluginProjection<InstanceState>;
+/**
+ * The input whose claim activates a scheduled assignment now: its recorded activation input while
+ * that was not removed; after a removal, the first input queued on the root since then that is
+ * still queued and that a person's wake brought; `null` while there is none. Each later removal
+ * reselects, since a removed input leaves the queue. Sourced input never qualifies, nor unsourced
+ * input without a person's wake: the host's own notices are not a person's.
+ */
+export declare function activationInput(assignment: AssignmentView): string | null;
+/** A response that asks for calls: the one later `tool/call` rows are placed in. A cut-off reply asks for none. */
+export declare function respond(state: ResponseCalls, event: JournalEvent<'assistant/message'>): void;
+/** A call of the latest response recorded: its position in that response, by its row. */
+export declare function call(state: ResponseCalls, event: JournalEvent<'tool/call'>): void;
+/**
+ * The epoch of `assignment`'s submission reminder: the later of its activation's claim and the
+ * person's latest input. `null` while it is not active.
+ */
+export declare function reminderEpoch(state: ReadonlyState<InstanceState>, assignment: AssignmentView): Seq | null;
+/**
+ * What an instance's continuation refers to in its definition, from recorded facts alone, so a
+ * root's catalog entry can carry it and the check needs nothing loaded: the definition's id; while it
+ * is live, the step it stands on; and each participant whose assignment of the current attempt is
+ * still open (`open`), or that has a conversation of its own in the instance, which later steps
+ * continue (`persistent`), with the context it was recorded in.
+ */
+export type DefinitionReferences = {
+    readonly id: string;
+    readonly step: string | null;
+    readonly participants: Readonly<Record<string, {
+        readonly context: 'conversation' | 'isolated';
+        readonly open: boolean;
+    }>>;
+};
+/**
+ * The participants with a conversation of their own in the instance, as their entries recorded
+ * them (an isolated assignment of `instance` lifetime), each with its current generation's child:
+ * the one later entries continue. A generation a restart superseded is history, not listed.
+ */
+export declare function persistentConversations(state: ReadonlyState<InstanceState>): Map<string, string>;
+/** What `state`'s continuation refers to in its definition ({@link DefinitionReferences}). */
+export declare function definitionReferences(state: ReadonlyState<InstanceState>): DefinitionReferences;
+/**
+ * Why an instance cannot continue on `registered`, the definition registered under its id now, or
+ * `null` when it can (the recovery compatibility check): the one rule every reader of execution
+ * applies. Execution always takes the definition registered now, so an edit applies to a running
+ * instance from its next action, and accepted results stay as recorded. It is held only where it
+ * literally cannot go on: no definition is registered under its id; the step it stands on is gone;
+ * a participant with an open assignment is gone, changed context (conversation or isolated) or is no
+ * longer assigned by that step; or a participant with a conversation of its own in the instance is
+ * gone or no longer isolated. What an entered attempt recorded at entry (each assignment's
+ * participant, child, lifetime, generation and checks) is its contract while its assignments are
+ * open, so an edit to those applies from the next entry; prompts and schemas apply from the next
+ * presentation or submission. Edge targets, options and restart choices are derived from the
+ * definition at each read, and registration checks they resolve, so none can dangle; an isolated
+ * participant or provider the opening never pinned refuses the entry that needs it.
+ */
+export declare function heldBy(references: DefinitionReferences, registered: WorkflowDefinition | undefined): string | null;
+/**
+ * The definition an instance executes by: the one registered under its id now, unless the instance
+ * cannot continue on it ({@link heldBy}). `undefined` then: execution is blocked
+ * (`missing-binding`), while reads, cancellation and a terminal outcome stay, and registering a
+ * definition that fits resumes it. An availability condition derived at each read, never part of
+ * the fold.
+ */
+export declare function executable(state: ReadonlyState<InstanceState>, registered: WorkflowDefinition | undefined): WorkflowDefinition | undefined;
+/** What a decision decides: the step's accepted outputs, and every input its attempt bound at entry. */
+export type Subject = {
+    readonly outputs: Readonly<Record<string, ReadonlyJsonValue>>;
+    readonly inputs: Readonly<Record<string, {
+        readonly value: ReadonlyJsonValue;
+        readonly citation: Citation | null;
+    }>>;
+};
+/** The decision reasons. */
+export type DecisionReason = 'gate' | 'exhaustion' | 'recovery';
+/** The persistent participants one revise choice may name in `restart`, and those it must name. */
+export type RestartChoice = {
+    readonly required: readonly string[];
+    readonly allowed: readonly string[];
+};
+/** A decision a person owes, derived from the facts that make it pending; `decide` addresses its `id`. */
+export type PendingDecision = {
+    readonly id: string;
+    readonly attempt: string;
+    readonly reason: DecisionReason;
+    /** The cited result revision; `null` for recovery. */
+    readonly result: string | null;
+    /** Exactly what is decided, from recorded facts: a card renders it and never re-resolves bindings. */
+    readonly subject: Subject;
+    /** What `decide` would take now. Empty verdicts while execution is blocked or cleanup is pending. */
+    readonly actions: {
+        /**
+         * Whether a recovery's cleanup is not established yet: its attempt's work still ending, or of
+         * unknown end. No verdict is offered meanwhile, and `decide` refuses without consuming it.
+         */
+        readonly cleanupPending: boolean;
+        readonly verdicts: readonly ('approve' | 'revise')[];
+        readonly options: readonly string[];
+        /**
+         * By revise choice: a plain retry, and each option offered. Empty but on a recovery, the only
+         * decision that restarts anyone; its required restarts are the allowed participants whose
+         * conversation delegations would not continue now.
+         */
+        readonly restart: {
+            readonly retry: RestartChoice;
+            readonly options: Readonly<Record<string, RestartChoice>>;
+        };
+    };
+    readonly detail: {
+        /** The transition exhaustion held back. */
+        readonly blocked?: {
+            readonly from: string;
+            readonly to: string;
+        };
+        readonly recovery?: {
+            readonly cause: 'failure' | 'stop';
+            readonly detail: string;
+            readonly candidates: Readonly<Record<string, ReadonlyJsonValue>>;
+            readonly reports: Readonly<Record<string, string>>;
+        };
+    };
+};
+/** The routing envelope's decision: what a person decided on a result. */
+export type ResultDecision = {
+    readonly reason: DecisionReason;
+    readonly verdict: 'approve' | 'revise';
+    readonly option: string | null;
+    readonly feedback: string | null;
+};
+/** The host decision that opened an attempt, by identity; presented with it, so feedback needs no binding. */
+export type AttemptCause = {
+    readonly decision: string;
+    /** The attempt the decision was made on. */
+    readonly attempt: string;
+    readonly verdict: 'approve' | 'revise';
+    readonly option: string | null;
+    readonly feedback: string | null;
+};
+/** What opened `attempt`, when a host decision did; `null` for the opening and automatic routing. */
+export declare function attemptCause(state: ReadonlyState<InstanceState>, attempt: AttemptView): AttemptCause | null;
+/** The subject of a decision on `attempt`: its result's outputs, and its inputs as bound. */
+export declare function subjectOf(state: ReadonlyState<InstanceState>, attempt: AttemptView): Subject;
+export {};

package/dist/plugins/workflows/index.d.ts

@@ -0,0 +1,28 @@
+import type { Plugin } from '@leuduan/cordis';
+import { type WorkflowsConfig } from './service.js';
+/**
+ * Structured workflows: definitions made with `defineWorkflow` and registered here by the host, with
+ * the restriction policies and prerequisite checks they name, and the instances that run them,
+ * through the `ctx.workflows` service: `opening` for a root's creation, `read`, `decide`, `cancel`,
+ * and `stop` for a person's Stop of a root, which recovers isolated work it stops. Each
+ * instance's root and isolated participant is told its assignments at its model steps, granted
+ * `submit_workflow_output`, whose accepted answer alone advances it, and reminded once per epoch to
+ * submit; each, and every thread it starts, is restricted through the exact assignment serving it
+ * until the instance ends. An opening pins what the instance runs on (participants' configuration,
+ * the host's check and evidence providers), and entries acquire their evidence outside the journal
+ * write. Isolated participants' tasks are started by the plugin itself, as delegations' owner of
+ * them, independently of the root's turns; a definition with isolated participants needs
+ * delegations mounted first. All configuration is required. Root-only, mounted once by the
+ * application. See `docs/workflows.md`.
+ */
+export declare const workflows: Plugin.Object<WorkflowsConfig>;
+export { defineWorkflow, WorkflowDefinitionError } from './definition.js';
+export type { Assignment, Binding, CanonicalDefinition, Condition, Definition, Edge, JsonScalar, JsonSchema, Participant, ParticipantModel, Step, StepOption, WorkflowDefinition, } from './definition.js';
+export { WorkflowRefusedError } from './service.js';
+export { SUBMIT_TOOL, WORKFLOWS_OWNER } from './record.js';
+export type { CancelRequest, CatalogEntry, DecideRequest, OpeningRequest, Prerequisite, StopCancel, RoleBinding, WorkflowsConfig, WorkflowsService, } from './service.js';
+export type { Acquired, CheckProvider, CheckRequest, Configured, EvidenceProvider, EvidenceRequest, PinOutcome, ProviderBinding, ProviderNotice, } from './providers.js';
+export type { DecisionReason, PendingDecision, ResultDecision, Subject } from './fold.js';
+export type { Citation } from './record.js';
+export type { InstanceView } from './view.js';
+export type { Restriction } from './policy.js';