@leuduan/lagent 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,381 @@
+import type { Context } from '@leuduan/cordis';
+import { z } from 'zod';
+import type { ModelRoute } from '../../llm/index.js';
+import type { InvocationContext, ModelSelection, WriteRows } from '../../loop/index.js';
+import type { Seq, ThreadEnvironment, ToolResultPayloadInput, TurnEndReason } from '../../models/index.js';
+import type { DeepReadonly } from '../../util/json.js';
+import type { InitialInstallationInput } from '../../services/presets.js';
+import type { Thread } from '../../services/thread.js';
+import type { StopBy, TaskRef, TaskSettlement } from './record.js';
+import type { RoleConfig } from './role.js';
+/**
+ * The child thread for one start tool's call, so a call re-dispatched after a crash finds the child
+ * it made instead of starting a second one. Named after the `tool/call` row (`context.callSeq`), not
+ * the provider's call id: a later turn may be handed the same id again, and it must get a thread of
+ * its own.
+ */
+export declare const childThreadId: (callerThreadId: string, callSeq: Seq) => string;
+/**
+ * The task one delegating call opens: its id, which is also the input id the child is handed, so
+ * `send` with it queues nothing twice and a re-dispatch finds the `started` row it wrote.
+ */
+export declare const taskIdOf: (callerThreadId: string, callSeq: Seq) => string;
+/**
+ * The caller and the `tool/call` row that opened task `taskId`, or `null` for an id no call made:
+ * only what `taskIdOf` writes parses.
+ */
+export declare function openingCallOf(taskId: string): {
+    readonly callerThreadId: string;
+    readonly callSeq: Seq;
+} | null;
+/**
+ * What names a task an owner's assignment opens: the owner, its instance (the root the work runs
+ * under), the attempt and assignment, and the participant generation it runs on. Each assignment of
+ * a generation is one task, so a repeated start finds the task it opened.
+ */
+export type AssignmentTaskKey = {
+    readonly owner: string;
+    readonly instance: string;
+    readonly attempt: string;
+    readonly assignment: string;
+    readonly generation: number;
+};
+/**
+ * What names the conversation an owner's participant runs in: one per participant generation for
+ * the instance, or, for a conversation that lives for one attempt (`attempt` not `null`), per
+ * attempt too. A restart is a new generation, so it never finds the conversation it replaces.
+ */
+export type AssignmentConversationKey = {
+    readonly owner: string;
+    readonly instance: string;
+    readonly participant: string;
+    readonly attempt: string | null;
+    readonly generation: number;
+};
+/** The task one assignment of one participant generation opens, which is also its input's id on the child. */
+export declare const assignmentTaskId: (key: AssignmentTaskKey) => string;
+/** The child thread a participant generation runs in; an instance-lived one has no attempt part. */
+export declare const assignmentChildId: (key: AssignmentConversationKey) => string;
+/**
+ * The input a `message_agent` steer queues on the child, derived from the caller and the call as a
+ * task's id is, so the child's rows say whether a given steer landed and a re-dispatch sends nothing
+ * twice. Never a task id: a steer opens no task.
+ */
+export declare const steerInputId: (callerThreadId: string, callSeq: Seq) => string;
+/**
+ * Decodes the caller and call sequence encoded in a task or steering input id, or returns `null`
+ * for another format. This does not verify that the call exists or supplied the input.
+ */
+export declare function delegatedInputCall(inputId: string): {
+    readonly callerThreadId: string;
+    readonly callSeq: Seq;
+} | null;
+/** What every steer `callerThreadId` sends starts with. */
+export declare const steerPrefix: (callerThreadId: string) => string;
+/** `threadId` as a child `callerThreadId` created, which only that caller may continue, read, steer or stop; or why it is not one. */
+export declare function ownChild(ctx: Context, callerThreadId: string, threadId: string): Thread | string;
+/**
+ * Why a call may not give `child` work, continuing or steering it, or `null` when it may: an owner's
+ * assignment created it, so only that owner does. Its caller still reads and stops it.
+ */
+export declare function ownerManaged(child: Thread): string | null;
+/** The tool that gives a child that exists more work, whichever tool started it. */
+export declare const MESSAGE_AGENT_TOOL = "message_agent";
+/** What a caller is told when a delegated thread stopped without an answer. */
+export declare const describeFailure: (reason: DeepReadonly<TurnEndReason> | null) => string;
+/** Whether the call returns at once with a receipt, leaving the child to work while the caller goes on. */
+export declare const BackgroundField: z.ZodDefault<z.ZodBoolean>;
+/**
+ * The fields every delegating tool takes besides what it delegates: the route to run the child on,
+ * and whether to wait for it. Spread into a tool's own parameters, so each delegating tool offers
+ * them alike; a fork, which keeps its source's route, takes `background` alone.
+ */
+export declare const DelegationFields: {
+    background: z.ZodDefault<z.ZodBoolean>;
+    provider: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    model: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    thinking_effort: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+        low: "low";
+        high: "high";
+        none: "none";
+        medium: "medium";
+        max: "max";
+    }>>>;
+};
+export type DelegationFieldValues = {
+    [K in keyof typeof DelegationFields]: z.output<(typeof DelegationFields)[K]>;
+};
+/**
+ * A delegating tool's parameters: its own `shape` with `DelegationFields`, where a blank string in a
+ * field that takes `null` reads as `null`, since some models send "" for "not set". Normalized ahead
+ * of validation rather than in the schema, so the schema advertised keeps its choices.
+ */
+export declare function delegationParameters<Shape extends z.ZodRawShape>(shape: Shape): z.ZodPreprocess<z.ZodObject<Shape & {
+    background: z.ZodDefault<z.ZodBoolean>;
+    provider: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    model: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    thinking_effort: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+        low: "low";
+        high: "high";
+        none: "none";
+        medium: "medium";
+        max: "max";
+    }>>>;
+} extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strip>, unknown>;
+/** The route fields a call named; an unnamed field keeps the route's own (`LlmService.resolveRoute`). */
+export declare const modelSelection: (fields: DelegationFieldValues) => ModelSelection;
+/**
+ * What a new child runs on: a registered global agent; a role, the agent named by its id, which the
+ * child's defining installation of the `role` preset defines in the child's own layer; or a fork
+ * of the caller, cut at the request that produced the call, on the caller's agent and route.
+ */
+export type DelegationTarget = {
+    readonly kind: 'agent';
+    readonly name: string;
+} | {
+    readonly kind: 'role';
+    readonly role: RoleConfig;
+} | {
+    readonly kind: 'fork';
+};
+/** The installation id a role child records its role under. */
+export declare const ROLE_INSTALLATION = "role";
+/**
+ * Why no child can be created on `role`, or `null`: its tools are checked against the global layer
+ * before anything is prepared, since its installation grants them without checking, and a child
+ * created with a missing one would lack it for good.
+ */
+export declare function roleRefusal(ctx: Context, role: RoleConfig): string | null;
+/** What a settled task told its caller: the answer, or why there is none. */
+export type DelegationOutcome = {
+    status: 'completed';
+    output: string;
+} | {
+    status: 'failed';
+    output: string;
+};
+/** What one delegating call asks for. */
+export type DelegationRequest = {
+    /**
+     * The child that does the task: a new one on `target`, named after this call, or one this thread
+     * created, continued by its id, whichever target made it.
+     */
+    readonly child: {
+        readonly kind: 'start';
+        readonly target: DelegationTarget;
+    } | {
+        readonly kind: 'continue';
+        readonly threadId: string;
+    };
+    /**
+     * Route fields folded over the route of the turn making the call for a new child, which is born on
+     * it, or over a continued child's own route, which they change; a fork takes none.
+     */
+    readonly selection?: ModelSelection;
+    /**
+     * Return a receipt once the task is open rather than wait for its answer; the task's drive
+     * outlives the call. Either way the task takes one of its origin root's `maxOpenTasks` slots.
+     */
+    readonly background?: boolean;
+    /** The task to open. A tool that must prepare it does so before it delegates. */
+    readonly task: string;
+    /**
+     * The caller's own rows for the write that opens the task, run inside it after delegations' checks
+     * pass and composed with the task's `started` row, input and cause: a creation's or a
+     * continuation's alike. A veto leaves nothing, no child created and no task opened, and the call
+     * is answered with its reason.
+     */
+    readonly rows?: WriteRows;
+    /**
+     * What the caller is told of a settled task, and of a delegation that failed before one: given
+     * the failure's text then. Without it, the answer or the failure as it is.
+     */
+    answer?(outcome: DelegationOutcome): ToolResultPayloadInput;
+};
+/**
+ * The authority a task is opened on, which its origin records: a caller's tool `call`, the
+ * invocation the call path adapts at the tool boundary (`DelegationsService.delegate`), with the
+ * child it names and how; or a registered owner's `assignment`, through its live registration
+ * (`DelegationsService.registerOwner`), with the configuration it pinned for the participant.
+ */
+export type TaskAuthority = {
+    readonly kind: 'call';
+    readonly context: InvocationContext;
+    /** A new child on `target`, or the existing child continued when `null`. */
+    readonly target: DelegationTarget | null;
+    readonly selection: ModelSelection;
+    readonly background: boolean;
+} | {
+    readonly kind: 'assignment';
+    readonly registration: AssignmentOwnerRegistration;
+    readonly callerThreadId: string;
+    readonly assignment: string;
+    readonly generation: number;
+    /** The caller's row that granted the assignment: ordered against stop obligations, never read as a call. */
+    readonly grantedSeq: Seq;
+    readonly configuration: PinnedConfiguration;
+};
+/** One start, as delegations' one admission reads it: the authority, the child and task it names, and what the task is. */
+export type TaskStart = {
+    readonly authority: TaskAuthority;
+    readonly childId: string;
+    readonly taskId: string;
+    readonly task: string;
+    readonly rows: WriteRows | null;
+    readonly signal: AbortSignal;
+};
+/**
+ * What an owner says of one of its assignments: it still authorizes its task (`allow`), or not,
+ * typed by what admission does next (see {@link Admission}): `hold` while what it needs is
+ * unavailable, `discard` once the assignment is superseded or stopped, `refusal` when it is refused
+ * for good, which the owner turns into its own recovery.
+ */
+export type OwnerVerdict = {
+    readonly kind: 'allow';
+} | {
+    readonly kind: 'hold' | 'discard' | 'refusal';
+    readonly reason: string;
+};
+/** One task an owner's assignment opens or opened, as its owner judges it: what its origin records. */
+export type AssignmentTask = TaskRef & {
+    readonly callerThreadId: string;
+    readonly assignment: string;
+    readonly generation: number;
+    readonly grantedSeq: Seq;
+};
+/**
+ * An owner of assignment-origin tasks, as it registers with delegations: its name, which its tasks'
+ * origins record, and its say over them. A name or an id grants nothing: only a live registration
+ * opens or runs an owner's task.
+ */
+export type AssignmentOwner = {
+    readonly name: string;
+    /**
+     * Whether the assignment still authorizes `task`, read synchronously from facts the owner keeps
+     * loaded: in `opening`, inside the write that opens or continues the task, where anything but
+     * `allow` refuses that write with its kind; in `running`, whenever core asks whether the task's
+     * child may run, where anything but `allow` holds it. Ask again with `AssignmentOwnerHandle.changed`.
+     */
+    authorize(task: AssignmentTask, phase: 'opening' | 'running'): OwnerVerdict;
+    /**
+     * Told, in the listener of the write that settled it, that a task of its settled, however it did:
+     * completed, failed, or stopped by anyone, a generic stop included; its outcome is durable, read
+     * with `AssignmentOwnerHandle.outcome`. Once per task in a process: a task that settled before the owner
+     * registered, across a restart included, is told right after it registers, while it is its
+     * child's latest.
+     */
+    settled(task: AssignmentTask): void;
+};
+/** A live registration, as delegations keeps it, until it is disposed. */
+export type AssignmentOwnerRegistration = {
+    readonly owner: AssignmentOwner;
+    disposed: boolean;
+};
+/**
+ * What an owner pins for a participant, exactly as its child is created on it and as a continuation
+ * finds it: the agent, the complete route and environment, the defining installations, each named
+ * by its id (delegations' admission refuses a start whose pin is not), and the constraint owners the
+ * child requires beside delegations' own, such as a check's that judges its answers.
+ */
+export type PinnedConfiguration = {
+    readonly agent: string;
+    readonly route: ModelRoute;
+    readonly environment: DeepReadonly<ThreadEnvironment>;
+    readonly installations: readonly InitialInstallationInput[];
+    readonly requires: readonly string[];
+};
+/**
+ * One start an owner asks for: the task of one assignment on one participant generation, under the
+ * caller whose row granted it, in the participant's conversation. Delegations derives the task and
+ * child ids from these (`assignmentTaskId`, `assignmentChildId`), creates the child on `configuration`
+ * when it does not exist and continues it otherwise, so the owner asks the same way whether the
+ * conversation is new or kept.
+ */
+export type AssignmentRequest = {
+    readonly callerThreadId: string;
+    readonly grantedSeq: Seq;
+    readonly instance: string;
+    readonly attempt: string;
+    readonly assignment: string;
+    readonly participant: string;
+    /** Whether the participant's conversation lives for the whole instance or for this attempt. */
+    readonly lifetime: 'instance' | 'attempt';
+    readonly generation: number;
+    readonly configuration: PinnedConfiguration;
+    /** The task's input on the child. */
+    readonly task: string;
+    /** The owner's own rows for the write that opens the task, as a call's `rows`. */
+    readonly rows?: WriteRows;
+    readonly signal: AbortSignal;
+};
+/** What an owner reads of one of its tasks: how it settled, if it has, who stopped it, if anyone did, and its latest prose. */
+export type AssignmentOutcome = {
+    readonly settlement: TaskSettlement | null;
+    /** Who stopped it and why: a generic stop (its caller's `stop_agent`, a host, a stop above it) included. */
+    readonly stop: {
+        readonly by: StopBy;
+        readonly reason: string;
+    } | null;
+    /**
+     * The latest assistant text since the task's claim, whatever settled it, open or not: a partial
+     * report its owner may show, never an answer.
+     */
+    readonly latestText: string | null;
+};
+/** An owner's live registration, as `registerOwner` returns it. */
+export type AssignmentOwnerHandle = {
+    /** Opens or replays the task `request` names, through delegations' one admission. */
+    start(request: AssignmentRequest): Promise<Admission>;
+    /** Task `task.taskId` as `task.childId` records it, or `null` when it records none. */
+    outcome(task: TaskRef): Promise<AssignmentOutcome | null>;
+    /** The owner's verdict on `childId`'s task may have changed: core asks again. */
+    changed(childId: string): void;
+    /** Withdraws the registration: unfinished starts are refused inside their writes, and its tasks held. */
+    dispose(): void;
+};
+/** A task an admission opened or found opened: where it runs, and, when it has settled, what its caller is told. */
+export type AdmittedTask = {
+    readonly taskId: string;
+    readonly childId: string;
+    readonly callerId: string;
+    readonly background: boolean;
+    /** The run request its opening write joined or opened, then each one it followed. */
+    readonly runId: string;
+    readonly outcome: DelegationOutcome | null;
+};
+/**
+ * What one admission decided, typed by what its starter does next rather than by its words:
+ * - `opened`: the task is open, by this write, or `replayed` from the write an earlier start of the
+ *   same task made, which takes no slot and reopens nothing.
+ * - `wait`: try again once it changes: every slot of the origin tree is taken (`capacity`), or the
+ *   child's earlier task, its run, its notice, its cleanup or its commands are still ending
+ *   (`predecessor`).
+ * - `hold`: something admission must read is unreadable or unavailable now: a task state, the
+ *   origin root, the owner an assignment needs, or what its owner says it needs.
+ * - `discard`: superseded: a stop over the caller, the end of the caller's own task, its owner
+ *   saying so, or the start's own cancellation, means nothing will open it.
+ * - `refusal`: durable for this child as asked: not one delegations manages, cancelled by a person,
+ *   stopped mid-work, commands with no established end, a role whose tools are missing, a caller
+ *   at its chain limit, or its owner refusing the assignment.
+ * - `conflict`: a start recorded under the task's identity differs from this one (its origin, or an
+ *   owner's task input or pinned configuration), or the child exists without it or is not the
+ *   owner's to continue; never adopted or replaced.
+ * - `vetoed`: the caller's own `rows` vetoed the write, for the reason it gave.
+ * Each kind but `opened` leaves nothing behind.
+ */
+export type Admission = {
+    readonly kind: 'opened';
+    readonly task: AdmittedTask;
+    readonly replayed: boolean;
+} | {
+    readonly kind: 'wait';
+    readonly on: 'capacity' | 'predecessor';
+    readonly reason: string;
+} | {
+    readonly kind: 'hold' | 'discard' | 'refusal' | 'conflict' | 'vetoed';
+    readonly reason: string;
+};
+/** An admission that did not open its task. */
+export type AdmissionRefused = Exclude<Admission, {
+    kind: 'opened';
+}>;

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

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+/**
+ * A sub-agent type given as configuration. Frozen: restoring requires a recorded configuration to
+ * parse back to itself, so any change, even a new field with a default, would strand every existing
+ * role child. Hence three fields and no more.
+ */
+export declare const RoleConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    basePrompt: z.ZodString;
+    tools: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type RoleConfig = z.output<typeof RoleConfigSchema>;
+export type RoleConfigInput = z.input<typeof RoleConfigSchema>;
+/** The role preset's id, registered by the `delegations` plugin when it mounts. */
+export declare const ROLE_PRESET = "role";
+/**
+ * Defines a role child's agent in the child's own layer: the agent named by the role id, with the
+ * role's base prompt, granted the role's tools. Recorded only at creation, by the delegations
+ * service for a role target, on a thread whose agent is the role id; the presets service checks that
+ * binding before anything is recorded.
+ *
+ * It does not check that the tools exist: a grant to a missing tool resolves to nothing, and a check
+ * here would stop existing children from ever activating once a root tool is renamed. The
+ * delegations service checks them before creating a child.
+ */
+export declare const rolePreset: import("../../services/preset.js").Preset<z.ZodObject<{
+    id: z.ZodString;
+    basePrompt: z.ZodString;
+    tools: z.ZodArray<z.ZodString>;
+}, z.core.$strict>>;