@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/services/presets/installations.d.ts

@@ -0,0 +1,139 @@
+import { Service, type Context, type ScopeKey } from '@leuduan/cordis';
+import type { InitialInstallation, Installation, InstallationLifetime } from '../../records/journal.js';
+import { type AnyPreset } from './definition.js';
+import type { Thread } from '../threads/index.js';
+/**
+ * An installation a caller asks for, at creation (as an {@link InitialInstallationInput}) or later
+ * (`Thread.configure`).
+ */
+export type InstallationInput = {
+    readonly presetId: string;
+    readonly config?: unknown;
+    /**
+     * Unique within the change or the creation; generated when omitted. Given, it makes a retried
+     * application idempotent. A removed id is never accepted again.
+     */
+    readonly installationId?: string;
+};
+/**
+ * An installation a thread is created with (`create`'s `installations`), with how long it lasts:
+ * `defining` ones are never removed, `configurable` ones are installations like any applied later.
+ * A creation preset is only ever `defining`.
+ */
+export type InitialInstallationInput = InstallationInput & {
+    readonly lifetime: InstallationLifetime;
+};
+/**
+ * An installation a thread's scope hands down to every thread a call there creates; see
+ * {@link handDown}. The id is required: it is what keeps a hand-down from colliding with another in
+ * its layer or with the child's own installations.
+ */
+export type HandDown = {
+    readonly presetId: string;
+    readonly config?: unknown;
+    readonly installationId: string;
+};
+/** What a configuration change records, decided against the thread's installations as they stand. */
+export type ConfigurationPlan = {
+    readonly rows: readonly ({
+        type: 'installation/applied';
+        data: Installation;
+        options: {
+            threadId: string;
+        };
+    } | {
+        type: 'installation/removed';
+        data: {
+            installation_id: string;
+        };
+        options: {
+            threadId: string;
+        };
+    })[];
+    /** Every installation the change applies, an earlier application of the same id included. */
+    readonly applied: readonly string[];
+    /** The installations it takes off; an id not installed is none. */
+    readonly removed: readonly string[];
+};
+/**
+ * What a preset installation means: the registry of presets a thread can install, how an
+ * installation is validated, an agent-defining one against its thread's agent included, which
+ * installations a thread's scope hands down to the children its calls create, and how a thread's
+ * recorded installations are mounted when it activates. A core service: the thread owner
+ * orchestrates creation, configuration and activation, and hands this service the thread, the scope
+ * or the state each question is about. Registrations do not survive a reload.
+ */
+export declare class PresetsService extends Service {
+    static inject: string[];
+    private readonly registry;
+    /** Each thread scope's hand-downs, in declaration order; the global layer stays empty. */
+    private readonly handDowns;
+    constructor(ctx: Context);
+    /** Makes `preset` installable on threads; returns the unregister function. */
+    register(preset: AnyPreset): () => void;
+    /** Whether a preset is registered under `presetId`. */
+    has(presetId: string): boolean;
+    /**
+     * The installations `entries` record, validated before anything is appended: a registered
+     * preset whose placement allows the use, a configuration its schema accepts and parses back to
+     * itself, and ids unique among them. At a creation on `agentName`, a preset that defines its
+     * thread's agent must define that one. Reads no thread state, so it fails only on a composition
+     * bug.
+     */
+    installationsFor(entries: readonly InstallationInput[], use: 'creation' | 'change', agentName?: string): Installation[];
+    /**
+     * The installations a creation on `agentName` records, each with its lifetime: validated as
+     * {@link installationsFor} validates a creation's, and a creation preset refused unless it is
+     * `defining`, since it can never be applied again once removed.
+     */
+    initialInstallations(entries: readonly InitialInstallationInput[], agentName: string): InitialInstallation[];
+    /**
+     * What a change records on `threadId`, decided against its installations as they stand:
+     * removals first, then applications, each id once. Removing an id not installed is no change; a
+     * defining installation is never removed. An application whose id is already this very
+     * installation, compared after defaults, is no change, which makes a retry idempotent; one whose
+     * id names another installation, or a removed one, is refused. The owner calls this before
+     * admitting the change and again inside its write.
+     */
+    plan(threadId: string, apply: readonly Installation[], remove: readonly string[]): ConfigurationPlan;
+    /**
+     * Declares in `scope` that every thread a call there creates is born with `handDown` installed,
+     * as a defining installation; returns the withdraw function. Use {@link handDown}, which ties it
+     * to the declaring plugin. Refused in the global layer, where it would reach the children of every
+     * conversation; for a preset that is not registered, since a child restores it from the registry
+     * whether or not its parent is live; for a configuration its preset would not record; and for an
+     * installation id already handed down in the same layer, so no rule has to choose between two
+     * declarations.
+     */
+    handDown(scope: ScopeKey | undefined, handDown: HandDown): () => void;
+    /**
+     * The installations a new thread on `agentName` is born with because the scope of the call
+     * creating it hands them down, each defining: from the closest layer out, each in declaration
+     * order, a closer declaration winning an id. Validated as the creation's own installations are,
+     * and refused when an id is also one of those: two owners for one installation is a composition
+     * bug, not something to resolve.
+     */
+    handedDown(scope: ScopeKey, threadId: string, agentName: string, own: readonly Installation[]): InitialInstallation[];
+    /**
+     * Mounts every recorded installation of `thread`, one at a time in recorded order so that
+     * registration order is stable across reopening; the owner calls it once the activation's
+     * listeners have settled, so installations follow the listeners' own plugins. Any failure fails
+     * the activation, which a run turns into a rejection with the input kept.
+     */
+    restore(thread: Thread): Promise<void>;
+    private requireRegistered;
+    /**
+     * Whether `installation`'s id is already this very installation. Throws when the id names a
+     * different installation, or one that was removed.
+     */
+    private alreadyApplied;
+}
+/** Makes `preset` installable on threads for the lifetime of the calling plugin. */
+export declare const registerPreset: (ctx: Context, preset: AnyPreset) => (() => void | Promise<void>);
+/**
+ * Hands `handDown` down, for the lifetime of the calling plugin, from the thread scope it is
+ * mounted in to every new thread a call there creates: each child is born with it as a defining
+ * installation, recorded with its spawn row. See {@link PresetsService.handDown} for what is
+ * refused. Looks the service up, so a caller need not inject it.
+ */
+export declare function handDown(ctx: Context, handDown: HandDown): () => void | Promise<void>;

