@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/services/threads/birth.d.ts

@@ -0,0 +1,219 @@
+import { type ModelRoute } from '../../llm/provider.js';
+import type { Journal } from '../../journal/index.js';
+import { type BirthConflict } from '../../loop/index.js';
+import { type BirthSpec, type ForkOpening, type FreshOpening, type RowRef, type WriteRows } from '../../state/index.js';
+import type { InitialInstallation, Installation, JournalEventInput, Seq, ThreadEnvironment, ThreadInput, ThreadOrigin, ThreadSummary } from '../../records/journal.js';
+import type { Wake } from '../../state/index.js';
+import { type DeepReadonly, type ReadonlyJsonValue } from '../../util/json.js';
+import type { InitialInstallationInput, PresetsService } from '../presets/installations.js';
+/**
+ * What must match when a creation or fork finds its id taken: `identity` is the thread's agent,
+ * origin and whether it is a fork, and for a fork its cut; `configuration` also compares the
+ * birth the request resolves to with the one recorded.
+ */
+export type Reuse = 'identity' | 'configuration';
+/**
+ * What a new thread's opening write carries beside its spawn row, the same for `create` and `fork`:
+ * one group, so the thread never exists without them. All of it is creation-only: a thread found
+ * again under its id gets none, whichever {@link Reuse} the request names.
+ */
+export type Opening = {
+    /** The caller chooses the id once per creation and reuses it on retries. */
+    id: string;
+    /** Never inherited by a fork: application markers belong to the thread they were written on. */
+    metadata?: Readonly<Record<string, ReadonlyJsonValue>>;
+    /**
+     * The thread's first input, queued for a turn of its own. A fork created with one owes only it,
+     * not a reply to the conversation it inherited, until a step claims it.
+     */
+    input?: ThreadInput;
+    /** The first input's id, for idempotent re-dispatch; a fresh one when omitted. */
+    inputId?: string;
+    /** Plugin rows for the same group, or a veto that rejects the creation with its refusal; see {@link WriteRows}. */
+    rows?: WriteRows;
+    /**
+     * A cause in the same group asking the new thread to run, naming its first input, as `send`'s
+     * `wake`: how a delegation authorizes a new child's task in the write that opens it. It states no
+     * route: the thread is born on its own.
+     */
+    wake?: Wake;
+};
+/**
+ * What a fresh thread is born with, as a request states it. Each field `defaults` or `caller`
+ * leaves out is filled from that source; `exact` states a whole {@link BirthSpec} instead.
+ */
+export type BirthInput<I> = {
+    /**
+     * The route the thread is born on, complete: required, since which model a conversation runs on
+     * is the caller's choice. A later change travels with a cause's route statement.
+     */
+    route: ModelRoute;
+    /**
+     * Where the thread's work happens, field by field. An omitted field is the default: the root's
+     * `cwd`, or with `caller` the caller's. The cwd must be absolute.
+     */
+    environment?: Partial<DeepReadonly<ThreadEnvironment>>;
+    /**
+     * Preset installations the thread is born with, recorded in its spawn row, so the thread never
+     * exists without them and a fork cut anywhere inherits them, each with its lifetime: a `defining`
+     * one is never removed, a `configurable` one changes through `Thread.configure` as one applied
+     * later does. Validated as a configuration change validates, a preset that defines its thread's
+     * agent must define this one, and a creation preset must be `defining`. With `caller`, the
+     * installations the caller's live scope hands down follow these, as defining ones.
+     */
+    installations?: readonly I[];
+    /**
+     * The constraint owners, by plugin name, that every run of the thread is under: a run waits while
+     * one is not registered and repaired, and so does a run of every thread created under it by
+     * origin, which records only its own. A set: sorted and deduplicated when recorded.
+     */
+    requires?: readonly string[];
+};
+/**
+ * Where a fresh thread's configuration comes from, and its origin: where the thread came from, in
+ * the shape a summary records it, immutable once recorded; creation refuses one whose cited row is
+ * not the caller's (`origins.validate`).
+ *
+ * - `defaults`: fields left out come from core's configuration.
+ * - `caller`: fields left out come from the caller, plus what its live scope hands down; the caller
+ *   must have a live activation, whatever the origin's cause.
+ * - `exact`: reads nothing from the caller or core: the spec is the birth.
+ */
+export type BirthChoice<I> = {
+    origin?: ThreadOrigin;
+    birth: {
+        from: 'defaults';
+    } & BirthInput<I>;
+} | {
+    origin: ThreadOrigin;
+    birth: {
+        from: 'caller';
+    } & BirthInput<I>;
+} | {
+    origin?: ThreadOrigin;
+    birth: {
+        from: 'exact';
+        spec: BirthSpec;
+    };
+};
+/**
+ * How `create` starts a thread: its {@link Opening}, a {@link BirthChoice} and a {@link Reuse},
+ * both required, with no default. `caller` goes with `identity` only: comparing a birth that came
+ * from the caller's live hand-downs would not be a comparison of birth facts. Under `configuration`
+ * installations must be named, since generated ids cannot compare.
+ */
+export type CreateThreadOptions = Opening & (({
+    reuse: 'identity';
+} & BirthChoice<InitialInstallationInput>) | ({
+    reuse: 'configuration';
+} & Exclude<BirthChoice<InitialInstallationInput & {
+    installationId: string;
+}>, {
+    birth: {
+        from: 'caller';
+    };
+}>));
+/**
+ * Where a fork is cut. `at` names the row itself: a `thread/spawned`, `turn/start`, `llm/request`
+ * or `turn/end` row of the source's lineage, as a bare seq or as the `{ threadId, seq }` pair the
+ * thread helpers return. `atTurn` names any row of the lineage and cuts at the end of the turn
+ * holding it, or with `before`, just ahead of the turn, at its `turn/start`: edit and resend, with
+ * `input` in the turn's place, which `before` therefore requires. A turn that has not ended cannot
+ * be cut at its end.
+ */
+export type ForkCut = {
+    at: Seq | RowRef;
+    atTurn?: never;
+    before?: never;
+} | {
+    atTurn: Seq | RowRef;
+    before?: boolean;
+    at?: never;
+};
+/**
+ * How to fork a thread; see {@link ThreadsService.fork}. A fork inherits its route and installations
+ * at the cut; `reuse` is required: `identity` is the cut, agent and origin, `configuration` also
+ * the fork's own environment and `requires`.
+ */
+export type ForkOptions = Opening & ForkCut & {
+    reuse: Reuse;
+    /** Set by a delegating tool; a fork someone asks for directly has none and is a root. */
+    origin?: ThreadOrigin;
+    /**
+     * The environment of the thread `fork` is called on, field by field, where omitted — also when the
+     * cut is redirected to an ancestor, whose working directory may differ.
+     */
+    environment?: Partial<DeepReadonly<ThreadEnvironment>>;
+    /** The constraint owners the fork's runs are under, as {@link BirthInput.requires}. None when omitted. */
+    requires?: readonly string[];
+};
+/** What resolving a birth reads from outside its options. */
+export type BirthContext = {
+    readonly journal: Journal;
+    readonly presets: PresetsService;
+    /** The `environment.cwd` a thread created without one gets. */
+    readonly defaultCwd: string;
+    /**
+     * The installations the live scope of caller `callerId` hands down to a child on `agent`, refused
+     * when the caller has no live activation: its plugins could not say what the child is born with.
+     */
+    readonly handedDown: (agent: string, own: readonly Installation[], callerId: string) => InitialInstallation[];
+};
+/**
+ * A resolved opening: what a creation or fork records, built once and used for validation,
+ * comparison, a write-time callback's payload and the spawn row.
+ */
+export type ResolvedOpening = {
+    readonly kind: 'fresh';
+    readonly opening: FreshOpening;
+} | {
+    readonly kind: 'fork';
+    readonly opening: ForkOpening;
+};
+/** Constraint owners as a spawn row records them: a set, sorted and without repeats. */
+export declare const canonicalRequires: (requires: readonly string[] | undefined) => string[];
+/**
+ * Resolves a fresh creation's birth, validated before anything is appended. `origin` is the
+ * validated one (`null` for a root). Under `configuration` reuse every installation must name its
+ * id: a generated one could never compare.
+ */
+export declare function resolveFresh(context: BirthContext, args: {
+    agent: string;
+    origin: ThreadOrigin | null;
+    birth: CreateThreadOptions['birth'];
+    reuse: Reuse;
+}): FreshOpening;
+/**
+ * Resolves a fork's own configuration: its environment, field by field from `options`, else from the
+ * thread `fork` was called on (`named`, even when the cut redirects to an ancestor), and its
+ * constraint owners. The route and installations are the cut's, never stated.
+ */
+export declare function resolveForkOwn(named: ThreadSummary, options: Pick<ForkOptions, 'environment' | 'requires'>): {
+    environment: ThreadEnvironment;
+    requires: string[];
+};
+/** What a fork goes on with from its cut and does not record: the route and installations as the lineage folds to there. */
+export declare function inheritsAt(journal: Journal, cut: RowRef): ForkOpening['inherits'];
+/** The spawn row a resolved opening records. */
+export declare function spawnRow(resolved: ResolvedOpening, metadata: NonNullable<Opening['metadata']>): JournalEventInput['thread/spawned'];
+/** What a request must match of an existing thread by identity: its agent, origin and kind, and for a fork its cut. */
+export type Identity = {
+    readonly kind: 'fresh' | 'fork';
+    readonly agent: string;
+    readonly origin: ThreadOrigin | null;
+    readonly cut?: RowRef;
+};
+/**
+ * What differs between an existing thread and the identity a request asks for: its agent, its
+ * origin, whether it is a fork, and for a fork its cut. The origin is compared as the request states it.
+ */
+export declare function identityConflicts(summary: ThreadSummary, requested: Identity): BirthConflict[];
+/**
+ * What differs between a fresh birth's recorded spawn row and the birth requested: route,
+ * environment, installations and `requires`, the last as a set. Installation order is significant.
+ */
+export declare function specConflicts(spawn: JournalEventInput['thread/spawned'], requested: BirthSpec): BirthConflict[];
+/** What differs between a fork's recorded own configuration and the one requested. */
+export declare function forkConflicts(summary: ThreadSummary, requested: Pick<ForkOpening, 'environment' | 'requires'>): BirthConflict[];
+/** Throws {@link BirthConflictError} when `conflicts` is not empty. */
+export declare function requireNoConflicts(threadId: string, conflicts: readonly BirthConflict[]): void;

