@leuduan/lagent 0.0.0-stage → 44.0.0

package/dist/state/surface.d.ts

@@ -0,0 +1,153 @@
+import type { Journal } from '../journal/index.js';
+import type { Reducer } from './thread.js';
+import type { ConversationMessage } from '../llm/primitives.js';
+import type { JournalEvent, ReplacementKind, Seq, SurfaceEventType } from '../records/journal.js';
+import type { ReadonlyState } from '../util/foldState.js';
+/** A journal row, named by the thread that owns it. Inherited rows belong to a fork's source lineage. */
+export type RowRef = {
+    readonly threadId: string;
+    readonly seq: Seq;
+};
+/**
+ * One message on the surface, with the row behind it.
+ *
+ * An original message is behind its own `input/message`, `assistant/message` or `tool/result` row;
+ * a stand-in is behind the `surface/replaced` row that put it there, whose `source_seqs` name what
+ * it replaced (see {@link replacedOriginals}). A `ConversationMessage` alone does not say which, nor
+ * whether a host sent it, and the replacement rules need both.
+ */
+export type SurfaceEntry = {
+    readonly row: RowRef;
+    readonly type: SurfaceEventType;
+    /**
+     * An `input/message` in role `developer` with no `source`: the host speaking. No replacement
+     * may touch one, since no plugin could bring it back in its place.
+     */
+    readonly directDeveloperInput: boolean;
+    readonly message: ConversationMessage;
+} | {
+    readonly row: RowRef;
+    readonly type: 'surface/replaced';
+    readonly kind: ReplacementKind;
+    readonly directDeveloperInput: false;
+    readonly message: ConversationMessage;
+};
+/** A surface entry as a plugin reads it from the fold: read-only all the way down, its message included. */
+export type SurfaceEntryView = ReadonlyState<SurfaceEntry>;
+export type SurfaceState = {
+    /** What the model sees, in order. */
+    readonly entries: SurfaceEntry[];
+    /**
+     * `surface/replaced` rows this fold skipped, with why. `replaceSurface` writes none that would be
+     * skipped, so an entry here is a row written past it: a bug or a hand-edited store. The fold
+     * records it rather than throwing, since a throwing core fold would leave every thread unopenable;
+     * such a thread is read and forked before the row, and never executed on (`CorruptHistoryError`).
+     */
+    readonly refused: {
+        readonly row: RowRef;
+        readonly refusal: ReplacementRefusal;
+    }[];
+};
+/**
+ * What the model sees, in journal order, with the row behind each message.
+ *
+ * The system prompt is not here: it is recorded once per thread on `thread/prompt` and sent beside
+ * the conversation. Content that has to come back byte-identical belongs here, as a thread's
+ * opening messages.
+ *
+ * A reply the stream cut off is not here either. It is journaled for the record, but as far as the
+ * conversation is concerned the model has not replied: the thread still owes an answer, recovery
+ * sees work left, and a delegating caller sees nothing to take. One rule, read by all three.
+ *
+ * A `surface/replaced` row is folded by splicing: a `span` puts its stand-in where the run it
+ * replaces was, a `rewrite` puts its stand-in in place of the one message it names. Every row it
+ * meets is judged by {@link judgeReplacement}, live or replayed, and `replaceSurface` judges a group
+ * the same way inside its write, so the engine writes no row that the fold would skip.
+ *
+ * A fork inherits all of it: the conversation is exactly what a fork continues. Inherited entries
+ * are named by their original rows, which belong to the source's lineage.
+ */
+export declare const surface: Reducer<SurfaceState>;
+/**
+ * Judges a group of replacements against `entries`, each against the surface the previous one
+ * left, without changing `entries`: the first refused, with its position, or `null` when the whole
+ * group may land.
+ */
+export declare function judgeGroup(entries: readonly SurfaceEntry[], group: readonly JournalEvent<'surface/replaced'>[]): {
+    readonly index: number;
+    readonly refusal: ReplacementRefusal;
+} | null;
+/**
+ * Whether a row put a message of its own on the surface: an `input/message`, a reply that was not
+ * cut off, or a tool result. The one predicate for it: the surface fold, {@link historyMessage} and
+ * history's numbering all gate on it. A `surface/replaced` row's stand-in is derived and never counts.
+ */
+export declare const isHistoryRow: (event: JournalEvent) => boolean;
+/**
+ * The message a row puts on a conversation, or `null` for a row that puts none there
+ * ({@link isHistoryRow}). The one row-to-message logic: the surface fold builds its entries from it
+ * and recall renders history from it, so the model reads what the model saw.
+ */
+export declare function historyMessage(event: JournalEvent): ConversationMessage | null;
+/** A replacement as the rules judge it: the row's data and the rows it cites. A journal row is one. */
+export type ReplacementCandidate = Pick<JournalEvent<'surface/replaced'>, 'data' | 'source_seqs'>;
+/** Which rule a refused replacement breaks; see {@link judgeReplacement}. */
+export type ReplacementRule = 'empty' | 'not-current' | 'developer-input' | 'newest-message' | 'unbalanced' | 'rewrite-target';
+export type ReplacementRefusal = {
+    readonly accepted: false;
+    readonly rule: ReplacementRule;
+    readonly message: string;
+};
+/**
+ * A judgment of one replacement against a surface. An accepted one says where it lands: the cited
+ * messages are `entries[start]` up to, not including, `entries[start + count]`.
+ */
+export type ReplacementVerdict = {
+    readonly accepted: true;
+    readonly start: number;
+    readonly count: number;
+} | ReplacementRefusal;
+/**
+ * Whether a replacement may land on a surface, as it stands. The one predicate for replacements:
+ * the surface fold runs it on every row it folds, `replaceSurface` on every group it writes, and a
+ * strategy may run it on a plan before it asks for anything.
+ *
+ * - **Not empty**: a `span` names at least one row; a `rewrite` names exactly one.
+ * - **Contiguous and current**: the cited rows are, in order, a contiguous run of the rows behind the
+ *   surface. A message already replaced is not current; its stand-in's row is.
+ * - **No direct developer input** is inside a span or rewritten: the host's instruction stays where
+ *   it was, in order with what surrounds it, with no plugin needed to restore it.
+ * - **A `span` keeps the newest message**, so what the thread owes is unchanged. It is also
+ *   **balanced**: no tool call on one side of either edge with its result on the other, and no tool
+ *   result straight after the stand-in (see {@link isBalancedCut}).
+ * - **A `rewrite` targets** a tool result, a `user`-role input, or a rewrite's stand-in: never an
+ *   assistant message, whose recorded provider state the Responses adapters replay in place of its
+ *   content; never a `developer` message, which speaks as the harness; never a span's stand-in, whose
+ *   text the strategy that wrote it owns. It may name the newest message. Its stand-in takes the role
+ *   and tool call id of what it rewrites, so balance and what is owed hold by identity.
+ *
+ * The roles a `span` stand-in may take are the row schema's to enforce, and are. Changing what this
+ * accepts changes what recorded rows mean on replay, so it bumps the journal format version.
+ */
+export declare function judgeReplacement(entries: readonly SurfaceEntry[], candidate: ReplacementCandidate): ReplacementVerdict;
+/**
+ * Whether the surface can be cut just before `entries[at]` (`at` from 0 to `entries.length`)
+ * without separating a tool call from its result: no tool result after the cut answers a call before
+ * it, and no call before it is still owed one. What a span's edges must be, and what a request built
+ * from a prefix of the surface must end on.
+ *
+ * Results are paired with the latest assistant message that called tools before them, as a
+ * provider pairs them and as `unansweredToolCalls` reads them, never by call id across the surface:
+ * providers reuse call ids from one turn to the next.
+ */
+export declare function isBalancedCut(entries: readonly SurfaceEntryView[], at: number): boolean;
+/**
+ * The original rows behind a row on the surface, in surface order: the row itself when it is an
+ * original, or for a `surface/replaced` row, the originals behind every row it cites, followed down
+ * through chains of spans and rewrites. Where any message came from, for whatever asks: recall's
+ * numbering, a checkpoint's range, the copied input.
+ *
+ * Every row a replacement the engine wrote cites was on the surface when it was written, so the walk
+ * meets only replacements that took effect; one the surface refused is not asked about here.
+ */
+export declare function replacedOriginals(journal: Pick<Journal, 'eventAt'>, row: RowRef): RowRef[];