package/dist/services/prompts.d.ts

@@ -0,0 +1,85 @@
+import { Context, Service, type ScopeKey } from '@leuduan/cordis';
+import { type PromptBlock } from '../llm/prompt.js';
+import { type ToolEntry } from '../loop/index.js';
+import type { AgentDefinition } from '../loop/index.js';
+import type { ThreadSummary } from '../records/journal.js';
+import { type AgentSelector } from './agents.js';
+export type PromptSlot = 'base' | 'instruction' | 'context';
+/**
+ * What a contribution is rendered against: the agent, where the thread works, and the tools it
+ * reaches.
+ *
+ * Deliberately not the thread's id or metadata. A recorded prompt is the head of every request a
+ * provider caches, so it must not depend on which thread it is: threads of one agent in one
+ * workspace then render the same prompt. Anything thread-specific belongs in the conversation, as
+ * a step contribution (see `workspaceNotice`).
+ */
+export type PromptRenderInput = {
+    readonly agent: AgentDefinition;
+    readonly thread: {
+        readonly environment: ThreadSummary['environment'];
+    };
+    /** What the agent may call from the rendering scope, as the registries stand at render time. */
+    readonly tools: readonly ToolEntry[];
+};
+/**
+ * One section a plugin adds to an agent's prompt.
+ *
+ * `render` is synchronous and pure in its inputs: anything needing IO reads it when the plugin
+ * mounts, and returns the cached value here. Returning `null` contributes nothing — or, for a tag
+ * that already exists, removes it.
+ */
+export type PromptContribution = {
+    readonly tag: string;
+    readonly slot: PromptSlot;
+    /** Which agents get it; see `AgentSelector`. */
+    readonly agents: AgentSelector;
+    /** Render order within the slot; ties break on `tag`. Default 0. */
+    readonly order?: number;
+    render(input: PromptRenderInput): string | null;
+};
+/**
+ * Prompt contributions, live like the other registries and layered by Cordis scope like tools:
+ * an untagged contribution is global, a contribution registered through a thread's context belongs
+ * to that thread's layer. The prompt itself is rendered once, when a thread first runs and every
+ * activation plugin is ready, and recorded on it; this service only says what that render
+ * would be right now.
+ */
+export declare class PromptsService extends Service {
+    static inject: string[];
+    private readonly layers;
+    constructor(ctx: Context);
+    /** Adds a contribution to one layer; returns the function that removes it. */
+    contribute(scope: ScopeKey | undefined, contribution: PromptContribution): () => void;
+    /**
+     * The prompt `agentName` would send on a thread rendered now from `scope`: the agent's base
+     * prompt, then the global layer's contributions, then each closer layer outward-in, each in
+     * declared order, never mount order. A contribution whose tag is already present replaces that
+     * section in place — so the closest layer wins a tag — and `null` removes it.
+     *
+     * The base prompt is seeded at the layer that defines the agent, so only that layer and closer
+     * ones can replace or remove it with a `base` contribution: for a global agent every layer can,
+     * while a scoped agent's own base prompt outranks every layer farther out. Instruction and context
+     * contributions apply from every layer. Throws for an agent unknown from `scope`.
+     */
+    render(scope: ScopeKey | undefined, agentName: string, thread: PromptRenderInput['thread']): PromptBlock[];
+}
+/** Registers a contribution in the calling plugin's layer for the lifetime of its fiber. */
+export declare const contributePrompt: (ctx: Context, contribution: PromptContribution) => (() => void | Promise<void>);
+export type TaggedSection = {
+    tag: string;
+    content: string;
+};
+/**
+ * A prompt as `ctx.prompts` assembles it: the agent's base prompt, then instruction sections, then
+ * context sections, so a section's bucket is what decides its position. The rendered result is
+ * recorded per thread.
+ */
+export type SystemPrompt = {
+    basePrompt: string;
+    instructions: TaggedSection[];
+    contextSections: TaggedSection[];
+};
+/** The prompt as ordered blocks — the one place its order is decided. */
+export declare function systemPromptBlocks(prompt: SystemPrompt): PromptBlock[];
+export declare const renderSystemPrompt: (prompt: SystemPrompt) => string;

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

