@manyoars/oars 0.4.1 → 0.5.2

package/dist/sessions/cells.js

@@ -7,6 +7,13 @@ import { CALL_SHAPE_METHOD, cellRef, contentHash, METHODS, RECOVERY_EDGE_METHOD
 import { recoveryCallsOf } from './recovery-calls.js';
 import { NO_RECALLS } from './recall-consequence.js';
 import { ERROR_CODES, EXTRACTOR_VERSION, harnessOf, observesUsage } from './schema.js';
+/** The last field of a stored cell key. `unknown` is 0 so every key written before held existed keeps its meaning. */
+export const EXPOSURE_CODES = { unknown: 0, shown: 1, held: 2 };
+const statesExposure = (graph) => 'heldPrompt' in graph;
+/** A cell's reading: its own `exposure`, or for a local cell the two readings it can tell apart. */
+export const exposureOfCell = (cell) => cell.exposure ?? (cell.exposed ? 'shown' : 'unknown');
+/** Shown wins over held, and held over unknown: a call in both windows counts as shown. */
+const exposureOf = (shown, held) => (shown ? 'shown' : held ? 'held' : 'unknown');
 export const UNKNOWN = 'unknown';
 /** The class name an effort cell carries: a class motif with no prompt class in it, so a read of prompt classes skips it by this prefix. */
 export const EFFORT_CLASS = 'effort:';
@@ -33,8 +40,39 @@ export const parseRecoveryClass = (cls) => {
     const found = /^recovery:([^/]+)\/([^>/]+)>([^>/]+)$/.exec(cls);
     return found === null ? null : { code: found[1] ?? '', failed: found[2] ?? '', next: found[3] ?? '' };
 };
-/** Whether a class motif names a prompt class, as opposed to one of the side cells (effort, or a failed call's code or what followed it). */
-export const isPromptClass = (cls) => cls !== null && ![EFFORT_CLASS, ERROR_CLASS, ERROR_VERSION_CLASS, RECOVERY_CLASS].some((prefix) => cls.startsWith(prefix));
+/**
+ * The week cell of a call's shape: `shape:<action>/<facet>/<value>`, one facet of what the call held and never a value. It keeps the harness version bucket and no model, so it joins three dimensions: the call's action, the
+ * facet's value, and version. `target` is the class of the path target, `arg` one member of the argument classes (a set is one cell per member, rule 2), `dropped` the `count` bucket of key names not sent, and `keys` the
+ * sorted key names joined by commas, the call-shape method's key (a long tail, so the pool holds it to the thresholded floor). Layer 1 adds one cell per sent key's value feature (`size`, `depth`, `extension`, `dir`, and each
+ * `pattern` feature, its value `<key>=<member>`), per closed value (`enum`, `<key>=<value>`), and per change kind (`change`). A class motif with no prompt class in it, like the others.
+ */
+export const SHAPE_CLASS = 'shape:';
+export const SHAPE_FACETS = ['target', 'arg', 'dropped', 'keys', 'size', 'depth', 'extension', 'dir', 'pattern', 'enum', 'change'];
+export const shapeClass = (action, facet, value) => `${SHAPE_CLASS}${action}/${facet}/${value}`;
+/** The three parts of a shape class name, or null for a name that is not one. An action name and a facet hold no `/`; the value is the rest. */
+export const parseShapeClass = (cls) => {
+    const found = /^shape:([^/]+)\/([^/]+)\/(.+)$/.exec(cls);
+    const facet = SHAPE_FACETS.find((name) => name === found?.[2]);
+    return found === null || facet === undefined ? null : { action: found[1] ?? '', facet, value: found[3] ?? '' };
+};
+/** The facets one call counts in: each that the record holds. A record captured before a facet existed has none of it, so it adds no cell of that facet. */
+export const shapeFacetsOf = (tool) => [
+    ...(tool.targetClass === undefined ? [] : [['target', tool.targetClass]]),
+    ...(tool.argClass ?? []).map((kind) => ['arg', kind]),
+    ...(tool.keysDropped === undefined ? [] : [['dropped', String(bucketOf('count', tool.keysDropped))]]),
+    ...(tool.keys.length === 0 ? [] : [['keys', [...tool.keys].sort().join(',')]]),
+    ...(tool.argFeatures ?? []).flatMap(({ key, valueSize, pathDepth, extension, dirKind, patternFeatures }) => [
+        ['size', `${key}=${valueSize}`],
+        ...(pathDepth === undefined ? [] : [['depth', `${key}=${pathDepth}`]]),
+        ...(extension === undefined ? [] : [['extension', `${key}=${extension}`]]),
+        ...(dirKind === undefined ? [] : [['dir', `${key}=${dirKind}`]]),
+        ...(patternFeatures ?? []).map((feature) => ['pattern', `${key}=${feature}`]),
+    ]),
+    ...(tool.argValues ?? []).map(({ key, enumValue }) => ['enum', `${key}=${enumValue}`]),
+    ...(tool.changeKind ?? []).map((kind) => ['change', kind]),
+];
+/** Whether a class motif names a prompt class, as opposed to one of the side cells (effort, a failed call's code or what followed it, or a call's shape). */
+export const isPromptClass = (cls) => cls !== null && ![EFFORT_CLASS, ERROR_CLASS, ERROR_VERSION_CLASS, RECOVERY_CLASS, SHAPE_CLASS].some((prefix) => cls.startsWith(prefix));
 /** The frame bucket of a cell that joins no axis. */
 export const NO_AXES = '-';
 const ONE_OPERATOR = 1;
@@ -94,7 +132,7 @@ export const cellIdOf = (cell) => {
 };
 /** The usage categories a prompt's tokens add up: thinking is part of the output already billed, so it is not summed. */
 const TOKEN_FIELDS = ['input', 'cacheWrite', 'cacheRead', 'output'];
-const newTally = (motifId, frameBucket, grain, day, exposed) => ({ motifId, frameBucket, grain, day, sessions: new Set(), ok: 0, failed: 0, tokens: 0, recorded: new Set(), recordedUnits: 0, durationMs: 0, exposed });
+const newTally = (motifId, frameBucket, grain, day, exposure) => ({ motifId, frameBucket, grain, day, sessions: new Set(), ok: 0, failed: 0, tokens: 0, recorded: new Set(), recordedUnits: 0, durationMs: 0, exposure });
 const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 /** A frame for a record captured before frames existed, from the fields it does hold, held to the same public vocabulary. */
 const oldFrame = (parts) => closedFrame({
@@ -125,23 +163,23 @@ const linesOf = (tools) => {
 export const deriveCells = (store, graph = NO_RECALLS) => {
     const tallies = new Map();
     const motifs = new Map();
-    const tallyAt = (motif, frameBucket, grain, day, exposed) => {
-        const key = `${motif.motifId}/${frameBucket}/${grain}/${day}/${String(exposed)}`;
+    const tallyAt = (motif, frameBucket, grain, day, exposure) => {
+        const key = `${motif.motifId}/${frameBucket}/${grain}/${day}/${exposure}`;
         const found = tallies.get(key);
         if (found !== undefined)
             return found;
-        const fresh = newTally(motif.motifId, frameBucket, grain, day, exposed);
+        const fresh = newTally(motif.motifId, frameBucket, grain, day, exposure);
         tallies.set(key, fresh);
         return fresh;
     };
     /** The tallies one occurrence counts into: its week cell, and for a one-step shape motif with a known day its live cell too (rule 6). A window of two or more steps, a named motif, and a class motif have no day cell. */
-    const talliesOf = (motif, frame, exposed, frameBucket = frameBucketOf(frame)) => {
+    const talliesOf = (motif, frame, exposure, frameBucket = frameBucketOf(frame)) => {
         motifs.set(motif.motifId, motif);
         const day = frame.day ?? UNKNOWN;
-        const weekly = tallyAt(motif, frameBucket, 'week', weekStartOf(day), exposed);
-        const tallies = motif.level === 'shape' && motif.steps.length === 1 && day !== UNKNOWN ? [weekly, tallyAt(motif, frameBucket, 'day', day, exposed)] : [weekly];
+        const weekly = tallyAt(motif, frameBucket, 'week', weekStartOf(day), exposure);
+        const tallies = motif.level === 'shape' && motif.steps.length === 1 && day !== UNKNOWN ? [weekly, tallyAt(motif, frameBucket, 'day', day, exposure)] : [weekly];
         // Fit's (name, platform, shell) cell: a week cell beside the versioned one, counting the same call.
-        return isPlainCall(motif) ? [...tallies, tallyAt(motif, environmentBucketOf(frame), 'week', weekStartOf(day), exposed)] : tallies;
+        return isPlainCall(motif) ? [...tallies, tallyAt(motif, environmentBucketOf(frame), 'week', weekStartOf(day), exposure)] : tallies;
     };
     const sessions = new Map([...store.sessions, ...store.subagents].map((session) => [session.session, session]));
     const prompts = new Map(store.prompts.map((prompt) => [`${prompt.session}#${String(prompt.index)}`, prompt]));
@@ -161,7 +199,8 @@ export const deriveCells = (store, graph = NO_RECALLS) => {
         for (const { motif, start } of motifsOf(steps)) {
             const window = steps.slice(start, start + motif.steps.length);
             const status = window.at(-1)?.status;
-            for (const tally of talliesOf(motif, frame, placed.slice(start, start + motif.steps.length).some(({ exposed }) => exposed))) {
+            const covered = placed.slice(start, start + motif.steps.length);
+            for (const tally of talliesOf(motif, frame, exposureOf(covered.some(({ exposed }) => exposed), covered.some((step) => 'held' in step && step.held)))) {
                 tally.sessions.add(first.parent);
                 if (status === 'ok')
                     tally.ok += 1;
@@ -188,10 +227,24 @@ export const deriveCells = (store, graph = NO_RECALLS) => {
             const code = ERROR_CODES.has(tool.errorCode) ? tool.errorCode : 'other';
             const motif = classMotif(recoveryClass(code, calls[at]?.steps[0]?.action ?? 'other', followed.next[0] ?? NO_NEXT));
             motifs.set(motif.motifId, motif);
-            const tally = tallyAt(motif, versionBucketOf(frame), 'week', weekStartOf(frame.day ?? UNKNOWN), false);
+            const tally = tallyAt(motif, versionBucketOf(frame), 'week', weekStartOf(frame.day ?? UNKNOWN), 'unknown');
             tally.sessions.add(first.parent);
             tally.failed += 1;
         }
+        // Each call's shape, by its first step's action: a week cell per facet it holds, counted by the call's own status.
+        for (const [at, tool] of line.entries()) {
+            const action = calls[at]?.steps[0]?.action ?? 'other';
+            for (const [facet, value] of shapeFacetsOf(tool)) {
+                const motif = classMotif(shapeClass(action, facet, value));
+                motifs.set(motif.motifId, motif);
+                const tally = tallyAt(motif, versionBucketOf(frame), 'week', weekStartOf(frame.day ?? UNKNOWN), 'unknown');
+                tally.sessions.add(first.parent);
+                if (tool.status === 'ok')
+                    tally.ok += 1;
+                if (tool.status === 'error')
+                    tally.failed += 1;
+            }
+        }
         // The failed calls by their `errorCode` (t868). Rule 6: a day cell exists for a known day only.
         const failedDay = frame.day ?? UNKNOWN;
         for (const tool of failedDay === UNKNOWN ? [] : line) {
@@ -209,7 +262,7 @@ export const deriveCells = (store, graph = NO_RECALLS) => {
                     for (const [prefix, bucket] of [[ERROR_CLASS, `${frame.harness}/${NO_AXES}/${frame.model ?? UNKNOWN}`], [ERROR_VERSION_CLASS, versionBucketOf(frame)]]) {
                         const motif = classMotif(`${prefix}${code}/${name}`);
                         motifs.set(motif.motifId, motif);
-                        const tally = tallyAt(motif, bucket, 'day', failedDay, false);
+                        const tally = tallyAt(motif, bucket, 'day', failedDay, 'unknown');
                         tally.sessions.add(first.parent);
                         tally.failed += 1;
                         if (counted.tokens !== null) {
@@ -226,9 +279,9 @@ export const deriveCells = (store, graph = NO_RECALLS) => {
     for (const prompt of store.prompts) {
         const session = sessions.get(prompt.session);
         const frame = framedPrompt(prompt, harnessOf(session ?? {}), session?.env.harness ?? null, null, session?.env.os ?? UNKNOWN);
-        const exposed = graph.exposedPrompt(prompt.session, prompt.index);
-        const effort = frame.effort === null ? [] : talliesOf(classMotif(effortClass(frame.effort, prompt.usage.thinking)), frame, exposed, NO_AXES);
-        for (const tally of [...talliesOf(classMotif(prompt.cls), frame, exposed), ...effort]) {
+        const exposure = exposureOf(graph.exposedPrompt(prompt.session, prompt.index), statesExposure(graph) && graph.heldPrompt(prompt.session, prompt.index));
+        const effort = frame.effort === null ? [] : talliesOf(classMotif(effortClass(frame.effort, prompt.usage.thinking)), frame, exposure, NO_AXES);
+        for (const tally of [...talliesOf(classMotif(prompt.cls), frame, exposure), ...effort]) {
             tally.sessions.add(prompt.session);
             if (prompt.errors > 0)
                 tally.failed += 1;
@@ -245,9 +298,10 @@ export const deriveCells = (store, graph = NO_RECALLS) => {
             tally.durationMs += (prompt.wallSec ?? 0) * 1000;
         }
     }
+    const stated = statesExposure(graph);
     const cells = [...tallies.values()]
-        .sort((a, b) => compare(a.motifId, b.motifId) || compare(a.frameBucket, b.frameBucket) || compare(a.grain, b.grain) || compare(a.day, b.day) || Number(a.exposed) - Number(b.exposed))
-        .map((tally) => ({ motifId: tally.motifId, frameBucket: tally.frameBucket, grain: tally.grain, day: tally.day, sessions: tally.sessions.size, clusters: ONE_OPERATOR, ok: tally.ok, failed: tally.failed, tokens: tally.recorded.size === 0 ? null : tally.tokens, tokenSessions: tally.recorded.size, tokenPrompts: tally.recordedUnits, durationMs: tally.durationMs, exposed: tally.exposed }));
+        .sort((a, b) => compare(a.motifId, b.motifId) || compare(a.frameBucket, b.frameBucket) || compare(a.grain, b.grain) || compare(a.day, b.day) || EXPOSURE_CODES[a.exposure] - EXPOSURE_CODES[b.exposure])
+        .map((tally) => ({ motifId: tally.motifId, frameBucket: tally.frameBucket, grain: tally.grain, day: tally.day, sessions: tally.sessions.size, clusters: ONE_OPERATOR, ok: tally.ok, failed: tally.failed, tokens: tally.recorded.size === 0 ? null : tally.tokens, tokenSessions: tally.recorded.size, tokenPrompts: tally.recordedUnits, durationMs: tally.durationMs, exposed: tally.exposure === 'shown', ...(stated ? { exposure: tally.exposure } : {}) }));
     return { cells, motifs: [...motifs.values()].sort((a, b) => compare(a.motifId, b.motifId)) };
 };
 export const serializeCells = (cells) => cells.map((cell) => `${JSON.stringify(cell)}\n`).join('');

package/dist/sessions/codex-hook-bin.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sessions/codex-hook-bin.js

@@ -0,0 +1,24 @@
+// The entry file Codex runs for the recording hook: `node codex-hook-bin.js`, with the hook event JSON on stdin. It imports only the store modules
+// (not the CLI) and always exits 0 with no output: a hook must never fail or block a session.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { defaultConfigDir } from '../credentials.js';
+import { runCodexHook } from './codex-hook.js';
+import { appendOwnerOnly } from './owner-only.js';
+try {
+    process.stdin.setEncoding('utf8');
+    let text = '';
+    for await (const chunk of process.stdin)
+        text += String(chunk);
+    const home = homedir();
+    await runCodexHook(text, {
+        storeDir: join(defaultConfigDir(process.env, process.platform, home), 'oars', 'sessions'),
+        home,
+        now: Date.now,
+        append: appendOwnerOnly,
+    });
+}
+catch {
+    // Fail-open.
+}
+process.exitCode = 0;

package/dist/sessions/codex-hook-install.d.ts

@@ -0,0 +1,21 @@
+/** What the install needs from the machine: the Codex home (`codexRoot`), the node binary, and the built `codex-hook-bin.js`. */
+export interface CodexInstall {
+    home: string;
+    nodePath: string;
+    hookBin: string;
+}
+export declare const codexHooksFile: (codex: CodexInstall) => string;
+/** The line the operator reads after an install: Codex does not run the entry until it is trusted. */
+export declare const CODEX_TRUST_NOTICE = "Codex asks you to review and trust a new hook before it runs it; until you do, nothing is recorded. Rows go to hook-rows.jsonl in the oars store, only while codex is allowed, and never leave this machine.";
+export declare const installCodexHook: (codex: CodexInstall) => Promise<{
+    file: string;
+    installed: string[];
+}>;
+export declare const uninstallCodexHook: (codex: CodexInstall) => Promise<{
+    file: string;
+    removed: string[];
+}>;
+export declare const codexHookStatus: (codex: CodexInstall) => Promise<{
+    file: string;
+    installed: string[];
+}>;

package/dist/sessions/codex-hook-install.js

@@ -0,0 +1,47 @@
+// `oars sessions hook install --harness codex`: writes the recording hook's entries into `hooks.json` in the Codex home, merging with what is there.
+// An entry is ours when its command ends with `codex-hook-bin.js"`, so uninstall removes those and nothing else. Nothing here runs on upgrade or on first
+// run, and nothing writes the trust Codex asks for: a non-managed hook is skipped until the operator reviews it in Codex.
+import { join } from 'node:path';
+import { CODEX_HOOK_EVENTS } from './codex-hook.js';
+import { groupsOf, hasOwn, hooksOf, readSettings, withoutOwn, writeSettings } from './install.js';
+const OWN_COMMAND = /codex-hook-bin\.js"$/;
+/** Seconds Codex waits; the hook appends one line and exits, so this is only a ceiling. */
+const TIMEOUT = 5;
+export const codexHooksFile = (codex) => join(codex.home, 'hooks.json');
+/** The line the operator reads after an install: Codex does not run the entry until it is trusted. */
+export const CODEX_TRUST_NOTICE = 'Codex asks you to review and trust a new hook before it runs it; until you do, nothing is recorded. Rows go to hook-rows.jsonl in the oars store, only while codex is allowed, and never leave this machine.';
+export const installCodexHook = async (codex) => {
+    const file = codexHooksFile(codex);
+    const settings = await readSettings(file);
+    const hooks = hooksOf(settings);
+    for (const event of CODEX_HOOK_EVENTS) {
+        const entry = { type: 'command', command: `"${codex.nodePath}" "${codex.hookBin}"`, timeout: TIMEOUT };
+        hooks[event] = [...withoutOwn(groupsOf(hooks, event), OWN_COMMAND), { hooks: [entry] }];
+    }
+    settings.hooks = hooks;
+    await writeSettings(file, settings);
+    return { file, installed: [...CODEX_HOOK_EVENTS] };
+};
+export const uninstallCodexHook = async (codex) => {
+    const file = codexHooksFile(codex);
+    const settings = await readSettings(file);
+    const hooks = hooksOf(settings);
+    const removed = CODEX_HOOK_EVENTS.filter((event) => hasOwn(groupsOf(hooks, event), OWN_COMMAND));
+    if (removed.length === 0)
+        return { file, removed: [] };
+    for (const event of removed) {
+        const kept = withoutOwn(groupsOf(hooks, event), OWN_COMMAND);
+        if (kept.length === 0)
+            Reflect.deleteProperty(hooks, event);
+        else
+            hooks[event] = kept;
+    }
+    settings.hooks = Object.keys(hooks).length === 0 ? undefined : hooks;
+    await writeSettings(file, settings);
+    return { file, removed: [...removed] };
+};
+export const codexHookStatus = async (codex) => {
+    const file = codexHooksFile(codex);
+    const hooks = hooksOf(await readSettings(file));
+    return { file, installed: CODEX_HOOK_EVENTS.filter((event) => hasOwn(groupsOf(hooks, event), OWN_COMMAND)) };
+};

package/dist/sessions/codex-hook-view.d.ts

@@ -0,0 +1,20 @@
+import type { HookRow } from './codex-hook.js';
+/** `beside`: the reader holds this rollout, so its record stands and these rows are shown next to it. `alone`: the reader holds none, so the rows stand by themselves and are degraded. */
+export type Standing = 'beside' | 'alone';
+export interface HookGroup {
+    /** The thread the rows name; null when the payload carried none. */
+    session: string | null;
+    /** Set for a subagent's rows, which carry the parent's session id. */
+    agentId: string | null;
+    standing: Standing;
+    /** True when the rows stand alone, so the record they make is the degraded one. */
+    degraded: boolean;
+    /** The rows as written, in order: not copied into a reader record, and not counted as one. */
+    rows: readonly HookRow[];
+}
+/**
+ * Groups `rows` by the thread they name (and by subagent, when they name one). A subagent's row carries the parent's session id, so keying it to the
+ * parent's rollout would fold one agent's calls into another's record: it always stands alone. `readerSessions` holds the session ids of the rollouts
+ * the reader can read; a rollout it refuses is simply absent from it.
+ */
+export declare const separateHookRows: (rows: readonly HookRow[], readerSessions: ReadonlySet<string>) => HookGroup[];

package/dist/sessions/codex-hook-view.js

@@ -0,0 +1,20 @@
+/**
+ * Groups `rows` by the thread they name (and by subagent, when they name one). A subagent's row carries the parent's session id, so keying it to the
+ * parent's rollout would fold one agent's calls into another's record: it always stands alone. `readerSessions` holds the session ids of the rollouts
+ * the reader can read; a rollout it refuses is simply absent from it.
+ */
+export const separateHookRows = (rows, readerSessions) => {
+    const groups = new Map();
+    for (const row of rows) {
+        const key = JSON.stringify([row.session, row.agentId]);
+        const group = groups.get(key);
+        if (group === undefined)
+            groups.set(key, { session: row.session, agentId: row.agentId, rows: [row] });
+        else
+            group.rows.push(row);
+    }
+    return [...groups.values()].map((group) => {
+        const beside = group.agentId === null && group.session !== null && readerSessions.has(group.session);
+        return { ...group, standing: beside ? 'beside' : 'alone', degraded: !beside };
+    });
+};

package/dist/sessions/codex-hook.d.ts

@@ -0,0 +1,77 @@
+import { type CanonicalAction } from './actions.js';
+import { type ArgClass } from './call-shape.js';
+/** The events the installed entry registers, as Codex names them. */
+export declare const CODEX_HOOK_EVENTS: readonly ["SessionStart", "PostToolUse", "PostModelRequest"];
+export declare const ERROR_FLAGS: readonly ["yes", "no", "unknown"];
+export type ErrorFlag = (typeof ERROR_FLAGS)[number];
+export declare const CWD_CLASSES: readonly ["repo", "home", "other", "none"];
+export type CwdClass = (typeof CWD_CLASSES)[number];
+export declare const RESULT_KINDS: readonly ["string", "object", "array", "null", "absent"];
+export type ResultKind = (typeof RESULT_KINDS)[number];
+/** The counters of one model request: a number the payload gave, else null. */
+export interface HookUsage {
+    input: number | null;
+    cacheRead: number | null;
+    cacheWrite: number | null;
+    output: number | null;
+    thinking: number | null;
+    total: number | null;
+}
+/** One line of `hook-rows.jsonl`. Which fields are set depends on `kind`; `degraded` is true when the payload lacked a field the kind needs, and `missing` names those fields. */
+export interface HookRow {
+    v: 1;
+    source: 'hook';
+    harness: 'codex';
+    kind: 'session' | 'tool' | 'model';
+    at: string;
+    session: string | null;
+    turn: string | null;
+    toolUseId: string | null;
+    /** Set only when the payload names a subagent: such a row carries the parent's session id and is never keyed to the parent thread's rollout. */
+    agentId: string | null;
+    action: CanonicalAction | null;
+    tool: string | null;
+    argClass: ArgClass[] | null;
+    resultKind: ResultKind | null;
+    error: ErrorFlag | null;
+    usage: HookUsage | null;
+    model: string | null;
+    cwdClass: CwdClass | null;
+    degraded: boolean;
+    missing: string[];
+}
+type Obj = {
+    [key: string]: unknown;
+};
+/** `unknown` unless the header Codex writes before the `Output:` line carries an exit line: the command's own text decides nothing, and a response with no such header says nothing. */
+export declare const errorFlagOf: (response: unknown) => ErrorFlag;
+/** The row for one hook payload, or undefined for an event this hook does not record. */
+export declare const hookRowOf: (payload: Obj, at: string, home?: string, repoRoot?: (cwd: string) => string | null) => HookRow | undefined;
+/**
+ * The saved `--allow` and `--deny` list, read strictly: undefined when `state.json` exists and cannot be read as a list of strings. Deposit
+ * treats such a file as an empty list, which allows every source; a hook that did the same would record under a `--deny codex` it lost.
+ */
+export declare const savedList: (storeDir: string) => Promise<string[] | undefined>;
+/**
+ * Whether a row may be written: the saved list allows the `codex` source (the gate deposit applies), and the payload's folder is not one a
+ * saved `--deny` names. The folder test uses the denials alone, because an `--allow codex` entry names no folder and would match none.
+ * A payload with no folder cannot be tested, so it records only when the list holds no denial.
+ */
+export declare const mayRecord: (saved: readonly string[] | undefined, cwd: string | null) => boolean;
+/** What the hook needs from the machine, so a test can stand in for each. */
+export interface CodexHookRuntime {
+    storeDir: string;
+    home: string;
+    now: () => number;
+    /** The lockless append; a failure reaches the note in `hook-calls.jsonl` and no partial row is left. */
+    append: (file: string, text: string) => Promise<void>;
+    /** The repo-root lookup for the folder class; a test stands in for it. */
+    repoRoot?: (cwd: string) => string | null;
+}
+/**
+ * Runs one hook call. It resolves whatever happens, prints nothing, and takes no lock. The row is built whole and written with one append, so a
+ * failure before or during the write leaves no partial row. A call the consent gate refuses leaves no trace at all; one that wrote a row, or
+ * failed, leaves a note in `hook-calls.jsonl` (the failure's first line, masked).
+ */
+export declare const runCodexHook: (stdin: string, runtime: CodexHookRuntime) => Promise<void>;
+export {};

package/dist/sessions/codex-hook.js

@@ -0,0 +1,255 @@
+// The Codex recording hook: when the operator installs it (`oars sessions hook install --harness codex`), Codex runs it after each tool call and
+// each model request, and it appends one closed-vocabulary row to `hook-rows.jsonl`. A row is a separately marked observation (`source: 'hook'`):
+// it is never merged into a record the store reader (`codex.ts`) made from the rollout, so a Codex release that changes the rollout format
+// degrades this record instead of stopping it. No prompt, command, output, or path enters a row; the payload's text is read here and goes no further.
+// Fail-open: the hook prints nothing, takes no lock, and exits 0 on every error, leaving a note in `hook-calls.jsonl`.
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { ACTION_TABLES, actionOf } from './actions.js';
+import { compileAllow, isDenial, slugOf } from './allow.js';
+import { argClassOf } from './call-shape.js';
+import { appendHookCall } from './hook-calls.js';
+import { mkdirOwnerOnly } from './owner-only.js';
+import { makeRepoRoot } from './repo-root.js';
+import { errorLine, tryLog } from './steps.js';
+import { paths } from './store.js';
+// The names the hook payload gives a tool that the rollout's table (`ACTION_TABLES.codex`) does not list: the hook contract says `Bash` and `apply_patch` carry `tool_input.command`.
+const HOOK_TOOLS = new Map([['Bash', 'shell.exec']]);
+/** The events the installed entry registers, as Codex names them. */
+export const CODEX_HOOK_EVENTS = ['SessionStart', 'PostToolUse', 'PostModelRequest'];
+export const ERROR_FLAGS = ['yes', 'no', 'unknown'];
+export const CWD_CLASSES = ['repo', 'home', 'other', 'none'];
+export const RESULT_KINDS = ['string', 'object', 'array', 'null', 'absent'];
+const isObj = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const str = (value) => (typeof value === 'string' && value !== '' ? value : null);
+const count = (value) => (typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null);
+const MODEL_NAME = /^[A-Za-z0-9._:/-]{1,64}$/;
+// A model configured by path (`/models/x.gguf`, `./x`, `~/x`, `C:/x`, `a/b/c`) names a place on the machine, which no row may hold.
+const PATH_SHAPED = /^(?:[/.~]|[A-Za-z]:)|\/.*\//;
+/** A model name as a closed shape: the name when it is plain, else `other`. An `org/model` name is plain; a path is not. */
+const modelOf = (value) => {
+    const name = str(value);
+    return name === null ? null : MODEL_NAME.test(name) && !PATH_SHAPED.test(name) ? name : 'other';
+};
+// The three spellings Codex gives a finished command's outcome (`Exit code: N`, `Process exited with code N`, `exit code N`), at the start of a line.
+const EXIT_LINE = /^[ \t]*(?:exit code:?[ \t]*|process exited with code[ \t]+)(-?\d+)[ \t]*$/im;
+// The line a command's output begins after: the header above it is Codex's, the text below is whatever the command printed.
+const OUTPUT_MARK = /(?:^|\n)Output:\n?/;
+/** `unknown` unless the header Codex writes before the `Output:` line carries an exit line: the command's own text decides nothing, and a response with no such header says nothing. */
+export const errorFlagOf = (response) => {
+    if (typeof response !== 'string')
+        return 'unknown';
+    const mark = OUTPUT_MARK.exec(response);
+    if (mark === null)
+        return 'unknown';
+    const code = EXIT_LINE.exec(response.slice(0, mark.index))?.[1];
+    return code === undefined ? 'unknown' : Number(code) === 0 ? 'no' : 'yes';
+};
+const resultKindOf = (response) => {
+    if (response === undefined)
+        return 'absent';
+    if (response === null)
+        return 'null';
+    if (Array.isArray(response))
+        return 'array';
+    return typeof response === 'string' ? 'string' : 'object';
+};
+const USAGE_KEYS = [
+    ['input', 'input_tokens'],
+    ['cacheRead', 'cached_input_tokens'],
+    ['cacheWrite', 'cache_write_input_tokens'],
+    ['output', 'output_tokens'],
+    ['thinking', 'reasoning_output_tokens'],
+    ['total', 'total_tokens'],
+];
+const blank = (kind, at, payload) => ({
+    v: 1,
+    source: 'hook',
+    harness: 'codex',
+    kind,
+    at,
+    session: str(payload.session_id),
+    turn: str(payload.turn_id),
+    toolUseId: null,
+    agentId: str(payload.agent_id),
+    action: null,
+    tool: null,
+    argClass: null,
+    resultKind: null,
+    error: null,
+    usage: null,
+    model: null,
+    cwdClass: null,
+    degraded: false,
+    missing: [],
+});
+/** What one PostToolUse payload becomes. A field the payload lacks is named in `missing`; one it adds is ignored. */
+const toolRow = (at, payload) => {
+    const row = blank('tool', at, payload);
+    const name = str(payload.tool_name);
+    const aliased = name === null ? undefined : HOOK_TOOLS.get(name);
+    const found = name === null ? undefined : aliased === undefined ? actionOf(ACTION_TABLES.codex, name) : { action: aliased, native: name };
+    row.toolUseId = str(payload.tool_use_id);
+    row.action = found?.action ?? null;
+    row.tool = found?.native ?? null;
+    row.argClass = isObj(payload.tool_input) ? argClassOf(payload.tool_input) : null;
+    row.resultKind = resultKindOf(payload.tool_response);
+    row.error = errorFlagOf(payload.tool_response);
+    row.missing = [
+        ...(row.session === null ? ['session_id'] : []),
+        ...(row.turn === null ? ['turn_id'] : []),
+        ...(row.toolUseId === null ? ['tool_use_id'] : []),
+        ...(name === null ? ['tool_name'] : []),
+        ...(row.argClass === null ? ['tool_input'] : []),
+        ...(payload.tool_response === undefined ? ['tool_response'] : []),
+    ];
+    return row;
+};
+/** What one PostModelRequest payload becomes. `token_usage` is null on a failed or cancelled attempt: the row is then degraded, and carries no counts. */
+const modelRow = (at, payload) => {
+    const row = blank('model', at, payload);
+    row.model = modelOf(payload.model);
+    const usage = payload.token_usage;
+    const missing = [...(row.session === null ? ['session_id'] : []), ...(row.turn === null ? ['turn_id'] : [])];
+    if (isObj(usage)) {
+        const counters = { input: null, cacheRead: null, cacheWrite: null, output: null, thinking: null, total: null };
+        row.usage = counters;
+        for (const [field, key] of USAGE_KEYS) {
+            counters[field] = count(usage[key]);
+            if (counters[field] === null)
+                missing.push(`token_usage.${key}`);
+        }
+    }
+    else
+        missing.push('token_usage');
+    row.missing = missing;
+    return row;
+};
+/** What the working folder is, as a class and never a path: inside a repository, the home folder itself, anywhere else, or not given. */
+const cwdClassOf = (cwd, home, repoRoot) => {
+    if (cwd === null)
+        return 'none';
+    if (slugOf(cwd) === slugOf(home))
+        return 'home';
+    return repoRoot(cwd) === null ? 'other' : 'repo';
+};
+const sessionRow = (at, payload, home, repoRoot) => {
+    const row = blank('session', at, payload);
+    row.model = modelOf(payload.model);
+    row.cwdClass = cwdClassOf(str(payload.cwd), home, repoRoot);
+    row.missing = [...(row.session === null ? ['session_id'] : []), ...(row.model === null ? ['model'] : []), ...(row.cwdClass === 'none' ? ['cwd'] : [])];
+    return row;
+};
+/** The row for one hook payload, or undefined for an event this hook does not record. */
+export const hookRowOf = (payload, at, home = homedir(), repoRoot = makeRepoRoot()) => {
+    const event = payload.hook_event_name;
+    const row = event === 'PostToolUse' ? toolRow(at, payload) : event === 'PostModelRequest' ? modelRow(at, payload) : event === 'SessionStart' ? sessionRow(at, payload, home, repoRoot) : undefined;
+    if (row !== undefined)
+        row.degraded = row.missing.length > 0;
+    return row;
+};
+/**
+ * The saved `--allow` and `--deny` list, read strictly: undefined when `state.json` exists and cannot be read as a list of strings. Deposit
+ * treats such a file as an empty list, which allows every source; a hook that did the same would record under a `--deny codex` it lost.
+ */
+export const savedList = async (storeDir) => {
+    let text;
+    try {
+        text = await readFile(paths(storeDir).state, 'utf8');
+    }
+    catch (error) {
+        return error instanceof Error && 'code' in error && error.code === 'ENOENT' ? [] : undefined;
+    }
+    try {
+        const state = JSON.parse(text);
+        if (!isObj(state))
+            return undefined;
+        const list = state.allow;
+        if (list === undefined)
+            return [];
+        return Array.isArray(list) && list.every((entry) => typeof entry === 'string') ? list : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Whether a row may be written: the saved list allows the `codex` source (the gate deposit applies), and the payload's folder is not one a
+ * saved `--deny` names. The folder test uses the denials alone, because an `--allow codex` entry names no folder and would match none.
+ * A payload with no folder cannot be tested, so it records only when the list holds no denial.
+ */
+export const mayRecord = (saved, cwd) => {
+    if (saved === undefined || !compileAllow(saved).allows('codex'))
+        return false;
+    const denials = saved.filter(isDenial);
+    if (denials.length === 0)
+        return true;
+    return cwd !== null && compileAllow(denials).allows(slugOf(cwd));
+};
+/**
+ * Reduces every absolute path in a note to `<path>`: a POSIX path, a drive path, or a UNC path, whether or not it sits under the home
+ * folder (a failure's message can name any folder, and no path enters a row or a note). Three passes, widest first: a quoted run that starts
+ * with a path is masked whole, to the last matching quote on the line and with the quotes kept, so a space or an apostrophe in it leaves no
+ * tail; the hook's own home, matched in either separator and any case like the store's home scrub, goes with the rest of its token; then
+ * any bare path token.
+ */
+const TOKEN_TAIL = /[^\s'"`,;)]*/.source;
+const maskPaths = (text, home) => {
+    const quoted = text.replace(/(['"`])(?:[A-Za-z]:[\\/]|\\\\|\/)[^\n]*\1/g, '$1<path>$1');
+    const pattern = home.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/(?:\\\\|\/)/g, '[\\\\/]');
+    const own = home === '' ? quoted : quoted.replace(new RegExp(pattern + TOKEN_TAIL, 'gi'), '<path>');
+    return own.replace(/(?:[A-Za-z]:[\\/]|\\\\|(?<![\w.~<>-])\/)[^\s'"`,;)]*/g, '<path>');
+};
+// JSON.parse's message quotes the input, and the note must hold none of it, so the failure is a fixed line.
+const parse = (text) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error('The hook input is not JSON.');
+    }
+    if (!isObj(parsed))
+        throw new Error('The hook input is not an object.');
+    return parsed;
+};
+/**
+ * Runs one hook call. It resolves whatever happens, prints nothing, and takes no lock. The row is built whole and written with one append, so a
+ * failure before or during the write leaves no partial row. A call the consent gate refuses leaves no trace at all; one that wrote a row, or
+ * failed, leaves a note in `hook-calls.jsonl` (the failure's first line, masked).
+ */
+export const runCodexHook = async (stdin, runtime) => {
+    const started = performance.now();
+    let session = null;
+    let wrote = false;
+    let failure;
+    let failed = false;
+    try {
+        const payload = parse(stdin);
+        session = str(payload.session_id);
+        // The gate comes first, so a denied folder is never walked for its repo root.
+        if (mayRecord(await savedList(runtime.storeDir), str(payload.cwd))) {
+            const row = hookRowOf(payload, new Date(runtime.now()).toISOString(), runtime.home, runtime.repoRoot);
+            if (row !== undefined) {
+                const line = `${JSON.stringify(row)}\n`;
+                await mkdirOwnerOnly(runtime.storeDir);
+                await runtime.append(paths(runtime.storeDir).hookRows, line);
+                wrote = true;
+            }
+        }
+    }
+    catch (thrown) {
+        failed = true;
+        failure = thrown;
+    }
+    if (!wrote && !failed)
+        return;
+    const ms = Math.round(performance.now() - started);
+    // Built only for a failure, and inside the guard, so a message that is not a string cannot throw past the note.
+    const error = failed
+        ? await Promise.resolve()
+            .then(() => errorLine(runtime.storeDir, new Error(maskPaths(failure instanceof Error ? failure.message : String(failure), runtime.home))))
+            .catch(() => 'unknown error')
+        : null;
+    await tryLog(() => appendHookCall(runtime.storeDir, { at: new Date(runtime.now()).toISOString(), event: 'codex-record', session, hit: wrote, ms, error }));
+};