@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/pool-outbox.js

@@ -0,0 +1,313 @@
+// The outbox (`oars pool deposit` and `oars pool outbox`): every batch that may leave this machine is first written here, as canonical JSON lines, and `deposit` stops. Nothing in this file
+// looks inside a batch except to name its fields, at every depth, for `--explain`; what a batch holds is the projection's business.
+import { createHash } from 'node:crypto';
+import { appendFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SKELETON_FORMAT, VOCAB_VERSION } from './pool-wire.js';
+import { contentHash } from './read.js';
+/** What `JSON.stringify` writes for a value, or undefined for one JSON cannot hold (the lib types call this a string always). */
+const encoded = (value) => JSON.stringify(value);
+/**
+ * JSON with keys sorted at every depth, so two writers of one batch write the same bytes. The sorted entries are written out directly: rebuilding an object would put an integer-like key such as `10` before `9` whatever the sort said.
+ * A value JSON cannot hold is left out of an object and written as null in an array, as `JSON.stringify` does.
+ */
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => encoded(entry) !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : 1));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`).join(',')}}`;
+    }
+    return encoded(value) ?? 'null';
+};
+/** The batch as one canonical JSON line: sorted keys, no optional whitespace, UTF-8 when written, and a newline at the end. These are the bytes that are hashed, printed, and sent. */
+export const canonicalBytes = (batch) => `${canonical(batch)}\n`;
+/** The most bytes one request of a deposit carries. The pool refuses a request past 1 MiB, so a batch past this goes in parts, each of them under that cap. */
+export const PART_BYTES = 512 * 1024;
+/**
+ * The batch cut into parts of at most `limit` UTF-8 bytes, never inside a character, so the parts join back to exactly the bytes that were hashed. A batch within the limit is one part.
+ */
+export const partsOf = (bytes, limit = PART_BYTES) => {
+    const parts = [];
+    let part = '';
+    let size = 0;
+    for (const character of bytes) {
+        const width = Buffer.byteLength(character, 'utf8');
+        if (size + width > limit) {
+            parts.push(part);
+            part = '';
+            size = 0;
+        }
+        part += character;
+        size += width;
+    }
+    parts.push(part);
+    return parts;
+};
+export const batchHash = (bytes) => createHash('sha256').update(Buffer.from(bytes, 'utf8')).digest('hex');
+/**
+ * `oars pool outbox --explain`: one row for each field name a batch holds, at any depth, saying what admits its values. A field with no row fails the command, so a field added to the batch adds its row here.
+ * A name that sits at more than one depth (`status`, `harness`, `frame`) has one row that reads true at each.
+ */
+export const FIELD_ROWS = {
+    action: 'The canonical action of a step, one of a closed list this client holds; never the harness tool text.',
+    agentType: 'The type of the subagent whose run holds a step: a built-in type of the harness, else the word custom; null on a step of the main run.',
+    allocated: 'Whether the step\'s token figure was divided among the calls of one model response (true) rather than measured for the call alone; absent when measured. A flag only, never a count.',
+    argClass: 'The kinds of value a call\'s arguments held, a sorted set of a closed list: path, url, pattern, command, number, flag, text, and none; never a value.',
+    cacheRead: 'A bucket of the tokens read from the cache in a prompt, a number, or null when the source never recorded it.',
+    cacheWrite: 'A bucket of the tokens written to the cache in a prompt, a number, or null when the source never recorded it.',
+    change: 'How far a delta moved, a signed bucket of its metric (a lower bound) in a number from -7 to 7 for calls per session and from -11 to 11 for thinking tokens; never the exact count.',
+    cls: 'The class of a prompt, one of a closed list of eight, computed from the kinds of tools it used; never its words.',
+    day: 'The UTC calendar day of the session as YYYY-MM-DD, or null; never a time of day.',
+    deltaKind: 'How a delta changed what the client ran: added, removed, or changed, one of a closed list the field allows; never a value.',
+    deltas: 'The changes the client found between its own before and after windows, each sent once with the session that filled the after window: a kind, a field, a name, a registry, a metric, and a bucketed change; never a session id, a root, a date, or an exact value.',
+    durationMs: 'The time of one tool call in milliseconds, exact, a number or null.',
+    effort: 'The effort level the model ran at, only when it is a public one; else the literal placeholder.',
+    errorCode: 'Why a tool call failed, one class of a closed list: an exit class (0, 1, 2, 126, 127, signal), an HTTP status class, a harness class (user-rejected, interrupted, permission-denied, input-validation, tool-use-error, timeout), or other; null on a call that did not fail or whose harness records no class. Never result text.',
+    editFollowed: 'Whether one of the calls that followed a failed call wrote a file, true or false: what followed, never that the failure was fixed.',
+    errors: 'A bucket of how many tool calls failed in a prompt, a number.',
+    explore: 'A bucket of how many steps of a prompt only looked (read a file, searched files, searched the web, or fetched a page), a number or null; never the exact count.',
+    field: 'What a delta is about, one of plugin, package, permissionMode, and effort: the field alone, never its value.',
+    flags: 'The flags of a shell command, each a flag name, never its value: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. Capture still drops a subcommand or flag off the pinned vocabulary of its program, so a real session sends no off-list subcommand (null) and no off-list flag; a subcommand or flag the vocabulary lists goes as its name. A multi-letter single-dash flag no public list holds (`-race`) is dropped.',
+    fieldsVersion: 'The version of the field list this client builds a batch from: a constant of this client, never a value from a session.',
+    format: 'The skeleton format number: a constant of this client, never a value from a session.',
+    filled: 'Whether the harness recorded a setup or a tool funnel for the session, true or false; false means the lists beside it are empty because nothing was recorded, not because no tool was in reach.',
+    frame: 'Where a session ran: the harness and its version, the model, the effort, the day, the platform, the shell, and the stack, each checked against its closed list, and the reach of the session (see `reach`). On a step it is a number, the position of the frame its call ran in, in the transcript list of frames.',
+    edges: 'The edges arriving at a step, each a kind and the position of the step it names, in the same transcript or, for a spawned edge, in the transcript that spawned this one; absent when none arrive.',
+    frames: 'The distinct frames a transcript\'s steps ran in, each as a frame above with the reach of the session; a step names one by position.',
+    frameworks: 'The frameworks of the project, each from a closed public list; never a path or a name of yours.',
+    harness: 'Which harness wrote the session, one of a closed list.',
+    harnessVersion: 'The harness version: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. A transcript or prompt frame carries the value capture closed it to (the public name, else `<literal>`), sent as it is; the version of a call, which capture keeps as its line names it, goes as the string after the gate.',
+    host: 'The host of a web fetch or search, the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters; null when the step names no host. Capture keeps the host as the address names it, without credentials, path, or query. The pool replaces a host with a keyed hash on arrival and serves it only once enough accounts report it.',
+    hour: 'The UTC hour of day, 0 to 23, beside the day; never a minute, a second, or an offset.',
+    id: "A hash the client computes per account from the account and the session, so a redeposit replaces and two accounts' sessions cannot be joined. Never the session id.",
+    identity: 'What a step called: a shell program with its subcommand and flags, an MCP server and tool, a skill, or a web host, each a name after redaction or `private`; null for an action with none.',
+    input: 'A bucket of the input tokens in a prompt, a number, or null when the source never recorded it.',
+    kind: 'How an edge came about, one of a closed list: next, spawned, retried, or after-error.',
+    keys: 'The input key names of a call, sorted: a public tool\'s from its published list and any other tool\'s only when each passes the name gate; none for a tool that went as private. Names only, never a value.',
+    keysDropped: 'A bucket of the key names of a call that were not sent, off a public tool\'s list or kept private by the gate, a number; never the names.',
+    intervention: 'Whether a human stepped in after a prompt\'s work and how, one of a closed list: none, after-error (the prompt\'s last call failed), redo (the next prompt edited the same file), revert (the next prompt undid the edit), user-stop (the human rejected a call or interrupted the turn), or unknown; absent when the prompt predates the signal. An outcome row, not a grade; never the next prompt\'s words.',
+    language: 'A programming language of the project, from a closed public list, or other for any language off the list, beside its share bucket.',
+    languageShare: 'How much of the files a session touched are in one language, one of four buckets: none, under 10 percent, 10 up to 50, or 50 and over; never a count of files.',
+    languageShares: 'The share bucket of each language of the project whose share is known; a language with no share is in the languages list alone.',
+    languages: 'The programming languages of the project, each from a closed public list.',
+    leaves: 'How many lines of a transcript its root covers, a count.',
+    merkleRoot: 'The Merkle root of a transcript: a SHA-256 over the hashes of its lines, one root for each transcript, the main one first; never a line.',
+    metric: 'What a delta measures, calls per session or thinking tokens, one of a closed list the field fixes.',
+    model: 'The model name: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. A transcript or prompt frame carries the value capture closed it to (the public name, else `<literal>`), sent as it is; the model of a call, which capture keeps as its line names it, goes as the string after the gate.',
+    ms: 'A bucket of the milliseconds a step took (a lower bound), a number or null; never the exact time.',
+    name: 'The name of a package a shell command pulled or a delta removed, as capture kept it: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. A plugin in a delta is always private, and null when a delta names its field alone.',
+    native: 'The name the harness gave the tool: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters.',
+    next: 'The actions of up to the next 5 calls of the same prompt after a failed call, each one of the closed list of canonical actions: what followed, never a fix; no command, path, or text.',
+    output: 'A bucket of the output tokens in a prompt, a number, or null when the source never recorded it.',
+    parent: 'The position of the call that spawned this step, in the tools of the transcript that spawnedIn names, a number, or null.',
+    platform: 'The operating system family, one of a closed list.',
+    program: 'The program a shell command ran, its basename only: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters.',
+    prompt: 'Which prompt of the batch a tool call follows, a position in this batch, or null.',
+    prompts: 'The prompts of a transcript: each a class, bucketed counts and tokens, and a frame; never their words.',
+    pulls: 'The packages a shell command pulled from a registry: the registry, the public package name, and its version.',
+    recoveryCalls: 'For a failed call, what followed it: the actions of up to its next 5 calls and whether one wrote a file. Absent on a call that did not fail; never a signature or text.',
+    registry: 'Which registry a pull or a removed package came from, one of a closed list; null for a delta whose name is private or absent.',
+    remainingTokens: 'A bucket of the tokens the run spent after a step (a lower bound), a number, or null when steps follow and none reported tokens: the bucket of the exact sum, with the subagent runs a main-run step spawned later in the session.',
+    server: 'The MCP server a call went to: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters.',
+    shell: 'The shell a command ran in, one of a closed list, or null.',
+    side: 'Whether a tool call ran as a side call, true or false.',
+    spawnedIn: 'The position, among the transcripts of the batch, of the transcript that spawned this one, a number; null for the main run and for a subagent whose spawner the batch does not hold.',
+    size: 'A size class of the repository, one of a closed list, or null; never a count of files.',
+    mcp: 'The MCP servers in reach of a session (offered, loaded, or called), each the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters, sorted; never a tool, an argument, or a path.',
+    orgSize: 'How many people the operator\'s organization has, one of a closed list of bands or unknown; set by the operator on this machine, never looked up.',
+    plugins: 'The plugins in reach of a session, each the word private, since no plugin list is pinned; their number, never their names.',
+    reach: 'The MCP servers, skills, and plugins in reach of a session, and whether the harness recorded them; every name is the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters (a plugin is always private).',
+    repoKey: "A hash of the repository salted with this store's salt: one store's sessions in one repository share it; one account on two machines gets two keys until the account salt lands. 16 hex characters; never a path, a remote, or a name.",
+    repoVisibility: 'Whether the repository is public or private, or unknown; set by the operator on this machine, never looked up.',
+    skill: 'The skill a step ran (a skill-run name capture keeps as it is after redaction), or the skill whose run the step\'s call sat in, the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. Absent on a step outside a skill\'s run.',
+    skills: 'The skills in reach of a session (called in it), each the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters, sorted.',
+    stack: 'The languages, frameworks, and size class of the project.',
+    status: 'Whether a tool call or a step succeeded: ok, error, or none.',
+    steps: 'The steps of a tool call, each an action in closed vocabulary with its bucketed cost and spawner.',
+    team: 'Whether the repository\'s local git log shows one commit author or several, or unknown; a count taken on this machine and dropped, never an author.',
+    sub: 'The subcommand of a shell program, or null: the name as it is after redaction; `private` when redaction changes it, an exclusion term matches it, it is not a name, or it is over 128 characters. Capture still drops a subcommand or flag off the pinned vocabulary of its program, so a real session sends no off-list subcommand (null) and no off-list flag; a subcommand or flag the vocabulary lists goes as its name.',
+    thinking: 'A bucket of the thinking tokens in a prompt, a number, or null when the source never recorded it.',
+    target: 'The position of the step an edge names, a number counted over the steps of one transcript in call order.',
+    targetClass: 'The class of the path a call touched, one of a closed list: source, test, config, doc, lockfile, generated, data, none, other; never the path or its name.',
+    timingPrint: 'A hash of the call durations of the main transcript in the order they ran, or null under 50 timed calls; the calls of a subagent are not in it.',
+    tokens: 'A bucket of tokens (a lower bound of the count), a number or null; a step holds one, never the exact count.',
+    tool: 'The tool of an MCP call: the name as it is after redaction, beside a server that is not private and in a harness whose spelling delimits the server; else the literal placeholder.',
+    tools: 'The tool calls of a transcript, each a status and duration and its steps, in the order they ran; never their targets or arguments.',
+    transcripts: 'The main transcript, then each subagent: its frame, prompts, and tool calls, every value checked against its field\'s list or the name shape before the batch is built.',
+    usage: 'The tokens of a prompt as buckets (lower bounds): input, cache write, cache read, output, and thinking.',
+    usageResponses: 'A bucket of the responses of a prompt that reported usage, what a partial usage sum covers; left out only for a record captured before the coverage existed (capture version 20).',
+    version: 'The version of a pulled package, only when it is a registry version; else the literal placeholder or null.',
+    vocabVersion: 'The version of the closed vocabulary this client built the batch under: a constant of this client, never a value from a session.',
+    wallSec: 'A bucket of the seconds a prompt took, or null.',
+};
+/**
+ * Every field name a batch holds, at any depth, sorted: the rows above. A batch is filed under this list, the skeleton format, and `VOCAB_VERSION`, so one built under an older list, form, or vocabulary is never printed or sent.
+ * A test holds this list equal to the fields of a real batch, so a field the sample holds without its row fails there.
+ */
+export const BATCH_FIELDS = Object.keys(FIELD_ROWS).sort();
+const fieldsStamp = (fields, format) => createHash('sha256').update(`${String(format)}:${fields.join(',')}`).digest('hex').slice(0, 8);
+/** The folder name of the batches this client builds now. A folder of any other name holds batches built under an older vocabulary, field list, or skeleton format. */
+export const currentStamp = (fields = BATCH_FIELDS, format = SKELETON_FORMAT) => `v${VOCAB_VERSION}-${fieldsStamp(fields, format)}`;
+/** One server's outbox: batches are per server, since a printed batch carries that server's credential. */
+export const outboxFolder = (storeDir, server) => join(storeDir, 'pool-outbox', contentHash(server));
+const BATCH_FILE = /^([0-9a-f]{16})\.([0-9a-f]{64})\.jsonl$/;
+/** Writes one session's batch under the current stamp. A session has one batch: an older batch of it is removed, and an identical one is written again, so an edited file is restored. */
+export const writeBatch = async (outbox, key, batch, stamp = currentStamp()) => {
+    const bytes = canonicalBytes(batch);
+    const hash = batchHash(bytes);
+    const folder = join(outbox, stamp);
+    await mkdir(folder, { recursive: true });
+    for (const name of await readdir(folder)) {
+        const found = BATCH_FILE.exec(name);
+        if (found?.[1] === key && found[2] !== hash)
+            await rm(join(folder, name), { force: true });
+    }
+    await writeFile(join(folder, `${key}.${hash}.jsonl`), bytes, 'utf8');
+    return { hash, folder, bytes: Buffer.byteLength(bytes) };
+};
+export const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+/** A path that is missing, or has a file where a folder should be, holds nothing. */
+const isAbsent = (error) => isMissing(error) || (error instanceof Error && 'code' in error && error.code === 'ENOTDIR');
+/** The names in a folder; a folder that does not exist yet holds none. */
+const namesIn = async (folder) => {
+    try {
+        return (await readdir(folder)).sort();
+    }
+    catch (error) {
+        if (isAbsent(error))
+            return [];
+        throw error;
+    }
+};
+/** Removes every batch under this stamp whose session is not in `kept`, and returns how many went. A session that fails a gate, leaves the allowlist, or is gone from the store never enters the outbox, so an earlier pass's batch of it cannot stay. */
+export const removeBatchesExcept = async (outbox, kept, stamp = currentStamp(), only) => {
+    const folder = join(outbox, stamp);
+    let removed = 0;
+    for (const name of await namesIn(folder)) {
+        const found = BATCH_FILE.exec(name);
+        if (found !== null && !kept.has(found[1] ?? '') && (only === undefined || found[1] === only)) {
+            await rm(join(folder, name), { force: true });
+            removed += 1;
+        }
+    }
+    return removed;
+};
+/** Removes the batch of one session, if it has one under this stamp, and returns how many files went. */
+export const removeBatchOf = async (outbox, key, stamp = currentStamp()) => removeBatchesExcept(outbox, new Set(), stamp, key);
+/** The bytes of a batch file, when they still hash to the name the file was written under; undefined when the file is gone or was edited. */
+export const unchangedBytes = async (file, hash) => {
+    let bytes;
+    try {
+        bytes = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+    return batchHash(bytes) === hash ? bytes : undefined;
+};
+/** The batches built under this client's vocabulary, field list, and skeleton format, and how many of their files no longer hash to their names. An edited file is not printed and cannot be sent: run `deposit` again to rebuild it. */
+export const heldBatches = async (outbox, stamp = currentStamp()) => {
+    const folder = join(outbox, stamp);
+    const batches = [];
+    let edited = 0;
+    for (const name of await namesIn(folder)) {
+        const found = BATCH_FILE.exec(name);
+        if (found === null)
+            continue;
+        const [, key = '', hash = ''] = found;
+        const file = join(folder, name);
+        const bytes = await unchangedBytes(file, hash);
+        if (bytes === undefined)
+            edited += 1;
+        else
+            batches.push({ key, hash, file, bytes });
+    }
+    return { batches, edited };
+};
+const shownFile = (outbox) => join(outbox, 'shown.log');
+/** Records that this hash was printed, one line for each print: the lock below sends only a hash that appears here. */
+export const markShown = async (outbox, hash, at) => {
+    await mkdir(outbox, { recursive: true });
+    await appendFile(shownFile(outbox), `${hash} ${new Date(at).toISOString()}\n`, 'utf8');
+};
+const wasShown = async (outbox, hash) => {
+    try {
+        return (await readFile(shownFile(outbox), 'utf8')).split('\n').some((line) => line.split(' ')[0] === hash);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return false;
+        throw error;
+    }
+};
+/**
+ * The lock on a send: a batch goes only if it is in the outbox, its hash was printed, and its file still hashes to that hash. The first check that fails names why. The nightly task sends with `requireShown: false`,
+ * because covenant acceptance is its consent and it prints nothing; the other two checks still hold.
+ */
+export const lockedBatch = async (outbox, hash, options = {}) => {
+    const folder = join(outbox, options.stamp ?? currentStamp());
+    const name = (await namesIn(folder)).find((entry) => BATCH_FILE.exec(entry)?.[2] === hash);
+    if (name === undefined)
+        return { ok: false, code: 'batch_unknown' };
+    if (options.requireShown !== false && !(await wasShown(outbox, hash)))
+        return { ok: false, code: 'batch_not_shown' };
+    const file = join(folder, name);
+    const bytes = await unchangedBytes(file, hash);
+    return bytes === undefined ? { ok: false, code: 'batch_changed' } : { ok: true, file, bytes };
+};
+/** Folders of an outbox other than the current stamp's: batches built under another vocabulary, field list, or skeleton format. */
+const staleFolders = async (outbox, stamp) => {
+    const names = [];
+    for (const name of await namesIn(outbox)) {
+        if (name !== stamp && STAMP_FOLDER.test(name))
+            names.push(join(outbox, name));
+    }
+    return names;
+};
+const STAMP_FOLDER = /^v[^./]+-[0-9a-f]{8}$/;
+const batchesIn = async (folder) => (await namesIn(folder)).filter((name) => BATCH_FILE.test(name)).length;
+/** Batches in one server's outbox that were built under another vocabulary, field list, or skeleton format: never printed, never sent. */
+export const staleBatches = async (outbox, stamp = currentStamp()) => {
+    let count = 0;
+    for (const folder of await staleFolders(outbox, stamp))
+        count += await batchesIn(folder);
+    return count;
+};
+/** Every server's stale batches, for `verify`. */
+export const staleBatchesAnywhere = async (storeDir, stamp = currentStamp()) => {
+    const root = join(storeDir, 'pool-outbox');
+    let count = 0;
+    for (const name of await namesIn(root))
+        count += await staleBatches(join(root, name), stamp);
+    return count;
+};
+/** Removes one server's stale batches, and returns how many there were. */
+export const discardStale = async (outbox, stamp = currentStamp()) => {
+    const count = await staleBatches(outbox, stamp);
+    for (const folder of await staleFolders(outbox, stamp))
+        await rm(folder, { recursive: true, force: true });
+    return count;
+};
+const collect = (value, into) => {
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collect(entry, into);
+    }
+    else if (typeof value === 'object' && value !== null) {
+        for (const [key, entry] of Object.entries(value)) {
+            into.add(key);
+            collect(entry, into);
+        }
+    }
+};
+/** Every field name in a batch, at any depth, each once and sorted. */
+export const fieldsOf = (batchBytes) => {
+    const names = new Set();
+    collect(JSON.parse(batchBytes), names);
+    return [...names].sort();
+};