@@ -0,0 +1,100 @@
+import { type Context, type Scope, type Scoped, type ScopeKey } from '@leuduan/cordis';
+import { type CompactOptions, type Lease, type LoopServices, type SurfacePrepareOutcome } from '../../loop/index.js';
+import type { ServedRun } from '../../loop/index.js';
+import type { Thread } from './thread.js';
+import type { AdmissionView } from './admission.js';
+import type { ThreadsService } from './service.js';
+/**
+ * One process-local activation: the thread's Cordis scope, the plugins mounted in it, their
+ * readiness, and the loop that runs in it. It owns resources, never admission: which operation
+ * holds the thread, and its cancellation, are the admission owner's, which the threads service
+ * keeps and which hands each run or compaction its signal and lease.
+ */
+export declare class ThreadActivation {
+    readonly scope: Scope;
+    readonly target: Scoped;
+    private readonly runtime;
+    private readonly loop;
+    private readiness;
+    private readonly controller;
+    private failed;
+    private prepared;
+    /** The plugin tree as it was when the activation became ready, which is what it runs with. */
+    private readyTree;
+    private staleBecause;
+    private draining;
+    private closingDone;
+    private readonly service;
+    private readonly admission;
+    readonly thread: Thread;
+    private readonly released;
+    constructor(service: ThreadsService, 
+    /** The admission owner's reads, given by the service that owns it. */
+    admission: AdmissionView, owner: Context, thread: Thread, loopServices: (scope: ScopeKey) => LoopServices, released: () => void);
+    /**
+     * From readiness on, the plugin tree is what the activation runs with. A guard on each of its
+     * plugins marks the activation stale before that plugin's disposers run, whatever unloads it: a
+     * dependency gone, a root mount disposed, a reload. Its own release marks it too, harmlessly.
+     */
+    private watchTree;
+    private markStale;
+    /**
+     * Whether the plugins changed since readiness: one unloaded or reloaded, or one added through
+     * `thread.ctx`, which is reported once. A stale activation dispatches nothing new, and the owner
+     * replaces it once the operation holding the thread settles.
+     */
+    isStale(): boolean;
+    /**
+     * Whether a setup in this activation is still running: its listeners and installations have not
+     * settled, or a plugin of its tree is in transition, one mounted later through `thread.ctx` or one
+     * reloading included. A change that waits for this activation to go, made from one of those
+     * setups, would wait on itself, so it is refused meanwhile. Not a readiness check: readiness is
+     * settled once.
+     */
+    get activating(): boolean;
+    private observe;
+    /** Aborts on release and on stop; what the activate listeners receive. */
+    get signal(): AbortSignal;
+    /** Whether readiness failed: the owner releases such an activation once its operation settles. */
+    get hasFailed(): boolean;
+    /** Set once `release()` has begun: resolves when the scope is disposed. The owner waits for it before activating again. */
+    get closed(): Promise<void> | undefined;
+    private settle;
+    /** One execution of the run `served`, under the admitted operation's signal and lease. */
+    run(options: {
+        signal: AbortSignal;
+        lease: Lease;
+        served: ServedRun;
+    }): Promise<void>;
+    /**
+     * One request to prepare the surface, under the admitted operation's signal and lease; see
+     * `Thread.compact`. Resolves with the outcome, `cancelled` when the signal aborts first.
+     */
+    compact(options: CompactOptions & {
+        signal: AbortSignal;
+        lease: Lease;
+    }): Promise<SurfacePrepareOutcome>;
+    /**
+     * Waits for readiness, settled once when the activation began, then checks the agent and records
+     * the prompt if the thread has none. Only then is the scope complete: the thread's plugins may
+     * define its agent, and an unknown one fails here, before a prompt is recorded or a turn opens,
+     * so input waits for a retry. A stale activation never gets here: the owner replaces it first.
+     */
+    private ready;
+    /**
+     * Resolves once the activation is ready: its listeners and installations settled, every plugin of
+     * its tree active. The same barrier a run uses: a settled but PENDING plugin is not ready, so a
+     * caller never reads a half-configured scope.
+     */
+    whenReady(): Promise<void>;
+    /** The owner releases scopes only after every thread has drained, including failed setup. */
+    stop(reason: Error): void;
+    /** Resolves once setup has ended, however, and every plugin mounted since is settled. */
+    whenIdle(): Promise<void>;
+    /**
+     * Disposes the scope once setup has ended. The owner calls this with no executing operation on
+     * the thread, or from the operation that is settling; the scope's own unload guard is what waits
+     * for a loop when something else disposes the scope.
+     */
+    release(): Promise<void>;
+}

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