package/dist/state/surfaceRead.d.ts

@@ -0,0 +1,20 @@
+import type { Journal, PluginJournal } from '../journal/index.js';
+import type { ConversationMessage } from '../llm/primitives.js';
+import type { ReadonlyState } from '../util/foldState.js';
+import { type ReplacementRefusal, type RowRef } from './surface.js';
+/**
+ * The first replacement `threadId`'s surface refused, or `null`: a thread that has one carries
+ * history no execution may continue from, which every entry that executes checks.
+ */
+export declare function refusedReplacement(journal: Pick<Journal, 'state'>, threadId: string): {
+    readonly row: RowRef;
+    readonly refusal: ReplacementRefusal;
+} | null;
+/**
+ * The last thing the model said on a thread, if anything: the message of the last
+ * `assistant/message` row on its lineage that the stream did not cut off. Found through the rows
+ * behind the surface, not by role, so an assistant-role stand-in is never reported as the model's
+ * last word; a reply a replacement took off the surface is still found, through the rows its
+ * stand-in replaced.
+ */
+export declare function lastAssistantMessage(journal: Pick<PluginJournal, 'eventAt' | 'state'>, threadId: string): ReadonlyState<ConversationMessage> | null;

package/dist/state/thread.d.ts

@@ -0,0 +1,73 @@
+import type { CoreFold } from '../journal/index.js';
+import type { JournalEvent } from '../records/journal.js';
+/**
+ * One concern of a thread's state: where it starts, and what a row does to it. `apply` may mutate
+ * `state` and return it, or return a fresh value; it never reads another concern.
+ */
+export type Reducer<S> = {
+    init(): S;
+    apply(state: S, event: JournalEvent): S;
+};
+/** Every concern of core's state, by the field it fills in {@link ThreadState}. */
+declare const REDUCERS: {
+    readonly surface: Reducer<import("./surface.js").SurfaceState>;
+    readonly turnBoundary: Reducer<{
+        lastTurn: number;
+        step: number;
+        lastReason: import("../records/journal.js").TurnEndReason | null;
+        turnOpen: boolean;
+        concludedTurn: number | null;
+    }>;
+    readonly answerCheck: Reducer<import("./turns.js").AnswerCheck>;
+    readonly dispatchedCalls: Reducer<Map<string, number>>;
+    readonly dispatchAttempts: Reducer<Map<string, import("./dispatches.js").DispatchAttempt>>;
+    readonly waits: Reducer<Map<number, import("./waits.js").WaitEntry>>;
+    readonly confirmations: Reducer<Map<string, import("./confirmations.js").ConfirmationState>>;
+    readonly executions: Reducer<Map<number, import("./confirmations.js").RuntimeExecution>>;
+    readonly threadRecord: Reducer<import("./birth.js").ThreadRecord | null>;
+    readonly threadRoute: Reducer<{
+        provider: string;
+        model: string;
+        thinking_effort: "low" | "high" | "none" | "medium" | "max" | null;
+    } | null>;
+    readonly threadPrompt: Reducer<{
+        kind: "base" | "instruction" | "context";
+        tag: string | null;
+        text: string;
+    }[] | null>;
+    readonly threadTools: Reducer<readonly {
+        input_schema: import("../llm/primitives.js").JsonObject;
+        name: string;
+        description: string;
+    }[] | null>;
+    readonly forkTask: Reducer<{
+        spawnSeq: import("../records/journal.js").Seq | null;
+        unclaimed: boolean;
+    }>;
+    readonly inbox: Reducer<import("./inputs.js").InboxState>;
+    readonly inputs: Reducer<Map<string, import("./inputs.js").InputRows>>;
+    readonly installations: Reducer<import("./installations.js").InstallationsState>;
+    readonly lastAnswer: Reducer<number | null>;
+    readonly requests: Reducer<import("./requests.js").RequestsState>;
+    readonly chain: Reducer<import("./chain.js").ChainState>;
+};
+type Concern = keyof typeof REDUCERS;
+type StateOf<K extends Concern> = ReturnType<(typeof REDUCERS)[K]['init']>;
+/** A thread's state as core folds it: one field per concern. */
+export type ThreadState = {
+    [K in Concern]: StateOf<K>;
+};
+/**
+ * Core's one fold: a thread's {@link ThreadState}, every concern reduced from the same rows. Fatal,
+ * as all of core's state is, and registered by the journal plugin before the journal opens. Read it
+ * with `journal.state(threadState, threadId).inbox`, and so on; a plugin reads it the same way but
+ * cannot register or make a fold of this kind.
+ */
+export declare const threadState: CoreFold<ThreadState>;
+/**
+ * One field of {@link ThreadState} as a reducer of its own, with the same fork rule, for a replay
+ * that folds only what it reads: `journal.stateAt` to a row, or a walk along a lineage. A reducer,
+ * not a projection, so it can never be registered as a second fold.
+ */
+export declare function subState<K extends Concern>(key: K): Reducer<StateOf<K>>;
+export {};

