@leuduan/lagent 0.0.0-stage → 44.0.0

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

@@ -0,0 +1,38 @@
+import type { Context } from '@leuduan/cordis';
+import type { AppendEntry } from '../../journal/index.js';
+import { type InstanceState } from './state.js';
+import type { InstanceRowInput } from './record.js';
+import type { Barrier } from './routing.js';
+import type { ReadonlyState } from '../../util/foldState.js';
+/**
+ * The one evidence barrier an instance's cancellation, its pending recovery's decision, the restarts
+ * that decision names and the successor it opens all wait on (decision 18 of the slice-2 plan). The
+ * lifetime owners answer for their own work, from durable evidence ({@link workUnder}): commands for
+ * whether each command ended, delegations for each task's settlement, cleanup and stop
+ * acknowledgement, and for whether a conversation can take another task (`continuation`). This
+ * combines them over what the instance owns:
+ *
+ * - an admitted cancellation: everything under the root;
+ * - a pending recovery: its attempt's isolated participants' children and everything under them,
+ *   with the root's stops of them; on a mixed step, whose root assignment it superseded too, also
+ *   the root's own work: its commands, the threads it started and the run that was under way at
+ *   the recovery's boundary; and each persistent participant's conversation, which is
+ *   draining while delegations says to wait, unknown while it cannot be asked (delegations not
+ *   mounted, the child not loaded), unresolved while its task state cannot be read, and
+ *   uncontinuable, so a decision must restart it, once delegations refuses it more work.
+ *
+ * Either way, a participant's start still in flight (`starting`, its assignments) is work still
+ * ending: it may yet open a task, or find its assignment superseded and open none. Anything else
+ * waits on nothing. Read synchronously, inside a write or while the threads it reads are held loaded.
+ */
+export declare function barrierOf(ctx: Context, state: ReadonlyState<InstanceState>, starting: readonly string[]): Barrier;
+/**
+ * The stop obligation, for the root write that records `row`, over the tasks a recovery it opens
+ * leaves running: when one of its observations ends a task without acceptance, the attempt recovers,
+ * and every other open isolated assignment's task that delegations' records show open or still
+ * draining is stopped for good, so nothing of the attempt keeps working while a person decides.
+ * Delegations carries it out from that write, or at its next repair. None otherwise.
+ */
+export declare function siblingStops(ctx: Context, state: ReadonlyState<InstanceState>, row: Extract<InstanceRowInput, {
+    op: 'observed';
+}>): AppendEntry<'ext'>[];

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

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { type ThinkingEffort } from '../../llm/primitives.js';
+import { type ReadonlyJsonValue } from '../../util/json.js';
+import type { ResultDecision } from './state.js';
+/** The edge target that completes an instance. */
+export declare const COMPLETE = "$complete";
+/** A value an edge predicate compares a field with. */
+export type JsonScalar = string | number | boolean | null;
+/** An isolated participant's model: a default, and whether the instance's starter may change it. */
+export type ParticipantModel = {
+    readonly provider: string;
+    readonly model: string;
+    readonly thinkingEffort?: ThinkingEffort;
+    readonly configurable: boolean;
+};
+export type Participant = 
+/** The root's own agent. */
+{
+    readonly context: 'conversation';
+}
+/** A delegated agent the workflow starts itself, under a host-bound role. */
+ | {
+    readonly context: 'isolated';
+    readonly lifetime: 'instance' | 'attempt';
+    readonly role: string;
+    readonly model: ParticipantModel;
+};
+export type Binding = {
+    /** The instance's input, a step's whole result, or one participant's output in it. */
+    readonly source: '$input' | {
+        readonly step: string;
+        readonly participant?: string;
+    };
+    readonly mode: 'current' | 'historical';
+    readonly optional: boolean;
+}
+/** A host-bound evidence provider, resolved at attempt entry. */
+ | {
+    readonly evidence: string;
+    readonly optional: boolean;
+};
+export type Assignment = {
+    readonly participant: string;
+    /** The step inputs this assignment receives. */
+    readonly reads: readonly string[];
+    readonly prompt: string;
+    readonly output: z.ZodType;
+    /** Host-bound check providers judging an isolated participant's answer; omitted = []. */
+    readonly checks?: readonly string[];
+};
+/** A choice a person may attach to a `revise`, with the decision reasons it may accompany. */
+export type StepOption = {
+    readonly name: string;
+    readonly on: readonly ('gate' | 'recovery')[];
+};
+/** One condition of an edge: the JSON Pointer `field` of the routing envelope equals `equals`. */
+export type Condition = {
+    readonly field: string;
+    readonly equals: JsonScalar;
+};
+export type Edge = {
+    readonly when: readonly Condition[] | 'otherwise';
+    readonly to: string;
+};
+export type Step = {
+    readonly inputs: Readonly<Record<string, Binding>>;
+    readonly assignments: readonly Assignment[];
+    /** A person's decision after every assignment is accepted. */
+    readonly gate: boolean;
+    /** Omitted = []. */
+    readonly options?: readonly StepOption[];
+    /** A host-bound allowlist policy name; `null` adds no step restriction. */
+    readonly restriction: string | null;
+    readonly maxAttempts: number;
+    /** Evaluated in order over the step's result; the first match is taken. The last is `otherwise`. */
+    readonly edges: readonly Edge[];
+};
+/**
+ * A workflow as its author writes it, handed to {@link defineWorkflow}. Its `id` is its whole
+ * identity: an edit that keeps the procedure's meaning (a prompt, a schema, an allowance) keeps the
+ * id and applies to running instances from their next action; a breaking one gets a new id.
+ */
+export type Definition = {
+    readonly id: string;
+    /** The instance's input. */
+    readonly input: z.ZodType;
+    readonly entry: string;
+    /** Host-bound checks on the conversation participant's agent; omitted = []. */
+    readonly prerequisites?: readonly string[];
+    readonly participants: Readonly<Record<string, Participant>>;
+    readonly steps: Readonly<Record<string, Step>>;
+};
+/** A definition's data with every omitted list filled in: what is validated. */
+export type DefinitionData = Omit<Definition, 'prerequisites' | 'steps'> & {
+    readonly prerequisites: readonly string[];
+    readonly steps: Readonly<Record<string, Omit<Step, 'options' | 'assignments'> & {
+        readonly options: readonly StepOption[];
+        readonly assignments: readonly (Assignment & {
+            readonly checks: readonly string[];
+        })[];
+    }>>;
+};
+/** A schema as its JSON Schema rendering: what the model is shown and an instance records. */
+export type JsonSchema = {
+    readonly [key: string]: ReadonlyJsonValue;
+};
+/**
+ * A definition as plain JSON: its data, omitted lists filled in, with every schema replaced by its
+ * rendering. It is the readable copy an instance records for audit and display, never executed.
+ */
+export type CanonicalDefinition = Omit<DefinitionData, 'input' | 'steps'> & {
+    readonly input: JsonSchema;
+    readonly steps: Readonly<Record<string, Omit<DefinitionData['steps'][string], 'assignments'> & {
+        readonly assignments: readonly (Omit<DefinitionData['steps'][string]['assignments'][number], 'output'> & {
+            readonly output: JsonSchema;
+        })[];
+    }>>;
+};
+/**
+ * A defined workflow: a frozen, canonical copy of the author's definition, admitted. Only
+ * {@link defineWorkflow} makes one, and registration takes nothing else. Its validators are rebuilt
+ * from the admitted schemas and held apart ({@link schemaOf}), so nothing the host holds, and
+ * nothing reachable from the definition, can change what it validates.
+ */
+export type WorkflowDefinition = CanonicalDefinition;
+/** A definition refused, with every problem found. */
+export declare class WorkflowDefinitionError extends Error {
+    readonly workflow: string;
+    readonly problems: readonly string[];
+    constructor(workflow: string, problems: readonly string[]);
+}
+export declare const isWorkflowDefinition: (value: unknown) => value is WorkflowDefinition;
+/** The schema `definition` validates its input, or one assignment's output, with; for this plugin only. */
+export declare function schemaOf(definition: WorkflowDefinition, target: '$input' | {
+    readonly step: string;
+    readonly participant: string;
+}): z.ZodType;
+/**
+ * Admits a workflow definition (§5 of the design): checks its shape, schemas and graph, then copies
+ * and freezes it. Every problem is reported at once in a {@link WorkflowDefinitionError}.
+ * Later changes to the object passed in change nothing about the definition returned. Names the host
+ * binds (restrictions, prerequisites, roles, providers) are checked when the definition is registered.
+ */
+export declare function defineWorkflow(definition: Definition): WorkflowDefinition;
+/** Splits a JSON Pointer into unescaped tokens, or `undefined` when it is not one. */
+export declare function pointerTokens(pointer: string): string[] | undefined;
+/** What a step's edges test: its accepted outputs by participant, and the decision on them. */
+export type Envelope = {
+    readonly outputs: Readonly<Record<string, ReadonlyJsonValue>>;
+    readonly decision: ResultDecision | null;
+};
+/**
+ * The edge routing takes: the first, in declaration order, whose every condition holds over
+ * `envelope`; a missing field holds no condition. Registration makes the last edge `otherwise`, so
+ * one always matches.
+ */
+export declare function selectEdge(edges: readonly Edge[], envelope: Envelope): Edge;
+/** What a recovery's revise with `option` routes over: no outputs, and the decision. */
+export declare const recoveryEnvelope: (option: string, feedback: string | null) => Envelope;
+/**
+ * Why `edge`, selected for a recovery's revise with `option`, cannot take it, or `null`: it must
+ * guard both `/decision/reason = recovery` and `/decision/option = option`, so an `otherwise` or a
+ * match that happens to hold never routes a recovery, and it must enter a step, not complete the
+ * instance, which a recovery has no result to complete with.
+ */
+export declare function recoveryEdgeProblem(edge: Edge, option: string): string | null;
+/** What a host binds by name for its definitions: what registration checks they name. */
+export type DefinitionBindings = {
+    /** Restriction policies, by name. */
+    readonly restrictions: ReadonlySet<string>;
+    /** Prerequisites the host checks, by name. */
+    readonly prerequisites: ReadonlySet<string>;
+    /** Roles isolated participants run under, by name. */
+    readonly roles: ReadonlySet<string>;
+    /** Check providers, by name. */
+    readonly checks: ReadonlySet<string>;
+    /** Evidence providers, by name. */
+    readonly evidence: ReadonlySet<string>;
+};
+/**
+ * Why `definition` cannot be registered against `bindings`: names it uses that the host does not
+ * bind. Whether a bound provider is available is asked at each opening, never here.
+ */
+export declare function bindingProblems(definition: WorkflowDefinition, bindings: DefinitionBindings): string[];

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

