@leuduan/lagent 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import type { WriteRows } from '../../loop/index.js';
+import type { InitialInstallation, ThreadEnvironment } from '../../models/index.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);
+}