@@ -0,0 +1,174 @@
+import type { Lease } from '../../loop/index.js';
+import type { CancelIntent, InboxTarget } from '../../records/journal.js';
+/**
+ * An exclusive operation on one thread; see `Admission.onOperation`. A `cancel` holds the thread from a
+ * `cancel()` until its write has landed and what it cancelled has released the thread.
+ */
+export type OperationKind = 'run' | 'compact' | 'rebuild' | 'configure' | 'release' | 'cancel';
+/** How an operation ended: as asked, by throwing, or because it was cancelled or lagent closed. */
+export type OperationEnding = 'completed' | 'failed' | 'cancelled';
+/** What holds a thread: the operation's kind, and the run request a run serves (`null` for any other). */
+export type OperationHolder = {
+    readonly kind: OperationKind;
+    readonly runId: string | null;
+};
+/**
+ * What `onOperation` listeners are told: an operation was admitted on a thread, or it settled and
+ * how. Process-local and never a journal row; `settled` is published once admission is released,
+ * so a listener may start the thread's next operation from it.
+ */
+export type OperationEvent = {
+    readonly thread_id: string;
+    readonly kind: OperationKind;
+    readonly phase: 'admitted';
+} | {
+    readonly thread_id: string;
+    readonly kind: OperationKind;
+    readonly phase: 'settled';
+    readonly ended: OperationEnding;
+};
+/**
+ * An admitted operation as the code running it sees it: what it is, and the signal and lease it
+ * hands to the work. Everything else about it is the owner's.
+ */
+export type AdmittedOperation = {
+    readonly threadId: string;
+    readonly kind: OperationKind;
+    /** The run request a run serves; `null` for any other operation. */
+    readonly runId: string | null;
+    readonly signal: AbortSignal;
+    readonly lease: Lease;
+};
+/**
+ * What a thread's handle and its activation ask the owner: whether it runs, where input waits, the
+ * cancel, and the unload guard's wait. Nothing that admits or settles an operation.
+ */
+export type AdmissionView = Pick<Admission, 'isRunning' | 'inputTarget' | 'cancel' | 'whenSettled' | 'isAdmitted'>;
+/**
+ * What one `cancel()` gets back: the run of the execution the thread's cancel captured, if it
+ * captured a run, and the one settlement of that cancel. `wrote` reports the call's own write,
+ * once it is queued, and only then aborts what the call captured, so a cancel an abort listener
+ * makes is written after this one. `capturedSettles` says, read inside that write, whether the
+ * captured execution's finalization is still to build its run's settlement: until then the
+ * finalization settles it by the cancel's intent; after, what it built stands, and a run it left
+ * pending is the cancel's to settle.
+ */
+export type CancelHandle = {
+    readonly capturedRunId: string | null;
+    readonly settled: Promise<void>;
+    capturedSettles(): boolean;
+    wrote(write: Promise<unknown>): void;
+};
+/**
+ * The one owner of which operation holds each thread: admission or refusal, the releasing phase,
+ * cancellation, and the publication of admission and settlement in the order
+ * docs/guides/threads.md#ordering states. It knows nothing of activations; the threads service runs
+ * each operation's work, and disposes activations under it, through `hold`.
+ */
+export declare class Admission {
+    /**
+     * The one operation admitted on each thread, from before its first `await` until its work and
+     * cleanup settled: what `cancel()` aborts and awaits, what refuses a second operation as busy,
+     * and what says whether input joins a run's next step.
+     */
+    private readonly admitted;
+    /** The cancel in progress on each thread, from its first call until it settles. */
+    private readonly cancels;
+    private readonly listeners;
+    private readonly closing;
+    private readonly report;
+    /**
+     * @param closing aborts once lagent is closing: nothing is admitted after, and it is composed
+     *   into every operation's signal.
+     */
+    constructor(closing: AbortSignal, report: (error: unknown) => void);
+    /** Refuses as admission would, without admitting: once lagent is closing, or busy while an operation holds the thread. */
+    requireFree(threadId: string): void;
+    /**
+     * Admits `kind` on the thread, or refuses it busy, synchronously, and publishes `admitted` before
+     * returning. The operation's signal composes shutdown's, `cancel()`'s and the caller's; its lease
+     * says whether it still holds the thread, for a callback that escaped it. A configuration change
+     * is admitted releasing: it starts by releasing the live activation, before anything can see it.
+     */
+    admit(threadId: string, kind: OperationKind, options?: {
+        readonly signal?: AbortSignal | undefined;
+        readonly runId?: string | undefined;
+    }): AdmittedOperation;
+    private operation;
+    /**
+     * Runs `work` as the admitted operation, then the disposal `cleanup` returns, if any, then its
+     * `finalize`, if any, both still under it, then releases admission and publishes `settled` in the
+     * same synchronous step, however `work` ended. `finalize` runs in the releasing phase: the
+     * operation still holds the thread, so nothing else is admitted and nothing mounts, but it executes
+     * nothing more, and input sent meanwhile waits for the next turn. It runs again when a cancel
+     * captured the operation while it ran, so it must be safe to repeat. Without either step nothing is
+     * awaited between the work's end and the release. The value `work` returns is its own, taken
+     * before admission is released. A failing finalization or disposal is reported; the admission is
+     * released all the same.
+     */
+    hold<T>(admitted: AdmittedOperation, work: () => Promise<T>, steps?: {
+        readonly finalize?: () => Promise<void>;
+        readonly cleanup?: () => Promise<void> | undefined;
+    }): Promise<T>;
+    /**
+     * Enters or leaves the operation's releasing phase; entering wakes whatever waits for it to stop
+     * executing. Set by whoever disposes an activation under the operation, before the disposal starts.
+     */
+    setReleasing(admitted: AdmittedOperation, releasing: boolean): void;
+    /**
+     * Starts the thread's cancel, or joins the one in progress, synchronously. The first call captures
+     * the operation admitted now, if any, and marks it with its intent; `wrote` aborts it (a release is
+     * waited for, never aborted). The run that operation serves settles by the intent of the first
+     * cancel that reached it. With nothing
+     * admitted, a `cancel` operation holds the thread at once, closing or not, since a shutdown still
+     * cancels. Either way the cancel holds the thread, refusing a run as busy, until every joined
+     * call's write has finished, landed or failed (`wrote`), and the captured operation has released;
+     * its `settled` then resolves, once for every call.
+     */
+    cancel(threadId: string, reason: string, intent: CancelIntent): CancelHandle;
+    /** The intent of the first cancel that captured `admitted`, or `null`: what the run it serves settles by. */
+    cancelIntent(admitted: AdmittedOperation): CancelIntent | null;
+    /**
+     * Records, inside the finalization's write, that `admitted` built its run's settlement: a cancel
+     * written after it settles a run that build left pending.
+     */
+    settlementBuilt(admitted: AdmittedOperation): void;
+    /** The thread's cancel holds the thread as a `cancel` operation of its own; published by the caller. */
+    private holdForCancel;
+    private wroteCancel;
+    /** Settles the thread's cancel once every joined write finished and what it captured released. */
+    private finishCancel;
+    /** What holds the thread now, or `null`. */
+    holder(threadId: string): OperationHolder | null;
+    /** Whether any operation holds the thread. */
+    isAdmitted(threadId: string): boolean;
+    /** Whether a run or a compaction holds the thread: what `Thread.status()` calls running. */
+    isRunning(threadId: string): boolean;
+    /**
+     * Whether the operation holding the thread is disposing its activation, a release or another in
+     * its releasing phase: nothing of the thread may be mounted meanwhile, and it executes nothing.
+     */
+    isReleasing(threadId: string): boolean;
+    /** Where input sent now waits: a run's next step while a run holds the thread and is not cancelled, else the next turn. */
+    inputTarget(threadId: string): InboxTarget;
+    /** Resolves once the operation holding the thread now, if any, has settled. */
+    settlement(threadId: string): Promise<void>;
+    /**
+     * Resolves once no operation that executes holds the thread: what an activation waits for before
+     * it disposes, so a scope never goes under a running loop. An operation disposing the activation
+     * is not waited for, since that would be the disposal waiting on itself.
+     */
+    whenSettled(threadId: string): Promise<void>;
+    /**
+     * Resolves once no operation holds any thread and no cancel is in progress: what shutdown waits
+     * for before releasing scopes. Read again after each wait, since a cancel takes over a thread its
+     * captured operation releases, and a shutdown still cancels.
+     */
+    drain(): Promise<void>;
+    /** Tells `listener` when an operation is admitted on any thread and when it settled; see {@link OperationEvent}. */
+    onOperation(listener: (event: OperationEvent) => void): () => void;
+    /** The owner's record of `admitted`, which must hold its thread: anything else is a caller bug. */
+    private holding;
+    /** One frozen copy for every listener, so no listener can change what the next one sees. */
+    private publish;
+}