package/dist/sessions/pool-print.d.ts

@@ -0,0 +1,26 @@
+/** One request as it will leave this machine. */
+export interface Outgoing {
+    method: 'GET' | 'POST' | 'PUT';
+    url: URL;
+    /** Every header this code sets. The HTTP layer adds `host`, `connection`, and `content-length` itself, and `printed` lists those too. */
+    headers: Array<[string, string]>;
+    body?: string;
+}
+/**
+ * The headers Node's `fetch` would otherwise add on its own, set here so the print lists all of them. `identity` also means a reply is never compressed, so the bytes read are the bytes signed.
+ * `sec-fetch-mode` and `accept-language` carry no information; they are pinned to what `fetch` sends anyway. A conditional request also gets `cache-control: no-cache` and `pragma: no-cache` from `fetch`; `ask` sets both beside `if-none-match`.
+ * `pool-socket.test.ts` compares the print with the headers a loopback server reads off the socket, so a header a later Node adds fails there.
+ */
+export declare const TRANSPORT_HEADERS: ReadonlyArray<[string, string]>;
+/** The credential's size, and nothing else about it. */
+export declare const maskOf: (secret: string) => string;
+/** The secrets of one run. A value added once is masked in every print after, wherever it appears. */
+export declare class Masker {
+    private readonly secrets;
+    add(secret: string): void;
+    mask(text: string): string;
+}
+/** The request as the wire carries it: the request line, `host` and `connection` first as the HTTP layer writes them, then the headers set here, then the length of a body. */
+export declare const printed: (request: Outgoing, masker: Masker) => string;
+/** The line the operator reads when the pool says to wait: a count of seconds, or an HTTP date, in plain words. Undefined when it is neither. */
+export declare const waitWords: (retryAfter: string, now: number) => string | undefined;