package/dist/state/turns.d.ts

@@ -0,0 +1,87 @@
+import type { Seq, TurnEndReason } from '../records/journal.js';
+import { type ResponseFinish } from '../llm/primitives.js';
+import type { Journal } from '../journal/index.js';
+import type { Reducer } from './thread.js';
+/**
+ * Where a thread is in its turns: the highest one opened, how many steps it has taken, how it ended,
+ * and whether a tool asked it to stop.
+ *
+ * `step` counts `step/start` since the last `turn/start`, so it is only meaningful while that turn
+ * is in flight — a finished turn's count says nothing about the next one. It is folded rather than
+ * counted in memory so the loop's decision stays a function of the journal across a restart.
+ * `turnOpen` holds while a turn is in flight — including one whose process died, which the thread
+ * closes as `interrupted` before it opens another.
+ *
+ * A fork continues the turn numbering and inherits `concludedTurn`, so a fork taken after a
+ * concluding result is not owed a reply either. Everything else here describes the source's
+ * execution and resets: a fork has no turn in flight and no outcome of its own, even when it was cut
+ * inside one of its source's turns.
+ */
+export declare const turnBoundary: Reducer<{
+    lastTurn: number;
+    step: number;
+    /** How this thread's own last turn ended; `null` before its first ends, or while one is open. */
+    lastReason: TurnEndReason | null;
+    turnOpen: boolean;
+    /**
+     * The turn in which a tool result asked for the turn to end, until input arrives. Holds across
+     * the turn boundary: the concluding result is not a reply the model owes, so nothing happens until
+     * someone sends something new — but only the turn it landed in is cut short by it.
+     */
+    concludedTurn: number | null;
+}>;
+/** Whether a thread's latest answer has been judged by its stop checks. */
+export type AnswerCheck = {
+    status: 'none';
+} | ({
+    status: 'pending' | 'accepted' | 'rejected';
+    seq: Seq;
+    text: string;
+} & ({
+    kind: 'reply';
+    finish: ResponseFinish;
+} | {
+    kind: 'concluded';
+}));
+/**
+ * The conversation's latest answer — a reply with no tool calls, or a result that concluded the
+ * turn — and whether a stop check has judged it.
+ *
+ * An answer is `pending` from the moment it is recorded until its turn ends `completed` (accepted)
+ * or `rejected`. Every other ending leaves it pending, so a check a crash, an abort or a failing
+ * listener cut short is still owed; new input supersedes the answer altogether. Folded from rows
+ * the loop writes anyway, so there is no marker for a crash to fall in front of.
+ *
+ * A fork resets it (see `threadState`'s fork table); a fork is never cut where a check is still owed,
+ * so nothing is lost.
+ */
+export declare const answerCheck: Reducer<AnswerCheck>;
+/**
+ * How the run that began after a row ended, and what it answered, read from the thread's events
+ * after that row. A run's outcome, not a delegation task's: an `aborted` turn ends a run, while a
+ * task stays open across it (the delegations plugin's own fold).
+ */
+export type RunOutcome = {
+    /** The last turn ending seen for this run, if any. */
+    reason: TurnEndReason | null;
+    /**
+     * The accepted answer: the reply, or the output of the tool result that concluded the turn. Empty
+     * until the run has answered — a provisional or rejected answer is not one.
+     */
+    output: string;
+    /** Whether the conversation has reached an answer: a complete reply, or a result that concluded the turn. */
+    answered: boolean;
+};
+/**
+ * How the run that began after `fromSeq` ended, and what it answered.
+ *
+ * The `answerCheck` reducer folded over the rows after `fromSeq`: the same rule the loop and its stop
+ * checks read, so an answer is a complete reply with nothing left to call, or a tool result that
+ * concluded the turn, and it becomes the run's answer only at the `turn/end(completed)` that
+ * accepted it. A process that died before that ending leaves it unaccepted, and the scan goes on to
+ * the turn that checks it. Scanning stops at the first turn ending that settles the run, answered or
+ * failed outright, so a later turn of the same thread is never mistaken for this run's.
+ */
+export declare function outcomeSince(journal: Journal, threadId: string, fromSeq: Seq): RunOutcome;
+/** A turn ending after which the run will not produce an answer without new input. */
+export declare const isRunFailure: (reason: TurnEndReason | null) => boolean;

