@robota-sdk/agent-session 3.0.7 → 3.1.1

package/dist/node.d.ts

@@ -0,0 +1,876 @@
+import { c as IExternalPayloadSink, d as IExternalPayloadReference, l as ISessionLogSink, o as IExternalPayloadSource, s as ISessionLogSource, t as ISessionClaimRefusalWords } from "./session-claims-DELiAZkZ.js";
+import { IArtifactSealer, IProcessMarkers, IToolResultSpillStore, TArtifactKind, TArtifactLockedReason, TArtifactSealing, TResolveInWorkspace } from "@robota-sdk/agent-core";
+import { IInteractiveSessionRecord, IInteractiveSessionStore, IPromptHistoryBlock, IPromptHistoryEntry, IPromptHistoryReadOptions, IPromptHistorySource, IPromptHistoryWriter, ISessionAuthorship, ISessionClaim, ISessionClaimOptions, ISessionExportOptions, ISessionLease, ISessionListEntry, ISessionLoadOptions, ISessionSaveOptions, ISessionStoreScan, TSessionLoadOutcome } from "@robota-sdk/agent-interface-session";
+//#region src/process-operation-lock.d.ts
+/** A held OS lock; releasing it twice is harmless. */
+interface IProcessOperationLockHandle {
+  release(): void;
+}
+/** Nonblocking exclusive operation locks for names in one host-owned directory. */
+interface IProcessOperationLock {
+  tryAcquire(name: string): IProcessOperationLockHandle | undefined;
+}
+/**
+ * Creates a host lock whose file is never unlinked while this namespace is in use. The OS releases
+ * the lock if its owner exits, including on a crash. A separate same-user program can still replace
+ * the path on POSIX; this is cooperative coordination, not a same-user security boundary.
+ */
+declare function createProcessOperationLock(directory: string): IProcessOperationLock;
+//#endregion
+//#region src/stored-session-codec.d.ts
+/** A stored record: the bytes that go on disk and the plaintext envelope they were made from. */
+interface IEncodedSession {
+  readonly stored: Uint8Array;
+  readonly text: string;
+}
+/** What a record's stored bytes are to a migration that seals what is still plain (#3679). */
+type TStoredSessionMigrationState =
+/** Not sealed framing: whatever it holds — a valid, corrupt, unsupported or bare record. */
+'plain' |
+/** Sealed in this build's framing, and it opens for this id. */
+'sealed' |
+/** Sealed in this build's framing and it does not open for this id: damaged, or other keys. */
+'does-not-open' |
+/** Sealed in a framing a newer build writes. */
+'newer-format';
+/**
+ * Where the bytes of session `id` stand for a migration: decided by whether they open for this id,
+ * never by framing alone. Opening needs the keys unlocked; with them locked it throws
+ * `ArtifactLockedError`, since "intact but locked" decides nothing.
+ */
+declare function storedSessionMigrationState(id: string, stored: Uint8Array, sealer: IArtifactSealer): TStoredSessionMigrationState;
+/**
+ * `raw` — a plain record's bytes exactly as stored, whatever they hold — sealed to session `id`, so a
+ * store that opens it reports the same status the plain bytes gave: a corrupt or unsupported record
+ * stays one, only no longer readable without the keys.
+ */
+declare function sealStoredSessionBytes(id: string, raw: Uint8Array, sealer: IArtifactSealer): Uint8Array;
+/** Whether plain `bytes` hold a valid record of session `id`: what a migration may offer to mark as the owner's. */
+declare function isPlainSessionRecordOf(id: string, bytes: Uint8Array): boolean;
+/** What a store found at a record's path before it writes over it. */
+type TStoredSessionFile =
+/** Nothing is there: "no such file" and nothing else. */
+{
+  readonly kind: 'absent';
+} |
+/**
+ * Something is there and it is not sealed framing; its bytes when the store read them whole (a store
+ * that seals does, so it can tell whether they are exactly what it holds).
+ */
+{
+  readonly kind: 'plain';
+  readonly bytes?: Uint8Array;
+} |
+/** A sealed file, read whole. */
+{
+  readonly kind: 'sealed';
+  readonly bytes: Uint8Array;
+} |
+/** Something is there and it could not be read: it may be sealed, so it is protected like one. */
+{
+  readonly kind: 'unreadable';
+} |
+/** Something is there, too large for this store to read back at all. */
+{
+  readonly kind: 'oversized';
+};
+/** What `bytes` (or their absence) are, for a store that read the whole file. */
+declare function classifyStoredSessionBytes(bytes: Uint8Array | undefined): TStoredSessionFile;
+//#endregion
+//#region src/stored-session-record.d.ts
+/**
+ * How a session store is built. `sealing` is required: every store states whether it keeps its
+ * records sealed or plain, because a store that silently kept them plain beside sealed ones would
+ * write plaintext next to them. A host that seals states it for every store it builds.
+ * `releaseCommand` is the host's command that releases a writer marker whose holder is not running,
+ * for a `has_writer` refusal to name; without it the refusal names none.
+ */
+interface ISessionStoreOptions extends ISessionClaimRefusalWords {
+  readonly sealing: TArtifactSealing;
+}
+/** The sealing `options` state; one that is not a {@link TArtifactSealing} (a call that ignores the types) is refused. */
+declare function sessionSealingOf(options: ISessionStoreOptions): TArtifactSealing;
+/** Refuses anything that is not a {@link TArtifactSealing}. */
+declare function assertSessionSealing(value: unknown): asserts value is TArtifactSealing;
+/**
+ * How a store reaches the file of each record — the one thing it gives {@link StoredSessionRecords}.
+ * Each method validates the id the way the store addresses its files.
+ */
+interface IStoredSessionFiles {
+  /**
+   * What is at session `id`'s path for a load or a listing, read whole, and what such a read reports
+   * when it could not read the file whole.
+   */
+  load(id: string): {
+    readonly file: TStoredSessionFile;
+    readonly unreadable: TSessionLoadOutcome;
+  };
+  /** What is at session `id`'s path now, read whole (plain files too in a store that seals), before it is replaced. */
+  current(id: string): TStoredSessionFile;
+  /** Replaces session `id`'s file with `stored`, whole. */
+  replace(id: string, stored: Uint8Array): void;
+  /** What an absent record is rebuilt as (a project session's replay log); without it, `missing`. */
+  rebuild?(id: string): TSessionLoadOutcome;
+}
+/**
+ * One store's stored form of its records: how it encodes, decodes, guards a replace, claims and
+ * remembers what it holds, over the files {@link IStoredSessionFiles} reaches. A store routes every
+ * read and write of a record through one of these.
+ */
+declare class StoredSessionRecords {
+  #private;
+  /** What a store that seals offers as `IInteractiveSessionStore.authorship`; absent from one that never does. */
+  readonly authorship: ISessionAuthorship | undefined;
+  /**
+   * @param markers the writer markers of the store's `claims` directory, beside its records: every
+   *   claim, lend and write of an id holds the id's marker, so a store without them does not exist.
+   * @param words how refusals are worded (`ISessionStoreOptions.releaseCommand`).
+   */
+  constructor(sealing: TArtifactSealing, files: IStoredSessionFiles, markers: IProcessMarkers, words?: ISessionClaimRefusalWords);
+  /** Whether this store writes its records sealed. */
+  get seals(): boolean;
+  /**
+   * What session `id` holds, saying which of the five things happened. Only a load that asks to `hold`
+   * remembers a record it read, so that this instance can go on saving the session after the keys
+   * lock; a probe remembers nothing, and so can never push a held session out of the bounded memory
+   * or keep plaintext it was only looking at.
+   */
+  load(id: string, options?: ISessionLoadOptions): TSessionLoadOutcome;
+  /** {@link load} for one entry of a listing, which no writer merges. */
+  listed(id: string): TSessionLoadOutcome;
+  /**
+   * Claims session `id` for a session this process runs and reads it in the same call (see
+   * `IInteractiveSessionStore.claim`): the id's writer marker is taken first — published, or taken
+   * over under `lease` — and the read follows, so nothing another writer saves can come between them.
+   * An in-process runner's claim of a record a handoff save left takes it over; a copy's read takes
+   * no marker. Throws `SessionClaimedError`: `has_writer` for an id claimed or lent here or held by
+   * another writer, naming it, and `released` for a lease that has ended.
+   */
+  claim(id: string, options?: ISessionClaimOptions): ISessionClaim;
+  /**
+   * Lends session `id` to another process (see `IInteractiveSessionStore.lend`): its marker is
+   * published for this process with the digest of a fresh nonce, which the borrowing process claims
+   * with, and the id counts as written here until the end, which removes the marker whoever holds it.
+   */
+  lend(id: string): ISessionLease;
+  /**
+   * Whether session `id` may have a writer now: a claim or a lend of this store, or the writer marker
+   * of any other holder whose owner is not provably gone. A surface that would open the id as another
+   * session asks this first.
+   */
+  hasWriter(id: string): boolean;
+  /**
+   * Saves `record` after the checks a save must pass: a claimed id is saved only under its live claim,
+   * and a claim that ended or lost its marker is refused (the write fence); a save without a claim
+   * takes the id's marker for the write and is refused while another writer holds it. Then the file
+   * there must be replaceable — absent, plain, exactly what this instance last wrote or holds, or
+   * sealed and openable here (a claimed id's only when it is what the owner wrote). What the check
+   * stops is a store replacing a sealed session nobody in this process can read. A write that fails
+   * with its bytes already in place is remembered as this store's own.
+   */
+  save(record: IInteractiveSessionRecord, options?: ISessionSaveOptions): void;
+  /** Removes session `id`'s record with `remove`, holding the id's marker; refused while another writer holds it. */
+  delete(id: string, remove: () => void): void;
+  /**
+   * The record this instance itself last wrote or holds, for a writer whose `load` said `locked`:
+   * offered only while the file is exactly the bytes it remembers. `undefined` when it holds nothing
+   * for `id` (and always in a store that seals nothing); `locked` with the reason `changed` when it
+   * does and the file is no longer those bytes, so the writer can say which of the two stopped it.
+   */
+  loadHeld(id: string): TSessionLoadOutcome | undefined;
+  /**
+   * The sealed record of session `id` as a token another store over the same files can take with
+   * {@link importHeld} (see `StoredSessionAuthorship.exportHeld`); `undefined` from a store that seals
+   * nothing, whose records anyone with the store reads from disk.
+   */
+  exportHeld(id: string, options?: ISessionExportOptions): string | undefined;
+  /**
+   * Holds the record a token from {@link exportHeld} carries, pinned, so a store that cannot open the
+   * file (a write-only subagent process) can go on with the session. Throws `TypeError` in a store
+   * that seals nothing: it would write the record in plaintext over the sealed one.
+   */
+  importHeld(id: string, token: string): void;
+  /** Forgets what this instance holds of session `id`, which was deleted. */
+  forget(id: string): void;
+}
+//#endregion
+//#region src/session-store.d.ts
+/**
+ * Where a store keeps the writer markers of its claims and lends: a directory beside the records that
+ * is not a `.json` file, so a listing never reads it as a session.
+ */
+declare const SESSION_CLAIMS_DIRECTORY = "claims";
+/** How a {@link NodeSessionStore} is built. */
+interface INodeSessionStoreOptions extends ISessionStoreOptions {
+  /**
+   * An ancestor of the store's directory the HOST also owns, tightened along with it (SEC-020).
+   * Optional because this adapter does not interpret its base directory as a trusted root and must
+   * not guess that a parent belongs to the product — which of them do is composition's knowledge.
+   * Left out, a store root that already exists keeps whatever mode it was given: the leaf is made
+   * 0700 and the directory above it is not touched.
+   */
+  readonly ownedRoot?: string;
+}
+/**
+ * Persistent session store backed by individual JSON files.
+ *
+ * Construct with a host-owned `baseDir`; framework project composition uses a separate
+ * authority-backed adapter over the same neutral port.
+ */
+declare class NodeSessionStore implements IInteractiveSessionStore {
+  private readonly baseDir;
+  private readonly ownedRoot;
+  /** How records are stored, and what this instance claims, wrote or holds. */
+  private readonly records;
+  /** What only a store that seals offers (`IInteractiveSessionStore.authorship`); absent from one that never does. */
+  readonly authorship?: ISessionAuthorship;
+  /**
+   * @param baseDir the directory holding the records.
+   * @param options `sealing` (required): `{ sealer }` seals what `save` writes and opens what `load`
+   *   reads; `'plain'` writes plain JSON and reports a sealed file it finds as `locked`.
+   *   `ownedRoot`: see {@link INodeSessionStoreOptions}. `releaseCommand`: see `ISessionStoreOptions`.
+   */
+  constructor(baseDir: string, options: INodeSessionStoreOptions);
+  /**
+   * Claims `id` for a session this process runs, reading it in the same call
+   * (`IInteractiveSessionStore.claim`): exclusive across processes and store instances, and every
+   * later save of the id must carry the claim until it is released.
+   */
+  claim(id: string, options?: ISessionClaimOptions): ISessionClaim;
+  /** Lends `id` to another process that will write it (`IInteractiveSessionStore.lend`). */
+  lend(id: string): ISessionLease;
+  /** Whether session `id` may have a writer now (`IInteractiveSessionStore.hasWriter`). */
+  hasWriter(id: string): boolean;
+  /**
+   * Ensure the storage directory exists AND that only its owner can enter it (SEC-020).
+   *
+   * The `existsSync` guard this replaces is the whole defect. It skipped the case that matters: a
+   * directory some earlier version, a shared CI checkout, or another local user left at a wider
+   * mode was adopted as ours with no signal. Measured under umask 022 before this change, a fresh
+   * sessions directory came out 0755 and its records 0644 — and a directory pre-created at 0777
+   * stayed 0777.
+   */
+  private ensureDir;
+  /**
+   * Absolute path to a session's JSON file.
+   *
+   * SEC-006: every public method routes through here, so validating the id at this one point covers
+   * `save` (write), `load` (read), and `delete` (unlink) at once.
+   *
+   * Issue #2240: `assertSafeSessionId` is the guard, and it is sound — no separator, no `.`/`..`
+   * can pass it. But it is a regex reject behind a helper, which static analysis does not model as
+   * a path sanitizer, so `js/path-injection` re-opened on `load` every time this function changed
+   * length. The containment check below is the shape such tools DO recognise: the resolved path
+   * must stay inside the resolved base directory. It is unreachable after the assertion and costs
+   * one `resolve`; it exists so the guard is visible where the sink is, not to replace the guard.
+   */
+  private filePath;
+  /**
+   * Persist a session record to disk atomically (CORE-019).
+   * Creates the storage directory if needed.
+   *
+   * Bytes go to a same-directory temp file first, then move into place with rename —
+   * a crash mid-write can therefore never leave a truncated JSON where the previous
+   * record used to be. Same-directory is load-bearing: cross-device rename is a copy.
+   *
+   * SEC-020: the atomic write now comes from `writeOwnerOnlyFile`, which carries the mode from the
+   * moment the temp file is created. The hand-rolled version here wrote it at the umask's default
+   * and let `rename` carry that mode to the final path, so every record was 0644 — and even setting
+   * the mode after the write would leave a window in which the full transcript was world-readable
+   * on disk.
+   */
+  save(session: IInteractiveSessionRecord, options?: ISessionSaveOptions): void;
+  /**
+   * What is at `path` now, for the guard before a save. Only "no such file" means there is nothing
+   * to protect; a file that cannot be opened or read is `unreadable`. The first bytes tell plain from
+   * sealed, so the common plain case costs one small read in a store that seals nothing, and the rest
+   * of the file is read through the same descriptor, so the bytes judged are those of one file: a
+   * sealed file's always, a plain one's in a store that seals, which must tell whether it is exactly
+   * what the store holds.
+   */
+  private readExisting;
+  /**
+   * Load a session by its ID, saying WHICH of the five things happened.
+   *
+   * `undefined` used to answer the first four — never saved, damaged, written by a build this one
+   * cannot read, and the read failed — and a caller that meant to preserve fields it does not own
+   * then treated "damaged" as "no prior record" and overwrote the file. The outcome type is what
+   * removes that, by making the caller answer the question it was not asking. The fifth, `locked`,
+   * is a sealed file this process cannot open right now: present and intact, so neither of the two.
+   *
+   * Only a load that asks to `hold` the session remembers a sealed record it opens (see
+   * {@link StoredSessionRecords.load}); a probe and the listing remember nothing.
+   */
+  load(id: string, options?: ISessionLoadOptions): TSessionLoadOutcome;
+  /** What is at session `id`'s path, read whole, for one load or listing of it. */
+  private loadFile;
+  /**
+   * The record this instance itself last wrote or holds, offered only while the file on disk is
+   * still exactly those bytes. It is what a writer needs when `load` says `locked` for a session it
+   * is running: the keys that read it back are locked, the copy it holds is not. `undefined` for
+   * a session this instance never held, or whose file has changed since.
+   */
+  loadHeld(id: string): TSessionLoadOutcome | undefined;
+  /** The sealed record of `id` as a token for another store over these files (see {@link StoredSessionRecords.exportHeld}). */
+  exportHeld(id: string, options?: ISessionExportOptions): string | undefined;
+  /** Holds the record a token from another store's `exportHeld` carries (see {@link StoredSessionRecords.importHeld}). */
+  importHeld(id: string, token: string): void;
+  /**
+   * Every session this directory holds, each with what the store concluded about it.
+   *
+   * Unreadable entries are REPORTED rather than skipped. A store that distinguishes four outcomes on
+   * `load` and then hides two of them from the surface a person browses has moved the defect rather
+   * than removed it: the difference a user experiences is between "my session vanished" and "my
+   * session needs a different build".
+   *
+   * The one exception is a sealed session this process cannot open: there is no record to describe
+   * (no title, no time, no workspace), so it is not an entry, and {@link scan} is how a surface
+   * still says that some sessions are there.
+   */
+  list(): readonly ISessionListEntry[];
+  /**
+   * The listing and how many sealed sessions it left out because they cannot be opened right now,
+   * from one read of each file, counted by why: locked keys, or no keys here at all. A record that
+   * cannot be read has nothing to show, so the counts are what keep those sessions from looking gone.
+   */
+  scan(): ISessionStoreScan;
+  private readAll;
+  /**
+   * The outcome for one directory entry, without letting a bad NAME throw out of `list`.
+   *
+   * `load` validates the id, because an id reaching it is a caller's value and a malformed one is a
+   * bug or an attack (SEC-006). A name read out of the directory is neither: the store did not
+   * choose it, and one file it cannot use as an id must not take the whole listing down with it.
+   * Routing `list` through `load` made exactly that happen — a single `my session.json` in the
+   * sessions directory threw, and the resume picker went with it.
+   *
+   * Reporting it is the same answer `list` gives for every other file it cannot read, which is the
+   * property this work exists to establish.
+   */
+  private outcomeForListedId;
+  /**
+   * Delete a session by its ID, holding its writer marker: refused while another writer holds it.
+   * No-ops silently if the session does not exist.
+   */
+  delete(id: string): void;
+}
+//#endregion
+//#region src/node-session-log-sink.d.ts
+/** Explicit host-filesystem sink for JSONL logs and their content-addressed sidecars. */
+declare class NodeSessionLogSink implements ISessionLogSink, IExternalPayloadSink {
+  private readonly logDirectory;
+  readonly externalPayloadSink: IExternalPayloadSink;
+  private readonly enabled;
+  private readonly lines;
+  private readonly payloads;
+  /**
+   * @param options `sealing` (required): `{ sealer }` seals every append (one sealed line per call)
+   *   and every sidecar; `'plain'` writes plain lines and content-addressed sidecars.
+   */
+  constructor(logDirectory: string, options: ISessionStoreOptions);
+  append(sessionId: string, text: string): void;
+  writeJson(sessionId: string, sha256: string, serialized: string): IExternalPayloadReference;
+  private writePayload;
+}
+//#endregion
+//#region src/stored-append-lines.d.ts
+/** The kinds of artifact an append store's lines are sealed as. */
+type TAppendLineKind = Extract<TArtifactKind, 'prompt-history-line' | 'session-log-line'>;
+/** One physical line of an append store, as this process can read it. Never carries key material. */
+type TStoredLine =
+/** A plain line (one element, verbatim), or a sealed record opened to the lines it holds. */
+{
+  readonly kind: 'lines';
+  readonly lines: readonly string[];
+} |
+/** Sealed and intact as far as anyone can tell; `reason` says whether an unlock here would read it. */
+{
+  readonly kind: 'locked';
+  readonly reason: TArtifactLockedReason;
+} |
+/** Sealed in this build's framing and it does not open for this owner: damaged, torn, or sealed with other keys. */
+{
+  readonly kind: 'does-not-open';
+} |
+/** Sealed in a framing version a newer build writes: never opened, never counted as damage. */
+{
+  readonly kind: 'newer-format';
+};
+/** How one append store keeps its lines: sealed as `kind`, bound to the owner id each call names. */
+declare class StoredLines {
+  #private;
+  constructor(sealing: TArtifactSealing, kind: TAppendLineKind);
+  /**
+   * What to append for `text` — one or more `\n`-terminated lines, exactly what a plain store
+   * appends in that call. Plain: `text` itself. Sealing: one sealed line with a newline before and
+   * after it. Throws whatever sealing throws; it never falls back to plaintext.
+   */
+  encode(text: string, ownerId: string): string;
+  /** One physical line (no `\n` in it), as this process can read it. Never throws. */
+  decode(line: string, ownerId: string): TStoredLine;
+  /**
+   * Strict: the plain-equivalent text of a whole store's `text`, for decoders that fail on any bad
+   * line (see {@link openedText}). A failure of the sealer that is neither `ArtifactLockedError` nor
+   * `ArtifactCorruptError` is a defect (a refused context, a misused key), not a damaged line, so it
+   * is thrown as it was rather than reported as corruption.
+   */
+  openText(text: string, ownerId: string): string;
+}
+/**
+ * The physical lines of a store's text. An UNTERMINATED final fragment with sealed framing, or so
+ * short that it is still only the start of it (`RSL` and a version digit, cut anywhere), is left
+ * out: every sealed append ends with a newline, so such a fragment is an append in progress (or one
+ * whose writer died), not a record. A plain fragment is kept as it is.
+ */
+declare function splitStoredLines(text: string): string[];
+/** One sidecar a sink is asked to write. */
+interface IStoredPayloadWrite {
+  readonly relativePath: string;
+  readonly data: string | Uint8Array;
+  /**
+   * The name is the content's own digest, so a file already at it holds these exact bytes and need
+   * not be written again. A sealed sidecar's name is random: a file already there is not this one.
+   */
+  readonly contentAddressed: boolean;
+}
+/**
+ * How a session-log sink places externalized JSON values beside its log, and how a source opens what
+ * it reads back. Plain: the content-addressed `<id>.payloads/<sha256>.json`. Sealing:
+ * `<id>.payloads/<22 random base64url characters>.sealed`, holding the payload sealed as
+ * `session-log-payload` for the session, written once per payload per instance.
+ */
+declare class StoredPayloads {
+  #private;
+  constructor(sealing: TArtifactSealing);
+  /**
+   * The reference a log line carries for `serialized`, after `write` has put its sidecar in place.
+   * `write` is called at most once; a sealed name is remembered only once `write` returned, so a
+   * failed write is attempted again for the next reference to the same payload.
+   */
+  place(sessionId: string, sha256: string, serialized: string, write: (target: IStoredPayloadWrite) => void): IExternalPayloadReference;
+  /** How many bytes to read for a payload whose plaintext budget is `maxBytes`. */
+  rawBudget(maxBytes: number): number;
+  /**
+   * The payload bytes in `stored` (what was read at `relativePath`), held to the plaintext budget
+   * exactly. A plain store reads every payload as bytes: only a sealed line can
+   * reference a sealed payload, and a plain reader never gets past the line. A sealing store passes
+   * plain bytes through too, so a directory written before sealing still resolves — a JSON payload
+   * never starts with the sealed magic — and opens sealed bytes bound to `ownerId`:
+   * `ArtifactLockedError` while they cannot be opened here, and `PAYLOAD_UNREADABLE` when they do
+   * not open, were sealed by a newer build, or have no owner to open them for. Any other failure of
+   * the sealer is a defect, thrown as it was. The caller then checks the result against the
+   * reference's digest and length.
+   */
+  open(stored: Uint8Array, maxBytes: number, ownerId: string | undefined, relativePath: string): Uint8Array;
+}
+/** What a stored sidecar is to a migration that seals what is still plain in place (#3679). */
+type TStoredPayloadMigrationState = 'plain' | 'sealed' | 'does-not-open' | 'newer-format';
+/**
+ * Where a sidecar of session `ownerId` stands: decided by whether it opens for that session, never by
+ * framing alone. With the keys locked it throws `ArtifactLockedError`.
+ */
+declare function storedPayloadMigrationState(stored: Uint8Array, ownerId: string, sealer: IArtifactSealer): TStoredPayloadMigrationState;
+/**
+ * A plain sidecar's bytes sealed for session `ownerId`, to be put back under the SAME name: a source
+ * opens sealed bytes whatever the name ({@link StoredPayloads.open}), and the digest and length every
+ * reference — nested ones included — checks are the plaintext's, so no reference changes.
+ */
+declare function sealStoredPayloadBytes(plain: Uint8Array, ownerId: string, sealer: IArtifactSealer): Uint8Array;
+/** The plain records a session log's text holds, as a migration would seal them. */
+declare function countPlainSessionLogLines(text: string): number;
+/** A whole session log's text with every plain line sealed, for a store that replaces the file whole. */
+interface ISealedSessionLogText {
+  readonly text: string;
+  readonly sealedLines: number;
+  readonly carriedLines: number;
+}
+/**
+ * `text` (a whole log, nothing appending to it) with every plain record sealed for session
+ * `ownerId` as {@link SessionLogLineSealer} seals it. An unfinished sealed append at the end, which
+ * no reader shows, is dropped; an unfinished plain line is a record, and is sealed.
+ */
+declare function sealSessionLogText(text: string, ownerId: string, sealer: IArtifactSealer): ISealedSessionLogText;
+//#endregion
+//#region src/session-log-sources.d.ts
+interface INodeExternalPayloadSourceOptions extends ISessionStoreOptions {
+  /**
+   * The session the payloads belong to, which a sealed one is bound to. Left out, it is the session
+   * whose `<id>.payloads` directory the reference names, the layout every sink writes.
+   */
+  readonly ownerId?: string;
+}
+/** Explicit host-filesystem adapter. A file path is never accepted by the neutral parser itself. */
+declare class NodeExternalPayloadSource implements IExternalPayloadSource {
+  private readonly baseDirectory;
+  private readonly payloads;
+  private readonly ownerId;
+  /**
+   * @param options `sealing` (required): `{ sealer }` opens sealed payloads (plain ones still
+   *   resolve); `'plain'` meets a sealed payload as one no key in this process opens.
+   */
+  constructor(baseDirectory: string, options: INodeExternalPayloadSourceOptions);
+  readBytes(relativePath: string, maxBytes: number): Uint8Array | undefined;
+  /** The bytes at the path, within the raw budget a sealed payload of `maxBytes` needs. */
+  private readStored;
+}
+/**
+ * Explicit host-filesystem adapter for a JSONL session log. The log's owner — the session id its
+ * sealed lines and payloads are bound to — is the file's stem, `<id>.jsonl`, the name every sink
+ * writes; a sealed log copied under another session's name does not open as that session's.
+ */
+declare class NodeSessionLogSource implements ISessionLogSource {
+  private readonly logFile;
+  readonly externalPayloadSource: IExternalPayloadSource;
+  private readonly lines;
+  private readonly ownerId;
+  /**
+   * @param options `sealing` (required): `{ sealer }` opens sealed lines and payloads (plain ones
+   *   still read); `'plain'` meets a sealed line as one no key in this process opens.
+   */
+  constructor(logFile: string, options: ISessionStoreOptions);
+  /** Strict: the plain-equivalent text, failing on the first line it cannot read (see {@link StoredLines.openText}). */
+  readText(): string | undefined;
+  /** Tolerant: every physical line in file order, each as this process can read it; `undefined` when there is no log. */
+  readStoredLines(): readonly TStoredLine[] | undefined;
+}
+//#endregion
+//#region src/append-file-rewrite.d.ts
+/** Why a file was left as it is. */
+type TAppendFileRefusal =
+/** A symbolic link, a directory, or anything else that is not a regular file. */
+'not-a-regular-file' |
+/** A regular file with another name too, which a rename would leave holding the old bytes. */
+'hard-linked';
+/** A catch-up that failed after the rename: what of the replaced file it never carried over. */
+interface IAppendFileCatchUpFailure {
+  /** Bytes of the replaced file past the last line carried over (at most what was lost). */
+  readonly unreadBytes: number;
+  /** The failure's name; never its message, which may quote what was being rewritten. */
+  readonly reason: string;
+}
+//#endregion
+//#region src/session-log-migration.d.ts
+interface IMigrateSessionLogsOptions {
+  /** Seals what is plain and opens what is sealed; the keys must be unlocked. */
+  readonly sealer: IArtifactSealer;
+  /** `false` plans: everything is read and counted exactly as a run would, and nothing is written. */
+  readonly apply: boolean;
+  /** An ancestor of the directory the host also owns, tightened along with it (SEC-020). */
+  readonly ownedRoot?: string;
+  /** Runs before each sidecar replace and each log replace; throwing stops the migration there. */
+  readonly beforeCommit?: () => void;
+  /** Waits between catch-up passes over a replaced log; defaults to a short timer. */
+  readonly pause?: () => Promise<void>;
+  /**
+   * Also removes the temp files crashed writes left; leave it off while another writer may be running.
+   * Off, they are still counted in `staleTemporaries` and left where they are.
+   */
+  readonly sweepTemporaries?: boolean;
+  /**
+   * When the migration started, in milliseconds by the filesystem's clock (its marker's time): a temp
+   * file is also judged stale against it, so one in a directory nothing changed in since is found.
+   */
+  readonly migrationStartedAt?: number;
+}
+/** A log whose catch-up failed after its rename, and what of the replaced file it left unread. */
+interface ISessionLogCatchUpFailure extends IAppendFileCatchUpFailure {
+  readonly path: string;
+}
+/** What a migration of one directory's logs did, or (planning) would do. */
+interface ISessionLogMigration {
+  /** Logs that held plain lines: sealed (or to seal). */
+  readonly logs: number;
+  /** The plain lines among them. */
+  readonly lines: number;
+  /** Plain sidecars sealed in place (or to seal). */
+  readonly payloads: number;
+  /** Logs and sidecars that hold no plaintext. */
+  readonly alreadySealed: number;
+  /** Sealed sidecars that do not open for their session, or that a newer build sealed: left as they are. */
+  readonly unopenable: readonly string[];
+  /**
+   * Links, entries that are not regular, logs and sidecars with another hard link, names that are not
+   * session ids.
+   */
+  readonly refused: readonly string[];
+  /**
+   * Logs and sidecars that changed while being sealed, that plaintext reached meanwhile, or that
+   * another rewrite replaced first.
+   */
+  readonly changed: readonly string[];
+  /** Logs sealed whose catch-up failed: lines appended to the replaced file meanwhile are lost. */
+  readonly catchUpFailed: readonly ISessionLogCatchUpFailure[];
+  /** Temp files crashed writes left: removed (or to remove) with `sweepTemporaries`, else left. */
+  readonly staleTemporaries: number;
+}
+/** Seals the plain logs and sidecars of `directory` as the module documentation describes. */
+declare function migrateSessionLogDirectory(directory: string, options: IMigrateSessionLogsOptions): Promise<ISessionLogMigration>;
+//#endregion
+//#region src/session-record-migration.d.ts
+interface IMigrateSessionRecordsOptions {
+  /** Seals what is plain and opens what is sealed; the keys must be unlocked. */
+  readonly sealer: IArtifactSealer;
+  /** `false` plans: everything is read and counted exactly as a run would, and nothing is written. */
+  readonly apply: boolean;
+  /**
+   * Runs before each replace, after the sealed record is written and flushed beside it; throwing
+   * stops the migration there with that record as it was.
+   */
+  readonly beforeCommit?: () => void;
+  /**
+   * Also removes the temp files crashed writes left; leave it off while another writer may be running.
+   * Off, they are still counted in `staleTemporaries` and left where they are.
+   */
+  readonly sweepTemporaries?: boolean;
+  /**
+   * When the migration started, in milliseconds by the filesystem's clock (its marker's time): a temp
+   * file is also judged stale against it, so one in a directory nothing changed in since is found.
+   */
+  readonly migrationStartedAt?: number;
+}
+/** What a migration of a store's records did, or (planning) would do. */
+interface ISessionRecordMigration {
+  /** Plain records sealed (or to seal). */
+  readonly sealed: number;
+  /** Records that already open sealed. */
+  readonly alreadySealed: number;
+  /** Sealed records that do not open here, or that a newer build sealed: left as they are. */
+  readonly unopenable: readonly string[];
+  /** `.json` files whose name is not a session id: left as they are. */
+  readonly unsafeNames: readonly string[];
+  /**
+   * `.json` entries that are links, not regular files, or regular files with another hard link:
+   * never followed or replaced, left as they are.
+   */
+  readonly refused: readonly string[];
+  /** Records that changed while being sealed: left as they are, for the next run. */
+  readonly changed: readonly string[];
+  /**
+   * The ids of records open in another process — their writer marker stands for an owner not
+   * provably gone — left as they are, for a run after it has closed.
+   */
+  readonly held: readonly string[];
+  /** Temp files crashed writes left with a record in them: removed (or to remove) with `sweepTemporaries`, else left. */
+  readonly staleTemporaries: number;
+  /**
+   * Each record this run sealed, by its id and the SHA-256 of the sealed bytes it put in place — the
+   * bytes the owner may then vouch for (`ISessionAuthorship.adopt`), and no others.
+   * Empty when planning.
+   */
+  readonly sealedRecords: readonly ISealedSessionRecord[];
+}
+/** One record a migration sealed: its id and the SHA-256 (lowercase hex) of the bytes it wrote. */
+interface ISealedSessionRecord {
+  readonly id: string;
+  readonly digest: string;
+}
+/** Seals the plain records of the store at `baseDir` as the module documentation describes. */
+declare function migrateNodeSessionStore(baseDir: string, options: IMigrateSessionRecordsOptions): ISessionRecordMigration;
+/**
+ * The working directories the store's records name — a valid record's `cwd`, and the `cwd` a corrupt
+ * or unsupported one still carries — opened with `sealer`, distinct, in file order. Writes nothing;
+ * a record that does not open names none.
+ */
+declare function readSessionStoreWorkingDirectories(baseDir: string, options: {
+  readonly sealer: IArtifactSealer;
+}): readonly string[];
+//#endregion
+//#region src/tool-result-spill-store.d.ts
+type TToolResultSpillErrorCode = 'invalid-options' | 'unsafe-root' | 'write-failed' | 'missing' | 'expired' | 'invalid-reference' | 'read-failed' | 'cleanup-failed' | 'closed';
+declare class ToolResultSpillError extends Error {
+  readonly code: TToolResultSpillErrorCode;
+  constructor(code: TToolResultSpillErrorCode);
+}
+/**
+ * Remove the spill directories under `parent` whose recorded owner can no longer be alive (a process
+ * killed before `shutdown()` or its exit removal could run). Returns the names removed.
+ */
+declare function sweepStaleToolResultSpillDirectories(parent: string): readonly string[];
+interface INodeToolResultSpillStoreOptions {
+  /**
+   * Host-owned, owner-only parent that already exists; it is used as it is. Spilled results are
+   * conversation content, so they never go to a directory the store picks: the store's directory in
+   * the parent records its owner, is removed when the process ends without reaching `shutdown()`,
+   * and is removed after a kill by {@link sweepStaleToolResultSpillDirectories}.
+   */
+  readonly parentDirectory: string;
+  readonly retentionMs?: number;
+  readonly now?: () => number;
+  /** Receives a fixed, payload-free reason if an idle expiry timer cannot delete a file. */
+  readonly onCleanupFailure?: (reason: 'cleanup-failed') => void;
+  /**
+   * Required. `{ sealer }` keeps every result sealed on disk, bound to its reference, as
+   * `<token>.sealed`, and opens it with the same sealer to read it back; a result that does not open
+   * reads as `read-failed`. `'plain'` writes each result as it is to `<token>.txt`.
+   */
+  readonly sealing: TArtifactSealing;
+}
+/**
+ * Node host implementation of core's opaque, session-lifetime spill port. A sealing store keeps the
+ * last result it opened in memory, so paging through a large result opens it once.
+ */
+declare class NodeToolResultSpillStore implements IToolResultSpillStore {
+  private readonly directory;
+  private readonly retentionMs;
+  private readonly now;
+  private readonly onCleanupFailure?;
+  private readonly sealer;
+  private readonly entries;
+  /** The result a sealing store opened last; forgotten with its entry. */
+  private opened?;
+  private expiryTimer?;
+  private cancelExitRemoval?;
+  private closed;
+  constructor(options: INodeToolResultSpillStoreOptions);
+  private assertRoot;
+  private scheduleExpiry;
+  write(content: string): Promise<{
+    readonly reference: string;
+  }>;
+  read(reference: string): Promise<string>;
+  /** What goes on disk for `content`: the text as it is, or sealed to the result's token. */
+  private storedForm;
+  /**
+   * The text a sealed result holds, held to the plaintext budget exactly. Any failure to open it —
+   * damaged, moved from another reference, sealed with other keys — is the caller's `read-failed`.
+   */
+  private openStored;
+  /**
+   * Removes a result. What a sealing store had open of it is forgotten first, so a removal that fails
+   * does not keep it in memory; a file already gone counts as removed, or one result deleted from
+   * outside would fail every later cleanup, and with it every write.
+   */
+  private removeEntry;
+  cleanupExpired(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/prompt-history-file.d.ts
+/** 64 KiB: a few hundred prompts per block — enough for the first frame, small enough to yield often. */
+declare const DEFAULT_PROMPT_HISTORY_BLOCK_BYTES: number;
+interface INodePromptHistoryFileOptions extends ISessionStoreOptions {
+  /** An ancestor of the file the host also owns, tightened along with the directory (SEC-020). */
+  readonly ownedRoot?: string;
+  /** Test seam: the read block size in bytes. */
+  readonly blockBytes?: number;
+}
+/** One line → an entry, or `undefined` when the line is not a well-formed entry. */
+declare function parsePromptHistoryLine(line: string): IPromptHistoryEntry | undefined;
+declare class NodePromptHistoryFile implements IPromptHistoryWriter, IPromptHistorySource {
+  private readonly path;
+  private readonly blockBytes;
+  private readonly ownedRoot;
+  private readonly lines;
+  /**
+   * @param options `sealing` (required): `{ sealer }` appends each entry as one sealed line and
+   *   opens sealed lines it reads (plain ones still read); `'plain'` appends plain lines and counts
+   *   a sealed line as one no key in this process opens.
+   */
+  constructor(path: string, options: INodePromptHistoryFileOptions);
+  append(entry: IPromptHistoryEntry): void;
+  /**
+   * Newest-first blocks. Only a missing file is the empty state (a fresh install, or history off);
+   * any other open or read failure is thrown so the surface renders it instead of an empty list.
+   */
+  read(options: IPromptHistoryReadOptions): AsyncIterable<IPromptHistoryBlock>;
+}
+//#endregion
+//#region src/prompt-history-compaction.d.ts
+/** Why a history was left as it is. */
+type TPromptHistoryRefusal = TAppendFileRefusal;
+interface IInspectPromptHistoryOptions {
+  /** Opens sealed lines; with the keys locked, inspecting a sealed line throws `ArtifactLockedError`. */
+  readonly sealer: IArtifactSealer;
+}
+interface ICompactPromptHistoryOptions {
+  /**
+   * Seals every entry and opens the sealed ones. Give the compaction a sealer of its own so all of
+   * its lines share one writer epoch. With the keys locked it stops with `ArtifactLockedError` and
+   * replaces nothing.
+   */
+  readonly sealer: IArtifactSealer;
+  /** An ancestor of the file the host also owns, tightened along with the directory (SEC-020). */
+  readonly ownedRoot?: string;
+  /**
+   * Runs once the new file is written and flushed, just before it replaces the history. Throwing
+   * abandons the compaction with nothing replaced and no temporary file left.
+   */
+  readonly beforeCommit?: () => void;
+  /** Waits between catch-up passes over the replaced file; defaults to a short timer. */
+  readonly pause?: () => Promise<void>;
+}
+type TPromptHistoryInspection = {
+  readonly status: 'missing';
+} | {
+  readonly status: 'refused';
+  readonly reason: TPromptHistoryRefusal;
+} | {
+  readonly status: 'present';
+  /** Physical lines that are plaintext. */
+  readonly plainLines: number;
+  /** Physical lines sealed in this build's framing that open. */
+  readonly sealedLines: number;
+  /** Physical lines that do not open here or that a newer build sealed. */
+  readonly unreadableLines: number;
+};
+type TPromptHistoryCompaction = {
+  readonly status: 'missing';
+} | {
+  readonly status: 'refused';
+  readonly reason: TPromptHistoryRefusal;
+} |
+/** Another compaction replaced the history before this one's rename; nothing was replaced. */
+{
+  readonly status: 'replaced';
+} |
+/** The history was deleted before this compaction's rename; nothing was put in its place. */
+{
+  readonly status: 'removed';
+} | {
+  readonly status: 'compacted';
+  /** Entries written sealed, one per line. */
+  readonly entries: number;
+  /** Of those, entries that were plain lines. */
+  readonly fromPlain: number;
+  /** Of those, entries appended after the snapshot and caught up from the replaced file. */
+  readonly caughtUp: number;
+  /** Lines that do not open here, or that a newer build sealed, carried over unchanged. */
+  readonly carriedOver: number;
+  /** The replaced file ended in an unfinished sealed append, which no reader shows; it was dropped. */
+  readonly droppedTail: boolean;
+  /** Plain lines in the new file afterwards: plaintext an older build appended meanwhile. */
+  readonly plainLinesAfter: number;
+  /**
+   * Set when the catch-up failed after the rename: entries appended to the replaced file from
+   * then on are not in the history (their session records hold them).
+   */
+  readonly catchUpFailed?: IAppendFileCatchUpFailure;
+};
+/** What the history holds, line by line, as {@link compactPromptHistoryFile} would find it. */
+declare function inspectPromptHistoryFile(path: string, options: IInspectPromptHistoryOptions): TPromptHistoryInspection;
+/**
+ * The distinct `project` values the history's entries name, plain or sealed, in the order first met;
+ * lines that do not open or do not parse are passed over. A history that is missing or refused names
+ * none. Writes nothing.
+ */
+declare function readPromptHistoryProjects(path: string, options: IInspectPromptHistoryOptions): readonly string[];
+/**
+ * Compacts the history at `path` as the module documentation describes. Rerunning it gives the same
+ * entries under a new writer epoch.
+ */
+declare function compactPromptHistoryFile(path: string, options: ICompactPromptHistoryOptions): Promise<TPromptHistoryCompaction>;
+//#endregion
+//#region src/workspace-path-resolver.d.ts
+declare function createNodeWorkspacePathResolver(cwd: string): TResolveInWorkspace;
+//#endregion
+//#region src/process-exit-flush.d.ts
+/**
+ * The Node host's answer to `IFileSessionLoggerOptions.registerExitFlush`: run `flush` when the
+ * process is about to end. `exit` listeners may only do synchronous work, which is what a logger's
+ * flush does. Pass this very function to every logger — the logger registers once per distinct
+ * function, so one process gets one listener however many loggers it creates.
+ */
+declare function registerProcessExitFlush(flush: () => void): void;
+//#endregion
+export { DEFAULT_PROMPT_HISTORY_BLOCK_BYTES, type IAppendFileCatchUpFailure, type ICompactPromptHistoryOptions, type IEncodedSession, type IInspectPromptHistoryOptions, type IMigrateSessionLogsOptions, type IMigrateSessionRecordsOptions, type INodeExternalPayloadSourceOptions, type INodePromptHistoryFileOptions, type INodeSessionStoreOptions, type INodeToolResultSpillStoreOptions, type ISealedSessionLogText, type ISealedSessionRecord, type ISessionLogCatchUpFailure, type ISessionLogMigration, type ISessionRecordMigration, type ISessionStoreOptions, type IStoredPayloadWrite, type IStoredSessionFiles, NodeExternalPayloadSource, NodePromptHistoryFile, NodeSessionLogSink, NodeSessionLogSource, NodeSessionStore, NodeToolResultSpillStore, SESSION_CLAIMS_DIRECTORY, StoredLines, StoredPayloads, StoredSessionRecords, type TAppendLineKind, type TPromptHistoryCompaction, type TPromptHistoryInspection, type TPromptHistoryRefusal, type TStoredLine, type TStoredPayloadMigrationState, type TStoredSessionFile, type TStoredSessionMigrationState, type TToolResultSpillErrorCode, ToolResultSpillError, assertSessionSealing, classifyStoredSessionBytes, compactPromptHistoryFile, countPlainSessionLogLines, createNodeWorkspacePathResolver, createProcessOperationLock, inspectPromptHistoryFile, isPlainSessionRecordOf, migrateNodeSessionStore, migrateSessionLogDirectory, parsePromptHistoryLine, readPromptHistoryProjects, readSessionStoreWorkingDirectories, registerProcessExitFlush, sealSessionLogText, sealStoredPayloadBytes, sealStoredSessionBytes, sessionSealingOf, splitStoredLines, storedPayloadMigrationState, storedSessionMigrationState, sweepStaleToolResultSpillDirectories };
+//# sourceMappingURL=node.d.ts.map