package/dist/sessions/pool-print.js

@@ -0,0 +1,68 @@
+// What `oars pool fetch` and `oars pool login` print before they send: the request line and every header, then the body, with a credential
+// masked as `<credential: n bytes>`. The text printed is built from the very headers and body handed to `fetch`, so the two cannot drift apart.
+/**
+ * The headers Node's `fetch` would otherwise add on its own, set here so the print lists all of them. `identity` also means a reply is never compressed, so the bytes read are the bytes signed.
+ * `sec-fetch-mode` and `accept-language` carry no information; they are pinned to what `fetch` sends anyway. A conditional request also gets `cache-control: no-cache` and `pragma: no-cache` from `fetch`; `ask` sets both beside `if-none-match`.
+ * `pool-socket.test.ts` compares the print with the headers a loopback server reads off the socket, so a header a later Node adds fails there.
+ */
+export const TRANSPORT_HEADERS = [
+    ['accept-encoding', 'identity'],
+    ['accept-language', '*'],
+    ['sec-fetch-mode', 'cors'],
+];
+/** The credential's size, and nothing else about it. */
+export const maskOf = (secret) => `<credential: ${String(Buffer.byteLength(secret))} bytes>`;
+/** Every way a secret can be written into a header or a body: bare, form-encoded, percent-encoded, and as the inside of a JSON string. */
+const spellings = (secret) => {
+    const form = new URLSearchParams({ k: secret }).toString().slice('k='.length);
+    const inJson = JSON.stringify(secret).slice(1, -1);
+    return [...new Set([secret, form, encodeURIComponent(secret), inJson])];
+};
+/** The secrets of one run. A value added once is masked in every print after, wherever it appears. */
+export class Masker {
+    secrets = new Set();
+    add(secret) {
+        if (secret !== '')
+            this.secrets.add(secret);
+    }
+    mask(text) {
+        // Longest first, so a secret that holds another is replaced whole.
+        const found = [...this.secrets].flatMap((secret) => spellings(secret).map((spelling) => ({ spelling, mask: maskOf(secret) }))).sort((a, b) => b.spelling.length - a.spelling.length);
+        return found.reduce((masked, { spelling, mask }) => masked.split(spelling).join(mask), text);
+    }
+}
+/** The request as the wire carries it: the request line, `host` and `connection` first as the HTTP layer writes them, then the headers set here, then the length of a body. */
+export const printed = (request, masker) => {
+    const { method, url, headers, body } = request;
+    const lines = [`${method} ${url.pathname}${url.search} HTTP/1.1`, `host: ${url.host}`, 'connection: keep-alive', ...headers.map(([name, value]) => `${name}: ${value}`)];
+    if (body !== undefined)
+        lines.push(`content-length: ${String(Buffer.byteLength(body))}`);
+    return masker.mask(`${lines.join('\n')}\n${body === undefined ? '' : `\n${body}\n`}`);
+};
+/** The line the operator reads when the pool says to wait: a count of seconds, or an HTTP date, in plain words. Undefined when it is neither. */
+export const waitWords = (retryAfter, now) => {
+    const seconds = /^\d+$/.test(retryAfter.trim()) ? Number(retryAfter.trim()) : Math.ceil((Date.parse(retryAfter) - now) / 1000);
+    if (!Number.isFinite(seconds))
+        return undefined;
+    if (seconds <= 0)
+        return 'now';
+    const units = [
+        ['day', 86_400],
+        ['hour', 3_600],
+        ['minute', 60],
+    ];
+    // Only two units are shown, so the last one shown is rounded up: an operator who retries at the time named must not get another 429.
+    const lead = units.findIndex(([, size]) => seconds >= size);
+    const step = lead < 0 ? 1 : (units[Math.min(lead + 1, units.length - 1)]?.[1] ?? 1);
+    const parts = [];
+    let left = Math.ceil(seconds / step) * step;
+    for (const [name, size] of units) {
+        const count = Math.floor(left / size);
+        left -= count * size;
+        if (count > 0)
+            parts.push(`${String(count)} ${name}${count === 1 ? '' : 's'}`);
+    }
+    if (parts.length === 0)
+        parts.push(`${String(left)} second${left === 1 ? '' : 's'}`);
+    return `in ${parts.slice(0, 2).join(' and ')}`;
+};

