@leuduan/lagent 0.0.0-stage → 44.0.0

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

@@ -0,0 +1,450 @@
+import { Context, Service, type ScopeKey } from '@leuduan/cordis';
+import type { PromptBlock } from '../../llm/prompt.js';
+import type { ChainStanding, ConfirmationState, RouteAuthority, Target, TurnLimits, BirthSpec, HoldBasis } from '../../state/index.js';
+import type { CompactOptions, StreamedChunk, SurfacePrepareOutcome, BirthConflict } from '../../loop/index.js';
+import { ChunkChannel } from '../../loop/index.js';
+import type { ThreadOrigin } from '../../records/journal.js';
+import { type DeepReadonly } from '../../util/json.js';
+import { type OwnerHandle, type OwnerRegistration, type StartOptions, type ThreadInspection } from './runOwner.js';
+import type { RunEvent, RunState } from './runEvents.js';
+import type { InstallationInput } from '../presets/installations.js';
+import { type CreateThreadOptions, type ForkOptions } from './birth.js';
+import { Thread } from './thread.js';
+import { ThreadView } from './view.js';
+export type ThreadsConfig = {
+    /** Default `environment.cwd` for threads created without one; absolute. */
+    cwd: string;
+    /** The turn limits, resolved once by `core`, which hands the journal the same ones. */
+    limits: TurnLimits;
+    /**
+     * What becomes of a thread the owner loaded to run once its execution lets go and nothing else
+     * holds it: `retire` takes it out of memory, `keep` leaves it loaded. The application's choice.
+     */
+    retention: RetainOptions['lastRelease'];
+    /** How many reactive turns in a row a thread may run before its chain is at the limit. */
+    chainLimit: number;
+};
+/**
+ * A change to one thread's preset installations; see `Thread.configure`. Removals are recorded
+ * before applications, so a change that replaces an installation lists the old id in `remove` and
+ * the new one in `apply`.
+ */
+export type ConfigurationChange = {
+    readonly apply?: readonly InstallationInput[];
+    /** Installation ids to take off; one not installed is no change. */
+    readonly remove?: readonly string[];
+    /**
+     * Render the recorded prompt again once the change is restored, the one way a preset's prompt
+     * sections reach a thread that has already run. A thread with no recorded prompt records one on
+     * its first run anyway.
+     */
+    readonly rebuildPrompt?: boolean;
+};
+/** What a configuration change did. */
+export type ConfigurationResult = {
+    /** The id of every installation the change applies, in order, one applied before included. */
+    readonly applied: readonly string[];
+    /** The installations it took off. */
+    readonly removed: readonly string[];
+};
+export type ThreadFilter = {
+    /** Threads whose `origin` is this one, caller and cause alike. */
+    origin?: ThreadOrigin;
+    /** Threads a caller thread created, by any cause. */
+    callerThreadId?: string;
+    agentName?: string;
+    /**
+     * This thread, and every thread created under it at any depth, by `origin`, in spawn order. One
+     * catalog read; an unknown thread has nothing under it.
+     */
+    under?: string;
+};
+/**
+ * `ctx.threads` as an application sees it: the questions about the set of threads, and what starts
+ * one. Everything about one thread is on its {@link Thread}.
+ */
+export interface Threads {
+    /**
+     * Aborts once lagent is closing: no thread is created, run or released after that. A refusal
+     * because lagent is closing throws `signal.reason` itself, so a host recognizes it by identity
+     * (`error === threads.signal.reason`), never by message.
+     */
+    readonly signal: AbortSignal;
+    /** The `environment.cwd` a thread created without one gets. */
+    readonly defaultCwd: string;
+    create(agentName: string, options: CreateThreadOptions): Promise<Thread>;
+    fork(sourceId: string, options: ForkOptions): Promise<Thread>;
+    get(threadId: string): Thread | undefined;
+    list(filter?: ThreadFilter): Thread[];
+    liveThreads(): Thread[];
+    /**
+     * Starts running threads, once, after the application composed its plugins and attached its
+     * observers: nothing runs before. Repairs the registered constraints' owners first, then runs the
+     * requests pending at boot that `resume` accepts, at most `startLimit` at once; the rest are held
+     * (`startup`) until a releasing cause. A second call is refused.
+     */
+    start(options: StartOptions): Promise<void>;
+    /**
+     * Where a thread stands: its state, current operation and primary hold, and what is behind a
+     * `missing` hold; `null` for an unknown thread. Synchronous: it admits nothing, changes no backoff
+     * and publishes nothing. `catalog` loads and activates nothing and reports the screening the
+     * catalog shows with this process's owners; `loaded` decides the hold from the thread's folds and
+     * throws unless the thread and the callers above it are loaded already.
+     */
+    inspect(threadId: string, options: {
+        readonly basis: HoldBasis;
+    }): ThreadInspection | null;
+    /** Every run's state changes, as {@link RunEvent}s. Returns the unsubscribe. */
+    onRunEvent(listener: (event: RunEvent) => void): () => void;
+    /**
+     * Where run `runId` of the thread stands, by the rule its events follow; `null` for a run it never
+     * had. Out of memory, a thread answers from its catalog entry, which knows its pending run and its
+     * latest settlement only: an older run reads `null` until the thread is loaded (a read or a hold).
+     */
+    runState(threadId: string, runId: string): RunState | null;
+    /**
+     * Where the thread's chain of unattended work stands: whether its open turn has a person's
+     * authority, how many reactive turns in a row it has run, and whether that reached the configured
+     * limit, which a producer of more unattended work (a background start, a notifying command)
+     * refuses at. Synchronous, by a caller that holds the thread, as `view` is.
+     */
+    chain(threadId: string): ChainStanding;
+    /**
+     * What differs between thread `threadId`'s recorded birth and `request`'s: the agent, that the
+     * thread is a fresh one and not a fork, then the route, environment, installations and `requires`
+     * its spawn row recorded, against the {@link BirthSpec} asked for. Empty when it is the same birth.
+     * The origin is not compared: an owner continuing its child on a later assignment checks the
+     * configuration it pinned for the participant. This is **birth** equality, read from the immutable
+     * spawn row outside any write, not the equality of the thread's current configuration. An unknown
+     * thread throws `UnknownThreadError`.
+     */
+    birthConflicts(threadId: string, request: {
+        agent: string;
+        spec: BirthSpec;
+    }): Promise<BirthConflict[]>;
+    /** Registers a feature as an owner, with its say over when its threads run; see {@link OwnerRegistration}. */
+    registerOwner(registration: OwnerRegistration): OwnerHandle;
+    pendingConfirmations(options?: {
+        under?: string;
+    }): Promise<DeepReadonly<ConfirmationState[]>>;
+    onChunk(listener: (chunk: StreamedChunk) => void): () => void;
+    retain(members: RetainedMembers, options: RetainOptions): Promise<Retention>;
+    /**
+     * What a thread's folds say, read synchronously by a caller that already holds the thread: inside
+     * a journal write or a contributor running for it, during its run, or under a retention. Loads
+     * nothing; a caller that holds nothing reads through `thread.read`. A view of a thread nothing
+     * holds may find it unloaded and throws `ThreadNotLoadedError`.
+     */
+    view(threadId: string): ThreadView;
+}
+/**
+ * A set of threads held in memory until `release()`; see `ctx.threads.retain`. Its members are
+ * read through `ctx.threads.view` while it holds them.
+ */
+export interface Retention {
+    /** Gives the set back; see `RetainOptions.lastRelease`. Releasing twice does nothing. */
+    release(): void;
+}
+/**
+ * The threads a retention keeps in memory, as a function the engine asks for them: read at the
+ * start, to load them, and again at release and by every other retention's check, since the set a
+ * host means (a conversation and what it delegated to, say) can grow while it is held. A constant
+ * set is `() => ids`. A member that appears later is covered by the live check, not loaded.
+ */
+export type RetainedMembers = () => Iterable<string>;
+export type RetainOptions = {
+    /**
+     * What releasing this retention does to its members that no other retention covers: `retire`
+     * takes them out of memory, as `close()` does, once any operation holding one has settled; `keep`
+     * leaves them loaded. Named by the caller, since what to cache is the host's choice.
+     */
+    readonly lastRelease: 'retire' | 'keep';
+};
+/**
+ * Durable handles, live activations, and application-wide shutdown. Registry lookups stay live;
+ * journal operations never require an execution runtime. Every question about the set of threads —
+ * listing, finding, lineage, what needs resuming — is answered from the journal's catalog, so a
+ * thread's rows are in memory only once something reads or runs it.
+ */
+export declare class ThreadsService extends Service<ThreadsConfig> {
+    static inject: string[];
+    readonly chunks: ChunkChannel;
+    readonly limits: TurnLimits;
+    readonly defaultCwd: string;
+    private readonly live;
+    /** The retentions not yet released, each with its membership as it reads now. */
+    private readonly retentions;
+    /** Retirements in flight, by thread: a new retention waits for one before it loads. */
+    private readonly retiring;
+    /** Which operation holds each thread; the handle and the activation are given its view at construction. */
+    private readonly admission;
+    /** When threads run: see {@link RunOwner}. */
+    private readonly owner;
+    private readonly retention;
+    private readonly chainLimit;
+    private readonly handles;
+    /** Threads whose corrupt history was reported; see `reportCorrupt`. */
+    private readonly reportedCorrupt;
+    private readonly controller;
+    private closing;
+    constructor(ctx: Context, config: ThreadsConfig);
+    /** See {@link Threads.signal}: refusals because lagent is closing throw this signal's reason itself. */
+    get signal(): AbortSignal;
+    /** Close execution admission and abort every loop before waiting for any one to finish. */
+    private shutdown;
+    /** Every thread in creation order, or those matching `filter`; from the catalog, loading nothing. */
+    list(filter?: ThreadFilter): Thread[];
+    get(threadId: string): Thread | undefined;
+    /** Threads with a live activation, running or not, in the order they activated. */
+    liveThreads(): Thread[];
+    start(options: StartOptions): Promise<void>;
+    inspect(threadId: string, { basis }: {
+        readonly basis: HoldBasis;
+    }): ThreadInspection | null;
+    onRunEvent(listener: (event: RunEvent) => void): () => void;
+    runState(threadId: string, runId: string): RunState | null;
+    chain(threadId: string): ChainStanding;
+    registerOwner(registration: OwnerRegistration): OwnerHandle;
+    /** The release as an admitted operation: the activation goes, then `after` runs, under one admission. */
+    private releaseUnder;
+    /**
+     * Keeps `members` loaded until the returned function is called. Releasing a `retire` retention
+     * then retires each of its members, its membership read again, that no other retention's current
+     * membership covers; releasing a `keep` one retires nothing. Waits for a retirement already in
+     * flight on a member before loading it, so a thread is never read as it is being dropped. A
+     * thread whose operation is admitted is retired once it settles; an ancestor a retained fork folds
+     * through stays, as the journal keeps it. Releasing twice does nothing, and once lagent is
+     * closing releasing only gives the hold back. `waitOn`, for the engine's own acquisition alone and
+     * not part of {@link RetainOptions}, names the members whose retirement in flight is waited for,
+     * all of them when omitted.
+     */
+    retain(members: RetainedMembers, options: RetainOptions & {
+        readonly waitOn?: readonly string[];
+    }): Promise<Retention>;
+    view(threadId: string): ThreadView;
+    /** The threads the retentions not yet released cover, by their membership as it reads now. */
+    private covered;
+    /**
+     * Takes a thread no retention covers out of memory: one retirement at a time per thread, after the
+     * operation admitted on it settles, and only if no retention covers it by then; refused quietly
+     * when an operation is admitted again meanwhile, since that operation's caller is reading it.
+     */
+    private retire;
+    /**
+     * Takes the thread out of the working set: releases an idle activation, then drops the thread's
+     * rows and folds from memory under the same admission, so nothing runs it in between; the catalog
+     * entry stays, and the next touch loads the thread again. The rows stay while a retention covers
+     * the thread, or a covered fork folds through it. Refused busy while an operation holds the
+     * thread. The threads it inherited from or delegated to are their own, closed on their own.
+     */
+    close(threadId: string): Promise<void>;
+    /**
+     * Starts a thread that continues `sourceId`'s conversation from the row `at`, on the same agent.
+     *
+     * The fork is one spawn row that names its source and cut; the journal folds the source's lineage
+     * up to there into every thread-scoped projection, so the fork inherits the conversation, the
+     * prompt, the route and plugin state without a copy, and nothing its source does later. What
+     * described the source's execution — queued input, calls in flight, usage — starts fresh.
+     *
+     * With `input`, the first input is queued in the same append, so the fork never exists without
+     * its task, and `rows` adds a plugin's rows to it or refuses it (see {@link Opening}). A cut at
+     * a row the source inherited is redirected to the thread that owns the row. Forking only reads
+     * the journal; the source may be running.
+     *
+     * Get-or-create, as `create` is: the recorded fork is returned when it matches by `reuse`, its
+     * resolved cut, agent and origin under `identity`, and also its own environment and `requires`
+     * under `configuration`; any other holder of the id throws `BirthConflictError`. Nothing else is
+     * compared or written.
+     */
+    fork(sourceId: string, options: ForkOptions): Promise<Thread>;
+    private forkHeld;
+    /** A fork found under its id: returned when it is the fork asked for, by its {@link Reuse}, else a conflict. */
+    private reuseFork;
+    /**
+     * A new thread's one group: its spawn row; its first input, if any, queued for a turn of its own
+     * and citing the spawn row, which is how a fork's folds tell its task from what it inherited; the
+     * cause its `wake` asks for, opening the thread's first run request; and last the rows the
+     * caller's `rows` adds, built inside the write. A veto of those rejects the creation, as a
+     * callback that threw does: the thread is never recorded.
+     */
+    private openingGroup;
+    /**
+     * Starts a thread on `agentName`, with its first input and a plugin's rows in the same append
+     * when given (see {@link Opening}). Get-or-create, the idempotent entry point a re-dispatched
+     * delegating call relies on.
+     *
+     * Two explicit choices say what is created and what an existing id must match. `birth.from` says
+     * where the thread's configuration comes from: `defaults` fills what is left out from core's
+     * configuration; `caller` from the origin's caller, whose live activation it requires, plus the
+     * installations its scope hands down; `exact` takes a whole spec and reads nothing. `reuse` says
+     * what an existing thread under the id must match to be returned: `identity`, its agent, origin and
+     * that it is not a fork, checked before anything of the request is resolved, or `configuration`,
+     * which also resolves the request and compares its birth with the recorded spawn row. A thread
+     * that does not match is never adopted: it throws {@link BirthConflictError}. Metadata, input,
+     * wake and rows apply to a new thread only; a write-time veto throws {@link WriteRefusedError}.
+     */
+    create(agentName: string, options: CreateThreadOptions): Promise<Thread>;
+    /** What resolving `threadId`'s birth reads beyond its options; see {@link BirthContext}. */
+    private birthContext;
+    /**
+     * A fresh creation's id already taken: the thread is returned when it is the one asked for. Its
+     * identity is always compared, and returned on, before the request is resolved or a live caller
+     * touched; under `configuration` reuse the request is resolved and its birth compared with the
+     * spawn row.
+     */
+    private reuseFresh;
+    /** What differs between `summary`'s recorded spawn row and the birth `spec`; read outside any write. */
+    private specConflictsOf;
+    birthConflicts(threadId: string, request: {
+        agent: string;
+        spec: BirthSpec;
+    }): Promise<BirthConflict[]>;
+    /**
+     * Requests waiting on the user: across every thread, or only on `under` and the threads created
+     * beneath it — the set one conversation's driver is responsible for answering. The threads that
+     * have any are found in the flushed catalog; only those are retained for the requests themselves,
+     * without activating plugins. Returns owned frozen snapshots and releases its retention even on failure.
+     */
+    pendingConfirmations(options?: {
+        under?: string;
+    }): Promise<DeepReadonly<ConfirmationState[]>>;
+    /**
+     * Loads a thread so its synchronous reads answer: its lineage — its own rows and those of the
+     * threads it was forked from — and the threads that called it, whose policies a running thread
+     * may read. A run, `compact()` and every write load what they need themselves; a host loads what
+     * it reads.
+     */
+    load(threadId: string): Promise<void>;
+    /**
+     * Reports, once per thread and process, a loaded thread whose surface refused a replacement: where
+     * its corrupt history is first seen. Nothing executes on it (`requireExecutable`).
+     */
+    private reportCorrupt;
+    /** Refuses to execute on a thread whose surface refused a replacement; it stays readable. */
+    private requireExecutable;
+    /** A thread and the threads that called it, out to its origin root: what a run of it reads. */
+    private readSet;
+    /**
+     * What an execution of `threadId`, a run or a compaction, reads, loaded and held for the whole of
+     * it: the thread and the callers out to its origin root, as they stand now, held by one retention
+     * that releases with `keep`, so the end of a child's run never retires a caller's activation. The
+     * callers are held loaded, never waited on: a retirement in flight is waited for on the thread
+     * alone, since a caller's own teardown may be waiting for this very execution. The release, once
+     * only, then retires the thread alone when the application's policy is `retire` and `retiring`
+     * says so, as a run's does; so does a failed acquisition, once the retention undid its holds. A
+     * compaction passes `retiring: false`: it releases every member with `keep`, so it never starts a
+     * retirement its own cleanup, or an activation's teardown reading the thread, could wait on. A
+     * retirement waits for the operation admitted on the thread to settle and is not started before.
+     * The one acquisition for an execution's reads: a storage or load failure is the caller's, a
+     * corrupt thread is `requireExecutable`'s to refuse.
+     */
+    private retainExecutionReads;
+    /** The model's output as it streams, on every thread. Returns the unsubscribe function. */
+    onChunk(listener: (chunk: StreamedChunk) => void): () => void;
+    /** `ancestorId` and every thread under it by `origin`, from the catalog. */
+    private subtreeIds;
+    /**
+     * The installations a new child is born with because its caller's scope hands them down, read
+     * from the caller's live activation, so only what the caller's own plugins declared applies.
+     */
+    private handedDown;
+    /**
+     * Changes a thread's preset installations as one operation; see `Thread.configure`. Validated,
+     * then admitted before anything is awaited (busy while another operation holds the thread,
+     * refused with `ThreadActivatingError` while the activation is still getting ready, and after
+     * shutdown), then decided against the installations as they stand: a change that records nothing,
+     * such as a retry, returns without touching the thread, even with a confirmation unfinished.
+     * Otherwise it is refused with `ThreadUnsettledError` for an unfinished confirmation, releases the live activation, records every installation change in
+     * one write decided again inside it, and restores the thread when it should.
+     */
+    configure(threadId: string, change: ConfigurationChange): Promise<ConfigurationResult>;
+    /** What a change may not be recorded under: shutdown, or a confirmation still unfinished (`ThreadUnsettledError`). */
+    private refuseRecording;
+    /**
+     * Throws `UnknownAgentError` for a global agent name that is not registered. A scoped name passes:
+     * only the thread's own installations can define it, and they are known once it is ready.
+     */
+    private requireGlobalAgent;
+    /**
+     * The origin `threadId` records, validated: a known caller within the delegation depth, citing a row
+     * of its lineage that is the cause it claims (`origins.validate`).
+     */
+    private originFor;
+    /** The prompt `threadId` would record if rendered now from `scope`, with the thread's plugins in it. */
+    private renderPrompt;
+    /** Records the thread's prompt the first time it is about to run; later turns reuse it. */
+    recordPromptOnce(scope: ScopeKey): Promise<void>;
+    /** Re-renders through the thread's activation, waiting for its plugins, and records the result. */
+    rebuildPrompt(threadId: string): Promise<PromptBlock[]>;
+    /**
+     * Activates the thread if need be and waits for its plugins. Readiness is a barrier, not an
+     * exclusive operation: a release or a configuration change in progress is waited for, since an
+     * activation on its way out is not ready, and the fresh one is then activated.
+     */
+    whenReady(threadId: string): Promise<void>;
+    /** The thread's live context, activating it; see `Thread.ctx`. */
+    contextOf(threadId: string): Context;
+    /** The current activation's signal, activating the thread; see `Thread.signal`. */
+    signalOf(threadId: string): AbortSignal;
+    private activate;
+    /**
+     * One execution of a run request under its admitted operation, the owner's to call: whatever the
+     * run reads is held (`retainExecutionReads`), and an interrupted turn is closed first, as a write,
+     * so it lands after any `send()` queued before this run, and what the run decides from is what
+     * that send left. The owner's continuation decision is asked at its entry and after every turn and
+     * recorded on `execution`, which the owner's finalization settles the request by. Resolves once
+     * the work is done, however it ended, a setup failure, settled as one, included; only a failure
+     * past its setup rejects.
+     */
+    private execute;
+    /**
+     * The thread's route as a statement is checked against, read where it is called: inside a write,
+     * as the write's rows stand. A route change is accepted only while no run serving the pending
+     * request holds the thread (a compaction does not count), and while no request is pending, the
+     * route cannot run, or the request is held by a failure or a cancellation (whatever else holds it):
+     * such a request runs only on a releasing cause, so changing its route moves nothing that is
+     * running or about to run. A runnable pending request is never moved under itself.
+     */
+    target(threadId: string): Target;
+    /** What checks every route statement, inside the write that records it: the one guard on route changes. */
+    readonly routes: RouteAuthority;
+    /**
+     * One request to prepare the surface; see `Thread.compact`. Cancellation owns it from this call:
+     * `cancel()`, the caller's signal or shutdown ends it at any point, and it then resolves
+     * `cancelled`, with nothing dispatched if it had not yet begun.
+     */
+    compact(threadId: string, options: CompactOptions): Promise<SurfacePrepareOutcome>;
+    /**
+     * Releases an activation whose setup failed while no operation held the thread; one that fails
+     * while an operation holds the thread is released by that operation as it settles. An operation
+     * admitted meanwhile waits for the disposal (`settledLive`) before it activates the thread again,
+     * so a retry never finds the failed scope's resources still held.
+     */
+    releaseFailed(threadId: string): Promise<void>;
+    /**
+     * The thread's activation for `operation`: one whose plugins changed since it was ready is
+     * released first, under the operation, marked as releasing so the scope's unload guard does not
+     * wait for it, and a fresh one is activated from the thread's listeners and installations.
+     */
+    private activationFor;
+    /** Resolves once the thread's activation, if one is being released, is gone: what every operation awaits before activating. */
+    private settledLive;
+    /** The loop's view of the registries, bound to one activation's scope. */
+    private loopServices;
+    /** The journal with core's writes, which the thread owner and the loop record through; never handed to a plugin. */
+    private get journal();
+    /**
+     * Runs `work` as an admitted operation other than a run, whose envelope is the owner's; see
+     * `Admission.hold`. An activation whose setup failed, or that went stale, could not be released
+     * while this operation held the thread: it is released as the operation's cleanup (`cleanup`).
+     */
+    private under;
+    /**
+     * The cleanup of every admitted operation, a run included, still under its admission: an
+     * activation whose setup failed, or that went stale, is released so a run meanwhile is busy and
+     * nothing activates afresh, in the releasing phase so the scope's unload guard does not wait for it.
+     */
+    private cleanup;
+    private requireThread;
+    private handle;
+}