package/dist/state/waits.d.ts

@@ -0,0 +1,38 @@
+import type { Seq } from '../records/journal.js';
+import type { ReadonlyJsonValue } from '../util/json.js';
+import type { Reducer } from './thread.js';
+/** A call's `wait/declared` row, as the waits fold keeps it. */
+export type WaitDeclaration = {
+    /** The `wait/declared` row. */
+    readonly seq: Seq;
+    readonly turn: number;
+    readonly step: number;
+    readonly call_id: string;
+    readonly call_seq: Seq;
+    readonly owner: string;
+    readonly dependency: {
+        readonly [key: string]: ReadonlyJsonValue;
+    };
+    readonly deadline_at: number | null;
+    readonly reason: string;
+};
+/** One declared wait: its declaration, the value it resolved with, and whether its call was answered. */
+export type WaitEntry = {
+    readonly declaration: WaitDeclaration;
+    value: {
+        readonly [key: string]: ReadonlyJsonValue;
+    } | null;
+    /** The call's `tool/result` landed: by its dispatch from the value, or by a cancel. */
+    answered: boolean;
+};
+/**
+ * Every wait the thread declared, by `call_seq`, kept after its call is answered, so answer-once can
+ * report a value recorded before. A fork starts with none: it is never cut with a call unanswered.
+ */
+export declare const waits: Reducer<Map<Seq, WaitEntry>>;
+/** Declared, with no value and no answer: what holds the thread, and what its owner still resolves. */
+export declare const isUnresolved: (entry: WaitEntry | undefined) => boolean;
+/** Declared and unanswered, resolved or not: the waiting call's authority, which a cancel answers. */
+export declare const isSuspended: (entry: WaitEntry | undefined) => boolean;
+/** The thread's suspended waits, in declaration order. */
+export declare const suspendedWaits: (state: ReadonlyMap<Seq, WaitEntry>) => WaitEntry[];