package/dist/sessions/pool-raw.d.ts

@@ -0,0 +1,27 @@
+/** Parts of a raw copy, each at most this many bytes: under the pool's 1 MB per request. */
+export declare const RAW_PART_BYTES: number;
+/** The folder of the raw copies this client builds now; one built under another redaction or capture version is never sent. */
+export declare const rawStamp: () => string;
+export declare const rawHash: (bytes: string) => string;
+/** Writes one redacted transcript for a session, replacing an earlier copy of the same place. */
+export declare const writeRaw: (outbox: string, key: string, place: number, bytes: string) => Promise<{
+    hash: string;
+    bytes: number;
+}>;
+export interface HeldRaw {
+    key: string;
+    place: number;
+    hash: string;
+    file: string;
+    body: string;
+    bytes: number;
+}
+/** The raw copies under the current stamp that still hash to their names; `edited` counts those that no longer do, which are neither printed nor sent. */
+export declare const heldRaw: (outbox: string) => Promise<{
+    copies: HeldRaw[];
+    edited: number;
+}>;
+/** Removes every raw copy whose session key is not in `kept` (all of them when none is), and returns how many went. A folder switched off, a consent withdrawn, or a session no longer passing the gates leaves nothing queued. */
+export declare const removeRawExcept: (outbox: string, kept: ReadonlySet<string>, only?: string) => Promise<number>;
+/** The parts a raw copy goes in, in order. */
+export declare const rawParts: (body: string) => string[];

