@leuduan/lagent 0.0.0-stage → 44.0.0

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

@@ -0,0 +1,112 @@
+import { type Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { Seq, ThreadOrigin } from '../../records/journal.js';
+import type { WorkflowDefinition } from './definition.js';
+import { type AssignmentView, type InstanceState } from './state.js';
+import { type ChildFacts } from './observations.js';
+import type { ReadonlyState } from '../../util/foldState.js';
+/**
+ * A host-bound allowlist, the shape of a tool-policy mode's rules without `approve`: calls outside
+ * `allow` are denied; a listed call gains no grant and still needs the host's permission.
+ */
+export declare const RestrictionSchema: z.ZodObject<{
+    allow: z.ZodArray<z.ZodString>;
+    denial: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type Restriction = z.output<typeof RestrictionSchema>;
+/** What the workflow's authority reads besides the journal: the host's allowlists and what is registered. */
+export type Governance = {
+    /** The restriction policies steps name, by name. */
+    readonly restrictions: Readonly<Record<string, Restriction>>;
+    /** The allowlist the root works under while no assignment of its own is active. */
+    readonly coordination: Restriction;
+    /** The definition `state` executes by; `undefined` while none it can continue on is registered. */
+    readonly executable: (state: ReadonlyState<InstanceState>) => WorkflowDefinition | undefined;
+};
+/**
+ * Where a thread's call stands under a live instance: working an assignment, under that step's
+ * restriction (`null` adds none); coordinating, under the coordination policy, with why; or with no
+ * workflow authority at all (`closed`), which denies every call, with why.
+ */
+export type Standing = {
+    readonly kind: 'assignment';
+    readonly assignment: AssignmentView;
+    readonly restriction: Restriction | null;
+} | {
+    readonly kind: 'coordination';
+    readonly why: string;
+} | {
+    readonly kind: 'closed';
+    readonly why: string;
+};
+/**
+ * A thread under an instance that opened, by how it is governed: the instance's `root`; an isolated
+ * `participant`'s child, created by the instance's assignment origin, with its facts; or an ordinary
+ * `descendant` of either, with the row on the root or participant whose call (or grant) created the
+ * first thread of its line below them: the authority it keeps, whatever that thread's caller does
+ * later. A thread created by a call keeps that call's authority; a persistent parent's later
+ * assignment grants it nothing new.
+ */
+export type Governed = {
+    readonly root: string;
+    readonly state: ReadonlyState<InstanceState>;
+} & ({
+    readonly kind: 'root';
+} | {
+    readonly kind: 'participant';
+    readonly thread: string;
+    readonly facts: ReadonlyState<ChildFacts>;
+} | {
+    readonly kind: 'descendant';
+    readonly source: Source;
+});
+/** Where an ordinary descendant's line was created: on the root, or on a participant's child, at row `seq`. */
+type Source = {
+    readonly kind: 'root';
+    readonly seq: Seq;
+} | {
+    readonly kind: 'participant';
+    readonly thread: string;
+    readonly facts: ReadonlyState<ChildFacts>;
+    readonly seq: Seq;
+};
+/** Whether `origin` is an assignment of this plugin's on the root `root`: an isolated participant's child. */
+export declare const participantOrigin: (origin: ThreadOrigin | null, root: string) => boolean;
+/**
+ * How `threadId` is governed by the instance at the top of its origin tree, read from the catalog
+ * and the folds of the threads above it, which a run of it keeps loaded; `undefined` when no
+ * instance opened there; `unreadable` when its caller chain does not reach a root, so what governs
+ * it cannot be said, which fails closed.
+ */
+export declare function governedBy(ctx: Context, threadId: string): Governed | {
+    readonly unreadable: string;
+} | undefined;
+/** The current attempt's assignment for the conversation participant, the root's own, while it is open. */
+export declare function rootAssignment(state: ReadonlyState<InstanceState>): AssignmentView | undefined;
+/**
+ * The assignment a participant's child `thread` was working at its row `seq` (now, when `undefined`):
+ * the one whose task input the child claimed last by then. A persistent participant's tasks run one
+ * after another, so that claim names the task a call of it serves, a parked call answered later
+ * included.
+ */
+export declare function participantServing(state: ReadonlyState<InstanceState>, thread: string, facts: ReadonlyState<ChildFacts>, seq: Seq | undefined): AssignmentView | undefined;
+/**
+ * Where a call recorded at `callSeq` on a governed thread stands (§10 of the design), each thread
+ * through the exact assignment serving it:
+ *
+ * - the root, by its own assignment ({@link rootStanding});
+ * - a participant's child, by the assignment whose task the call serves ({@link participantServing}):
+ *   its step's restriction while that assignment is open, and nothing once it closed;
+ * - an ordinary descendant, by the authority that created its line: a line the root started while
+ *   coordinating coordinates, one started under an assignment, the root's or a participant's,
+ *   works under that assignment's restriction while it is open, and has none once it closed.
+ */
+export declare function standingOf(governed: Governed, governance: Governance, callSeq: Seq | undefined): Standing;
+/**
+ * Mounts the workflow's authority on the application root: the vote on every call, and the grant
+ * of `submit_workflow_output` to the agent of each instance root and each isolated participant's
+ * child, in its activation's scope, from activation while its instance has not ended until the row
+ * that ends it. The grant only offers the tool; the vote decides every call of it.
+ */
+export declare function enforceAuthority(ctx: Context, governance: Governance): void;
+export {};