@manyoars/oars 0.3.0 → 0.4.1

package/dist/sessions/recall-next.js

@@ -0,0 +1,241 @@
+// The next-node read (t926): what the agent is shown at the moments before it decides. Two reads, both from cells and never from text: the recovery edge (what followed this
+// failure, for this action and error class) and the split positions (the places in a repo's earlier work where the next step is not settled). A read is built from the kept
+// bundle for the session's setup first and the local pool's reads second, and every shown or held one is a `Recall` row, so the holdback arms are real.
+import { CANONICAL_ACTIONS } from './actions.js';
+import { harnessBucket } from './cells.js';
+import { appendRecall, armOf, makeRecall, parseRecalls, recallsPath } from './recall-object.js';
+import { frameOfTail, tailOf } from './recall-push.js';
+import { sessionBundle } from './pool-replica.js';
+import { readIdOf } from './recall-reads.js';
+import { closedName, count, evidenceOf } from './recall-render.js';
+import { LITERAL } from './public-vocabulary.js';
+/**
+ * The count a recovery edge needs before it is served from the local pool. The pool's own served floor is `K_CELL` (5 accounts, `packages/pool/src/derive.ts`); a bundle's read has
+ * cleared it already, so only a local edge is held to this, counted in followed steps because one operator's store is one account.
+ */
+export const RECOVERY_FLOOR = 5;
+/** The steps a position needs behind it before it can be called split: t782's qualifying cell is a cell topped up to 20 sessions. */
+export const POSITION_MIN_N = 20;
+/** The band of t782 plan 1.7: the leading option's share, 20 to 80 percent inclusive. A settled position (above) and a diffuse one (below) are not listed. */
+export const POSITION_BAND = { low: 0.2, high: 0.8 };
+/**
+ * The bytes a table may add to a turn's context. Eight lines of about 70 bytes: a session start or a prompt carries it every time it is sent, and a table the agent has to
+ * read past is one it stops reading. Bundle positions come first, then local ones, each by observations; the cap cuts from the end, so a local position goes before a bundle one.
+ */
+export const TABLE_CAP_BYTES = 600;
+const TOP_NEXT = 3;
+const MAX_FOLLOWED = 3;
+const isCount = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+const isAction = (name) => CANONICAL_ACTIONS.some((action) => action === name);
+const byWeight = (a, b) => b.followed - a.followed || a.next.localeCompare(b.next);
+/**
+ * The recovery edges of a set of reads, by `action/errorCode`, each next step summed over its weeks. A next step that is not a canonical action (or `none`) is left out, so the
+ * names a hook shows are the closed ones whatever a store holds.
+ */
+export const recoveryEdgesOf = (reads, keep = () => true) => {
+    const grouped = new Map();
+    // The failures of one action and error class, once: every week's reads of its next steps share a week's failures, so a next step seen in fewer weeks must not get a smaller denominator.
+    // A week's failures are the sum of what followed them, so the total over every next step is that sum over all its weeks.
+    const failures = new Map();
+    for (const read of reads) {
+        if (read.family !== 'recovery')
+            continue;
+        const { action, errorCode, next } = read.slice;
+        const { followed, of } = read.value;
+        if (action === undefined || errorCode === undefined || next === undefined || !isCount(followed) || !isCount(of) || followed === 0)
+            continue;
+        const key = `${action}/${errorCode}`;
+        failures.set(key, (failures.get(key) ?? 0) + followed);
+        if (!(next === 'none' || isAction(next)))
+            continue;
+        const edges = grouped.get(key) ?? new Map();
+        grouped.set(key, edges);
+        const have = edges.get(next);
+        if (have === undefined) {
+            edges.set(next, { edge: { next, followed, of, clusters: read.clusters, readId: read.readId, day: read.asOf.day }, heaviest: followed });
+            continue;
+        }
+        have.edge.followed += followed;
+        have.edge.clusters = Math.max(have.edge.clusters, read.clusters);
+        if (followed > have.heaviest) {
+            have.heaviest = followed;
+            have.edge.readId = read.readId;
+        }
+        if (read.asOf.day !== null && (have.edge.day === null || read.asOf.day > have.edge.day))
+            have.edge.day = read.asOf.day;
+    }
+    const edges = {};
+    for (const [key, byNext] of grouped) {
+        const sorted = [...byNext.values()].map((weighted) => ({ ...weighted.edge, of: failures.get(key) ?? weighted.edge.of })).sort(byWeight);
+        if (sorted[0] !== undefined && keep(sorted[0].followed))
+            edges[key] = sorted.slice(0, MAX_FOLLOWED);
+    }
+    return edges;
+};
+/** True when a position's prefix names only canonical actions (no identity, no class): the table prints names and numbers and nothing a store wrote. */
+const closedPrefix = (prefix) => prefix.split('>').every(isAction);
+/** The positions of a set of reads where the next step is split by t782's rule: enough observations, and the leading step's share inside the band. */
+export const positionsOf = (reads) => {
+    const positions = [];
+    for (const read of reads) {
+        if (read.family !== 'next-step')
+            continue;
+        const { prefix } = read.slice;
+        const { next, topShare } = read.value;
+        if (prefix === undefined || !closedPrefix(prefix) || !isCount(topShare) || topShare < POSITION_BAND.low || topShare > POSITION_BAND.high || read.n < POSITION_MIN_N)
+            continue;
+        if (typeof next !== 'object' || next === null)
+            continue;
+        const ranked = Object.entries(next)
+            .filter(([action, times]) => isAction(action) && isCount(times))
+            .sort(([a, one], [b, two]) => two - one || a.localeCompare(b))
+            .slice(0, TOP_NEXT);
+        if (ranked.length < 2)
+            continue;
+        positions.push({ prefix, n: read.n, next: ranked, clusters: read.clusters, readId: read.readId, day: read.asOf.day });
+    }
+    return positions.sort((a, b) => b.n - a.n || a.prefix.localeCompare(b.prefix));
+};
+/**
+ * What a failure is answered with: the bundle's edges for this action and error class if it holds any (they cleared the pool's floor), else the local pool's. Silent when the top
+ * next step is a same-step retry (direction 13c), when a local edge is under `RECOVERY_FLOOR`, or when the top is that nothing followed (`ended`).
+ */
+export const recoveryDecision = (bundle, local, action, code) => {
+    const key = `${action}/${code}`;
+    const fromBundle = bundle?.recovery[key];
+    const source = fromBundle === undefined || bundle === undefined ? undefined : { edges: fromBundle, source: 'bundle', poolVersion: bundle.poolVersion };
+    const fromLocal = local?.recovery[key];
+    const chosen = source ?? (fromLocal === undefined || local === undefined ? undefined : { edges: fromLocal, source: 'local', poolVersion: local.poolVersion });
+    const top = chosen?.edges[0];
+    if (chosen === undefined || top === undefined)
+        return { kind: 'none' };
+    // A tie with another next step is not a retry-only cell, so it is served; the strict lead is what direction 13c silences.
+    const second = chosen.edges[1];
+    if (top.next === action && (second === undefined || top.followed > second.followed))
+        return { kind: 'retry' };
+    if (top.next === 'none')
+        return { kind: 'ended' };
+    if (chosen.source === 'local' && top.followed < RECOVERY_FLOOR)
+        return { kind: 'floor' };
+    return { kind: 'serve', ...chosen };
+};
+const percent = (part, whole) => `${String(Math.round((part / whole) * 100))}%`;
+/** The recovery read as text: names (closed) and numbers. */
+export const renderRecovery = (action, code, edges) => {
+    const shown = edges.filter((edge) => closedName(edge.next) !== LITERAL);
+    const total = shown[0]?.of ?? 0;
+    const lines = shown.map((edge) => `${edge.next} x${String(edge.followed)}${total > 0 ? ` (${percent(edge.followed, total)})` : ''}`);
+    const rendered = [`oars recall, counts from earlier sessions: after a failed ${action} (${code})${total > 0 ? ` in ${count(total, 'failure')}` : ''}, the next step was`, `  ${lines.join(', ')}`, `  read ${shown[0]?.readId ?? ''} (recovery)`].join('\n');
+    return { rendered, names: shown.map((edge) => edge.next) };
+};
+/** The positions table, with every position that fits under the cap and nothing when none does. */
+export const renderPositions = (positions) => {
+    const header = 'oars recall, next steps that earlier sessions split on (counts, not advice):';
+    const listed = [];
+    let used = Buffer.byteLength(header);
+    const lines = [];
+    for (const position of positions) {
+        const line = `- after ${position.prefix}: ${position.next.map(([action, times]) => `${action} ${percent(times, position.n)}`).join(', ')} (n ${String(position.n)})`;
+        const size = Buffer.byteLength(line) + 1;
+        if (used + size > TABLE_CAP_BYTES)
+            break;
+        used += size;
+        listed.push(position);
+        lines.push(line);
+    }
+    return { rendered: listed.length === 0 ? '' : [header, ...lines].join('\n'), listed, names: [...new Set(listed.flatMap((position) => position.next.map(([action]) => action)))] };
+};
+/**
+ * The key a hook index files the local pool's reads under for a session: its harness and the bucket of the version it runs (`recall-frames.ts`). A session whose version is not
+ * stated is read across every version of its harness, which is the filter that can be applied honestly.
+ */
+export const frameKeyOf = (asker) => `${asker.harness}/${asker.harnessVersion === null ? '*' : harnessBucket(asker.harnessVersion)}`;
+/** The bundle's and the local pool's positions as one list, a prefix once: the bundle's positions by observations, then the local ones it lacks by observations. */
+export const mergePositions = (bundle, local) => {
+    const byObservations = (a, b) => b.n - a.n || a.prefix.localeCompare(b.prefix);
+    const seen = new Set(bundle.map((position) => position.prefix));
+    return [...[...bundle].sort(byObservations), ...local.filter((position) => !seen.has(position.prefix)).sort(byObservations)];
+};
+/** A read as the evidence record wants it: counts and closed names only. */
+const evidenceRead = (read, setup) => ({
+    readId: read.readId,
+    family: read.family,
+    tool: read.tool,
+    keys: [],
+    n: read.n,
+    count: read.count,
+    calls: read.calls,
+    clusters: read.clusters,
+    firstDay: null,
+    lastDay: read.day,
+    harnesses: [setup.harness],
+    harnessVersions: setup.harnessVersion === null ? [] : [setup.harnessVersion],
+    models: [],
+    followed: read.followed,
+});
+/** The asker's frame, from the tail of its transcript. */
+export const frameFor = (input) => frameOfTail(input.tail, input.platform, input.at);
+/** The reads of the kept bundle for the asker's harness and version; undefined with no version stated, no bundle, or a bundle that does not verify (never an error). */
+export const bundleNext = async (storeDir, asker) => {
+    const bundle = asker.harnessVersion === null ? undefined : await sessionBundle(storeDir, { harness: asker.harness, harnessVersion: asker.harnessVersion });
+    return bundle === undefined ? undefined : { poolVersion: bundle.asOf.pool, recovery: recoveryEdgesOf(bundle.reads), positions: positionsOf(bundle.reads) };
+};
+/**
+ * A served or held read: the row is written before anything is injected, and the arm is the session's for this query against this pool. The row is the recall's exposure record
+ * (ids and counts, and the rendered text a held read would have shown); an arm that kept it back is returned so the hook injects nothing.
+ */
+export const recordRead = async (input, frame, query, armPrefix, poolVersion, rendered, names, reads) => {
+    const recall = makeRecall({
+        sid: input.sid,
+        at: input.at,
+        frame,
+        mode: 'push',
+        query,
+        poolVersion,
+        arm: armOf(input.sid, armPrefix, poolVersion),
+        reads: reads.map((read) => read.readId),
+        rendered,
+        names,
+        evidence: reads.map((read) => evidenceOf(read, frame)),
+    });
+    await appendRecall(input.storeDir, recall);
+    return recall;
+};
+/** The recovery read for one failure, as a recall row. */
+export const recoveryRecall = (input, setup, action, code, decision) => {
+    const frame = frameFor(input);
+    const { rendered, names } = renderRecovery(action, code, decision.edges);
+    const top = decision.edges[0];
+    const read = evidenceRead({ readId: top?.readId ?? '', family: 'recovery', tool: action, n: top?.followed ?? 0, count: top?.followed ?? 0, calls: top?.of ?? null, clusters: top?.clusters ?? 1, day: top?.day ?? null, followed: decision.edges.map((edge) => [edge.next, edge.followed]) }, setup);
+    return recordRead(input, frame, { form: 'question', family: 'recovery', prefix: [`${action}/${code}`] }, [`${action}/${code}`], decision.poolVersion, rendered, names, [read]);
+};
+/** The old signature line's recall: the local signature index, held to the same retry rule and floor. */
+export const signatureRecall = (input, setup, tool, sig, found, poolVersion) => {
+    const frame = frameFor(input);
+    const followed = found.followed.map(([next]) => next).join(', ');
+    const rendered = `oars recall: seen in ${String(found.sessions)} sessions; what followed: ${followed === '' ? 'nothing recorded' : followed}`;
+    const read = evidenceRead({ readId: readIdOf(sig), family: 'recovery', tool, n: found.sessions, count: found.sessions, calls: null, clusters: 1, day: null, followed: found.followed }, setup);
+    return recordRead(input, frame, { form: 'question', family: 'recovery', prefix: [readIdOf(sig)] }, [readIdOf(sig)], poolVersion, rendered, found.followed.map(([next]) => next), [read]);
+};
+/**
+ * The signature line is a same-step retry when the tool that failed is the one that most often followed, strictly: a tie with another tool is not a retry-only cell. It keeps its
+ * own floor, the index's two sessions: it states how many sessions saw the error, so a thin count is printed as thin, which a cell's share is not.
+ */
+export const isSignatureRetry = (tool, found) => {
+    const [first, second] = found.followed;
+    return first?.[0] === tool && (second === undefined || first[1] > second[1]);
+};
+/** The positions table for a session, as a recall row; undefined when no position qualifies or the table is the one `previous` already sent. */
+export const positionsRecall = (input, setup, positions, poolVersion, previous) => {
+    const { rendered, listed, names } = renderPositions(positions);
+    if (listed.length === 0 || rendered === previous)
+        return Promise.resolve(undefined);
+    const frame = frameFor(input);
+    const reads = listed.map((position) => evidenceRead({ readId: position.readId, family: 'next-step', tool: position.next[0]?.[0] ?? '', n: position.n, count: position.next[0]?.[1] ?? 0, calls: position.n, clusters: position.clusters, day: position.day, followed: position.next }, setup));
+    return recordRead(input, frame, { form: 'question', family: 'next-step', prefix: ['positions'] }, ['positions'], poolVersion, rendered, names, reads);
+};
+/** The text the session was last sent a table with, from `recalls.jsonl`; undefined when it was never sent one. */
+export const lastTable = async (storeDir, sid) => {
+    const mine = parseRecalls(await tailOf(recallsPath(storeDir))).filter((recall) => recall.mode === 'push' && recall.sid === sid && recall.query.family === 'next-step');
+    return mine.at(-1)?.answer.rendered;
+};