package/dist/sessions/pool-raw.js

@@ -0,0 +1,68 @@
+// The raw part of the outbox (t884): one redacted copy of each transcript of a session that passed the gates, in the same outbox as the batches and printed by the same command. A copy is named for its
+// session key, its place among the session's transcripts (0 is the main one), and the SHA-256 of its redacted bytes, which is the hash the pool's `/v1/raw/:sha256` routes take.
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { partsOf } from './pool-outbox.js';
+import { REDACTION_VERSION } from './redact.js';
+import { CAPTURE_VERSION } from './schema.js';
+const RAW_FILE = /^([0-9a-f]{16})\.(\d+)\.([0-9a-f]{64})\.redacted$/;
+/** Parts of a raw copy, each at most this many bytes: under the pool's 1 MB per request. */
+export const RAW_PART_BYTES = 512 * 1024;
+/** The folder of the raw copies this client builds now; one built under another redaction or capture version is never sent. */
+export const rawStamp = () => `raw-r${REDACTION_VERSION}-c${CAPTURE_VERSION}`;
+export const rawHash = (bytes) => createHash('sha256').update(Buffer.from(bytes, 'utf8')).digest('hex');
+const namesIn = async (folder) => {
+    try {
+        return (await readdir(folder)).sort();
+    }
+    catch {
+        return [];
+    }
+};
+/** Writes one redacted transcript for a session, replacing an earlier copy of the same place. */
+export const writeRaw = async (outbox, key, place, bytes) => {
+    const folder = join(outbox, rawStamp());
+    const hash = rawHash(bytes);
+    await mkdir(folder, { recursive: true });
+    for (const name of await namesIn(folder)) {
+        const found = RAW_FILE.exec(name);
+        if (found?.[1] === key && Number(found[2]) === place && found[3] !== hash)
+            await rm(join(folder, name), { force: true });
+    }
+    await writeFile(join(folder, `${key}.${String(place)}.${hash}.redacted`), bytes, 'utf8');
+    return { hash, bytes: Buffer.byteLength(bytes) };
+};
+/** The raw copies under the current stamp that still hash to their names; `edited` counts those that no longer do, which are neither printed nor sent. */
+export const heldRaw = async (outbox) => {
+    const folder = join(outbox, rawStamp());
+    const copies = [];
+    let edited = 0;
+    for (const name of await namesIn(folder)) {
+        const found = RAW_FILE.exec(name);
+        if (found === null)
+            continue;
+        const file = join(folder, name);
+        const body = await readFile(file, 'utf8');
+        if (rawHash(body) === found[3])
+            copies.push({ key: found[1] ?? '', place: Number(found[2]), hash: found[3], file, body, bytes: Buffer.byteLength(body) });
+        else
+            edited += 1;
+    }
+    return { copies, edited };
+};
+/** Removes every raw copy whose session key is not in `kept` (all of them when none is), and returns how many went. A folder switched off, a consent withdrawn, or a session no longer passing the gates leaves nothing queued. */
+export const removeRawExcept = async (outbox, kept, only) => {
+    const folder = join(outbox, rawStamp());
+    let removed = 0;
+    for (const name of await namesIn(folder)) {
+        const found = RAW_FILE.exec(name);
+        if (found !== null && !kept.has(found[1] ?? '') && (only === undefined || found[1] === only)) {
+            await rm(join(folder, name), { force: true });
+            removed += 1;
+        }
+    }
+    return removed;
+};
+/** The parts a raw copy goes in, in order. */
+export const rawParts = (body) => partsOf(body, RAW_PART_BYTES);