package/dist/state/wake.d.ts

@@ -0,0 +1,32 @@
+import type { AppendEntry } from '../journal/index.js';
+import type { RunChain } from '../records/journal.js';
+import type { PendingRun } from './requests.js';
+import { type RouteAuthority, type RouteStatement } from './route.js';
+/**
+ * How a write asks its thread to run: the cause it records beside what it brings. A person's wake
+ * names no authority: it releases the failure, cancellation and startup holds, and its turns are a
+ * person's. A plugin's names its own: `releases` whether it releases those holds, a person's or a
+ * host's authority, and `chain` how a turn it opens counts. Either may state the route it runs on
+ * (`RouteStatement`).
+ */
+export type Wake = {
+    readonly route?: RouteStatement;
+} & ({
+    readonly releases?: undefined;
+    readonly chain?: undefined;
+} | {
+    readonly releases: boolean;
+    readonly chain: RunChain;
+});
+/**
+ * The rows that record `wake` on a thread whose pending request is `pending`, built inside the
+ * write that brings it, which read `pending` there: a `run/requested` when none is pending, then
+ * the cause, naming the input it brought, if any, and the route it changed the thread to, if it did;
+ * and the run the cause joins or opens. A route statement is checked by `routes`, the thread owner,
+ * which is the one guard on every route-changing write; a refusal throws, refusing the whole write.
+ * A write with no `routes` (a thread's opening group, a plugin's resolution) takes no statement.
+ */
+export declare function causeRows(threadId: string, pending: PendingRun | null, wake: Wake, inputId: string | null, routes?: RouteAuthority): {
+    readonly runId: string;
+    readonly rows: AppendEntry[];
+};

package/dist/stores/durableObject.d.ts

@@ -0,0 +1,23 @@
+import { SqlJournalStore, type SqlConnection, type SqlExclusivity } from './sql.js';
+import { type DurableObjectStorage } from './durableObjectConnection.js';
+export type { DurableObjectStorage } from './durableObjectConnection.js';
+/** What `DurableObjectJournalStore` needs from the host, with no default. */
+export type DurableObjectJournalStoreOptions = {
+    /** Names the journal in errors, such as `IncompatibleJournalError`; a Durable Object has nothing to derive it from, so `do:${ctx.id}` is the natural choice. */
+    readonly identity: string;
+};
+/**
+ * Journal in a Durable Object's own SQLite storage: the schema, contract checks and format stamp of
+ * every SQL store, with each write confirmed durable by `storage.sync()` before it resolves, so an
+ * append that resolved survives a crash. One writer per storage: a second store over the same
+ * `ctx.storage` is refused, whichever instance makes it. A failed append revokes the journal; the
+ * host resets the object, and the next instance rebuilds from committed storage. Construct one over
+ * `ctx.storage` and pass it to `core` as `store`.
+ */
+export declare class DurableObjectJournalStore extends SqlJournalStore {
+    private readonly storage;
+    private readonly identity;
+    constructor(storage: DurableObjectStorage, options: DurableObjectJournalStoreOptions);
+    protected connect(): SqlConnection;
+    protected exclusive(): Promise<SqlExclusivity>;
+}

package/dist/stores/durableObject.js

