@manyoars/oars 0.2.0 → 0.3.0

package/dist/sessions/hook-index.js

@@ -0,0 +1,157 @@
+// The hook index: a small file written at the end of every deposit so a hook never parses the whole observation log.
+// SessionStart reads `projects` (the recurring signatures per project folder); PostToolUse reads `signatures` (sessions and
+// what followed, by exact signature). Both are pure functions of the store.
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { resolveReads } from './recall-pool.js';
+import { aboveBaseRate, fitReads, toolShapeId } from './recall-reads.js';
+import { expandHome } from './allow.js';
+import { slugOf } from './store.js';
+const INDEX_FILE = 'hook-index.json';
+/** A signature is "recurring" once it has been seen in this many sessions. */
+export const RECURRING_SESSIONS = 2;
+const PER_PROJECT = 12;
+const FOLLOWED = 3;
+/** SessionStart ranks by sessions within this many latest sessions of its repository: the `measure --last 300 --repo` window the G1 reading uses. */
+export const RECENT_SESSIONS = 300;
+const topFollowed = (following) => Object.entries(following)
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, FOLLOWED);
+const tally = () => ({ sessions: new Set(), following: {}, harness: new Set() });
+// The same order `measure` uses, so the window here is the window `measure --last 300 --repo` counts.
+const byStart = (a, b) => (a.tsFirst ?? '').localeCompare(b.tsFirst ?? '') || a.session.localeCompare(b.session);
+const WORKTREE_SLUG = '--claude-worktrees-';
+/**
+ * Groups project folder slugs into repositories without knowing any root: a worktree slug folds into its repository's, and a slug that
+ * extends another stored slug (a subfolder) joins the shortest one, the same extension rule `belongs` applies at recall time.
+ */
+const repositoryOf = (projects) => {
+    const baseOf = (project) => project.split(WORKTREE_SLUG)[0] ?? project;
+    const bases = [...new Set(projects.map(baseOf))].sort((a, b) => a.length - b.length);
+    return (project) => {
+        const base = baseOf(project);
+        return bases.find((candidate) => base === candidate || base.startsWith(`${candidate}-`)) ?? base;
+    };
+};
+export const buildIndex = (store, redactDomains, at, reads = []) => {
+    const projectOf = new Map(store.sessions.map((session) => [session.session, session.project]));
+    // The latest 300 of each repository, not of the whole store: another repository's deposits must not move this one's ranking.
+    const family = repositoryOf([...new Set(store.sessions.map((session) => session.project))]);
+    const byRepository = new Map();
+    for (const session of store.sessions) {
+        const key = family(session.project);
+        const group = byRepository.get(key) ?? [];
+        byRepository.set(key, group);
+        group.push(session);
+    }
+    const recentNames = new Set([...byRepository.values()].flatMap((group) => group.sort(byStart).slice(-RECENT_SESSIONS).map((session) => session.session)));
+    const overall = new Map();
+    const byProject = new Map();
+    for (const error of store.errors) {
+        const project = projectOf.get(error.session);
+        const targets = [overall];
+        if (project !== undefined) {
+            const own = byProject.get(project) ?? new Map();
+            byProject.set(project, own);
+            targets.push(own);
+        }
+        for (const target of targets) {
+            const entry = target.get(error.sig) ?? tally();
+            target.set(error.sig, entry);
+            entry.sessions.add(error.session);
+            if (error.harnessVersion !== null)
+                entry.harness.add(error.harnessVersion);
+            for (const tool of error.next)
+                entry.following[tool] = (entry.following[tool] ?? 0) + 1;
+        }
+    }
+    const signatures = {};
+    for (const [sig, entry] of overall) {
+        if (entry.sessions.size >= RECURRING_SESSIONS)
+            signatures[sig] = { sessions: entry.sessions.size, followed: topFollowed(entry.following) };
+    }
+    const projects = {};
+    for (const [project, sigs] of byProject) {
+        const rows = [...sigs.entries()]
+            .filter(([, entry]) => entry.sessions.size >= RECURRING_SESSIONS)
+            .map(([sig, entry]) => ({
+            sig,
+            sessions: entry.sessions.size,
+            recent: [...entry.sessions].filter((name) => recentNames.has(name)).length,
+            followed: topFollowed(entry.following),
+            harness: [...entry.harness].sort(),
+        }))
+            .filter((row) => row.recent > 0)
+            .sort((a, b) => b.recent - a.recent || b.sessions - a.sessions || a.sig.localeCompare(b.sig))
+            .slice(0, PER_PROJECT);
+        if (rows.length > 0)
+            projects[project] = rows;
+    }
+    return { at, redactDomains: [...redactDomains], projects, signatures, fit: Object.fromEntries(resolveReads(aboveBaseRate(store, fitReads(store)), reads).map((read) => [toolShapeId(read.tool, read.keys), read])) };
+};
+export const indexPath = (storeDir) => join(storeDir, INDEX_FILE);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+// The file is ours; these checks guard a torn or foreign file, and the inner rows are trusted as written (as the store's are).
+const isIndex = (value) => isRecord(value) && isRecord(value.projects) && isRecord(value.signatures) && Array.isArray(value.redactDomains) && typeof value.at === 'string';
+/** The index as written, or undefined when there is none (or it is torn): a hook then says nothing. */
+export const readIndex = async (storeDir) => {
+    try {
+        const parsed = JSON.parse(await readFile(indexPath(storeDir), 'utf8'));
+        return isIndex(parsed) ? parsed : undefined;
+    }
+    catch {
+        // A missing or torn index is "no index".
+        return undefined;
+    }
+};
+/** `<root>/.claude/worktrees/<name>` belongs to `<root>`, so a worktree session sees its repository's history. */
+export const repositoryRoot = (cwd) => {
+    const marker = /[\\/]\.claude[\\/]worktrees[\\/]/.exec(cwd);
+    return marker === null ? cwd : cwd.slice(0, marker.index);
+};
+/** A project folder belongs to the repository when its slug is the root's slug or extends it (a subfolder or a worktree). */
+const belongs = (project, rootSlug) => project === rootSlug || project.startsWith(`${rootSlug}-`);
+/** True when a project folder slug belongs to the repository `root` sits in (a worktree path counts as its repository). */
+export const inRepository = (project, root) => belongs(project, slugOf(repositoryRoot(resolve(expandHome(root)))));
+const clip = (text, length) => (text.length <= length ? text : `${text.slice(0, length - 1)}…`);
+/** The top recurring signatures for the repository, as a short block for injection; undefined when there is nothing to say. */
+export const contextBlock = (index, options) => {
+    const rootSlug = slugOf(repositoryRoot(options.cwd));
+    const merged = new Map();
+    for (const [project, rows] of Object.entries(index.projects)) {
+        if (!belongs(project, rootSlug))
+            continue;
+        for (const row of rows) {
+            if (options.harness !== undefined && !row.harness.includes(options.harness))
+                continue;
+            const have = merged.get(row.sig);
+            if (have === undefined) {
+                merged.set(row.sig, { ...row });
+                continue;
+            }
+            have.sessions += row.sessions;
+            have.recent += row.recent;
+            const following = {};
+            for (const [tool, count] of [...have.followed, ...row.followed])
+                following[tool] = (following[tool] ?? 0) + count;
+            have.followed = topFollowed(following);
+        }
+    }
+    const rows = [...merged.values()].sort((a, b) => b.recent - a.recent || b.sessions - a.sessions || a.sig.localeCompare(b.sig)).slice(0, options.top);
+    if (rows.length === 0)
+        return undefined;
+    const header = `oars recall: errors that recur in this repository's earlier sessions${options.harness === undefined ? '' : ` (Claude Code ${options.harness})`}. Check these before retrying:`;
+    const lines = rows.map((row) => {
+        const followed = row.followed.map(([tool]) => tool).join(', ');
+        return `- ${clip(row.sig, 120)} (${String(row.recent)} sessions in the last ${String(RECENT_SESSIONS)}${followed === '' ? '' : `; next: ${followed}`})`;
+    });
+    const kept = [];
+    let used = header.length;
+    for (const line of lines) {
+        if (used + 1 + line.length > options.maxChars)
+            break;
+        kept.push(line);
+        used += 1 + line.length;
+    }
+    return kept.length === 0 ? undefined : [header, ...kept].join('\n');
+};