package/dist/sessions/pool-replica.d.ts

@@ -0,0 +1,35 @@
+import { type Bundle, type PinnedKey } from './pool-wire.js';
+import type { Harness } from './schema.js';
+export declare const textIn: (value: object, key: string) => string | undefined;
+export declare const numberIn: (value: object, key: string) => number | undefined;
+export declare const isObject: (value: unknown) => value is object;
+/** One server's sign-in, as `login` saved it. */
+export interface SignIn {
+    server: string;
+    account: string;
+    token: string;
+    expiresAt: number;
+    /** Pinned at the first login to this server; every bundle is checked against it. */
+    signingKey: PinnedKey;
+}
+export declare const signInOf: (value: unknown) => SignIn | undefined;
+export declare const signInsFile: (storeDir: string) => string;
+/** Every saved sign-in. A file that cannot be read stops the command: treating it as empty would forget a pin and trust whatever key the server names next. */
+export declare const loadSignIns: (storeDir: string, step: string) => Promise<SignIn[]>;
+/** One folder per harness under the server's, so a fetch for one harness never overwrites another's bundle of the same version. */
+export declare const replicaFile: (storeDir: string, server: string, harness: Harness, harnessVersion: string) => string;
+/** What an earlier fetch kept: the bundle, checked again against the pinned key, and the ETag the pool sent with it. Nothing readable and verified is nothing kept, and the next fetch is then an ordinary one. */
+export declare const keptReplica: (file: string, key: PinnedKey, harness: Harness, harnessVersion: string) => Promise<{
+    etag: string | undefined;
+    bundle: Bundle;
+} | undefined>;
+/** A session's harness and the version it runs, as a hook input, a transcript, or the store states them. */
+export interface Setup {
+    harness: Harness;
+    harnessVersion: string;
+}
+/**
+ * The kept bundle for a session's own harness and version, from the first signed-in server that kept one which still verifies; undefined otherwise. It never throws: a damaged
+ * sign-in file, a missing or corrupt replica, or one signed for another harness all mean the caller answers from the local store alone, and a hook must not fail on any of them.
+ */
+export declare const sessionBundle: (storeDir: string, setup: Setup | undefined) => Promise<Bundle | undefined>;