@@ -0,0 +1 @@
+import{a as c}from"../chunks/JCTBX33H.js";import{l as i}from"../chunks/BBCW2FZK.js";import"../chunks/MMNNZCBO.js";import"../chunks/G44LG6VL.js";import"../chunks/D4PQP5MA.js";function o(e){return{exec:t=>{e.sql.exec(t).toArray()},run:(t,...r)=>{e.sql.exec(t,...r).toArray()},all:(t,...r)=>e.sql.exec(t,...r).toArray(),transaction:async t=>{let r=e.transactionSync(t);return await e.sync(),r},close:()=>{}}}var n=new WeakMap;function s(e,t){if(n.has(e))throw new i(t);let r={};return n.set(e,r),{identity:t,release:()=>{n.get(e)===r&&n.delete(e)}}}var l=class extends c{storage;identity;constructor(t,r){super(r.identity),this.storage=t,this.identity=r.identity}connect(){return o(this.storage)}async exclusive(){return s(this.storage,this.identity)}};export{l as DurableObjectJournalStore};

package/dist/stores/durableObjectConnection.d.ts

@@ -0,0 +1,27 @@
+import type { SqlConnection, SqlExclusivity, SqlValue } from './sql.js';
+/**
+ * The part of a Durable Object's `ctx.storage` the store uses, typed structurally so this package
+ * takes no dependency on the Workers types. The real object satisfies it as it is.
+ */
+export type DurableObjectStorage = {
+    sql: {
+        exec(query: string, ...bindings: SqlValue[]): {
+            toArray(): unknown[];
+        };
+    };
+    transactionSync<T>(body: () => T): T;
+    sync(): Promise<void>;
+};
+/**
+ * Runs the store's SQL on the object's own SQLite. A transaction's local commit is synchronous, and
+ * its result resolves only after `sync()` confirms the write is durable. A `sync()` rejection is the
+ * transaction's failure and rolls nothing back: the local commit completed and may have persisted.
+ */
+export declare function durableObjectConnection(storage: DurableObjectStorage): SqlConnection;
+/**
+ * The one writer of a storage. Wrappers over the same storage share the entry, so a second
+ * acquisition is refused whichever wrapper makes it; the platform runs one instance of an object,
+ * but that instance can still hold two stores over one `ctx.storage`. Release clears only the
+ * entry this acquisition made, so a stale release never clears a replacement's.
+ */
+export declare function durableObjectExclusivity(storage: object, identity: string): SqlExclusivity;

package/dist/stores/memory.d.ts

