@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/recall-render.js

@@ -0,0 +1,168 @@
+// What an agent reads from a recall. Answers render from structured fields only (spec Section 3): every name passes a closed test and the rest is numbers, so
+// error text and other authored strings stay out of an agent's context, whatever a store's records hold.
+import { ACTION_TABLES, actionOf, CANONICAL_ACTIONS } from './actions.js';
+import { LITERAL, PUBLIC_MCP_SERVERS, PUBLIC_PACKAGES, publicModel, publicVersion } from './public-vocabulary.js';
+import { PROMPT_CLASSES } from './schema.js';
+const DAY_MS = 86_400_000;
+const KEY_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,25}$/;
+const KEY_WORD_BREAK = /_+|(?<=[a-z0-9])(?=[A-Z])/;
+const MAX_KEY_WORDS = 3;
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const READ_ID = /^(read:)?[0-9a-f]{16}$/;
+/**
+ * An input key is an identifier of at most three words: in a scan of real tool rows, 390 of 406 distinct keys were, `run_in_background` and `dangerouslyDisableSandbox` among them.
+ * Any longer and an identifier can say a whole instruction. A rare longer key is only left off the line; the shape's ID still holds it.
+ */
+const isKeyName = (key) => KEY_NAME.test(key) && key.split(KEY_WORD_BREAK).filter((word) => word !== '').length <= MAX_KEY_WORDS;
+/** A public name as it stands: a package, a model, a canonical action, a tool a harness's table lists, or a published MCP server. Anything else is what the asker or a record wrote. */
+export const closedName = (name) => {
+    const isPublic = PUBLIC_PACKAGES.has(name) || publicModel(name) === name || CANONICAL_ACTIONS.some((action) => action === name) || Object.values(ACTION_TABLES).some((table) => Object.hasOwn(table.rows, name)) || PUBLIC_MCP_SERVERS.has(name);
+    return isPublic ? name : LITERAL;
+};
+const known = (value) => value !== null && value !== undefined && value !== LITERAL;
+const harnessName = (name) => (Object.hasOwn(ACTION_TABLES, name) ? name : null);
+const publicDay = (day) => (day !== null && DAY.test(day) ? day : null);
+const versionParts = (version) => {
+    const parts = version.split('.').map(Number);
+    return parts.every((part) => Number.isInteger(part)) ? parts : undefined;
+};
+/** The gap in the last component when every other component agrees; undefined when the two do not line up as one count, which an agent must not read as near. */
+const lastGap = (asker, evidence) => {
+    const mine = versionParts(asker);
+    const theirs = versionParts(evidence);
+    if (mine === undefined || theirs === undefined || mine.length !== theirs.length)
+        return undefined;
+    const last = mine.length - 1;
+    if (mine.slice(0, last).some((part, index) => part !== theirs[index]))
+        return undefined;
+    return (mine[last] ?? 0) - (theirs[last] ?? 0);
+};
+const newest = (versions) => versions.flatMap((version) => (versionParts(version) === undefined ? [] : [version])).sort((a, b) => a.localeCompare(b, 'en', { numeric: true })).pop();
+const axis = (asker, evidence) => {
+    if (!known(asker) || evidence.length === 0)
+        return 'unknown';
+    return evidence.includes(asker) ? 'same' : 'differs';
+};
+export const deltaOf = (asker, read) => {
+    const version = asker?.harnessVersion;
+    const latest = newest(read.harnessVersions);
+    const model = axis(asker?.model, read.models);
+    const lastDay = publicDay(read.lastDay);
+    const today = publicDay(asker?.day ?? null);
+    return {
+        harness: axis(asker?.harness, read.harnesses),
+        harnessVersions: known(version) && latest !== undefined ? (lastGap(version, latest) ?? null) : null,
+        model,
+        modelVersions: model === 'unknown' ? null : read.models.filter((name) => name !== asker?.model).length,
+        // A cell's frame bucket holds no platform, shell, or stack, so a read cannot state them: unknown, never a guess of `same`.
+        platform: 'unknown',
+        shell: 'unknown',
+        stack: 'unknown',
+        toolVersion: null,
+        ageDays: lastDay === null || today === null ? null : Math.round((Date.parse(today) - Date.parse(lastDay)) / DAY_MS),
+    };
+};
+const closedNames = (values, isPublic) => values.flatMap((value) => {
+    const name = isPublic(value);
+    return known(name) ? [name] : [];
+});
+/** A class P row an agent also reads over MCP, so its names pass the same closed tests a rendered answer does, and a value they refuse is dropped. */
+export const evidenceOf = (read, asker) => ({
+    ref: READ_ID.test(read.readId) ? read.readId : LITERAL,
+    frameRange: { harnesses: closedNames(read.harnesses, harnessName), harnessVersions: closedNames(read.harnessVersions, publicVersion), models: closedNames(read.models, publicModel) },
+    firstDay: publicDay(read.firstDay),
+    lastDay: publicDay(read.lastDay),
+    n: read.n,
+    clusters: read.clusters,
+    delta: deltaOf(asker, read),
+});
+export const count = (value, noun) => `${String(value)} ${noun}${value === 1 ? '' : 's'}`;
+/** A range of public versions, newest last; a version the vocabulary refuses is dropped, never shown. */
+const versionRange = (versions) => {
+    const shown = closedNames(versions, publicVersion);
+    if (shown.length === 0)
+        return 'version unknown';
+    const sorted = [...shown].sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+    const [first] = sorted;
+    const last = sorted[sorted.length - 1];
+    return first === last ? String(first) : `${String(first)}-${String(last)}`;
+};
+const modelsOf = (models) => {
+    const shown = closedNames(models, publicModel);
+    return shown.length === 0 ? 'model unknown' : shown.join(', ');
+};
+const signed = (value) => (value > 0 ? `+${String(value)}` : String(value));
+const distance = (delta) => {
+    const harness = delta.harness !== 'same' ? delta.harness : delta.harnessVersions === null ? 'same, version gap unknown' : delta.harnessVersions === 0 ? 'same' : signed(delta.harnessVersions);
+    const age = delta.ageDays === null ? 'unknown' : count(delta.ageDays, 'day');
+    return `from you: harness ${harness}, model ${delta.model}, age ${age}`;
+};
+const isCanonical = (name) => CANONICAL_ACTIONS.some((action) => action === name);
+/** What a native tool is to the harnesses a read ran under: the first table that lists it, else what any of them can say of it. A read naming no harness asks every table. */
+const toolOf = (read, tool) => {
+    const tables = Object.entries(ACTION_TABLES).filter(([name]) => read.harnesses.includes(name));
+    const said = (tables.length === 0 ? Object.values(ACTION_TABLES) : tables.map(([, table]) => table)).map((table) => actionOf(table, tool));
+    return said.find((entry) => entry.native !== LITERAL) ?? said.find((entry) => entry.action !== 'other') ?? { action: 'other', native: LITERAL };
+};
+/** A stored motif read's name: its class, or its canonical steps without their identities. Undefined for a name that is neither, such as a native tool. */
+const motifOf = (tool) => {
+    if (PROMPT_CLASSES.some((cls) => cls === tool))
+        return tool;
+    const steps = tool.split('>').map((step) => step.replace(/\[.*$/, ''));
+    return steps.every(isCanonical) ? steps.join('>') : undefined;
+};
+const nameOf = (read) => {
+    // An entity read is about the name itself, which need not be a tool: `actionOf` would read a model or a server as `other`, naming nothing.
+    if (read.family === 'entity')
+        return closedName(read.tool);
+    // A stored read whose slice names no motif or action goes by its family, which is a closed name too.
+    if (read.tool === read.family)
+        return read.family;
+    const motif = motifOf(read.tool);
+    if (motif !== undefined)
+        return motif;
+    const { action, native } = toolOf(read, read.tool);
+    const name = native === LITERAL ? action : native;
+    const keys = read.keys.filter(isKeyName);
+    return keys.length === 0 ? name : `${name} [${keys.join(', ')}]`;
+};
+/** Several tools can sit behind one action, and the same word twice would read as two things, so each action is stated once with the sum. A next-step read already states actions. */
+const followedActions = (read) => {
+    const sums = new Map();
+    for (const [tool, times] of read.followed) {
+        const action = isCanonical(tool) ? tool : toolOf(read, tool).action;
+        sums.set(action, (sums.get(action) ?? 0) + times);
+    }
+    return [...sums].sort((a, b) => b[1] - a[1]);
+};
+/** What a read with no denominator counts. A model is not called: its entity read counts the transcript lines that requested it. */
+const nounOf = (read) => {
+    if (read.family === 'entity')
+        return read.models.includes(read.tool) ? 'request' : 'call';
+    if (read.family === 'next-step')
+        return 'call';
+    return read.family === 'recovery' || read.family === 'fit' ? 'error' : 'observation';
+};
+const line = (read, asker) => {
+    const followed = followedActions(read);
+    const failures = read.calls === null ? count(read.count, nounOf(read)) : `failed ${String(read.count)} of ${count(read.calls, 'call')}`;
+    const harnesses = read.harnesses.flatMap((name) => harnessName(name) ?? []);
+    const lastDay = publicDay(read.lastDay) ?? 'unknown';
+    const id = READ_ID.test(read.readId) ? read.readId : LITERAL;
+    const parts = [
+        `${nameOf(read)} | ${failures}, ${count(read.n, 'session')}, ${count(read.clusters, 'cluster')} | ${harnesses.join(', ') || 'harness unknown'} ${versionRange(read.harnessVersions)}, ${modelsOf(read.models)}, last ${lastDay}`,
+        `  ${distance(deltaOf(asker, read))}`,
+        ...(followed.length === 0 ? [] : [`  then: ${followed.map(([action, times]) => `${action} x${String(times)}`).join(', ')}`]),
+        `  read ${id} (${read.family})`,
+    ];
+    return { text: parts.join('\n'), names: followed.map(([action]) => action) };
+};
+const PREAMBLE = 'oars recall, counts from earlier sessions:';
+export const renderAnswer = (reads, asker) => {
+    if (reads.length === 0)
+        return { rendered: '', names: [] };
+    const lines = reads.map((read) => line(read, asker));
+    return { rendered: [PREAMBLE, ...lines.map((entry) => entry.text)].join('\n'), names: [...new Set(lines.flatMap((entry) => entry.names))] };
+};
+/** The text for a miss: what was asked for is left out, because the asker wrote it. */
+export const MISS_TEXT = 'oars recall: no answer in the local store.';

package/dist/sessions/redact.d.ts

@@ -0,0 +1,6 @@
+export declare const PATTERNS: ReadonlyArray<readonly [RegExp, string]>;
+/** Shannon entropy in bits per character. */
+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;

package/dist/sessions/redact.js

@@ -0,0 +1,54 @@
+// 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.
+export const PATTERNS = [
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g, '<secret>'],
+    [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, '<secret>'],
+    [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, '<secret>'],
+    [/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, '<secret>'],
+    [/\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}\b/g, '<secret>'],
+    [/\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{10,}\b/g, '<secret>'],
+    [/\bwhsec_[A-Za-z0-9]{10,}\b/g, '<secret>'],
+    [/\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g, '<secret>'],
+    [/\bAIza[0-9A-Za-z_-]{30,}\b/g, '<secret>'],
+    [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, '<secret>'],
+    [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{12,}/gi, '$1 <secret>'],
+    // user:password@host inside a URL
+    [/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/:@]+:[^\s/@]+@/gi, '$1<secret>@'],
+    // NAME=value and "name": "value" where the name says it is a secret
+    [/\b([A-Za-z0-9_-]*(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|credential)[A-Za-z0-9_-]*)(["']?\s*[=:]\s*)(["']?)[^\s"'&,;]{4,}\3/gi, '$1$2$3<secret>$3'],
+];
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+/g;
+// A pinned alias, `foo@npm:bar@1.0.0` or `jsr:@scope/bar@1.0.0`, ends in `bar@1.0.0`, which EMAIL reads as an address. Digits and dots after
+// the `@` are a version, never a domain, so that one shape right after `npm:` or `jsr:` (and an optional scope) is kept. An all-numeric four-part tail is an
+// IP address, a real host, so it stays masked (as in `extract.ts` `VERSIONED`); any other address stays masked too.
+const ALIAS_PREFIX = /(?<![A-Za-z0-9])(?:npm|jsr):(?:@[A-Za-z0-9._~-]+\/)?$/;
+const DOTTED_VERSION = /@(?!\d+\.\d+\.\d+\.\d+$)\d+(?:\.\d+)+$/;
+const TOKEN = /[A-Za-z0-9+_=-]{24,}/g;
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Shannon entropy in bits per character. */
+export const entropy = (text) => {
+    const counts = new Map();
+    for (const char of text)
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    let bits = 0;
+    for (const count of counts.values()) {
+        const p = count / text.length;
+        bits -= p * Math.log2(p);
+    }
+    return bits;
+};
+const looksRandom = (token) => /[a-z]/.test(token) && /[A-Z]/.test(token) && /\d/.test(token) && entropy(token) >= 4;
+/** `domains` are the organization domains to mask (`example.com` also masks `mail.example.com`). */
+export const makeRedactor = (domains = []) => {
+    const domainRule = domains.length === 0 ? undefined : new RegExp(`(?:[A-Za-z0-9-]+\\.)*(?:${domains.map((domain) => escapeRegExp(domain.toLowerCase())).join('|')})\\b`, 'gi');
+    return (text) => {
+        let out = text;
+        for (const [pattern, replacement] of PATTERNS)
+            out = out.replace(pattern, replacement);
+        out = out.replace(EMAIL, (match, offset, whole) => DOTTED_VERSION.test(match) && ALIAS_PREFIX.test(whole.slice(0, offset)) ? match : '<email>');
+        if (domainRule !== undefined)
+            out = out.replace(domainRule, '<org-domain>');
+        return out.replace(TOKEN, (token) => (looksRandom(token) ? '<secret>' : token));
+    };
+};

