@manyoars/oars 0.4.1 → 0.5.1

package/dist/sessions/copilot.js

@@ -38,6 +38,7 @@ import { readdir, readFile, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { createInterface } from 'node:readline';
+import { holdsOnlyKinds } from './head-only.js';
 /** The Copilot home for an environment; a test passes its own so it never reads the real one. */
 export const copilotRoot = (env, home = homedir()) => {
     const set = env.COPILOT_HOME;
@@ -91,6 +92,9 @@ const iso = (value) => {
 };
 /** The non-blank lines that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
 export const eventBadLines = (text) => text.split('\n').filter((raw) => raw.trim() !== '' && parse(raw) === undefined);
+/** Event types that carry no turn by design: the session's own start, resume, context, model, and shutdown records, its journal link, usage checkpoint, error, and abort. A log of these alone is a session started and quit. */
+const EVENT_HEAD_KINDS = new Set(['session.start', 'session.resume', 'session.context_changed', 'session.model_change', 'session.shutdown', 'session.journal_link', 'session.usage_checkpoint', 'session.error', 'abort']);
+export const eventHeadOnly = (text) => holdsOnlyKinds(text, EVENT_HEAD_KINDS);
 /**
  * The exit code of a shell call: `shellExecution.exitCode` (session-events.ts, ToolExecutionCompleteData, "Experimental shell completion facts"). The
  * schema's `result.contents` also has `shell_exit` parts, but it says `shellExecution` is captured before persisted result contents are stripped, and no
@@ -365,6 +369,11 @@ const joinFiles = (texts) => {
     });
     return kept.join('\n') + (kept.length === 0 ? '' : '\n');
 };
+/** The session's events as one text; a session with no archives is read as it is, and only a rotated one has replayed events to drop. */
+const logText = async (session) => {
+    const texts = await Promise.all([...session.archives, session.file].map((path) => readFile(path, 'utf8')));
+    return session.archives.length === 0 ? (texts[0] ?? '') : joinFiles(texts);
+};
 export const openCopilotStore = async (root) => {
     const base = join(root, 'session-state');
     const unreadable = [];
@@ -375,7 +384,7 @@ export const openCopilotStore = async (root) => {
     catch (error) {
         if (missing(error))
             return undefined;
-        return { sessions: [], transcript: () => Promise.reject(new Error('no sessions')), rejected: 0, unreadable: [{ file: base, reason: reasonOf(error, base) }] };
+        return { sessions: [], transcript: () => Promise.reject(new Error('no sessions')), headOnly: () => Promise.resolve(false), rejected: 0, unreadable: [{ file: base, reason: reasonOf(error, base) }] };
     }
     const sessions = [];
     let rejected = 0;
@@ -421,10 +430,9 @@ export const openCopilotStore = async (root) => {
         sessions,
         rejected,
         unreadable,
+        headOnly: async (session) => eventHeadOnly(await logText(session)),
         transcript: async (session) => {
-            const texts = await Promise.all([...session.archives, session.file].map((path) => readFile(path, 'utf8')));
-            // A session with no archives is read as it is; only a rotated one has replayed events to drop.
-            const text = session.archives.length === 0 ? (texts[0] ?? '') : joinFiles(texts);
+            const text = await logText(session);
             const lines = [...eventLines(text, session.id).map((line) => JSON.stringify(line)), ...eventBadLines(text)];
             return lines.join('\n') + (lines.length === 0 ? '' : '\n');
         },

package/dist/sessions/derive.js

@@ -263,7 +263,8 @@ export const deriveSession = (capture, redact) => {
         example: cut(error.line, ERROR_EXAMPLE_CHARS),
         toolUseId: error.toolUseId,
         next: tools.slice(error.after, error.after + 2).map((tool) => tool.tool),
-        editFollowed: tools.slice(error.after, error.after + 6).some((tool) => EDITS.has(tool.tool)),
+        // `isEdit` skips an edit whose own result was an error, so the stored row and `recoveryCalls` (the wire's value) read one rule.
+        editFollowed: tools.slice(error.after, error.after + 6).some(isEdit),
         prompt: error.prompt,
         cls: error.prompt === null ? null : (classOf.get(error.prompt) ?? null),
     }));

package/dist/sessions/empty-state.d.ts

@@ -0,0 +1,17 @@
+import type { Source } from './sources.js';
+import type { DepositResult, SessionsRuntime } from './store.js';
+/** `recall` over a store with no sessions in it. */
+export declare const EMPTY_RECALL = "Your store is empty, so there is nothing to recall. See it work on made-up sessions with `oars sessions try`, or fill it with `oars sessions deposit`, which reads this machine's coding-agent session logs into a local store and archives a copy of each transcript.";
+/** `books` over a store with no sessions in it; `what` is "prompts" or "pulls". */
+export declare const emptyBooks: (what: string) => string;
+/**
+ * The lines a deposit that read nothing adds: every place it looked and what it found there. A source with no root on this machine was
+ * not looked in, and neither was one the run's `read` list leaves out, so neither is listed. Paths are the reader's own, printed on their own terminal.
+ */
+export declare const nothingFoundLines: (result: DepositResult, runtime: SessionsRuntime, table: readonly Source[], read: readonly string[]) => string[];
+/**
+ * One line when this run read from entries it was not given: they came from the list an earlier deposit saved (`state.json`), so a plain
+ * `oars sessions deposit` is not reading every source. `applied` is what the run reads, `given` what it was handed. A saved denial (`--deny`)
+ * is not an allow entry, so it is not named here.
+ */
+export declare const savedListNote: (applied: readonly string[], given: readonly string[], file: string) => string[];

package/dist/sessions/empty-state.js

@@ -0,0 +1,38 @@
+// What `deposit`, `recall`, and `books` say when there is nothing to show, so a first run reads as "nothing found here" and not as a broken tool.
+import { compileAllow, isDenial } from './allow.js';
+/** The two commands that get someone out of an empty store: watch it work on made-up sessions first with `sessions try`, or fill it from their own sessions with `sessions deposit`. */
+const WAYS_OUT = "See it work on made-up sessions with `oars sessions try`, or fill it with `oars sessions deposit`, which reads this machine's coding-agent session logs into a local store and archives a copy of each transcript.";
+/** `recall` over a store with no sessions in it. */
+export const EMPTY_RECALL = `Your store is empty, so there is nothing to recall. ${WAYS_OUT}`;
+/** `books` over a store with no sessions in it; `what` is "prompts" or "pulls". */
+export const emptyBooks = (what) => `No ${what} in the store: it is empty. ${WAYS_OUT}`;
+/**
+ * The lines a deposit that read nothing adds: every place it looked and what it found there. A source with no root on this machine was
+ * not looked in, and neither was one the run's `read` list leaves out, so neither is listed. Paths are the reader's own, printed on their own terminal.
+ */
+export const nothingFoundLines = (result, runtime, table, read) => {
+    const allow = compileAllow(read);
+    const places = [
+        `Claude Code: ${runtime.projectsRoot} (${String(result.folders.length)} project folders read, ${String(result.skippedFolders)} not on the allowlist)`,
+        ...table.flatMap((source) => {
+            const root = runtime.sourceRoots?.[source.name];
+            return root === undefined || !allow.allows(source.name) ? [] : [`${source.label}: ${root} (${String(result.sources[source.name]?.read ?? 0)} sessions read)`];
+        }),
+    ];
+    return ['Found no sessions. Looked in:', ...places.map((place) => `  ${place}`), 'Run it after a coding-agent session has run on this machine, or see oars work first with `oars sessions try`.'];
+};
+/** Entries named in the note before it says "and N more". */
+const NOTE_ENTRIES = 5;
+/**
+ * One line when this run read from entries it was not given: they came from the list an earlier deposit saved (`state.json`), so a plain
+ * `oars sessions deposit` is not reading every source. `applied` is what the run reads, `given` what it was handed. A saved denial (`--deny`)
+ * is not an allow entry, so it is not named here.
+ */
+export const savedListNote = (applied, given, file) => {
+    const saved = applied.filter((entry) => !isDenial(entry) && !given.includes(entry));
+    if (saved.length === 0)
+        return [];
+    const shown = saved.slice(0, NOTE_ENTRIES).join(', ');
+    const more = saved.length > NOTE_ENTRIES ? `, and ${String(saved.length - NOTE_ENTRIES)} more` : '';
+    return [`Used the --allow list saved by an earlier run (${shown}${more}), kept in ${file}. \`--allow\` adds folders to it and \`--deny\` leaves one out.`];
+};

package/dist/sessions/exclusion.js

@@ -7,7 +7,7 @@ import { chmod, lstat, mkdir, readdir, readFile, realpath, rename, rm, stat, wri
 import { dirname, join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { CliError, ExitCode } from '../errors.js';
-import { loadStore, paths } from './store.js';
+import { loadStore, paths, sourceRoots, sourcesOf } from './store.js';
 /** `OARS_EXCLUSION_TERMS` names the term file; the default sits beside the claude config's other local-only session-commons files. */
 export const exclusionPaths = (projectsRoot, env, out) => {
     const commons = join(dirname(projectsRoot), 'session-commons');
@@ -141,7 +141,51 @@ const filesIn = async (root, source, project, session, found) => {
         found.push({ path, key: `${session}/subagents/${path.slice(subagents.length + 1).split('\\').join('/')}`, main: false, source });
     return unreadable;
 };
-/** Both the harness's folder and oars' raw archive, because either can be the only copy left. */
+/**
+ * Where each session of a non-Claude source keeps its file, by the store's session id (`<source>-<id>`), read once per runtime and source: opening a source's store walks all of it.
+ * Only a transcript file counts: a source that keeps its sessions in a database names the database for every session, and that is no text the gate can read.
+ */
+const sourceFileCache = new WeakMap();
+const sourceFileMap = (runtime, name, open) => {
+    const known = sourceFileCache.get(runtime) ?? new Map();
+    sourceFileCache.set(runtime, known);
+    const found = known.get(name) ?? open();
+    known.set(name, found);
+    return found;
+};
+/** The harness's own file for a session of a source the runtime reads (a Codex rollout): the only copy there is, since oars archives nothing for a source. */
+const sourceFilesOf = async (runtime, session, found) => {
+    const roots = sourceRoots(runtime);
+    const source = sourcesOf(runtime).find((one) => roots.has(one.name) && session.startsWith(`${one.name}-`));
+    const root = source === undefined ? undefined : roots.get(source.name);
+    if (source === undefined || root === undefined)
+        return false;
+    try {
+        const files = await sourceFileMap(runtime, source.name, async () => {
+            const store = await source.open(root);
+            const byId = new Map();
+            if (store === undefined)
+                return byId;
+            try {
+                for (const one of store.sessions)
+                    byId.set(`${source.name}-${one.id}`, store.where(one));
+            }
+            finally {
+                store.close();
+            }
+            return byId;
+        });
+        const path = files.get(session);
+        // A hit in it is counted with the harness's folders: it is the harness's own file, as a Claude Code transcript is.
+        if (path !== undefined && path.endsWith('.jsonl') && (await isFile(path)))
+            found.push({ path, key: `${session}.jsonl`, main: true, source: 'projects' });
+        return false;
+    }
+    catch {
+        return true;
+    }
+};
+/** Both the harness's folder and oars' raw archive, because either can be the only copy left; a source's session also has its own file. */
 const filesOf = async (runtime, project, session) => {
     const files = [];
     const raw = paths(runtime.storeDir).raw;
@@ -152,7 +196,8 @@ const filesOf = async (runtime, project, session) => {
             unreadable = true;
     const first = await filesIn(runtime.projectsRoot, 'projects', project, session, files);
     const second = await filesIn(raw, 'raw', project, session, files);
-    return { files, unreadable: unreadable || first || second };
+    const third = await sourceFilesOf(runtime, session, files);
+    return { files, unreadable: unreadable || first || second || third };
 };
 /** The transcript files of one session, the main one first, one per path under the project folder (the harness's copy before oars' raw archive's): what a raw copy is built from, after the gate has cleared them. */
 export const transcriptFilesOf = async (runtime, project, session) => {

package/dist/sessions/extract.d.ts

@@ -1,3 +1,4 @@
+import { type CommandWords } from './call-shape.js';
 import { type RepoSize } from './public-vocabulary.js';
 import { type WordOfCommand } from './identity.js';
 import type { Redactor } from './redact.js';
@@ -56,6 +57,8 @@ export interface ExtractInput {
     redact: Redactor;
     /** The per-account salt for path targets; the store keeps it beside the log. */
     salt?: string;
+    /** The salt a repository's key is hashed under, derived from the account salt so a machine given it by enrollment keys a repository as the trusted machine does; absent means `salt`. */
+    repoSalt?: string;
     /** The salt's `sid` (first 8 hex of its SHA-256), stamped on every capture record; null when no salt is in play. */
     sid?: string | null;
     /** The repository root holding a working directory (worktree segments already stripped), or null; absent means no repository is known. */
@@ -85,6 +88,7 @@ export interface Capture {
     errorLines: ErrorLineObservation[];
     skeleton: Skeleton;
 }
+export declare const LOCAL_COMMAND_TAGS: ReadonlySet<string>;
 export declare const INJECTED_TAGS: ReadonlySet<string>;
 export declare const LEADING_TAG: RegExp;
 export interface PromptOpening {
@@ -125,6 +129,9 @@ type ShellLink = 'and' | 'pipe' | 'break' | 'end';
 export interface ShellCommand {
     program: string;
     args: ShellWord[];
+    /** The words before the program (assignments, wrappers, block words) and the program's own word, as written: the name read takes variable names from them. */
+    before: ShellWord[];
+    head: ShellWord;
     read: boolean;
     /** How the next command joins this one. */
     link: ShellLink;
@@ -144,17 +151,23 @@ export interface PlannedCommit {
     readBack: boolean;
 }
 export interface ShellRead {
+    /** Every command's words, for the name read (`argNamesOf`). */
+    words: CommandWords[];
     segments: ShellSegment[];
     /** The same commands as `segments`, in public names, apart from a pull's package name, which is kept as it is after redaction, with the redacted text they compare by. */
     steps: ShellStepRead[];
     pulls: ToolPull[];
     commitPlan: PlannedCommit[];
+    /** The paths a `git restore` or `git checkout --` names, as written, in the commands whose status the call reports. Not in `segments`: a slashed path stays out of `run`. */
+    restores: string[];
 }
+/** The shell a command is written for, which decides its escapes alone: a call whose tool the harness's `shells` table maps to `powershell` (Claude Code's `PowerShell`, and the `powershell` that Copilot, Pi, and Gemini name) reads a backslash as plain and a backtick as the escape, every other call by POSIX's. */
+type ShellDialect = 'posix' | 'powershell';
 export declare const CHANGES_FOLDER: ReadonlySet<string>;
-/** Every simple command of a shell call, in order, after the bodies are dropped and the command is redacted. `oars gate` reads the same commands as capture. */
-export declare const shellCommands: (command: string, redact: Redactor) => ShellCommand[];
+/** Every simple command of a shell call, in order, after the bodies are dropped and the command is redacted. Capture passes the dialect of the tool; `gate/checks.ts:524` and `projection.ts:95` call it with the POSIX default. */
+export declare const shellCommands: (command: string, redact: Redactor, dialect?: ShellDialect) => ShellCommand[];
 /** A shell call's segments, pulls, and the commits it holds, from the command alone. The command is redacted before anything is kept. */
-export declare const readShell: (command: string, redact: Redactor) => ShellRead;
+export declare const readShell: (command: string, redact: Redactor, dialect?: ShellDialect) => ShellRead;
 /**
  * What a clean result says about the planned commits: one entry per commit made, the sha when its `[branch sha]` line or a read-back
  * names it, else null, since a count may stand without a sha. A refused commit makes no entry: the call can be clean behind `; echo done`.