package/dist/sessions/pool-replica.js

@@ -0,0 +1,91 @@
+// The kept pool bundle: where `oars pool fetch` keeps one harness version's signed bundle, the sign-ins whose pinned keys verify it, and the one reader every caller uses (t926).
+// `poolFetch` reads it for its ETag, and recall, the MCP tool, and the hooks read it for the session's own harness and version. A reader for recall is fail-open: no bundle,
+// one for another harness, or one that does not verify means local reads only, and nothing is printed.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { isMissing } from './pool-outbox.js';
+import { isBundleVersion, verifyBundle } from './pool-wire.js';
+import { contentHash } from './read.js';
+export const textIn = (value, key) => {
+    const found = Reflect.get(value, key);
+    return typeof found === 'string' && found !== '' ? found : undefined;
+};
+export const numberIn = (value, key) => {
+    const found = Reflect.get(value, key);
+    return typeof found === 'number' && Number.isFinite(found) ? found : undefined;
+};
+export const isObject = (value) => typeof value === 'object' && value !== null;
+const keyOf = (value) => {
+    if (!isObject(value))
+        return undefined;
+    const [kty, crv, x] = [textIn(value, 'kty'), textIn(value, 'crv'), textIn(value, 'x')];
+    return kty === 'OKP' && crv === 'Ed25519' && x !== undefined ? { kty, crv, x } : undefined;
+};
+export const signInOf = (value) => {
+    if (!isObject(value))
+        return undefined;
+    const [server, account, token, expiresAt] = [textIn(value, 'server'), textIn(value, 'account'), textIn(value, 'token'), numberIn(value, 'expiresAt')];
+    const signingKey = keyOf(Reflect.get(value, 'signingKey'));
+    return server === undefined || account === undefined || token === undefined || expiresAt === undefined || signingKey === undefined ? undefined : { server, account, token, expiresAt, signingKey };
+};
+export const signInsFile = (storeDir) => join(storeDir, 'pool-accounts.json');
+/** Every saved sign-in. A file that cannot be read stops the command: treating it as empty would forget a pin and trust whatever key the server names next. */
+export const loadSignIns = async (storeDir, step) => {
+    const file = signInsFile(storeDir);
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return [];
+        throw error;
+    }
+    const damaged = new CliError(`${file} cannot be read. Remove it, then run oars pool login again.`, ExitCode.INVALID, step);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw damaged;
+    }
+    if (!Array.isArray(parsed))
+        throw damaged;
+    const entries = parsed;
+    return entries.map((entry) => {
+        const signIn = signInOf(entry);
+        if (signIn === undefined)
+            throw damaged;
+        return signIn;
+    });
+};
+/** One folder per harness under the server's, so a fetch for one harness never overwrites another's bundle of the same version. */
+export const replicaFile = (storeDir, server, harness, harnessVersion) => join(storeDir, 'pool-replica', contentHash(server), harness, `${encodeURIComponent(harnessVersion)}.json`);
+/** What an earlier fetch kept: the bundle, checked again against the pinned key, and the ETag the pool sent with it. Nothing readable and verified is nothing kept, and the next fetch is then an ordinary one. */
+export const keptReplica = async (file, key, harness, harnessVersion) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const verified = await verifyBundle(parsed, key, harness, harnessVersion);
+    return verified.ok ? { etag: isObject(parsed) ? textIn(parsed, 'etag') : undefined, bundle: verified.bundle } : undefined;
+};
+/**
+ * The kept bundle for a session's own harness and version, from the first signed-in server that kept one which still verifies; undefined otherwise. It never throws: a damaged
+ * sign-in file, a missing or corrupt replica, or one signed for another harness all mean the caller answers from the local store alone, and a hook must not fail on any of them.
+ */
+export const sessionBundle = async (storeDir, setup) => {
+    if (setup === undefined || !isBundleVersion(setup.harnessVersion))
+        return undefined;
+    const signIns = await loadSignIns(storeDir, 'recall').catch(() => []);
+    for (const { server, signingKey } of signIns) {
+        const kept = await keptReplica(replicaFile(storeDir, server, setup.harness, setup.harnessVersion), signingKey, setup.harness, setup.harnessVersion);
+        if (kept !== undefined)
+            return kept.bundle;
+    }
+    return undefined;
+};