@@ -0,0 +1,29 @@
+import type { JournalEvent, Seq, ThreadSummary } from '../records/journal.js';
+import { JournalStore, type AppendOutcome, type Attempt, type ThreadIndexEntry, type WriterLease } from '../journal/index.js';
+/**
+ * In-memory backing, keeping serialized rows so it exercises the same round trip as SQLite. Its
+ * writer lease is exclusive within the process, which is as far as its rows reach.
+ */
+export declare class MemoryJournalStore extends JournalStore {
+    private readonly rows;
+    /** Each row's thread and seq, so a read need not parse every row. */
+    private readonly index;
+    private readonly threadIndex;
+    private readonly catalog;
+    private readonly attempts;
+    /** The acquisition the writer record names; `undefined` while nobody holds the lease. */
+    private writer;
+    get size(): number;
+    acquireWriter(): Promise<WriterLease>;
+    protected doOpen(): Promise<void>;
+    protected doClose(): Promise<void>;
+    protected doHead(): Promise<Seq>;
+    protected doAppend(attempt: Attempt, digest: string): Promise<AppendOutcome>;
+    protected doRead(threadId: string): Promise<JournalEvent[]>;
+    protected doRowAt(seq: Seq): Promise<JournalEvent | undefined>;
+    protected doThreads(): Promise<ThreadIndexEntry[]>;
+    protected doSummaries(): Promise<ThreadSummary[]>;
+    protected doPutSummaries(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    protected doReplaceCatalog(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    private headSeq;
+}

package/dist/stores/sql.d.ts

@@ -0,0 +1,59 @@
+import type { JournalEvent, Seq, ThreadSummary } from '../records/journal.js';
+import { JournalStore, type AppendOutcome, type Attempt, type ThreadIndexEntry, type WriterLease } from '../journal/index.js';
+export type SqlValue = string | number | null;
+/** A synchronous SQLite connection: what the two stores differ in, except exclusivity. */
+export type SqlConnection = {
+    /** Statements without parameters or results; may hold several (the schema). */
+    exec(sql: string): void;
+    run(sql: string, ...params: SqlValue[]): void;
+    all<Row>(sql: string, ...params: SqlValue[]): Row[];
+    /** Runs `body` as one write transaction, rolled back when it throws; resolves once the commit is durable. */
+    transaction<T>(body: () => T): Promise<T>;
+    /** Releases this adapter's resources; never the host's storage. */
+    close(): void;
+};
+/** The exclusivity a store's platform grants, taken before anything is read: an OS lock, an in-process registry. */
+export type SqlExclusivity = {
+    readonly identity: string;
+    release(): void;
+};
+/**
+ * The journal store over a synchronous SQLite connection: the schema and its version stamp, the
+ * writer record, every append, summary and catalog check, and row parsing. A subclass supplies the
+ * connection and the exclusivity its platform grants; nothing else differs between stores.
+ */
+export declare abstract class SqlJournalStore extends JournalStore {
+    private db;
+    /** The acquisition this store holds, recorded in `writer` once the database is open. */
+    private acquisition;
+    private readonly location;
+    /** `location` names the journal in errors, such as `IncompatibleJournalError`. */
+    protected constructor(location: string);
+    /** Opens the connection `doOpen` uses; the store closes it in `doClose`. */
+    protected abstract connect(): SqlConnection;
+    /** Takes the platform's exclusivity for `acquireWriter`, or rejects with `JournalBusyError`. */
+    protected abstract exclusive(): Promise<SqlExclusivity>;
+    acquireWriter(): Promise<WriterLease>;
+    /**
+     * Inside a transaction: refuses unless `writer` is the acquisition this store holds and the writer
+     * record names it. The held acquisition alone fences a released lease whose record could not be
+     * cleared; the record alone fences another process that took the journal over.
+     */
+    private requireWriter;
+    /** Names this store's acquisition in the writer record, which every append checks. */
+    private recordWriter;
+    protected doOpen(): Promise<void>;
+    protected doClose(): Promise<void>;
+    private requireDb;
+    protected doHead(): Promise<Seq>;
+    private headOf;
+    protected doAppend(attempt: Attempt, digest: string): Promise<AppendOutcome>;
+    protected doRead(threadId: string): Promise<JournalEvent[]>;
+    protected doRowAt(seq: Seq): Promise<JournalEvent | undefined>;
+    protected doThreads(): Promise<ThreadIndexEntry[]>;
+    protected doSummaries(): Promise<ThreadSummary[]>;
+    protected doPutSummaries(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    protected doReplaceCatalog(summaries: readonly ThreadSummary[], writer: string): Promise<void>;
+    private writeSummaries;
+    private rows;
+}

package/dist/stores/sqlite.d.ts

@@ -0,0 +1,31 @@
+import { SqlJournalStore, type SqlConnection, type SqlExclusivity } from './sql.js';
+/** What `SqliteJournalStore` needs from the host, with no default for either. */
+export type SqliteJournalStoreOptions = {
+    /**
+     * The directory the writer-lock files live in, an absolute path. Every process that opens this
+     * journal must be given the same one, or two writers are not refused; one beside the journal is
+     * the natural choice.
+     */
+    readonly lockDirectory: string;
+    /**
+     * How long, in total, an append or a catalog write waits for another connection's write lock, a
+     * shell or a backup say, before it fails with `StoreBusyError`. `0` does not wait.
+     */
+    readonly busyTimeoutMs: number;
+};
+/**
+ * SQLite-backed journal at `<directory>/journal.db`: the rows in `events`, the thread index in
+ * `threads` and the attempt record in `attempts`, written in one transaction per group; the catalog
+ * in `summaries`, written after; the writer record in `writer`; the format stamp in `meta`. The
+ * writer lease is an operating system lock, so a process that dies releases it; the record holds the
+ * acquisition id every append checks. Construct one and pass it to `core` as `store`.
+ */
+export declare class SqliteJournalStore extends SqlJournalStore {
+    private readonly lockDirectory;
+    private readonly busyTimeoutMs;
+    readonly directory: string;
+    constructor(directory: string, options: SqliteJournalStoreOptions);
+    get databasePath(): string;
+    protected connect(): SqlConnection;
+    protected exclusive(): Promise<SqlExclusivity>;
+}

package/dist/stores/sqlite.js

@@ -0,0 +1 @@
+import{a as m}from"../chunks/JCTBX33H.js";import{l as u,m as h}from"../chunks/BBCW2FZK.js";import"../chunks/MMNNZCBO.js";import"../chunks/G44LG6VL.js";import"../chunks/D4PQP5MA.js";import{closeSync as d,mkdirSync as c,openSync as w,realpathSync as f,statSync as p}from"node:fs";import{isAbsolute as M,join as n}from"node:path";import{DatabaseSync as y}from"node:sqlite";var b=class extends m{lockDirectory;busyTimeoutMs;directory;constructor(t,e){super(n(t,"journal.db")),this.directory=t;let{lockDirectory:r,busyTimeoutMs:s}=e;if(!M(r))throw new TypeError(`lockDirectory must be an absolute path: ${r}`);if(!Number.isFinite(s)||s<0)throw new TypeError(`busyTimeoutMs must be a finite number of milliseconds, zero or more: ${s}`);this.lockDirectory=r,this.busyTimeoutMs=s}get databasePath(){return n(this.directory,"journal.db")}connect(){return c(this.directory,{recursive:!0}),new a(this.databasePath,this.busyTimeoutMs)}async exclusive(){c(this.directory,{recursive:!0}),d(w(this.databasePath,"a",384));let t=f(this.databasePath),{dev:e,ino:r}=p(t,{bigint:!0});c(this.lockDirectory,{recursive:!0,mode:448});let s=new y(n(this.lockDirectory,`${e}-${r}.db`));try{s.exec("PRAGMA busy_timeout=0; BEGIN EXCLUSIVE")}catch(i){throw s.close(),l(i)?new u(t):i}return{identity:`sqlite:${e}:${r}`,release:()=>s.close()}}},a=class{db;path;busyTimeoutMs;statements=new Map;writes=Promise.resolve();constructor(t,e){this.path=t,this.busyTimeoutMs=e,this.db=new y(t);try{this.db.exec("PRAGMA journal_mode=WAL")}catch(r){throw this.db.close(),r}}exec(t){this.db.exec(t)}run(t,...e){this.statement(t).run(...e)}all(t,...e){return this.statement(t).all(...e)}transaction(t){let e=()=>this.write(t),r=this.writes.then(e,e);return this.writes=r.catch(()=>{}),r}close(){this.statements.clear(),this.db.close()}statement(t){let e=this.statements.get(t);return e===void 0&&(e=this.db.prepare(t),this.statements.set(t,e)),e}async write(t){await this.beginWrite();try{let e=t();return this.db.exec("COMMIT"),e}catch(e){throw this.rollback(),e}}async beginWrite(){let t=Date.now();for(let e=5;;e=Math.min(e*2,100))try{this.db.exec("BEGIN IMMEDIATE");return}catch(r){if(!l(r))throw r;let s=Date.now()-t;if(s>=this.busyTimeoutMs)throw new h(this.path,s);await new Promise(i=>setTimeout(i,Math.min(e,this.busyTimeoutMs-s)))}}rollback(){if(this.db.isTransaction)try{this.db.exec("ROLLBACK")}catch(t){console.error(t)}}},l=o=>{let t=o?.errcode;return typeof t=="number"&&(t&255)===5};export{b as SqliteJournalStore};

package/dist/sys/environment.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/**
+ * What a process lagent spawns may see, and which programs lagent itself runs: both chosen by the
+ * host, never read from lagent's own process. A plugin that spawns takes them as required
+ * configuration; the helpers here only build them from what the host hands in.
+ */
+/** A spawned process's whole environment, as configuration: every variable it gets, nothing else. */
+export declare const SpawnEnvironmentSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/**
+ * The overrides for a process with no terminal: colour and pagers off, and an editor that fails at
+ * once rather than sitting until the deadline. `CI` is deliberately not set, since test runners
+ * change more than interactivity under it.
+ */
+export declare const NON_INTERACTIVE_ENVIRONMENT: Readonly<Record<string, string>>;
+/** How a host derives a spawn environment from its own. */
+export type SpawnEnvironmentPolicy = {
+    /**
+     * Variables whose names match one of these patterns are dropped. A pattern matches a whole name,
+     * case-insensitively; `*` stands for any run of characters.
+     */
+    readonly drop: readonly string[];
+    /** Set over what remains. */
+    readonly set: Readonly<Record<string, string>>;
+};
+/** `source` filtered and overridden by `policy`: the whole environment a spawned process gets. */
+export declare function buildSpawnEnvironment(source: Readonly<Record<string, string | undefined>>, policy: SpawnEnvironmentPolicy): Record<string, string>;
+/**
+ * The programs lagent runs itself, by absolute path: never looked up through a spawned process's
+ * `PATH`, which a workspace can reach. `rg` is `null` when there is none; the search tools, which
+ * run it, are then not provided.
+ */
+export declare const TrustedProgramsSchema: z.ZodObject<{
+    git: z.ZodString;
+    rg: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type TrustedPrograms = z.output<typeof TrustedProgramsSchema>;
+/**
+ * Each trusted program as the first executable file of its name in `searchPath`'s directories, in
+ * order. Relative directories are skipped: what they name depends on the working directory. Throws
+ * when `git` is not found; `rg` is `null` when it is not.
+ */
+export declare function resolveTrustedPrograms(searchPath: string): TrustedPrograms;