@leuduan/lagent 0.0.0-stage → 0.1.2

package/dist/journal/store.d.ts

@@ -0,0 +1,181 @@
+import type { JournalEvent, Seq, ThreadSummary } from '../models/index.js';
+/**
+ * One group's write: a fresh identity, the head it was numbered from, the writer's acquisition, and
+ * the rows. Immutable once made, so a write whose answer was lost can be sent again as it was.
+ */
+export type Attempt = {
+    readonly id: string;
+    readonly baseHead: Seq;
+    readonly writer: string;
+    readonly rows: readonly JournalEvent[];
+};
+/** What an append did: wrote the rows, or found the same attempt already written and wrote nothing. */
+export type AppendOutcome = 'appended' | 'duplicate';
+/** One thread as the store indexes it, from its rows alone: where it began and how far it reaches. */
+export type ThreadIndexEntry = {
+    readonly threadId: string;
+    readonly spawnSeq: Seq;
+    readonly lastSeq: Seq;
+};
+/**
+ * The right to append: exclusive while held, with an acquisition id the store checks inside every
+ * append, so rows from a writer that lost the lease are refused rather than detected afterwards.
+ */
+export type WriterLease = {
+    /** What the lease is held on, for messages. */
+    readonly identity: string;
+    readonly acquisitionId: string;
+    release(): Promise<void>;
+};
+/**
+ * Durable backing for the journal: the rows, one thread at a time, an index of the threads, the
+ * catalog of summaries beside them, and the record of who may write. Every method is asynchronous,
+ * so a store across a network implements the same contract as SQLite; the conformance suite
+ * (`plugins/store/conformance.ts`) is what every store passes.
+ *
+ * `append` must be durable enough that a crash after it resolves still replays the rows, because
+ * nothing else records them. That is also why `read` refuses a row it cannot parse rather than
+ * skipping it: the conversation is derived from these rows, so a dropped one rewrites history.
+ *
+ * The catalog is written after the rows, by the journal, from folds that hold only durable rows; it
+ * can trail the rows by one group after a crash, and the thread index — kept in the append's own
+ * transaction — is how the journal finds the summaries to refresh when it opens.
+ */
+export declare abstract class JournalStore {
+    private opened;
+    get isOpen(): boolean;
+    /** Initializes resources and loads persisted state; idempotent. */
+    open(): Promise<void>;
+    /** Releases resources; idempotent. */
+    close(): Promise<void>;
+    /**
+     * Takes the writer lease, refused with {@link JournalBusyError} while another holds it. May be
+     * called before `open()`: a store whose exclusivity comes from the operating system takes it before
+     * reading anything.
+     */
+    abstract acquireWriter(): Promise<WriterLease>;
+    /** The highest `seq` the store holds; 0 when it holds nothing. */
+    head(): Promise<Seq>;
+    /**
+     * Writes an attempt's rows as one unit — all of them survive a crash or none do — and indexes
+     * their thread, in one transaction, checked against three things in that transaction:
+     *
+     * - an attempt with this id already written is `duplicate` when its content — head, writer and
+     *   rows — is the same, and {@link AttemptMismatchError} when it is not, before anything else is
+     *   checked, so a resend after the head or the writer moved on is still recognized; an attempt's
+     *   identity is kept as long as its rows;
+     * - the writer record must name `attempt.writer`, else {@link WriterLostError};
+     * - the head must still be `attempt.baseHead`, else {@link JournalConflictError}.
+     *
+     * The rows are one thread's, in ascending seq order above `baseHead` — consecutive as the journal
+     * writes them; a gap is allowed so a test can store a journal thinned on purpose — and a thread the
+     * index does not hold must begin with its spawn row. A thread has exactly one spawn row; a
+     * second is refused without writing any part of the attempt.
+     *
+     * A store that cannot tell whether a commit landed — a remote one whose answer was lost, say —
+     * should say so with a typed ambiguous failure: the journal can then send the same attempt again,
+     * and a `duplicate` answer proves the rows are durable, though not that this process still holds
+     * the writer lease. Neither shipped store can lose an answer, so the journal has no such resend
+     * yet; it is built with the store that needs it.
+     */
+    append(attempt: Attempt): Promise<AppendOutcome>;
+    /** One thread's own rows, in `seq` order. A fork's source is read whole; the journal bounds the lineage. */
+    read(threadId: string): Promise<JournalEvent[]>;
+    /** The row at `seq`, whichever thread it belongs to. */
+    rowAt(seq: Seq): Promise<JournalEvent | undefined>;
+    /** Every thread the store holds, in spawn order: one entry per thread, whatever the journal's length. */
+    threads(): Promise<ThreadIndexEntry[]>;
+    /** Every summary the catalog holds, in spawn order. */
+    summaries(): Promise<ThreadSummary[]>;
+    /**
+     * Writes summaries, each replacing its thread's unless the stored one already describes more of
+     * the thread (a higher `through_seq`): a late write never undoes a newer one. Checked against the
+     * writer record as an append is, else {@link WriterLostError}.
+     */
+    putSummaries(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    /** Replaces the whole catalog in one transaction: a rebuild's write, checked against the writer record. */
+    replaceCatalog(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    protected abstract doOpen(): Promise<void>;
+    protected abstract doClose(): Promise<void>;
+    protected abstract doHead(): Promise<Seq>;
+    /** Implements {@link append}'s checks and write in one transaction; `digest` identifies the content. */
+    protected abstract doAppend(attempt: Attempt, digest: string): Promise<AppendOutcome>;
+    protected abstract doRead(threadId: string): Promise<JournalEvent[]>;
+    protected abstract doRowAt(seq: Seq): Promise<JournalEvent | undefined>;
+    protected abstract doThreads(): Promise<ThreadIndexEntry[]>;
+    protected abstract doSummaries(): Promise<ThreadSummary[]>;
+    protected abstract doPutSummaries(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    protected abstract doReplaceCatalog(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    /**
+     * The event as it stands.
+     *
+     * Nothing is normalized and nothing is dropped for size: a row that reads back differently from
+     * the event in memory makes a live process and a resumed one disagree about their own history,
+     * and the fields most able to disagree are the ones this engine does not model — what a provider
+     * needs back verbatim and the arguments the model sent a tool, neither of which has a schema to
+     * restore what a tidy-up removed. `llm/request` records the prompt as a size and digest precisely
+     * so that no row ever has to be trimmed.
+     */
+    protected serialize(event: JournalEvent): string;
+    protected serializeSummary(summary: ThreadSummary): string;
+    private requireOpen;
+}
+/** The content identity of a whole attempt — head, writer and rows: what tells a resent attempt from a different one with the same id. */
+export declare function digestOf(attempt: Pick<Attempt, 'baseHead' | 'writer' | 'rows'>): string;
+export declare class JournalBusyError extends Error {
+    readonly location: string;
+    constructor(location: string);
+}
+/**
+ * A write that waited its whole budget for another connection's write lock on the store, a shell or
+ * a backup say, and gave up. Nothing of it was written.
+ */
+export declare class StoreBusyError extends Error {
+    readonly location: string;
+    readonly waitedMs: number;
+    constructor(location: string, waitedMs: number);
+}
+/** An append numbered from a head the store has moved past: another writer, or a lost answer resent as new rows. */
+export declare class JournalConflictError extends Error {
+    readonly expected: Seq;
+    readonly actual: Seq;
+    constructor(expected: Seq, actual: Seq);
+}
+/** An append by a writer the store's record no longer names: its lease was taken by another. */
+export declare class WriterLostError extends Error {
+    readonly acquisitionId: string;
+    constructor(acquisitionId: string);
+}
+/** An attempt id already written with other rows: two different writes under one identity. */
+export declare class AttemptMismatchError extends Error {
+    readonly attemptId: string;
+    constructor(attemptId: string);
+}
+/** A journal row that cannot be parsed by this build. */
+export declare class CorruptJournalError extends Error {
+    readonly payload: string;
+    readonly cause: unknown;
+    constructor(payload: string, cause: unknown);
+}
+/** Parses one stored row; `shape` turns the parsed payload into the event's wire form when the store keeps it in parts. */
+export declare function parseStoredEvent(payload: string, shape?: (stored: unknown) => unknown): JournalEvent;
+export declare function parseStoredSummary(payload: string): ThreadSummary;
+/**
+ * The journal format this build reads and writes. Bump it whenever the event alphabet or storage
+ * layout changes; a populated journal stamped with anything else is refused rather than partially read.
+ * A breaking change to persisted rows bumps it too, a plugin's extension row version bump included.
+ * Indexes enforcing existing invariants do not change the format.
+ */
+export declare const JOURNAL_VERSION = 38;
+/** A journal written by a build whose format this one cannot read. */
+export declare class IncompatibleJournalError extends Error {
+    readonly found: number;
+    readonly location: string;
+    constructor(found: number, location: string);
+}
+/**
+ * Judges a journal's version stamp on open. An empty journal is adopted whatever it says, and
+ * anything else holding rows is refused, because half a conversation is worse than none. A journal
+ * with no stamp at all reads as `0`.
+ */
+export declare function checkJournalVersion(stamped: number, hasRows: boolean, location: string): void;

package/dist/kit/claim.d.ts

@@ -0,0 +1,13 @@
+import type { Context } from '@leuduan/cordis';
+/**
+ * Claims `key`, a thread by its id or by its activation's scope, for the calling plugin within
+ * `kind`, for as long as the calling plugin's fiber lives: for a behaviour a thread runs at most
+ * once, such as an `AGENTS.md` briefing. `holder` is
+ * how a later refusal names this claim. Throws `refusal(holder)` with the holder of a live claim of
+ * the same kind on the same key, so the plugin that claimed later fails, and with it the
+ * activation, rather than running beside the first. Claims of different kinds never meet.
+ *
+ * Synchronous: the check and the claim are one step, and the claim is an effect of the caller's
+ * fiber, so a release, an unload or a failed setup frees the thread for the next activation.
+ */
+export declare function claimThread(ctx: Context, kind: string, key: unknown, holder: string, refusal: (holder: string) => string): void;

package/dist/kit/drain.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from '@leuduan/cordis';
+/**
+ * Runs `drain` before any owner of `ctx` starts its cleanup, and before the journal's owner does:
+ * as an unload guard on every fiber from `ctx` up to the root, and on the fiber that provides the
+ * journal. Guards on one fiber run together before its disposers, so every service draining this
+ * way is signalled before any of them is awaited, and the journal is still writable for their final
+ * rows. `drain` must be idempotent, since several owners can unload, and must not await its own
+ * owner's teardown, which waits for the guard.
+ */
+export declare function drainBeforeUnload(ctx: Context, drain: () => Promise<void>): void;

package/dist/kit/extension.d.ts

@@ -0,0 +1,180 @@
+import type { Context } from '@leuduan/cordis';
+import type { z } from 'zod';
+import type { AppendOptions, PluginJournal, PluginProjection } from '../journal/index.js';
+import type { ContentPartInput } from '../llm/index.js';
+import { type ModelStep, type RowRef } from '../loop/index.js';
+import { type AgentSelector } from './scope.js';
+import type { ExtensionRecord, InputRole, JournalEvent, Seq, StepContribution } from '../models/index.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import type { DeepReadonly } from '../util/json.js';
+export declare class ExtensionVersionError extends Error {
+    readonly record: ExtensionRecord;
+    readonly supportedVersion: number;
+    constructor(record: ExtensionRecord, supportedVersion: number);
+}
+/**
+ * One plugin-owned event schema. A row of another version is refused with
+ * {@link ExtensionVersionError}: the journal is not migrated, and neither are a plugin's rows.
+ *
+ * `policyState` says a `lagent/tool/authorize` listener decides from these rows: one that lands
+ * while a call is authorized sends the decision round again. Rows of an event that does not say so
+ * never do, so diagnostics and notices cost an authorization nothing.
+ */
+export declare function defineExtensionEvent<Schema extends z.ZodType>(definition: {
+    plugin: string;
+    instanceId?: string;
+    kind: string;
+    version: number;
+    schema: Schema;
+    policyState?: boolean;
+}): {
+    /** A validated record carrying `value`: what an `ext` row holds, and a contribution's `source`. */
+    record: (value: z.input<Schema>) => ExtensionRecord;
+    /** `value` validated as this event's payload, its defaults applied. */
+    parse: (value: z.input<Schema>) => z.output<Schema>;
+    /** A validated row for an atomic `journal.appendAll` batch; every row names its thread. */
+    entry: (value: z.input<Schema>, options: AppendOptions) => {
+        type: "ext";
+        data: {
+            plugin: string;
+            instance_id: string;
+            kind: string;
+            version: number;
+            data: z.core.util.JSONType;
+        };
+        options: AppendOptions;
+    };
+    /** Appends one row carrying `value`; resolves once it is durable. */
+    append(journal: PluginJournal, value: z.input<Schema>, options: AppendOptions): Promise<JournalEvent<"ext">>;
+    read(event: JournalEvent): z.output<Schema> | undefined;
+    /** A validated `lagent/llm/step` contribution whose `source` is this event carrying `value`. */
+    contribution(message: {
+        role?: InputRole;
+        content: string | readonly ContentPartInput[];
+    }, value: z.input<Schema>, options?: {
+        sourceSeqs?: readonly Seq[];
+    }): StepContribution;
+    /** Whether `record` — a contribution's or a rejection's `source` — is one of this event's. */
+    matchesSource(record: DeepReadonly<ExtensionRecord>): boolean;
+    /** A `lagent/turn/stop` rejection whose `source` is this event carrying `value`. */
+    rejection(reason: string, value: z.input<Schema>): {
+        decision: "reject";
+        reason: string;
+        source: ExtensionRecord;
+    };
+    /** The value a contributed `input/message` carries, when this event is its source. */
+    readContribution: (event: JournalEvent) => z.output<Schema> | undefined;
+    /**
+     * The value `source` carries — a queued input's or a contribution's — when it is one of this
+     * event's; `undefined` for any other. Another version is refused, as for a row.
+     */
+    readSource: (source: DeepReadonly<ExtensionRecord> | null) => z.output<Schema> | undefined;
+    /**
+     * What a thread was told through this event's contributions: every notice row, with the value
+     * it carried and whether it is still on the thread's surface. Read it with {@link latestNotice}
+     * and {@link latestVisible}.
+     *
+     * A thread was told something only while the notice is on its surface. A `surface/replaced`
+     * row that cites a notice row clears that row's visibility, for good; nothing else does. So a
+     * plugin that tells a thread a fact compares it with what the model can still see, and tells it
+     * again once a replacement took it away, with no scan of the surface at any step. Thread-scoped
+     * and inherited: a fork, and `stateAt`, see what was visible at their row of the lineage.
+     */
+    told: PluginProjection<ToldNotices<z.output<Schema>>>;
+    /**
+     * Unrelated events are ignored. Failure makes this projection unavailable, not the journal.
+     *
+     * A fork inherits a thread-scoped state by default; `onFork: 'reset'` starts each fork from
+     * `init()` instead, for state that describes what the source did rather than its conversation.
+     * `apply` also gets the `ext` row that carried the value.
+     */
+    projection<State>(fold: {
+        key: string;
+        init(): State;
+        apply(state: State, value: z.output<Schema>, event: JournalEvent<"ext">): State;
+        onFork?: "inherit" | "reset";
+    }): PluginProjection<State>;
+};
+/**
+ * One notice a thread was told: the row that told it, the value its `source` carried, and whether
+ * the model can still see it.
+ */
+export type ToldNotice<Value> = {
+    readonly row: RowRef;
+    readonly value: Value;
+    /**
+     * Whether the notice is still on the thread's surface: cleared by the first `surface/replaced`
+     * row that cites it. What was recorded is one fact; whether the model can still see it, another.
+     */
+    readonly visible: boolean;
+};
+/** Every notice of one kind a thread was told, oldest first: the state of an event's `told` fold. */
+export type ToldNotices<Value> = {
+    readonly notices: readonly ToldNotice<Value>[];
+};
+/**
+ * The latest notice told, visible or not; `null` when none was ever told. For recorded text: a
+ * notice whose latest telling is no longer visible is told again from that row, as recorded.
+ */
+export declare function latestNotice<Value>(told: ToldNotices<Value>): ToldNotice<Value> | null;
+/**
+ * What the latest notice the model can still see says; `null` when none is visible. For live facts:
+ * compare the fact as it stands with this, and tell it when they differ, rendered against this
+ * value, as a first telling when it is `null` and as a change from it otherwise.
+ *
+ * Not the latest notice's value: an earlier notice can outlive a later one. A restriction told
+ * early and lifted by a later notice that a replacement took away is still what the model sees, so
+ * the lift has to be told again.
+ */
+export declare function latestVisible<Value>(told: ToldNotices<Value>): Value | null;
+/** What {@link tellOnStep} uses of an event `defineExtensionEvent` declared, `Input` and `Output` its payload's. */
+export type NoticeEvent<Input, Output> = {
+    parse(value: Input): Output;
+    readonly told: PluginProjection<ToldNotices<Output>>;
+    contribution(message: {
+        content: string;
+    }, value: Input): StepContribution;
+};
+/** One fact a thread is told at its model steps; see {@link tellOnStep}. */
+export type StepNotice<Input, Output> = {
+    /** The event each notice is recorded as, whose `told` fold says what the model can still see. */
+    readonly event: NoticeEvent<Input, Output>;
+    /** Whose threads are told; without it, every thread this plugin's listener reaches. */
+    readonly agents?: AgentSelector;
+    /**
+     * Where the notice is recorded among the step's contributions: lower first, equal ranks in
+     * listener order, 0 when omitted. See {@link ModelStep.contribute}.
+     */
+    readonly rank?: number;
+    /** What is true for this step, or `undefined` to tell nothing at it. */
+    current(step: ModelStep): Input | undefined;
+    /**
+     * The notice's text: `value` as a first telling when `told`, the latest notice the model can still
+     * see, is `null`, and as a change from it otherwise; `null` to tell nothing. `notices` is every
+     * notice of the event, for a plugin whose rule needs more than the latest visible one. What was
+     * told is read from the journal's fold, so it is the read-only view of `Output`.
+     */
+    render(value: Output, told: ReadonlyState<Output> | null, at: {
+        readonly step: ModelStep;
+        readonly notices: ToldNotices<ReadonlyState<Output>>;
+    }): string | null;
+};
+/**
+ * Tells a thread a fact as a conversation message at its model steps: at each step already due,
+ * `current` says what is true, and when it differs from the latest notice the model can still see
+ * the step carries the rendered notice, recorded as the event. So a fact is told on the first step,
+ * again when it changes, and again after a replacement took the notice off the surface; several
+ * changes between two steps are one notice, and a change back is none. A plugin whose notice one
+ * plugin's failure must not silence keeps its own event, as every notice does. The event's schema
+ * must give the same value parsed twice, since the notice is recorded from `current` and compared
+ * after it is read back.
+ *
+ * ```ts
+ * tellOnStep(ctx, {
+ *   event: routeNotice,
+ *   current: (step) => step.route,
+ *   render: (route, told) => (told === null ? `You run on ${route.model}.` : `You now run on ${route.model}.`),
+ * })
+ * ```
+ */
+export declare function tellOnStep<Input, Output>(ctx: Context, notice: StepNotice<Input, Output>): void;

package/dist/kit/grants.d.ts

@@ -0,0 +1,9 @@
+import { type Context } from '@leuduan/cordis';
+import type { AgentSelector } from './scope.js';
+/**
+ * Grants `toolName` to the agents `agents` selects, for the life of the calling plugin's fiber, or
+ * until the returned disposer runs. The selector is stored as given: registries are live, so
+ * a grant to `'global'` or `'all'` is matched against each agent when it asks, agents registered
+ * later included.
+ */
+export declare function grantTool(ctx: Context, toolName: string, agents: AgentSelector): () => void | Promise<void>;

package/dist/kit/modes.d.ts

@@ -0,0 +1,65 @@
+import type { Context } from '@leuduan/cordis';
+import type { PluginJournal } from '../journal/index.js';
+import type { WriteRows } from '../loop/index.js';
+/** One set of durable modes, as {@link defineModes} takes it. */
+export type ModesDefinition<Mode extends string> = {
+    /** Names the modes in the journal, so two sets never mix. */
+    readonly name: string;
+    /**
+     * Where a thread's mode is recorded and read: on the thread itself, or on its origin root
+     * (`Thread.originRoot`), so a delegated thread is in its conversation's mode and switching the
+     * conversation switches every thread it started.
+     */
+    readonly authority: 'thread' | 'conversation';
+    /** The mode before one is recorded. */
+    readonly initial: NoInfer<Mode>;
+    /** Every mode the set has; what each one means belongs to the feature that reads it. */
+    readonly modes: readonly Mode[];
+};
+/**
+ * A set of durable modes: the state a feature reads to decide what a thread may do, and the host's
+ * way to set it. Each read and write takes a context that injects `journal` and `threads`.
+ */
+export type Modes<Mode extends string = string> = ModesDefinition<Mode> & {
+    /** The mode in force on `threadId`: its authority's latest recorded mode, or `initial`. */
+    of(ctx: Context, threadId: string): Mode;
+    /** Records `mode` on `threadId`'s authority, only when it changes it, decided inside the write. */
+    set(ctx: Context, threadId: string, mode: Mode): Promise<void>;
+    /**
+     * The rows that record `mode` in the write that creates or forks a thread (`Opening.rows`),
+     * so the thread never exists in another mode: always one row, `initial` included, so an opening
+     * leaves evidence of the choice (a fork would otherwise go on in the mode it inherits). The mode
+     * is validated here, before anything is written. Refused inside the write, which then records
+     * nothing, anywhere but an opening write, and for a thread with an `origin` under `conversation`
+     * authority, which is in its conversation's mode.
+     */
+    opening(mode: Mode): WriteRows;
+    /**
+     * The thread a mode is recorded on for `threadId`: itself, or for `conversation`, its
+     * `originRoot`. Throws {@link MissingAuthorityError} when that root cannot be found, so no thread
+     * part-way up is taken for it; a thread the catalog does not hold is its own.
+     */
+    authorityOf(ctx: Context, threadId: string): string;
+    /** The mode recorded on `threadId` itself, or `null`: what a catalog contribution computes. */
+    recorded(journal: PluginJournal, threadId: string): Mode | null;
+};
+/** A conversation mode asked for a thread whose caller chain does not reach its origin root. */
+export declare class MissingAuthorityError extends Error {
+    constructor(threadId: string, modes: string);
+}
+/**
+ * Defines a set of durable modes, once per `name` in a process. A mode is an `ext` row on the
+ * authority thread, declared policy state, so a switch while a call is authorized decides it again.
+ * The set owns that state only: what a mode means, and what the model is told about it, belong to
+ * the feature that reads it (see `toolPolicy`).
+ *
+ * ```ts
+ * const permissions = defineModes<'ask' | 'auto'>({
+ *   name: 'app:permission',
+ *   authority: 'conversation',
+ *   initial: 'ask',
+ *   modes: ['ask', 'auto'],
+ * })
+ * ```
+ */
+export declare function defineModes<Mode extends string>(definition: ModesDefinition<Mode>): Modes<Mode>;

package/dist/kit/retries.d.ts

@@ -0,0 +1,25 @@
+import { type Clock } from './timers.js';
+/**
+ * Consecutive failures and the retry timer of work whose write failed, by key: what ask, schedules
+ * and delegations each kept beside their deadlines. Owns the counts and one timer queue of retries;
+ * the feature keeps its liveness checks, its deadlines, its reporting and what a retry does. There
+ * is no attempt identity: a retry is the feature's own check, which decides again from current state.
+ */
+export type RetryTracker = {
+    /**
+     * Records one more failure of `key` and arms `retry` after the backoff its count earns, replacing a
+     * retry already pending for it. The retry firing keeps the count: only `succeeded` or `clear`
+     * resets it. Inert once disposed.
+     */
+    failed(key: string, retry: () => void): void;
+    /** `key`'s work went through: its count and pending retry are forgotten. */
+    succeeded(key: string): void;
+    /** `key`'s work is no longer wanted: its count and pending retry are forgotten. */
+    clear(key: string): void;
+    /** Whether `key` has failed since it last succeeded or was cleared, its retry pending or in flight. */
+    pending(key: string): boolean;
+    /** Cancels every retry and forgets every count; later calls do nothing. Whoever creates a tracker disposes it. */
+    dispose(): void;
+};
+/** A {@link RetryTracker} whose retries are timed on `clock`; a retry that throws is handed to `report`. */
+export declare function retryTracker(clock: Clock, report: (error: unknown) => void): RetryTracker;

package/dist/kit/scope.d.ts

@@ -0,0 +1,32 @@
+import { type Context } from '@leuduan/cordis';
+import { z } from 'zod';
+/**
+ * The agents a plugin's `agents` option selects. Required wherever it appears: which agents a
+ * composition has is the host's to say, so none of the shipped plugins defaults it. `'global'` is
+ * every globally registered agent, those registered later included; `'all'` is every thread's agent,
+ * scoped ones included; a list names agents, global or scoped.
+ */
+export declare const AgentSelectorSchema: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"global">, z.ZodLiteral<"all">]>;
+export type AgentSelector = readonly string[] | 'global' | 'all';
+/**
+ * Whether `selector` selects `agentName`. One meaning wherever a selector appears, whether the plugin
+ * equips (a grant, a prompt section, a notice) or restricts (a mode, a stop check). `'global'` never
+ * selects a scoped agent (`isScopedAgentName`), so a role child gets only what names it or says
+ * `'all'`; a gate that must cover role children says `'all'`.
+ *
+ * Registries are live, so a selector is a predicate evaluated when the plugin acts — granting,
+ * rendering a prompt section, authorizing a call — rather than a list resolved once at mount.
+ */
+export declare const selects: (selector: AgentSelector, agentName: string) => boolean;
+/**
+ * Whether `name` is an agent name for a scoped registration: one containing a dot, such as
+ * `codex.explore`. Global agent names never contain one, so the two kinds cannot collide, and the
+ * agents registry refuses a registration of the wrong kind.
+ */
+export declare const isScopedAgentName: (name: string) => boolean;
+/**
+ * Refuses a plugin mounted in a thread's scope when `name`, the thing mounted, serves every thread
+ * from the application root. The predicate is `scopeOf(ctx) === undefined`: an untagged application
+ * context passes, so this is not a root-identity check.
+ */
+export declare function requireUnscoped(ctx: Context, name: string): void;

package/dist/kit/service.d.ts

@@ -0,0 +1,7 @@
+import type { Context } from '@leuduan/cordis';
+/**
+ * The root service `name`, or a refusal naming `user`, the plugin or tool that depends on it, when
+ * it is not mounted. Checked where a plugin mounts, so a composition without the service fails
+ * there rather than leaving the plugin silently inactive, and looked up again at each call.
+ */
+export declare function requireService<K extends string & keyof Context>(ctx: Context, name: K, user: string): NonNullable<Context[K]>;

package/dist/kit/strategy.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from '@leuduan/cordis';
+import type { SurfaceStrategy } from '../loop/index.js';
+/**
+ * Makes `strategy` the one that prepares `threadId`'s surface, for as long as the calling plugin's
+ * fiber lives. A thread runs one strategy: a second, from another mount or installation, throws, so
+ * the plugin that came later fails, and with it the activation, rather than running beside the first.
+ */
+export declare function provideStrategy(ctx: Context, threadId: string, strategy: SurfaceStrategy): void;
+/** The strategy that prepares `threadId`'s surface, if any. */
+export declare function strategyOf(ctx: Context, threadId: string): SurfaceStrategy | undefined;

package/dist/kit/timers.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+/**
+ * Wall-clock time and timers, for a plugin that acts at a time of day: what it reads `now` from
+ * and arms its timer on, passed in by the application so a test moves both itself.
+ */
+export type Clock = {
+    /** Wall-clock milliseconds since the epoch, as `Date.now()`. */
+    now(): number;
+    /** Calls `fire` once, `ms` of elapsed time from now; returns the cancel. */
+    setTimer(ms: number, fire: () => void): () => void;
+};
+/** A configuration field that takes a {@link Clock}: `systemClock` in an application, a manual clock in a test. */
+export declare const ClockSchema: z.ZodCustom<Clock, Clock>;
+/**
+ * The process's clock: `Date.now()` and `setTimeout`, its timers `unref`'d so a pending wake never
+ * keeps a process alive.
+ */
+export declare const systemClock: Clock;
+/** The longest one wait lasts: every wake reads the wall clock again, so a jump is noticed within it. */
+export declare const MAX_WAIT_MS = 60000;
+/**
+ * How long to put off work whose write failed, after `failures` failures in a row: a second, doubling
+ * up to ten minutes, so a store that fails for a while is not hammered and one that recovers is
+ * tried again soon.
+ */
+export declare function retryDelayMs(failures: number): number;
+/**
+ * Keyed deadlines on one process timer: `set` (re)arms a key for a wall-clock time, `delete`
+ * forgets it, `dispose` cancels the timer and drops every entry. Entries fire in deadline order,
+ * each once, when a wake finds the wall clock at or past it; its key is removed before it fires.
+ */
+export type TimerQueue = {
+    set(key: string, at: number, fire: () => void): void;
+    delete(key: string): void;
+    dispose(): void;
+};
+/**
+ * A {@link TimerQueue} on `clock`: one timer for the earliest deadline, each wait clamped to
+ * {@link MAX_WAIT_MS}, and `now()` read again at every wake, so a wall clock set back is absorbed
+ * and one set forward is noticed within a minute. Whoever creates a queue owns it, and disposes it.
+ * A `fire` that throws is handed to `report`; the others still fire.
+ */
+export declare function timerQueue(clock: Clock, report: (error: unknown) => void): TimerQueue;