@manyoars/oars 0.1.1 → 0.3.0

package/dist/sessions/verify.js

@@ -0,0 +1,286 @@
+// `oars sessions verify`: consistency invariants over a skeleton, run locally before any future upload. A skeleton holds ids,
+// timestamps, tool linkage and token counts, never content, so the check needs nothing the store does not already hold.
+import { CAPTURE_VERSION, OLDEST_READABLE_CAPTURE } from './schema.js';
+/** The order the classes print in: the two scopings a check needs to hold, then the two causes of a total above the sum. */
+const CLASSES = [
+    { cls: 'resume scope', holds: true },
+    { cls: 'subagent transcripts', holds: true },
+    { cls: 'harness side calls', holds: false },
+    { cls: 'other', holds: false },
+];
+const emptyClasses = () => CLASSES.map((entry) => ({ ...entry, checks: 0, example: null }));
+export const INVARIANTS = [
+    'tool_result names an earlier tool_use',
+    'parentUuid resolves in the file',
+    'message timestamps never step back more than 1 s',
+    'assistant lines carry a request id; shared ids have consecutive apiBlockIndex',
+    'thinking tokens never exceed output tokens',
+    'cost-state totals equal summed usage since the process start, subagents included',
+];
+const STEP_BACK_MS = 1000;
+const verifyToolLinkage = (lines) => {
+    const seen = new Set();
+    let checked = 0;
+    let violations = 0;
+    for (const line of lines) {
+        for (const result of line.results) {
+            checked += 1;
+            if (result === null || !seen.has(result))
+                violations += 1;
+        }
+        for (const tool of line.tools)
+            if (tool.id !== null)
+                seen.add(tool.id);
+    }
+    return { name: INVARIANTS[0], checked, violations };
+};
+const verifyParents = (lines) => {
+    const ids = new Set(lines.map((line) => line.uuid).filter((uuid) => uuid !== null));
+    const withParent = lines.filter((line) => line.parentUuid !== null);
+    return { name: INVARIANTS[1], checked: withParent.length, violations: withParent.filter((line) => line.parentUuid !== null && !ids.has(line.parentUuid)).length };
+};
+const verifyTimestamps = (lines) => {
+    const stamps = lines
+        .filter((line) => line.role !== null && line.ts !== null)
+        .map((line) => Date.parse(line.ts ?? ''))
+        .filter((millis) => !Number.isNaN(millis));
+    let violations = 0;
+    for (let index = 1; index < stamps.length; index += 1)
+        if ((stamps[index - 1] ?? 0) - (stamps[index] ?? 0) > STEP_BACK_MS)
+            violations += 1;
+    return { name: INVARIANTS[2], checked: Math.max(stamps.length - 1, 0), violations };
+};
+const verifyRequests = (lines) => {
+    const assistants = lines.filter((line) => line.type === 'assistant');
+    const groups = new Map();
+    let checked = 0;
+    let violations = 0;
+    for (const line of assistants) {
+        checked += 1;
+        if (line.requestId === null) {
+            violations += 1;
+            continue;
+        }
+        groups.set(line.requestId, [...(groups.get(line.requestId) ?? []), line]);
+    }
+    for (const group of groups.values()) {
+        if (group.length < 2 || group.some((line) => line.apiBlockIndex === null))
+            continue;
+        for (let index = 1; index < group.length; index += 1) {
+            checked += 1;
+            if ((group[index]?.apiBlockIndex ?? 0) !== (group[index - 1]?.apiBlockIndex ?? 0) + 1)
+                violations += 1;
+        }
+    }
+    return { name: INVARIANTS[3], checked, violations };
+};
+const verifyThinking = (lines) => {
+    const reporting = lines.filter((line) => line.hasThinking && line.usage !== null);
+    return { name: INVARIANTS[4], checked: reporting.length, violations: reporting.filter((line) => (line.usage?.thinking ?? 0) > (line.usage?.output ?? 0)).length };
+};
+const KEYS = ['input', 'cacheWrite', 'cacheRead', 'output'];
+/** Assistant usage from `since` on. Every content block of one API response is its own line and repeats its usage: once per request id. */
+const sumUsage = (lines, since) => {
+    const sums = { input: 0, cacheWrite: 0, cacheRead: 0, output: 0 };
+    const counted = new Set();
+    for (const line of lines) {
+        if (line.type !== 'assistant' || line.usage === null)
+            continue;
+        if (line.ts !== null && Date.parse(line.ts) < since)
+            continue;
+        if (line.requestId !== null) {
+            if (counted.has(line.requestId))
+                continue;
+            counted.add(line.requestId);
+        }
+        for (const key of KEYS)
+            sums[key] += line.usage[key];
+    }
+    return sums;
+};
+/**
+ * The harness's `cost-state` totals (A2, diagnosed on the operator's store 2026-11-01) cover only the process that wrote them
+ * (from `startTime`, so a resumed session's earlier lines are outside) and include the session's subagent transcripts. Within
+ * that scope the recorded usage must equal the totals, and a sum above them fails. A total above the sum is not a failure: the
+ * harness also counts side calls no transcript records (001cf645's `modelUsage` has a `claude-haiku` entry and no assistant line
+ * of that model), so it is reported as observed, under that class on a key such a model reported a nonzero amount on, else under `other`.
+ * A check that holds only once a scope is applied is counted under that scope.
+ */
+const verifyCost = (lines, delegated, session) => {
+    const last = [...lines].reverse().find((line) => line.costState !== null)?.costState;
+    const observed = emptyClasses();
+    if (last === undefined || last === null)
+        return { name: INVARIANTS[5], checked: 0, violations: 0, observed };
+    const since = last.since === null ? Number.NEGATIVE_INFINITY : Date.parse(last.since);
+    const scoped = sumUsage([...lines, ...delegated], since);
+    const resumed = sumUsage(lines, since);
+    const unscoped = sumUsage(lines, Number.NEGATIVE_INFINITY);
+    const named = new Set([...lines, ...delegated].map((line) => line.model));
+    // A key is a side call only when a model no line names reported a nonzero amount on it; the entries of an older skeleton carry none.
+    const sideKeys = new Set(last.models.filter((entry) => !named.has(entry.model)).flatMap((entry) => entry.keys));
+    const note = (cls) => {
+        const entry = observed.find((candidate) => candidate.cls === cls);
+        if (entry === undefined)
+            return;
+        entry.checks += 1;
+        entry.example ??= session;
+    };
+    let checked = 0;
+    let violations = 0;
+    for (const key of KEYS) {
+        const total = last[key];
+        if (total === null)
+            continue;
+        checked += 1;
+        if (scoped[key] > total)
+            violations += 1;
+        else if (scoped[key] < total)
+            note(sideKeys.has(key) ? 'harness side calls' : 'other');
+        else if (unscoped[key] !== total) {
+            if (resumed[key] !== unscoped[key])
+                note('resume scope');
+            if (scoped[key] !== resumed[key])
+                note('subagent transcripts');
+        }
+    }
+    return { name: INVARIANTS[5], checked, violations, observed };
+};
+/** `delegated` holds the lines of the session's subagent transcripts, which its cost-state totals include. */
+export const verifySkeleton = (skeleton, delegated = []) => [
+    verifyToolLinkage(skeleton.lines),
+    verifyParents(skeleton.lines),
+    verifyTimestamps(skeleton.lines),
+    verifyRequests(skeleton.lines),
+    verifyThinking(skeleton.lines),
+    verifyCost(skeleton.lines, delegated, skeleton.session),
+];
+/** A subagent transcript is stored as `<parent>~...~agent-<id>`; a main session's id holds no `~`. */
+const mainSessionOf = (session) => session.split('~')[0] ?? session;
+/** The subagent transcripts' lines, keyed by the main session they belong to. */
+const delegatedLines = (skeletons) => {
+    const delegated = new Map();
+    for (const skeleton of skeletons) {
+        const parent = mainSessionOf(skeleton.session);
+        if (parent !== skeleton.session)
+            delegated.set(parent, (delegated.get(parent) ?? []).concat(skeleton.lines));
+    }
+    return delegated;
+};
+/** Sums each invariant over many skeletons, each main session's cost-state checked with its subagent transcripts' lines. */
+export const verifyAll = (skeletons, delegatedFrom = skeletons) => {
+    const totals = INVARIANTS.map((name) => ({ name, checked: 0, violations: 0 }));
+    // `--session` filters `skeletons` but row 6 still needs the subagent transcripts' lines, so they come from `delegatedFrom`.
+    const delegated = delegatedLines(delegatedFrom);
+    for (const skeleton of skeletons) {
+        for (const [index, result] of verifySkeleton(skeleton, delegated.get(skeleton.session)).entries()) {
+            const total = totals[index];
+            if (total !== undefined) {
+                total.checked += result.checked;
+                total.violations += result.violations;
+                if (result.observed !== undefined)
+                    total.observed = mergeClasses(total.observed ?? emptyClasses(), result.observed);
+            }
+        }
+    }
+    return totals;
+};
+const mergeClasses = (into, from) => into.map((entry, index) => {
+    const other = from[index];
+    return other === undefined ? entry : { ...entry, checks: entry.checks + other.checks, example: entry.example ?? other.example };
+});
+const classLine = (label, classes) => {
+    const shown = classes.filter((entry) => entry.checks > 0);
+    if (shown.length === 0)
+        return [];
+    const parts = shown.map((entry) => `${String(entry.checks)} ${entry.cls}${entry.example === null ? '' : ` (e.g. ${entry.example})`}`);
+    return [`      ${label}: ${parts.join(', ')}`];
+};
+const formatResult = (result) => {
+    const classes = result.observed ?? [];
+    const above = classes.filter((entry) => !entry.holds);
+    const observed = above.reduce((sum, entry) => sum + entry.checks, 0);
+    const holding = result.checked - result.violations - observed;
+    return [
+        `${result.violations === 0 ? 'PASS' : 'FAIL'}  ${result.name}: ${String(holding)} of ${String(result.checked)} hold${result.violations === 0 ? '' : `, ${String(result.violations)} exceptions`}${observed === 0 ? '' : `, ${String(observed)} observed`}`,
+        ...classLine('equal only within scope', classes.filter((entry) => entry.holds)),
+        ...classLine('total above the recorded sum, as observed', above),
+    ];
+};
+export const formatVerify = (results, sessions) => [`${String(sessions)} skeletons checked`, ...results.flatMap(formatResult)].join('\n');
+export const CAPTURE_INVARIANTS = [
+    'every session is captured at the current capture version (none is cv-behind)',
+    'sessions captured at the current version share one sid',
+    'every fileHash on a session is a path target of one of its tool calls',
+    'a path target names its base; no other target does',
+];
+const HASH = /^[0-9a-f]{16}$/;
+/**
+ * The CAPTURE 4 fields, checked over the store's capture records: cv-behind sessions (a session captured at an older readable
+ * version, not yet captured again, unless `frozen` names it: its transcript is gone from the harness and `raw/` (or, for a Cursor
+ * session, its composer is gone from Cursor), so it is counted apart, never a violation), a mixed `sid` (two salts in one store, so
+ * path joins hold only within each), `fileHashes` that no tool call explains, and `targetBase` set on, or missing from, the wrong
+ * kind of target. Skeleton invariants stay in {@link verifyAll}.
+ */
+export const verifyCaptured = (sessions, tools, frozen = new Set()) => {
+    const current = sessions.filter((session) => session.cv === CAPTURE_VERSION);
+    const readable = sessions.filter((session) => Number(session.cv) >= OLDEST_READABLE_CAPTURE);
+    const counts = new Map();
+    for (const session of current)
+        if (session.sid !== null)
+            counts.set(session.sid, (counts.get(session.sid) ?? 0) + 1);
+    const majority = [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+    const targets = new Map();
+    for (const tool of tools)
+        if (tool.targetBase !== null && tool.target !== null)
+            targets.set(tool.session, (targets.get(tool.session) ?? new Set()).add(tool.target));
+    const currentTools = tools.filter((tool) => tool.cv === CAPTURE_VERSION);
+    return [
+        { name: CAPTURE_INVARIANTS[0], checked: readable.length, violations: readable.filter((session) => Number(session.cv) < Number(CAPTURE_VERSION) && !frozen.has(session.session)).length },
+        { name: CAPTURE_INVARIANTS[1], checked: current.length, violations: current.filter((session) => session.sid !== majority).length },
+        {
+            name: CAPTURE_INVARIANTS[2],
+            checked: current.length,
+            violations: current.filter((session) => session.fileHashes.some((hash) => targets.get(session.session)?.has(hash) !== true)).length,
+        },
+        {
+            name: CAPTURE_INVARIANTS[3],
+            checked: currentTools.length,
+            violations: currentTools.filter((tool) => (tool.targetBase !== null) !== (tool.target !== null && HASH.test(tool.target))).length,
+        },
+    ];
+};
+const statusOf = (result) => (result.violations > 0 ? 'fail' : result.checked === 0 ? 'not run' : 'pass');
+/**
+ * A result for every session with a skeleton or a capture record: {@link verifySkeleton} with the session's subagent transcripts' lines as `delegated`,
+ * then {@link verifyCaptured} over the session's own capture records. A session with no skeleton gets rows 1 to 6 at `checked: 0` (`not run`) and its real
+ * rows 7 to 10. Row 8 (one `sid`) is read within the one session, so it cannot fail for a session with a non-null `sid`; a current-version session with a
+ * null `sid` fails it. The store-wide row stays in `verifyCaptured` over all sessions.
+ */
+export const verifySessions = (skeletons, sessions, tools, frozen = new Set()) => {
+    const delegated = delegatedLines(skeletons);
+    const byId = (records) => {
+        const grouped = new Map();
+        for (const record of records)
+            grouped.set(record.session, (grouped.get(record.session) ?? []).concat(record));
+        return grouped;
+    };
+    const skeletonOf = new Map(skeletons.map((skeleton) => [skeleton.session, skeleton]));
+    const ownSessions = byId(sessions);
+    const ownTools = byId(tools);
+    const ids = [...new Set([...skeletons.map((skeleton) => skeleton.session), ...sessions.map((session) => session.session)])];
+    return ids.map((id) => {
+        const skeleton = skeletonOf.get(id);
+        const skeletonRows = skeleton === undefined ? INVARIANTS.map((name) => ({ name, checked: 0, violations: 0 })) : verifySkeleton(skeleton, delegated.get(id));
+        const results = [...skeletonRows, ...verifyCaptured(ownSessions.get(id) ?? [], ownTools.get(id) ?? [], frozen)];
+        return { session: id, invariants: results.map((result) => ({ ...result, status: statusOf(result) })) };
+    });
+};
+/** Per-session lines the default text prints; the JSON lists them all. */
+export const SESSION_LINE_CAP = 20;
+/** One line per session with a failing row, naming the rows, capped at {@link SESSION_LINE_CAP} with a count of the rest; empty when none fails. Ids and row names only. */
+export const formatSessionResults = (results) => {
+    const lines = results
+        .filter((entry) => entry.invariants.some((row) => row.status === 'fail'))
+        .map((entry) => `      ${entry.session}: FAIL ${entry.invariants.filter((row) => row.status === 'fail').map((row) => row.name).join('; ')}`);
+    return [...lines.slice(0, SESSION_LINE_CAP), ...(lines.length > SESSION_LINE_CAP ? [`      and ${String(lines.length - SESSION_LINE_CAP)} more; --json lists all`] : [])].join('\n');
+};

package/dist/sessions/vocab-load.d.ts

@@ -0,0 +1,26 @@
+/** One package ecosystem: the seeded names with their published versions, and the names that resolve but sit outside `seed_top`. */
+export interface PackageSnapshot {
+    ecosystem: string;
+    seedTop: number;
+    seed: ReadonlyMap<string, ReadonlySet<string>>;
+    resolved: ReadonlySet<string>;
+}
+export interface ProgramEntry {
+    subs: ReadonlySet<string>;
+    flags: ReadonlySet<string>;
+}
+export interface Vocabulary {
+    version: string;
+    snapshotDate: string;
+    packages: ReadonlyMap<string, PackageSnapshot>;
+    programs: ReadonlyMap<string, ProgramEntry>;
+    models: ReadonlySet<string>;
+    harnessVersions: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/** packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. */
+export declare const VOCAB_DIR: import("url").URL;
+export declare const PACKAGE_FILES: readonly ["npm.json", "pypi.json", "crates.json", "rubygems.json", "homebrew.json", "go.json", "maven.json"];
+/** Reads and checks every snapshot under `dir` (default: the shipped folder). */
+export declare const readVocabulary: (dir?: URL) => Vocabulary;
+/** The shipped vocabulary, read once on first use: reading 6 MB of JSON is not free, and most commands never project. */
+export declare const vocabulary: () => Vocabulary;

package/dist/sessions/vocab-load.js

@@ -0,0 +1,61 @@
+// Loads the pinned vocabulary snapshots shipped in packages/cli/vocab/ (pool vocabulary spec Section 1.3). The only file here that reads the disk:
+// public-vocabulary.ts stays free of the filesystem so the pool's Worker can bundle it, and projection.ts takes the loaded `Vocabulary` as an argument.
+// A snapshot that does not parse is an error and never an empty list: an empty list would quietly project every name as `private`.
+import { readFileSync } from 'node:fs';
+import { VOCAB_SNAPSHOT_DATE, VOCAB_VERSION } from './public-vocabulary.js';
+/** packages/cli/vocab/, from src/sessions/ in a test and from dist/sessions/ once built: the same depth. */
+export const VOCAB_DIR = new URL('../../vocab/', import.meta.url);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const recordAt = (value, where) => {
+    if (!isRecord(value))
+        throw new Error(`vocabulary ${where}: expected an object`);
+    return value;
+};
+const stringsAt = (value, where) => {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string'))
+        throw new Error(`vocabulary ${where}: expected a list of strings`);
+    return value.filter((item) => typeof item === 'string');
+};
+const readJson = (dir, file) => recordAt(JSON.parse(readFileSync(new URL(file, dir), 'utf8')), file);
+const packageSnapshot = (dir, file) => {
+    const json = readJson(dir, file);
+    const seed = json['seed'];
+    if (!Array.isArray(seed))
+        throw new Error(`vocabulary ${file}: seed must be a list`);
+    const entries = seed.map((pair) => {
+        if (!Array.isArray(pair) || typeof pair[0] !== 'string')
+            throw new Error(`vocabulary ${file}: a seed entry is [name, versions]`);
+        return [pair[0], new Set(stringsAt(pair[1], `${file} versions`))];
+    });
+    const ecosystem = json['ecosystem'];
+    const seedTop = json['seedTop'];
+    if (typeof ecosystem !== 'string' || typeof seedTop !== 'number')
+        throw new Error(`vocabulary ${file}: ecosystem and seedTop are required`);
+    return { ecosystem, seedTop, seed: new Map(entries), resolved: new Set(stringsAt(json['resolved'], `${file} resolved`)) };
+};
+export const PACKAGE_FILES = ['npm.json', 'pypi.json', 'crates.json', 'rubygems.json', 'homebrew.json', 'go.json', 'maven.json'];
+/** Reads and checks every snapshot under `dir` (default: the shipped folder). */
+export const readVocabulary = (dir = VOCAB_DIR) => {
+    const manifest = readJson(dir, 'manifest.json');
+    const snapshotDate = manifest['snapshotDate'];
+    if (snapshotDate !== VOCAB_SNAPSHOT_DATE) {
+        throw new Error(`vocabulary snapshots are dated ${String(snapshotDate)} but VOCAB_VERSION ${VOCAB_VERSION} pins ${VOCAB_SNAPSHOT_DATE}: bump both together`);
+    }
+    const packages = new Map(PACKAGE_FILES.map((file) => packageSnapshot(dir, file)).map((snapshot) => [snapshot.ecosystem, snapshot]));
+    const programs = new Map(Object.entries(recordAt(readJson(dir, 'programs.json')['programs'], 'programs')).map(([name, entry]) => {
+        const held = recordAt(entry, `programs.${name}`);
+        return [name, { subs: new Set(stringsAt(held['subs'], `programs.${name}.subs`)), flags: new Set(stringsAt(held['flags'], `programs.${name}.flags`)) }];
+    }));
+    const harnesses = recordAt(readJson(dir, 'harness.json')['harnesses'], 'harnesses');
+    return {
+        version: VOCAB_VERSION,
+        snapshotDate,
+        packages,
+        programs,
+        models: new Set(stringsAt(readJson(dir, 'models.json')['ids'], 'models.ids')),
+        harnessVersions: new Map(Object.entries(harnesses).map(([harness, versions]) => [harness, new Set(stringsAt(versions, `harness.${harness}`))])),
+    };
+};
+let loaded;
+/** The shipped vocabulary, read once on first use: reading 6 MB of JSON is not free, and most commands never project. */
+export const vocabulary = () => (loaded ??= readVocabulary());

package/dist/sessions/vscode-copilot.d.ts

@@ -0,0 +1,38 @@
+/** The folder that holds one folder per VS Code build; a test passes its own so it never reads the real one. */
+export declare const vscodeAppData: (platform: NodeJS.Platform, env: {
+    [name: string]: string | undefined;
+}, home?: string) => string;
+type Obj = {
+    [key: string]: unknown;
+};
+/** A session found in the store, before it is read. */
+export interface VscodeSession {
+    /** The file's name without its extension, which is the session id (chatSessionStore.ts:738-741) and names the skeleton. */
+    id: string;
+    /** The workspace's folder; null for an empty window or a remote workspace. */
+    folder: string | null;
+    /** The files that hold it, newest first (the `.jsonl` ahead of the `.json` on a tie); the first that reads is the session. */
+    files: string[];
+    size: number;
+    mtimeMs: number;
+}
+export interface VscodeStore {
+    sessions: VscodeSession[];
+    /** The session as transcript text for `captureSession`; throws when no file of it can be read or holds no parseable entry. */
+    transcript: (session: VscodeSession) => Promise<string>;
+    /** Files skipped because their name is not a safe file name (it names a skeleton), counted so the skip is never silent. */
+    rejected: number;
+    /** Folders and files that could not be inspected, reported once each and never fatal; the reason names no path. */
+    unreadable: {
+        file: string;
+        reason: string;
+    }[];
+}
+/** The non-blank log lines that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
+export declare const chatBadLines: (text: string) => string[];
+/** The chat data a file holds: the `.json` form is the object itself, the `.jsonl` form is replayed. Throws when nothing parses. */
+export declare const chatData: (text: string, jsonl: boolean) => Obj;
+/** One chat session as the lines `captureSession` reads. */
+export declare const chatLines: (data: Obj, fallbackId: string, folder: string | null) => Obj[];
+export declare const openVscodeCopilotStore: (root: string) => Promise<VscodeStore | undefined>;
+export {};