package/dist/sessions/recall-object.d.ts

@@ -34,6 +34,8 @@ export interface RecallAnswer {
     reads: string[];
     /** The size of what was injected, or of what a held recall would have injected. */
     tokens: number;
+    /** The UTF-8 bytes of `rendered`: what a hook injected, or would have. Absent on rows written before it was recorded. */
+    bytes?: number;
     /** What the asker saw, or for a held recall would have seen. It holds structured fields only (`recall-render.ts`). */
     rendered: string;
     /** The closed names a follow can match: canonical actions, in the order shown. */

package/dist/sessions/recall-object.js

@@ -28,6 +28,7 @@ export const makeRecall = (input) => ({
         kind: input.reads.length === 0 ? 'miss' : 'hit',
         reads: [...input.reads],
         tokens: Math.ceil(input.rendered.length / CHARS_PER_TOKEN),
+        bytes: Buffer.byteLength(input.rendered),
         rendered: input.rendered,
         names: [...input.names],
     },

package/dist/sessions/recall-push.d.ts

@@ -1,8 +1,8 @@
 import type { HookIndex } from './hook-index.js';
 import { type Recall } from './recall-object.js';
 import { type Frame } from './schema.js';
-/** A file's last bytes; a first line this cuts in two fails to parse and is skipped by whoever reads it. */
-export declare const tailOf: (file: string) => Promise<string>;
+import { tailOf } from './transcript-tail.js';
+export { tailOf };
 /**
  * The asker's frame, as far as a transcript's tail states it. The stack and the shell need the whole transcript, which a hook has no time to read, so they stay
  * unknown here; `delta` says unknown for them, and derive reads the session's real frame.

package/dist/sessions/recall-push.js

@@ -1,66 +1,18 @@
 // The push: a pre-tool hook's recall (spec Section 2.7). The harness tells the hook only the call it is about to run, so the query is the call's shape, and a shape
 // with a read over the floors and `PUSH_MIN_LIFT` is the one thing that can arm a push. A held push stores what it would have shown and injects nothing, which is the unexposed baseline.
-import { open } from 'node:fs/promises';
 import { closedFrame, closedStack, utcDay } from './frame.js';
 import { appendRecall, armOf, makeRecall, parseRecalls, recallsPath } from './recall-object.js';
 import { toolShapeId } from './recall-reads.js';
 import { evidenceOf, renderAnswer } from './recall-render.js';
 import { harnessOf } from './schema.js';
-/** How far back a hook looks in a growing file: enough for the session's latest lines, and a bound on what a hook on every call can cost. */
-const TAIL_BYTES = 64 * 1024;
-const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
-const openIfThere = async (file) => {
-    try {
-        return await open(file, 'r');
-    }
-    catch (error) {
-        if (isMissing(error))
-            return undefined;
-        throw error;
-    }
-};
-/** A file's last bytes; a first line this cuts in two fails to parse and is skipped by whoever reads it. */
-export const tailOf = async (file) => {
-    const handle = await openIfThere(file);
-    if (handle === undefined)
-        return '';
-    try {
-        const { size } = await handle.stat();
-        const length = Math.min(size, TAIL_BYTES);
-        const buffer = Buffer.alloc(length);
-        await handle.read(buffer, 0, length, size - length);
-        return buffer.toString('utf8');
-    }
-    finally {
-        await handle.close();
-    }
-};
-const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
-const text = (value) => (typeof value === 'string' && value !== '' ? value : null);
-const parsedLines = (tail) => tail.split('\n').flatMap((line) => {
-    try {
-        const parsed = JSON.parse(line);
-        return isRecord(parsed) ? [parsed] : [];
-    }
-    catch {
-        return [];
-    }
-});
+import { statedOf, tailOf } from './transcript-tail.js';
+export { tailOf };
 /**
  * The asker's frame, as far as a transcript's tail states it. The stack and the shell need the whole transcript, which a hook has no time to read, so they stay
  * unknown here; `delta` says unknown for them, and derive reads the session's real frame.
  */
 export const frameOfTail = (tail, platform, at) => {
-    let harnessVersion = null;
-    let model = null;
-    let effort = null;
-    // Oldest first, so the newest line that states a field wins.
-    for (const line of parsedLines(tail)) {
-        harnessVersion = text(line.version) ?? harnessVersion;
-        effort = text(line.effort) ?? effort;
-        if (isRecord(line.message))
-            model = text(line.message.model) ?? model;
-    }
+    const { harnessVersion, model, effort } = statedOf(tail);
     return closedFrame({ harness: harnessOf({}), harnessVersion, model, effort, day: utcDay(at), platform, shell: null, stack: closedStack({ languages: [], frameworks: [], size: null }) });
 };
 /**

package/dist/sessions/recall-reads.d.ts

@@ -46,6 +46,13 @@ export interface FitFloors {
  * calls that always fail (`Monitor` with `query`, `Read` with `path`), and leave Bash, whose failures do not depend on its shape. Open parameters.
  */
 export declare const FIT_FLOORS: FitFloors;
+/**
+ * The floors the pre-tool push holds a shape to (t926). The pre-tool hook fires after the call is decided, so a push is a warning or nothing: a shape that fails less than half
+ * its calls is a base rate (the two broad shell shapes, `Bash` and `PowerShell` with a command, fail about a third of theirs whatever the command) and warning on it tells the
+ * agent nothing it can act on. A shape that fails at least half its calls is a defect of the call itself (`Monitor` with `query`, `Read` with `path`). Pulls and the pool keep
+ * `FIT_FLOORS`: a base rate is still a fact to read on request.
+ */
+export declare const PUSH_FLOORS: FitFloors;
 /** `keep` narrows which calls are tallied, not what can come next: the call after a kept one is what followed it, wherever the slice ends. */
 export declare const fitReads: (store: Store, floors?: FitFloors, keep?: (call: ToolObservation) => boolean) => RecallRead[];
 /** The action of a tool under the first of its harnesses whose table lists it, else under the first harness (the default one when a read names none). */

package/dist/sessions/recall-reads.js

@@ -102,6 +102,13 @@ export const callsBySession = (store) => {
  * calls that always fail (`Monitor` with `query`, `Read` with `path`), and leave Bash, whose failures do not depend on its shape. Open parameters.
  */
 export const FIT_FLOORS = { minFailedSessions: 3, minFailedShare: 0.1, minCalls: 20 };
+/**
+ * The floors the pre-tool push holds a shape to (t926). The pre-tool hook fires after the call is decided, so a push is a warning or nothing: a shape that fails less than half
+ * its calls is a base rate (the two broad shell shapes, `Bash` and `PowerShell` with a command, fail about a third of theirs whatever the command) and warning on it tells the
+ * agent nothing it can act on. A shape that fails at least half its calls is a defect of the call itself (`Monitor` with `query`, `Read` with `path`). Pulls and the pool keep
+ * `FIT_FLOORS`: a base rate is still a fact to read on request.
+ */
+export const PUSH_FLOORS = { ...FIT_FLOORS, minFailedShare: 0.5 };
 /** `keep` narrows which calls are tallied, not what can come next: the call after a kept one is what followed it, wherever the slice ends. */
 export const fitReads = (store, floors = FIT_FLOORS, keep = () => true) => {
     const models = modelsByPrompt(store);

package/dist/sessions/recovery-calls.d.ts

@@ -0,0 +1,21 @@
+import type { CanonicalAction } from './actions.js';
+import type { ToolObservation } from './schema.js';
+/** What the scan reads of a call, so a stored call and a skeleton's call both fit: its run, prompt, status, and the action of its first step. */
+export type Followed = Pick<ToolObservation, 'side' | 'prompt'> & {
+    status: ToolObservation['status'] | 'other';
+    steps?: readonly {
+        action: CanonicalAction;
+    }[];
+};
+/** How many following calls a failed call lists. */
+export declare const RECOVERY_CALLS = 5;
+/** What followed one failed call: the actions of the next calls, and whether any of them wrote a file. */
+export interface RecoveryCalls {
+    next: CanonicalAction[];
+    editFollowed: boolean;
+}
+/**
+ * What followed the call at `at` of a transcript's calls in the order they ran: null for a call that did not fail. The calls that followed are the later ones of the same prompt and the same run (a
+ * subagent's call is not what the main run did next), up to 5. The scan ends at the first later call of that run that belongs to another prompt.
+ */
+export declare const recoveryCallsOf: (calls: readonly Followed[], at: number) => RecoveryCalls | null;

package/dist/sessions/recovery-calls.js

@@ -0,0 +1,25 @@
+/** How many following calls a failed call lists. */
+export const RECOVERY_CALLS = 5;
+/** The actions that write a file: the stored error row's `editFollowed` counts the same tools (`Edit`, `Write`, `MultiEdit`). */
+const WRITES = new Set(['file.edit', 'file.write']);
+/** A call's action is its first step's; a call with no step is `other`. */
+const actionOf = ({ steps }) => steps?.[0]?.action ?? 'other';
+/**
+ * What followed the call at `at` of a transcript's calls in the order they ran: null for a call that did not fail. The calls that followed are the later ones of the same prompt and the same run (a
+ * subagent's call is not what the main run did next), up to 5. The scan ends at the first later call of that run that belongs to another prompt.
+ */
+export const recoveryCallsOf = (calls, at) => {
+    const failed = calls[at];
+    if (failed === undefined || failed.status !== 'error')
+        return null;
+    const next = [];
+    for (let index = at + 1; index < calls.length && next.length < RECOVERY_CALLS; index += 1) {
+        const call = calls[index];
+        if (call === undefined || call.side !== failed.side)
+            continue;
+        if (call.prompt !== failed.prompt)
+            break;
+        next.push(actionOf(call));
+    }
+    return { next, editFollowed: next.some((action) => WRITES.has(action)) };
+};

package/dist/sessions/redact.d.ts

@@ -4,3 +4,14 @@ export declare const entropy: (text: string) => number;
 export type Redactor = (text: string) => string;
 /** `domains` are the organization domains to mask (`example.com` also masks `mail.example.com`). */
 export declare const makeRedactor: (domains?: readonly string[]) => Redactor;
+/** How many values of a redacted text were masked: each placeholder is one. */
+export declare const placeholders: (text: string) => number;
+/** The names this machine's person goes by in a transcript: the account's and the home folder's. A name under three characters would mask ordinary words, so it is left to the path rules. */
+export declare const localNames: (home?: string, account?: () => string) => string[];
+/** A whole transcript body redacted for upload, and how many values were masked (placeholders added, a count and nothing else). `names` are the local usernames to mask wherever they stand as a whole word. */
+export declare const redactTranscript: (body: string, domains?: readonly string[], names?: readonly string[]) => {
+    text: string;
+    masked: number;
+};
+/** The version of the rules above, stated to the pool with every raw part; a change to any rule of `redactTranscript` raises it. */
+export declare const REDACTION_VERSION = "1";

package/dist/sessions/redact.js

@@ -1,3 +1,5 @@
+import { homedir, userInfo } from 'node:os';
+import { basename } from 'node:path';
 // Redaction before anything is written to the session store. Deterministic and conservative: it would rather over-mask a
 // long random-looking token than let a secret through. Pattern rules first, then emails, the organization domains the
 // operator names, and last an entropy rule for long mixed-case tokens no pattern knew.
@@ -52,3 +54,60 @@ export const makeRedactor = (domains = []) => {
         return out.replace(TOKEN, (token) => (looksRandom(token) ? '<secret>' : token));
     };
 };
+// What a whole transcript holds beyond what a slice of one does (t884): home paths and usernames, environment values, and hosts. A raw copy that
+// leaves the machine goes through these after `makeRedactor`'s rules. Best effort, not a proof: `docs/sessions-store.md` ("The raw copy") lists what it cannot catch.
+const URL_HOST = /(\b[a-z][a-z0-9+.-]*:\/\/)(?:[^\s/@"'\\]*@)?[A-Za-z0-9.-]+(?::\d+)?/gi;
+const IPV4 = /\b(?:\d{1,3}\.){3}\d{1,3}\b/g;
+const INTERNAL_NAME = /\b(?:[a-z0-9-]+\.)+(?:internal|local|lan|corp|intranet|home|localdomain)\b/gi;
+const UNIX_HOME = /(\/(?:home|Users)\/)(?![<.])[^/\s"'\\]+/g;
+const WINDOWS_HOME = /([A-Za-z]:[\\/]+Users[\\/]+)(?![<.])[^\\/\s"']+/gi;
+const ENVIRONMENT = /\b((?:export\s+)?[A-Z][A-Z0-9_]{2,}=)(?!<)(?:\\?["'][^"'\\]*\\?["']|[^\s"'\\]+)/g;
+// The harness names a project folder after its path: `/Users/name/work` becomes `-Users-name-work`, and `C:\\Users\\name\\work` becomes `C--Users-name-work`. The name runs to the next hyphen, so a hyphenated name is masked whole earlier, by the local-name rule (which also matches each name in this encoded form).
+const ENCODED_HOME = /(?<![A-Za-z0-9])((?:[A-Za-z]-)?-(?:Users|home)-)(?!<)[^-\s"'\\/]+/g;
+// A shell prompt, `name@box:~/dir$`: a box name with no dot is not an address, so the email rule leaves it.
+const PROMPT = /(?:<user>|\b[A-Za-z0-9._-]+)@[A-Za-z0-9-]+(?=:[~/.])/g;
+// Full, compressed, and loopback forms. A clock time (`10:20:30`) has no `::`, so it is never one.
+const IPV6 = /(?<![0-9A-Za-z:])(?:(?:[0-9a-f]{1,4}:){7}[0-9a-f]{1,4}|(?:[0-9a-f]{1,4}:){1,7}:(?:[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,6})?|::[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,6})(?![0-9A-Za-z:])/gi;
+const MIN_NAME = 3;
+const PLACEHOLDER = /<(?:secret|email|org-domain|host|user|env)>/g;
+/** How many values of a redacted text were masked: each placeholder is one. */
+export const placeholders = (text) => text.match(PLACEHOLDER)?.length ?? 0;
+/** The account name; `userInfo()` throws when the uid has no passwd entry (a container run with `--user <uid>`), so the environment stands in. */
+const accountName = () => userInfo().username;
+/** The names this machine's person goes by in a transcript: the account's and the home folder's. A name under three characters would mask ordinary words, so it is left to the path rules. */
+export const localNames = (home = homedir(), account = accountName) => {
+    const read = () => {
+        try {
+            return account();
+        }
+        catch {
+            return process.env['USER'] || process.env['USERNAME'] || '';
+        }
+    };
+    return [...new Set([read(), basename(home)].filter((name) => name.length >= MIN_NAME))];
+};
+// Each name also stands in its encoded-folder form (`John Smith` is `John-Smith` in `C--Users-John-Smith-repo`), and the longest goes first so `mary-jane` is never cut to `mary`.
+const nameRule = (names) => {
+    const usable = names.filter((name) => name.length >= MIN_NAME);
+    const forms = [...new Set(usable.flatMap((name) => [name, name.replace(/[^A-Za-z0-9]/g, '-')]))].sort((a, b) => b.length - a.length);
+    return forms.length === 0 ? undefined : new RegExp(`(?<![A-Za-z0-9<])(?:${forms.map(escapeRegExp).join('|')})(?![A-Za-z0-9>])`, 'gi');
+};
+/** A whole transcript body redacted for upload, and how many values were masked (placeholders added, a count and nothing else). `names` are the local usernames to mask wherever they stand as a whole word. */
+export const redactTranscript = (body, domains = [], names = []) => {
+    const named = nameRule(names);
+    // The names go first: a hyphenated or spaced name must be masked whole before the path rules take its first word.
+    const known = makeRedactor(domains)(body);
+    const redacted = (named === undefined ? known : known.replace(named, '<user>'))
+        .replace(URL_HOST, '$1<host>')
+        .replace(INTERNAL_NAME, '<host>')
+        .replace(IPV4, '<host>')
+        .replace(IPV6, '<host>')
+        .replace(UNIX_HOME, '$1<user>')
+        .replace(WINDOWS_HOME, '$1<user>')
+        .replace(ENCODED_HOME, '$1<user>')
+        .replace(PROMPT, '<user>@<host>')
+        .replace(ENVIRONMENT, '$1<env>');
+    return { text: redacted, masked: Math.max(0, placeholders(redacted) - placeholders(body)) };
+};
+/** The version of the rules above, stated to the pool with every raw part; a change to any rule of `redactTranscript` raises it. */
+export const REDACTION_VERSION = '1';