@@ -0,0 +1,95 @@
+import type { ReadonlyJsonValue } from '../../util/json.js';
+import type { CanonicalDefinition } from './definition.js';
+import type { InstanceState, ResultDecision } from './state.js';
+import type { Acquired } from './hostBindings.js';
+import type { ReadonlyState } from '../../util/foldState.js';
+import { type Entered, type InstanceRowInput, type TransitionCause } from './record.js';
+/**
+ * The results no longer current: each retired by its own step's re-entry (and `retiring`, retired
+ * by an entry being planned), and transitively each result whose attempt bound a stale one as a
+ * `current` input. Historical bindings need no freshness. A result binds only results accepted
+ * before it, so one pass in acceptance order settles every chain.
+ */
+export declare const staleResults: (state: ReadonlyState<InstanceState>, retiring?: ReadonlySet<string>) => Set<string>;
+/**
+ * The results that were no longer current when row `seq` was recorded: retired by the entries
+ * recorded up to it, and what was bound to those. What went stale after it is the difference from
+ * {@link staleResults}.
+ */
+export declare function staleAsOf(state: ReadonlyState<InstanceState>, seq: number): Set<string>;
+/** A recorded decision as the routing envelope carries it. */
+export declare function resultDecision(state: ReadonlyState<InstanceState>, decision: string | null): ResultDecision | null;
+/**
+ * The value input `name` of an attempt was bound to, as recorded: immutable results make a result's
+ * citation exact, and evidence is read from the entry that recorded it, never acquired again.
+ */
+export declare function boundValue(state: ReadonlyState<InstanceState>, entered: ReadonlyState<Entered>, name: string): ReadonlyJsonValue;
+/**
+ * A decision being planned in the same write as the entry: what it records on `result` (`null` for
+ * a recovery's), and the persistent participants it restarts, whose new generation the entry pins.
+ */
+export type Deciding = {
+    readonly result: string | null;
+    readonly id: string;
+    readonly decision: ResultDecision;
+    readonly restart: readonly string[];
+};
+/** An entry refused: the input that could not be bound, and why. Nothing is retired or consumed. */
+export type EntryRefusal = {
+    readonly refused: string;
+};
+/** The evidence an entry needs before it can be planned: what to acquire, for exactly this attempt. */
+export type EvidenceNeeds = {
+    readonly transition: string;
+    readonly attempt: string;
+    readonly step: string;
+    readonly inputs: readonly {
+        readonly input: string;
+        readonly provider: string;
+    }[];
+};
+/** Evidence acquired outside the write, for one transition into one attempt, by input. */
+export type EntryEvidence = {
+    readonly transition: string;
+    readonly attempt: string;
+    readonly inputs: ReadonlyMap<string, Acquired>;
+};
+/**
+ * Plans entering `step`, atomically: re-entry retires the step's current result, then every input
+ * binds against what remains, then the attempt opens with its assignments. The plan is one
+ * `entered` row, so its write retires, binds, opens and consumes the step's allowance together, or,
+ * refused, does none of it. Each assignment records where it runs and what activates it: the
+ * conversation participant's runs on the root, activated by `activation`, the host's first input at
+ * opening and the transition's scheduling input after; an isolated participant's runs as the task
+ * of its assignment on the child of its generation (the one a restart being decided gives it), its
+ * task's input activating it.
+ *
+ * - A `current` binding needs the producer's current result, approved if the step is gated; an
+ *   optional one binds `null` only when the producer has accepted nothing (for that participant).
+ *   A stale or unapproved result is not absence. The step's own current result is always retired
+ *   by its entry, so an optional current self-binding binds `null`.
+ * - A `historical` binding takes the producer's latest accepted result, retired or stale included,
+ *   such as the one this entry retires; optional when there is none yet.
+ * - An isolated participant the opening did not pin (one the definition registered now added, or
+ *   moved off the conversation) cannot run: the entry is refused.
+ * - An evidence binding takes what its provider acquired for this very attempt (`evidence`), with
+ *   the provider's citation, the value recorded in the row; once every other input binds, what is
+ *   not acquired yet is returned as `needs`. Absence binds `null` when the binding is optional and
+ *   refuses the entry otherwise; an unavailable answer refuses it either way.
+ */
+export declare function planEntry(state: ReadonlyState<InstanceState>, definition: CanonicalDefinition, request: {
+    readonly instance: string;
+    readonly step: string;
+    readonly cause: TransitionCause;
+    readonly activation: string;
+    /** The decision this entry's write records, which bindings already see. */
+    readonly deciding?: Deciding;
+    /** Evidence acquired for the entry; used only when it is for this very transition and attempt. */
+    readonly evidence?: EntryEvidence;
+}): {
+    readonly row: Extract<InstanceRowInput, {
+        op: 'entered';
+    }>;
+} | EntryRefusal | {
+    readonly needs: EvidenceNeeds;
+};

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

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import type { WriteRows } from '../../state/index.js';
+import type { InitialInstallation, ThreadEnvironment } from '../../records/journal.js';
+import type { DeepReadonly, JsonValue } from '../../util/json.js';
+/**
+ * A conversation's configuration as a provider pins from it: the root's, as the host proposes to
+ * create it, or an isolated participant's, as its opening resolved it. Installation ids are left
+ * out: they name installations, they do not configure them.
+ */
+export type Configured = DeepReadonly<{
+    environment: ThreadEnvironment;
+    installations: Omit<InitialInstallation, 'installation_id'>[];
+}>;
+/** What a binding tells the workflows that subscribe to it: its availability may have changed, or it is gone for good. */
+export type ProviderNotice = 'availability' | 'disposed';
+/** The pin a provider gives an opening, from which everything the instance asks of it is served; or why it cannot. */
+export type PinOutcome = {
+    readonly config: JsonValue;
+} | {
+    readonly refused: string;
+};
+/**
+ * What every provider binding is: a direct host binding, named by the definitions that use it. Its
+ * name is its whole identity, as a definition's id is: a change that would break the instances
+ * running on it binds under a new name. An instance records the serializable pin it was opened
+ * with, and runs only on a binding that still accepts that pin.
+ */
+export type ProviderBinding = {
+    /** Why it cannot serve now, or `null` when it can; synchronous. */
+    unavailable(): string | null;
+    /** Why it cannot serve a pin recorded earlier, or `null` when it can. */
+    validate(config: DeepReadonly<JsonValue>): string | null;
+    /** The pin an opening records from `configured`; asked outside any write, cancellable. */
+    pin(configured: Configured, signal: AbortSignal): Promise<PinOutcome>;
+    /**
+     * Calls `listener` when what `unavailable` answers may have changed, and once with `disposed`
+     * when the binding is gone for good. Returns the unsubscribe.
+     */
+    subscribe(listener: (notice: ProviderNotice) => void): () => void;
+};
+/**
+ * One requirement a check records for an assignment, in the write that opens the assignment's task:
+ * the pin the instance recorded, the owner and assignment it is for, the participant generation
+ * serving it, and the input whose claim activates it, the task's.
+ */
+export type CheckRequest = {
+    readonly config: DeepReadonly<JsonValue>;
+    readonly owner: string;
+    readonly assignment: string;
+    readonly generation: number;
+    readonly inputId: string;
+};
+/**
+ * A check provider: judges an isolated participant's answer through a requirement it owns. Its pin
+ * is taken from the configuration of each participant whose assignments list it. Every thread such
+ * an assignment runs on is created requiring `requires`, the constraint owners its judgement needs,
+ * so the thread is held rather than its answer accepted unchecked while the check's owner is
+ * missing; `owed` gives the rows recording the requirement, decided inside the write that opens the
+ * assignment's task, which they may refuse.
+ */
+export type CheckProvider = ProviderBinding & {
+    readonly requires: readonly string[];
+    owed(request: CheckRequest): WriteRows;
+};
+/** What one acquisition found: a value with its citation detail, a genuine absence, or no answer now. */
+export type Acquired = {
+    readonly kind: 'value';
+    readonly value: JsonValue;
+    /** Whether the value is a snapshot (`true`) or describes something live that can change. */
+    readonly immutable: boolean;
+    /** What the citation records of how it was acquired, such as a baseline. */
+    readonly detail: JsonValue;
+}
+/** There is nothing to bind: an optional binding binds `null`. */
+ | {
+    readonly kind: 'absent';
+}
+/** It could not be acquired now: never absence, so the entry is refused. */
+ | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+/** One acquisition for an attempt's entry. */
+export type EvidenceRequest = {
+    /** The pin the instance recorded at its opening. */
+    readonly config: DeepReadonly<JsonValue>;
+    readonly instance: string;
+    readonly attempt: string;
+    readonly step: string;
+    readonly input: string;
+    readonly signal: AbortSignal;
+};
+/**
+ * An evidence provider: supplies an input no participant produced, acquired at attempt entry
+ * outside the journal write. Its pin is taken from the root's configuration. A throw is an
+ * `unavailable` answer; an abort of the request's signal cancels the entry.
+ */
+export type EvidenceProvider = ProviderBinding & {
+    acquire(request: EvidenceRequest): Promise<Acquired>;
+};
+export declare const CheckProviderSchema: z.ZodCustom<CheckProvider, CheckProvider>;
+export declare const EvidenceProviderSchema: z.ZodCustom<EvidenceProvider, EvidenceProvider>;
+/** What an instance records of one provider at its opening. */
+export type ProviderPin = {
+    readonly config: JsonValue;
+};
+/**
+ * The providers one mount binds, as workflows holds them: it owns the subscription to each, the
+ * bindings that told it they are gone, and every acquisition in flight, which a provider's disposal
+ * or the mount's drain aborts and awaits. A binding is usable for a recorded pin only while it is
+ * not disposed, says it is available and accepts the pinned configuration.
+ */
+export declare class Providers {
+    private readonly disposed;
+    private readonly inFlight;
+    private readonly drained;
+    private readonly bindings;
+    constructor(bindings: Providers['bindings']);
+    /** Subscribes to every binding: `changed` hears each notice, after a disposal is taken in. Returns the unsubscribe. */
+    watch(changed: (kind: 'check' | 'evidence', name: string, notice: ProviderNotice) => void): () => void;
+    /** Why `name` cannot serve `pin` now, or `null`: absent, gone, unavailable, or refusing the pin. */
+    problem(kind: 'check' | 'evidence', name: string, pin: DeepReadonly<ProviderPin> | undefined): string | null;
+    /**
+     * The pin an opening records for `name`, refused when it is unavailable or refuses `configured`;
+     * rejects only with {@link CancelledError}.
+     */
+    pin(kind: 'check' | 'evidence', name: string, configured: Configured, signal: AbortSignal): Promise<ProviderPin | {
+        readonly refused: string;
+    }>;
+    /**
+     * Acquires evidence from `name` under the instance's pin: `unavailable` when the binding cannot
+     * serve the pin or the provider fails; rejects only with {@link CancelledError}, cancelled by the
+     * request's signal, the provider's disposal or the drain.
+     */
+    acquire(name: string, pin: DeepReadonly<ProviderPin> | undefined, request: Omit<EvidenceRequest, 'config'>): Promise<Acquired>;
+    /** Aborts every acquisition and pin in flight, and waits for each provider's own work to settle. */
+    drain(): Promise<void>;
+    private table;
+    private dispose;
+    /** Runs `work` under a signal the caller's, the drain or the provider's disposal aborts, kept until it settles. */
+    private tracked;
+}
+/** An acquisition or pin cancelled: by its caller's signal, the provider's disposal or the mount's drain. */
+export declare class CancelledError extends Error {
+    constructor(cause: unknown);
+}

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/records/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 { resolveParticipantModels, WorkflowRefusedError } from './participantModels.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 './hostBindings.js';
+export type { DecisionReason, PendingDecision, ResultDecision, Subject } from './state.js';
+export type { Citation } from './record.js';
+export type { InstanceView } from './view.js';
+export type { Restriction } from './policy.js';