package/dist/sessions/repo-root.d.ts

@@ -0,0 +1,10 @@
+/** A resolver for working directories; answers are cached, since a transcript repeats a handful of directories thousands of times. */
+export declare const makeRepoRoot: (exists?: (path: string) => boolean) => ((cwd: string) => string | null);
+/** `https://User:pw@GitHub.com/org/repo.git`, `git@github.com:org/repo.git`, and `ssh://git@github.com/org/repo/` all read `github.com/org/repo`. */
+export declare const normalizeRemote: (url: string) => string;
+/**
+ * A resolver from a repository root to its identity string: `origin:<normalized remote>` when the repository's `config` names an
+ * `origin`, else `path:<root>`. The `config` is `<root>/.git/config`, or for a linked worktree (`.git` is a file) the common
+ * directory's, reached through the file's `gitdir:` line and that directory's `commondir` file. Any step failing falls back to the path.
+ */
+export declare const makeRepoIdentity: (read?: (path: string) => string | null) => ((root: string) => string);

package/dist/sessions/repo-root.js

@@ -0,0 +1,101 @@
+// The repository root a working directory sits in, for hashing file paths from the repository rather than from wherever the harness ran
+// (spec Section 1.1, CAPTURE 4). A linked worktree under `<root>/.claude/worktrees/<name>` resolves to `<root>`, as A9 counted it; any
+// other directory resolves to the nearest ancestor holding a `.git` entry (a folder, or the file a linked worktree keeps). The walk
+// looks at the file system rather than running `git rev-parse`, so it costs no process per distinct directory and still answers for a
+// directory that has since been deleted (it walks up to the nearest ancestor that exists). Absent a repository it answers null.
+//
+// `makeRepoIdentity` names the repository itself, so two clones of one repository, or one clone on two machines, share a `repo` value:
+// the normalized `origin` remote URL read from the repository's `config` (no git process), else the absolute root path.
+import { existsSync, readFileSync } from 'node:fs';
+import { posix } from 'node:path';
+const WORKTREE = /^(.+?)\/\.claude\/worktrees\/[^/]+(?:\/.*)?$/;
+/** A resolver for working directories; answers are cached, since a transcript repeats a handful of directories thousands of times. */
+export const makeRepoRoot = (exists = existsSync) => {
+    const cache = new Map();
+    return (cwd) => {
+        const start = cwd.replace(/\\/g, '/').replace(/\/+$/, '');
+        const known = cache.get(start);
+        if (known !== undefined)
+            return known;
+        const linked = WORKTREE.exec(start);
+        let found = linked?.[1] ?? null;
+        // posix.dirname('C:') is '.', which would probe the deposit process's own directory: stop at a drive or filesystem root first.
+        for (let dir = start; found === null;) {
+            if (exists(`${dir}/.git`))
+                found = dir;
+            const parent = posix.dirname(dir);
+            if (found !== null || parent === '.' || parent === dir)
+                break;
+            dir = parent;
+        }
+        cache.set(start, found);
+        return found;
+    };
+};
+/** `https://User:pw@GitHub.com/org/repo.git`, `git@github.com:org/repo.git`, and `ssh://git@github.com/org/repo/` all read `github.com/org/repo`. */
+export const normalizeRemote = (url) => {
+    const bare = url
+        .trim()
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, '')
+        .replace(/^[^@/]*@/, '')
+        .replace(/^([^/:]+):(?!\d+(?:\/|$))/, '$1/')
+        .replace(/\/+$/, '')
+        .replace(/\.git$/, '')
+        .replace(/\/+$/, '');
+    const slash = bare.indexOf('/');
+    return slash < 0 ? bare.toLowerCase() : `${bare.slice(0, slash).toLowerCase()}${bare.slice(slash)}`;
+};
+/** The `url` of `[remote "origin"]` in a git `config`, or null. */
+const originUrl = (config) => {
+    let inOrigin = false;
+    for (const line of config.split(/\r?\n/)) {
+        const section = /^\s*\[(.*)\]\s*$/.exec(line);
+        if (section !== null)
+            inOrigin = /^remote\s+"origin"$/i.test(section[1] ?? '');
+        else if (inOrigin) {
+            const url = /^\s*url\s*=\s*(.+?)\s*$/i.exec(line);
+            if (url !== null)
+                return url[1] ?? null;
+        }
+    }
+    return null;
+};
+const isAbsolutePath = (path) => path.startsWith('/') || /^[A-Za-z]:\//.test(path);
+const resolveFrom = (base, path) => (isAbsolutePath(path) ? path : posix.normalize(`${base}/${path}`));
+/** The text of a file, or null when it cannot be read. */
+const readOrNull = (path) => {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * A resolver from a repository root to its identity string: `origin:<normalized remote>` when the repository's `config` names an
+ * `origin`, else `path:<root>`. The `config` is `<root>/.git/config`, or for a linked worktree (`.git` is a file) the common
+ * directory's, reached through the file's `gitdir:` line and that directory's `commondir` file. Any step failing falls back to the path.
+ */
+export const makeRepoIdentity = (read = readOrNull) => {
+    const cache = new Map();
+    const configOf = (root) => {
+        const direct = read(`${root}/.git/config`);
+        if (direct !== null)
+            return direct;
+        const pointer = /^gitdir:\s*(.+?)\s*$/m.exec(read(`${root}/.git`) ?? '')?.[1];
+        if (pointer === undefined)
+            return null;
+        const gitdir = resolveFrom(root, pointer);
+        const common = read(`${gitdir}/commondir`)?.trim();
+        return read(`${common === undefined || common === '' ? gitdir : resolveFrom(gitdir, common)}/config`);
+    };
+    return (root) => {
+        const known = cache.get(root);
+        if (known !== undefined)
+            return known;
+        const url = originUrl(configOf(root) ?? '');
+        const identity = url === null ? `path:${root.toLowerCase()}` : `origin:${normalizeRemote(url)}`;
+        cache.set(root, identity);
+        return identity;
+    };
+};