package/dist/sessions/hooks.d.ts

@@ -0,0 +1,13 @@
+import type { HookCall } from './schema.js';
+import { type SessionsRuntime } from './store.js';
+export type HookEvent = HookCall['event'];
+export declare const HOOK_EVENTS: readonly HookEvent[];
+/** The runtime a hook process runs with. Only `nightly` reads the non-Claude stores (a saved `--allow cursor` or `--allow codex`); the Stop path stays free of it. */
+export declare const hookRuntime: (event: HookEvent, env: {
+    [name: string]: string | undefined;
+}, platform: NodeJS.Platform, home: string, io: Pick<SessionsRuntime, "stdin" | "stdout">) => SessionsRuntime;
+/**
+ * Runs one hook. It never fails or blocks the session it runs in: whatever happens, it resolves (the process exits 0), and the
+ * hook-call line records the outcome, with the failure's first line when there was one, so the record is evidence, not a claim.
+ */
+export declare const runHook: (event: HookEvent, stdin: string, runtime: SessionsRuntime, now: () => number) => Promise<string | undefined>;

package/dist/sessions/hooks.js

@@ -0,0 +1,170 @@
+// The hook entry points. Each takes the hook's stdin and returns the text for stdout (or undefined for none). They are fail-open:
+// any error inside one is swallowed, so a hook can never fail or block a Claude Code session. Each call is counted in
+// `hook-calls.jsonl` with its own duration, so `measure` can count recall calls per session and the timings can be checked.
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { defaultConfigDir } from '../credentials.js';
+import { cursorRoot } from './cursor.js';
+import { SOURCES, sourceLabel } from './sources.js';
+import { signatureOf } from './extract.js';
+import { appendHookCall } from './hook-calls.js';
+import { contextBlock, readIndex } from './hook-index.js';
+import { pushRecall } from './recall-push.js';
+import { toolShapeId } from './recall-reads.js';
+import { makeRedactor } from './redact.js';
+import { errorLine, inputKey, logStep, newContext, runDeposit, stampKey, tryLog } from './steps.js';
+import { deposit, depositSession, readSaved } from './store.js';
+import { recordSurvival } from './survival.js';
+export const HOOK_EVENTS = ['session-start', 'pre-tool', 'post-tool', 'stop', 'nightly'];
+const TOP = 5;
+const MAX_CHARS = 1200;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const parse = (stdin) => {
+    try {
+        const parsed = JSON.parse(stdin);
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+};
+const str = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
+const additional = (eventName, context) => `${JSON.stringify({ hookSpecificOutput: { hookEventName: eventName, additionalContext: context } })}\n`;
+const sessionStart = async (runtime, input) => {
+    const cwd = str(input.cwd);
+    const index = cwd === undefined ? undefined : await readIndex(runtime.storeDir);
+    const block = index === undefined || cwd === undefined ? undefined : contextBlock(index, { cwd, top: TOP, maxChars: MAX_CHARS });
+    return block === undefined ? { hit: false, queried: index !== undefined } : { output: additional('SessionStart', block), hit: true, queried: true };
+};
+const inputKeys = (input) => (isRecord(input.tool_input) ? Object.keys(input.tool_input) : []);
+/**
+ * The fit push. The only output this hook writes is `additionalContext`: it holds no permission decision and changes no input, so whatever it does, the call runs as asked.
+ * A call with no read says nothing and logs no recall step: that is nearly every call, and nobody asked. A held push is a hit, for what it would have shown, with no output.
+ */
+const preTool = async (runtime, input, now) => {
+    const sid = str(input.session_id);
+    const tool = str(input.tool_name);
+    if (sid === undefined || tool === undefined)
+        return { hit: false, queried: false };
+    const index = await readIndex(runtime.storeDir);
+    if (index === undefined)
+        return { hit: false, queried: false };
+    const recall = await pushRecall({ storeDir: runtime.storeDir, sid, tool, keys: inputKeys(input), transcript: str(input.transcript_path), platform: process.platform, at: new Date(now()).toISOString(), index });
+    if (recall === undefined)
+        return { hit: false, queried: false };
+    return recall.arm === 'shown' ? { output: additional('PreToolUse', recall.answer.rendered), hit: true, queried: true } : { hit: true, queried: true };
+};
+/** A failed tool arrives as PostToolUseFailure with the text in `error` (Bash and PowerShell start it with `Exit code N`); a PostToolUse response that starts that way is read too. */
+const failureText = (input) => {
+    const failed = str(input.error);
+    if (failed !== undefined)
+        return failed;
+    const response = str(input.tool_response);
+    return response !== undefined && /^Exit code \d+/.test(response) ? response : undefined;
+};
+const postTool = async (runtime, input) => {
+    const tool = str(input.tool_name);
+    const text = failureText(input);
+    if (tool === undefined || text === undefined)
+        return { hit: false, queried: false };
+    const index = await readIndex(runtime.storeDir);
+    if (index === undefined)
+        return { hit: false, queried: false };
+    const found = index.signatures[signatureOf(tool, text, makeRedactor(index.redactDomains))];
+    if (found === undefined)
+        return { hit: false, queried: true };
+    const followed = found.followed.map(([next]) => next).join(', ');
+    const context = `oars recall: seen in ${String(found.sessions)} sessions; what followed: ${followed === '' ? 'nothing recorded' : followed}`;
+    return { output: additional(str(input.hook_event_name) ?? 'PostToolUseFailure', context), hit: true, queried: true };
+};
+const stop = async (runtime, input, now) => {
+    const transcript = str(input.transcript_path);
+    if (transcript === undefined)
+        return { hit: false, queried: false };
+    // The SessionEnd hook is the `stop` trigger (spec 4.1); derive and index follow at the nightly run, so only a deposit row is logged.
+    const deposited = await runDeposit(newContext(runtime.storeDir, now, 'stop'), false, inputKey('stop', [transcript], []), async (trace) => ({ value: await depositSession(runtime, transcript, now, trace), in: { transcript: 1 } }));
+    return { hit: deposited === 'deposited', queried: false };
+};
+const nightly = async (runtime, now) => {
+    // A state.json that cannot be read is a failed deposit run like any other: its error row and the skipped derive row (spec 4.4) are logged.
+    const saved = await readSaved(runtime.storeDir).catch((failure) => runDeposit(newContext(runtime.storeDir, now, 'nightly'), true, inputKey('nightly', [], []), () => Promise.reject(failure instanceof Error ? failure : new Error(String(failure)))));
+    if (saved.allow.length === 0)
+        return { hit: false, queried: false };
+    const result = await runDeposit(newContext(runtime.storeDir, now, 'nightly'), true, inputKey('nightly', saved.allow, saved.redactDomains), async (trace) => {
+        const done = await deposit(runtime, { allow: saved.allow, redactDomains: saved.redactDomains, now }, trace);
+        return { value: done, in: { transcript: done.sessions + done.subagents + done.unchanged } };
+    });
+    const survival = await recordSurvival(runtime, saved.allow, now);
+    // A source store that could not be read does not fail the run, so the record carries it or nobody sees it.
+    const counts = Object.entries(result.sources);
+    const unreadable = counts.flatMap(([, tally]) => tally.unreadableLogged)[0];
+    if (unreadable !== undefined)
+        return { hit: true, queried: false, error: await errorLine(runtime.storeDir, unreadable) };
+    // A skip for an unsafe session id is likewise reported, never silent (the `rejected` doc in sources.ts); an unreadable store, which names its own reason, takes precedence.
+    const skipped = counts.find(([, tally]) => tally.rejected > 0);
+    if (skipped !== undefined)
+        return { hit: true, queried: false, error: `Skipped ${String(skipped[1].rejected)} ${sourceLabel(skipped[0], runtime.sources ?? SOURCES)} sessions whose id is not a safe file name` };
+    // A survival read that fails every night is otherwise invisible, for the same reason; it comes last because the run itself did not lose a session.
+    return survival === null ? { hit: true, queried: false, error: await errorLine(runtime.storeDir, 'Commit survival not read this run.') } : { hit: true, queried: false };
+};
+/** What a lookup hook looks up, as its recall key (spec 4.2 names none for a lookup): the cwd for session-start, the failure's signature for post-tool, the call's shape for pre-tool; null when it had nothing to look up. */
+const lookupKey = (event, input) => {
+    if (event === 'session-start') {
+        const cwd = str(input.cwd);
+        return cwd === undefined ? null : stampKey(event, cwd);
+    }
+    const tool = str(input.tool_name);
+    if (event === 'pre-tool')
+        return tool === undefined ? null : stampKey(event, toolShapeId(tool, inputKeys(input)));
+    const text = failureText(input);
+    return event === 'post-tool' && tool !== undefined && text !== undefined ? stampKey(event, signatureOf(tool, text, makeRedactor([]))) : null;
+};
+/** The runtime a hook process runs with. Only `nightly` reads the non-Claude stores (a saved `--allow cursor` or `--allow codex`); the Stop path stays free of it. */
+export const hookRuntime = (event, env, platform, home, io) => ({
+    storeDir: join(defaultConfigDir(env, platform, home), 'oars', 'sessions'),
+    projectsRoot: join(env.CLAUDE_CONFIG_DIR ?? join(home, '.claude'), 'projects'),
+    ...(event === 'nightly' ? { cursorRoot: cursorRoot(platform, env, home), sourceRoots: Object.fromEntries(SOURCES.map((source) => [source.name, source.root(platform, env, home)])) } : {}),
+    ...io,
+});
+/**
+ * Runs one hook. It never fails or blocks the session it runs in: whatever happens, it resolves (the process exits 0), and the
+ * hook-call line records the outcome, with the failure's first line when there was one, so the record is evidence, not a claim.
+ */
+export const runHook = async (event, stdin, runtime, now) => {
+    const started = performance.now();
+    let session = null;
+    let outcome = { hit: false, queried: false };
+    let failed = false;
+    let failure;
+    let key = null;
+    try {
+        const input = parse(stdin);
+        key = lookupKey(event, input);
+        session = str(input.session_id) ?? null;
+        if (event === 'session-start')
+            outcome = await sessionStart(runtime, input);
+        else if (event === 'pre-tool')
+            outcome = await preTool(runtime, input, now);
+        else if (event === 'post-tool')
+            outcome = await postTool(runtime, input);
+        else if (event === 'stop')
+            outcome = await stop(runtime, input, now);
+        else
+            outcome = await nightly(runtime, now);
+    }
+    catch (thrown) {
+        failure = thrown;
+        failed = true;
+    }
+    const ms = Math.round(performance.now() - started);
+    // The failure line is masked once, the same for the hook-calls line and the step row beside it; both writes are guarded, so a counter
+    // that cannot be written never costs the session its context.
+    const line = failed ? await errorLine(runtime.storeDir, failure).catch(() => 'unknown error') : outcome.error ?? null;
+    await tryLog(() => appendHookCall(runtime.storeDir, { at: new Date(now()).toISOString(), event, session, hit: outcome.hit, ms, startMs: Math.round(started), error: line }));
+    // A lookup hook that ran a query (or failed trying) is a `recall` step started by its own trigger; the deposit hooks logged their rows as they ran.
+    if (key !== null && (failed || outcome.queried)) {
+        const report = { in: { query: 1 }, out: failed ? {} : { matches: outcome.hit ? 1 : 0 }, key };
+        await tryLog(() => logStep(newContext(runtime.storeDir, now, event), 'recall', failed ? 'error' : 'ok', ms, report, line));
+    }
+    return outcome.output;
+};

package/dist/sessions/identity.d.ts

@@ -0,0 +1,22 @@
+import { type ActionTable, type CanonicalAction } from './actions.js';
+import type { PullIdentity, ShellIdentity, StepIdentity, ToolPull } from './schema.js';
+/** A word of a shell command, as the tokenizer read it. */
+export interface WordOfCommand {
+    text: string;
+    quoted: boolean;
+}
+export declare const NUMBER_FLAG = "-N";
+export declare const isPositional: ({ text, quoted }: WordOfCommand) => boolean;
+/** A pull in public names. A private package's version can still identify it, so it is masked with the name; a stated version stays stated. */
+export declare const pullIdentity: (pull: ToolPull) => PullIdentity;
+/** A shell step whose program is private or unreadable: its flags are its own, so none are kept. */
+export declare const UNREAD_SHELL: ShellIdentity;
+export declare const shellIdentity: (program: string, args: readonly WordOfCommand[], pulls: readonly ToolPull[]) => ShellIdentity;
+/** What a non-shell call's step reads as. `native` comes back masked unless every name it holds is public, since an MCP name spells out its server. */
+export declare const callIdentity: (table: ActionTable, action: CanonicalAction, native: string, shown: string, input: {
+    skill: string | undefined;
+    url: string | undefined;
+}) => {
+    native: string;
+    identity: StepIdentity;
+};

package/dist/sessions/identity.js

@@ -0,0 +1,101 @@
+// A step's `identity` (recall spec Section 2.2): what the step acted on, by action, in public names only. Every name passes through
+// `public-vocabulary.ts`, so what may leave the machine is decided in that one file; anything it does not list becomes `<literal>`.
+import { mcpOf } from './actions.js';
+import { BUNDLING_PROGRAMS, isPublicMcpTool, isRegistryVersion, LITERAL, PUBLIC_FLAGS, PUBLIC_HOSTS, PUBLIC_MCP_SERVERS, PUBLIC_PACKAGES, PUBLIC_PROGRAMS, PUBLIC_SKILLS, PUBLIC_SUBCOMMANDS } from './public-vocabulary.js';
+const orLiteral = (name, allowed) => (allowed.has(name) ? name : LITERAL);
+const SHORT_CLUSTER = /^-[a-z]{1,4}$/;
+const SHORT_LETTER = /^-[A-Za-z]$/;
+// A short flag with a value joined after a non-letter, as in `-c1-200`: the first capture is the name and the rest is the value, which is dropped.
+const JOINED_VALUE = /^(-[A-Za-z])[^A-Za-z]/;
+// `head -20`: the digits are the value and the flag has no name of its own, so every such flag reads alike.
+const BARE_NUMBER = /^-\d+$/;
+export const NUMBER_FLAG = '-N';
+/**
+ * The names one flag word holds, without its value. On a program that bundles, a short cluster reads as its letters, so `-rf` and `-fr` agree;
+ * a value joined to a flag there can still read as letters, one each and never the word. On any other program the cluster is the literal.
+ */
+const flagNames = (text, bundles) => {
+    const name = text.split('=')[0] ?? text;
+    if (name.startsWith('--') || PUBLIC_FLAGS.has(name))
+        return [orLiteral(name, PUBLIC_FLAGS)];
+    if (SHORT_LETTER.test(name))
+        return [name];
+    if (BARE_NUMBER.test(name))
+        return [NUMBER_FLAG];
+    const joined = JOINED_VALUE.exec(name)?.[1];
+    if (joined !== undefined)
+        return [joined];
+    return bundles && SHORT_CLUSTER.test(name) ? Array.from(name.slice(1), (letter) => `-${letter}`) : [LITERAL];
+};
+const flagsOf = (program, args) => {
+    const bundles = BUNDLING_PROGRAMS.has(program);
+    const flags = new Set();
+    for (const { text, quoted } of args) {
+        if (text === '--')
+            break;
+        if (quoted || !text.startsWith('-') || text.includes('$'))
+            continue;
+        for (const name of flagNames(text, bundles))
+            flags.add(name);
+    }
+    return [...flags].sort();
+};
+export const isPositional = ({ text, quoted }) => !quoted && text !== '' && !text.startsWith('-') && !/[$\\/]/.test(text);
+/** A subcommand from the program's own table, wherever a global flag's value left it; a positional word outside the table is the literal. */
+const subOf = (program, args) => {
+    const table = PUBLIC_SUBCOMMANDS.get(program);
+    if (table === undefined)
+        return null;
+    const positional = args.filter(isPositional);
+    const known = positional.find(({ text }) => table.has(text));
+    if (known !== undefined)
+        return known.text;
+    return positional.length === 0 ? null : LITERAL;
+};
+const REGISTRY_OF = {
+    npm: 'npm',
+    pypi: 'pypi',
+    cargo: 'crates',
+    go: 'go',
+    gem: 'rubygems',
+    brew: 'homebrew',
+    skill: 'skill',
+    plugin: 'plugin',
+    mcp: 'mcp',
+};
+/** A pull in public names. A private package's version can still identify it, so it is masked with the name; a stated version stays stated. */
+export const pullIdentity = (pull) => {
+    const name = orLiteral(pull.name, PUBLIC_PACKAGES);
+    const showsVersion = name !== LITERAL && pull.version !== null && isRegistryVersion(pull.version);
+    return { registry: REGISTRY_OF[pull.ecosystem], name, version: pull.version === null ? null : showsVersion ? pull.version : LITERAL };
+};
+/** A shell step whose program is private or unreadable: its flags are its own, so none are kept. */
+export const UNREAD_SHELL = { program: LITERAL, sub: null, flags: [] };
+export const shellIdentity = (program, args, pulls) => {
+    if (!PUBLIC_PROGRAMS.has(program))
+        return UNREAD_SHELL;
+    const identity = { program, sub: subOf(program, args), flags: flagsOf(program, args) };
+    return pulls.length === 0 ? identity : { ...identity, pulls: pulls.map(pullIdentity) };
+};
+const hostOf = (url) => {
+    if (url === undefined || url === '')
+        return { host: null };
+    // The parser drops credentials, the path, and the query, and lower-cases the host; the list then decides.
+    const parsed = URL.canParse(url) ? new URL(url).hostname : '';
+    return { host: orLiteral(parsed, PUBLIC_HOSTS) };
+};
+/** What a non-shell call's step reads as. `native` comes back masked unless every name it holds is public, since an MCP name spells out its server. */
+export const callIdentity = (table, action, native, shown, input) => {
+    if (action === 'web.fetch' || action === 'web.search')
+        return { native: shown, identity: hostOf(input.url) };
+    if (action === 'skill.run')
+        return { native: shown, identity: { skill: orLiteral(input.skill ?? '', PUBLIC_SKILLS) } };
+    const mcp = action === 'mcp.call' ? mcpOf(table, native) : undefined;
+    if (mcp === undefined)
+        return { native: shown, identity: null };
+    if (!PUBLIC_MCP_SERVERS.has(mcp.server))
+        return { native: LITERAL, identity: { server: LITERAL, tool: LITERAL } };
+    if (!table.toolDelimited || !isPublicMcpTool(mcp.server, mcp.tool))
+        return { native: LITERAL, identity: { server: mcp.server, tool: LITERAL } };
+    return { native, identity: { server: mcp.server, tool: mcp.tool } };
+};

package/dist/sessions/install.d.ts

@@ -0,0 +1,54 @@
+export declare const RETENTION_FLOOR = 365;
+export declare const DEFAULT_RETENTION = 30;
+export declare const TASK_NAME = "OarsSessionsNightly";
+/** What the install needs from the machine, so a test can stand in for each. */
+export interface InstallRuntime {
+    nodePath: string;
+    /** Absolute path of the built `hook-bin.js`. */
+    hookBin: string;
+    /** `<claude config dir>/settings.json`. */
+    userSettings: string;
+    cwd: string;
+    /** Runs `schtasks` with these arguments. */
+    schtasks: (args: string[]) => Promise<{
+        code: number;
+        output: string;
+    }>;
+}
+export type Scope = 'user' | 'project' | 'file';
+/** A settings file is open-ended JSON the harness owns; only the keys named here are read or written. */
+interface Json {
+    [key: string]: unknown;
+}
+/**
+ * The post-tool command reads the event first in the hook shell (Git Bash on Windows, where the harness runs hooks) and starts node only
+ * when the failure text carries `Exit code`: a fresh node costs 250 ms to seconds on Windows, the shell builtins a few milliseconds.
+ */
+export declare const commandOf: (runtime: InstallRuntime, arg: string) => string;
+export declare const settingsPath: (runtime: InstallRuntime, scope: Scope, file: string | undefined) => string;
+export declare const readSettings: (path: string) => Promise<Json>;
+/** The retention the file sets: its `cleanupPeriodDays` when a number, else the harness default. */
+export declare const effectiveRetention: (settings: Json) => number;
+export interface InstallResult {
+    file: string;
+    installed: string[];
+    retention: string;
+}
+export declare const installHooks: (runtime: InstallRuntime, path: string, keepRetention: boolean) => Promise<InstallResult>;
+export declare const uninstallHooks: (path: string) => Promise<{
+    file: string;
+    removed: string[];
+}>;
+export interface FileStatus {
+    file: string;
+    scope: Scope;
+    installed: string[];
+    retentionDays: number;
+}
+export declare const hookStatus: (runtime: InstallRuntime, extra: string | undefined) => Promise<FileStatus[]>;
+/** The `schtasks` arguments for the nightly task: the same node and hook-bin the hooks use, at a fixed hour. */
+export declare const scheduleArgs: (runtime: InstallRuntime, hour: number) => string[];
+export declare const SCHEDULE_HOUR = 3;
+export declare const setSchedule: (runtime: InstallRuntime, mode: "nightly" | "off") => Promise<string>;
+export declare const scheduleStatus: (runtime: InstallRuntime) => Promise<string>;
+export {};