package/dist/services/threads/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What the rest of the package uses of `services/threads/`: the thread handle and its read view, run
+ * events, run-owner registration and the creation and fork shapes. Code outside this folder imports
+ * from here; `admission.ts`, `activation.ts` and the run owner's internals stay private to it.
+ */
+export { ThreadsService } from './service.js';
+export type { ConfigurationChange, ConfigurationResult, RetainOptions, RetainedMembers, Retention, ThreadFilter, Threads, ThreadsConfig, } from './service.js';
+export type { Thread } from './thread.js';
+export type { CancelOptions, ConfirmationAnswer } from './thread.js';
+export type { ThreadView } from './view.js';
+export type { BirthChoice, BirthInput, CreateThreadOptions, ForkCut, ForkOptions, Opening, Reuse } from './birth.js';
+export type { MissingDetail, OwnerHandle, OwnerReadiness, OwnerRegistration, StartOptions, StartupPolicy, ThreadInspection, WaitResolution, WaitValue, } from './runOwner.js';
+export { UnknownRunError, heldOrSettled, waitForRun } from './runEvents.js';
+export type { RunEvent, RunSource, RunState } from './runEvents.js';

package/dist/services/threads/runEvents.d.ts

@@ -0,0 +1,79 @@
+import type { RunOutcomeKind, RunSettledReason } from '../../records/journal.js';
+import type { DurableRunState, Hold, HoldBasis } from '../../state/index.js';
+/**
+ * Where one run request stands, as its waiters see it: waiting to be admitted (`requested`), with
+ * an execution serving it (`running`, finalization included), held with the request still pending,
+ * or settled. A held run carries its structured `hold` and the `basis` it was read on, an immutable
+ * observation at publication, not a snapshot of the thread. `{ reason: 'shutdown' }` is what a
+ * waiter is told when the application closes under it.
+ */
+export type RunState = {
+    readonly state: 'requested';
+} | {
+    readonly state: 'running';
+} | {
+    readonly state: 'held';
+    readonly hold: Hold;
+    readonly basis: HoldBasis;
+} | {
+    readonly state: 'settled';
+    readonly outcome: RunOutcomeKind;
+    readonly reason: RunSettledReason;
+    readonly errorText: string | null;
+};
+/**
+ * One change of a run's state, published as it happens: `requested` once its cause is durable,
+ * `running` at admission, and `held` or `settled` only after the execution's finalization and its
+ * release of the thread, so nothing that reads it can still find the execution running.
+ */
+export type RunEvent = {
+    readonly threadId: string;
+    readonly runId: string;
+} & RunState;
+/**
+ * The read rule, the same as the events': a run an execution serves is `running` until that
+ * execution releases the thread, even when its settlement row is already durable; a settled run
+ * with no live execution is its settlement; a pending one is what the owner's current decision for
+ * it says, `held` with its hold or `requested`, since holds have no rows to read. `null` for a
+ * run the reader does not know: one the thread never had, or, on a thread out of memory, one older
+ * than its pending run and its latest settlement, which its catalog entry does not keep.
+ */
+export declare function readRunState(facts: {
+    readonly durable: DurableRunState;
+    /** Whether an execution serving this run holds the thread now. */
+    readonly executing: boolean;
+    /** The hold the owner currently reads on the thread's pending request, `null` when it has none to say. */
+    readonly held: {
+        readonly hold: Hold;
+        readonly basis: HoldBasis;
+    } | null;
+}): RunState | null;
+/** Where a waiter reads runs from: the event stream, and the read that follows the same rule. */
+export type RunSource = {
+    onRunEvent(listener: (event: RunEvent) => void): () => void;
+    runState(threadId: string, runId: string): RunState | null;
+};
+/**
+ * A run a waiter named is unknown to the catalog: the thread never had it, or the thread is out of
+ * memory and the run is older than its pending run and its latest settlement. A read or a hold
+ * loads the thread, which knows its every run.
+ */
+export declare class UnknownRunError extends Error {
+    readonly threadId: string;
+    readonly runId: string;
+    constructor(threadId: string, runId: string);
+}
+/**
+ * Waits until run `runId` on `threadId` reaches a state `until` accepts, and resolves with it, where
+ * `source` is `ctx.threads`. The wait is for that run: not for the input that asked for it to be
+ * answered, nor for the thread to go quiet, since a cause that lands while an execution finishes is
+ * carried to a successor request. `queued.runId` of a `send` names the run to wait for. It
+ * subscribes first and reads the state after, so a change that happened before the call is read,
+ * not missed; on each event of the run it reads again rather than trust the event, which may be
+ * stale by the time it is delivered. Rejects with the signal's reason when aborted (the run goes on),
+ * with {@link UnknownRunError} for a run unknown to the catalog, and with whatever the read or
+ * `until` threw; unsubscribes however it ends.
+ */
+export declare function waitForRun(source: RunSource, threadId: string, runId: string, until: (state: RunState) => boolean, signal?: AbortSignal): Promise<RunState>;
+/** What a caller waiting for a run's work to stop waits for: the run held or settled, as `waitForRun`'s `until`. */
+export declare const heldOrSettled: (state: RunState) => boolean;