@manyoars/oars 0.2.0 → 0.4.0

package/dist/sessions/exclusion.js

@@ -0,0 +1,361 @@
+// The exclusion rule (register A38): a session is excluded if any line of its main or subagent transcript holds a listed term,
+// scanned locally before anything is deposited to the pool. A session with no raw to scan is excluded, and so is every session when
+// the term file is missing or empty (fail closed). The term list is a local file and never lives in this repository; nothing here
+// prints, logs, or returns a term or a line of a transcript, only counts and session ids.
+import { createReadStream } from 'node:fs';
+import { chmod, lstat, mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { CliError, ExitCode } from '../errors.js';
+import { loadStore, paths } 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');
+    const terms = env.OARS_EXCLUSION_TERMS;
+    return { terms: terms === undefined || terms === '' ? join(commons, 'exclusion-terms.txt') : terms, list: out ?? join(commons, 'exclusion-list.jsonl') };
+};
+/** The terms, lowercased; a missing, unreadable, or undecodable file gives none, which excludes everything. */
+export const loadTerms = async (file) => {
+    try {
+        const text = await readFile(file, 'utf8');
+        // A UTF-16 file (Windows PowerShell 5.1 `>`) decodes to NULs, and other bytes to U+FFFD: terms that never match would read every session as clean.
+        if (text.includes('\u0000') || text.includes('\ufffd'))
+            return [];
+        return text.split(/\r?\n/).map((line) => line.trim().toLowerCase()).filter((line) => line !== '');
+    }
+    catch {
+        return [];
+    }
+};
+const isAbsent = (error) => error instanceof Error && 'code' in error && (error.code === 'ENOENT' || error.code === 'ENOTDIR');
+/** A missing folder is empty; any other failure (ENOTDIR for a plain file, EACCES, EPERM, EBUSY) is thrown, so a folder that was not read never reads as clean. */
+const entriesOf = async (dir) => {
+    try {
+        return await readdir(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+};
+/**
+ * The one rule for a path at any level: a link that leads nowhere, or an entry of the wrong kind (a plain file where a folder belongs, a folder where
+ * a transcript belongs), means what is under it was not scanned. Windows reports a listing of a path under a plain file as ENOENT, so the kind is checked here and not left to the listing.
+ * An absent path is not one.
+ */
+const badLink = async (path, kind) => {
+    let entry;
+    try {
+        entry = await lstat(path);
+    }
+    catch (error) {
+        return !isAbsent(error);
+    }
+    try {
+        const target = entry.isSymbolicLink() ? await stat(path) : entry;
+        return kind === 'directory' ? !target.isDirectory() : !target.isFile();
+    }
+    catch {
+        return true;
+    }
+};
+/**
+ * A link is followed, as the main file's `stat` follows one; a link that leads nowhere or to the wrong kind, or a plain entry named like a transcript that is not a file, is a bad entry, and so is a folder that cannot be listed
+ * and a folder reached a second time (a link back into a folder already walked, which would loop and count a transcript once per pass).
+ * The walk goes on past every bad entry and `found` holds every transcript it reached, so the verdict does not depend on the listing order; true when any entry was bad.
+ * `seen` holds the real path of every folder entered.
+ */
+const jsonlUnder = async (dir, found, seen) => {
+    let bad = false;
+    for (const entry of await entriesOf(dir)) {
+        const path = join(dir, entry.name);
+        const named = entry.name.endsWith('.jsonl');
+        // A plain entry named like a transcript goes through the helper too: a folder or a FIFO there is not a file, and what is under it was not scanned.
+        if ((entry.isSymbolicLink() || named) && (await badLink(path, named ? 'file' : 'directory'))) {
+            bad = true;
+            continue;
+        }
+        const target = entry.isSymbolicLink() ? await stat(path) : entry;
+        if (target.isDirectory()) {
+            try {
+                const real = await realpath(path);
+                if (seen.has(real)) {
+                    bad = true;
+                    continue;
+                }
+                seen.add(real);
+                if (await jsonlUnder(path, found, seen))
+                    bad = true;
+            }
+            catch {
+                bad = true;
+            }
+        }
+        else if (named)
+            found.push(path);
+    }
+    return bad;
+};
+/** A main that is not there is false; any other failure (EACCES, EPERM, ELOOP) is thrown, so a main that was not examined never reads as absent. */
+const isFile = async (path) => {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (error) {
+        if (isAbsent(error))
+            return false;
+        throw error;
+    }
+};
+/** Adds the transcripts of the session in one source (the main file and everything under `<session>/subagents/`) to `found`; true when a level could not be read. */
+const filesIn = async (root, source, project, session, found) => {
+    const folder = join(root, project);
+    const main = join(folder, `${session}.jsonl`);
+    // A link that leads nowhere or a wrong kind of entry reads as an absent one below, so every level is checked first (a directory at the main makes the session unreadable here).
+    let unreadable = await badLink(main, 'file');
+    for (const path of [folder, join(folder, session), join(folder, session, 'subagents')])
+        if (await badLink(path, 'directory'))
+            unreadable = true;
+    try {
+        if (await isFile(main))
+            found.push({ path: main, key: `${session}.jsonl`, main: true, source });
+    }
+    catch {
+        unreadable = true;
+    }
+    const subagents = join(folder, session, 'subagents');
+    const agents = [];
+    try {
+        // The folder itself is seen first, so a link back to it is a repeat; a folder that is not there has no real path and nothing to walk.
+        const seen = new Set();
+        seen.add(await realpath(subagents).catch(() => subagents));
+        if (await jsonlUnder(subagents, agents, seen))
+            unreadable = true;
+    }
+    catch {
+        unreadable = true;
+    }
+    // Every file the walk reached is scanned, so a hit is counted whatever the listing order.
+    for (const path of agents)
+        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. */
+const filesOf = async (runtime, project, session) => {
+    const files = [];
+    const raw = paths(runtime.storeDir).raw;
+    // A root that is a link leading nowhere makes `lstat` of everything under it ENOENT, so the roots are checked here.
+    let unreadable = false;
+    for (const root of [runtime.projectsRoot, runtime.storeDir, raw])
+        if (await badLink(root, 'directory'))
+            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 };
+};
+/** 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) => {
+    const seen = new Map();
+    for (const { key, path, main } of (await filesOf(runtime, project, session)).files)
+        if (!seen.has(key))
+            seen.set(key, { key, path, main });
+    return [...seen.values()].sort((a, b) => (a.main === b.main ? (a.key < b.key ? -1 : 1) : a.main ? -1 : 1));
+};
+/** Whether any line of the file holds a term. Streamed, so a large transcript is never held whole. */
+const holdsTerm = async (path, terms) => {
+    const stream = createReadStream(path, { encoding: 'utf8' });
+    const lines = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of lines) {
+            const lower = line.toLowerCase();
+            if (terms.some((term) => lower.includes(term)))
+                return true;
+        }
+        return false;
+    }
+    finally {
+        lines.close();
+        // `close` leaves the stream open, so a file that returned early on a hit would keep its descriptor.
+        stream.destroy();
+    }
+};
+const judge = async (terms, session) => {
+    if (terms.length === 0)
+        return { excluded: true, reason: 'no-terms', hits: [] };
+    const { files } = session;
+    const hits = [];
+    let unreadable = session.unreadable;
+    for (const file of files) {
+        try {
+            if (await holdsTerm(file.path, terms))
+                hits.push({ key: file.key, main: file.main, source: file.source });
+        }
+        catch {
+            unreadable = true;
+        }
+    }
+    if (hits.length > 0)
+        return { excluded: true, reason: 'term', hits };
+    // Without the main transcript the session cannot be scanned in full, so it is excluded; its subagent files were scanned above, so a hit there counts.
+    if (!files.some((file) => file.main))
+        return { excluded: true, reason: unreadable ? 'unreadable' : 'no-raw', hits };
+    return unreadable ? { excluded: true, reason: 'unreadable', hits } : { excluded: false, reason: 'clean', hits };
+};
+/**
+ * When the newest file of a session was last written, in epoch milliseconds, over the same files the gate scans (the main transcript, its subagents, and oars' raw copies), or 0 when it has none.
+ * A transcript that kept growing since the last capture is newer here than in the store, so the deposit command reads it to tell a session still in progress from one that has ended.
+ */
+export const lastWritten = async (runtime, project, session) => {
+    const { files } = await filesOf(runtime, project, session);
+    const times = await Promise.all(files.map(async ({ path }) => (await stat(path)).mtimeMs));
+    return Math.max(0, ...times);
+};
+/** The A38 rule for one session; `extra` adds terms to the file's, but never stands in for it, so a missing or empty term file still excludes everything. */
+export const checkSession = async (runtime, termsFile, project, session, extra = []) => {
+    const fromFile = await loadTerms(termsFile);
+    return judge(fromFile.length === 0 ? [] : [...fromFile, ...extra.map((term) => term.toLowerCase())], await filesOf(runtime, project, session));
+};
+/** The harness names a session folder with a UUID. */
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A directory, or a link to one; a link that leads nowhere throws, so a folder that was not scanned never reads as clean. */
+const leadsToDirectory = async (path, entry) => (entry.isSymbolicLink() ? (await stat(path)).isDirectory() : entry.isDirectory());
+/** The sessions of one project folder: every entry named like a main file, and every entry named like a session folder. Other directories are returned apart. */
+const sessionIds = async (root, project) => {
+    const ids = [];
+    const dirs = [];
+    for (const entry of await entriesOf(join(root, project))) {
+        // An entry named like a main file or a session folder is a session whatever it is: `filesIn` reads one of the wrong kind (a link that leads nowhere,
+        // a folder named `<id>.jsonl`, a plain file named `<id>`) as unreadable, so the scan lists it as the gate does.
+        if (entry.name.endsWith('.jsonl'))
+            ids.push(entry.name.slice(0, -'.jsonl'.length));
+        else if (SESSION_ID.test(entry.name) && !entry.isDirectory())
+            ids.push(entry.name);
+        else if (await leadsToDirectory(join(root, project, entry.name), entry))
+            dirs.push(entry.name);
+    }
+    return { ids: [...ids, ...dirs.filter((name) => SESSION_ID.test(name))], others: dirs.filter((name) => !SESSION_ID.test(name)) };
+};
+const emptyHits = () => ({ main: 0, subagent: 0 });
+/** Scans every session in the harness's folders, the raw archive, and the store's own log. Returns counts and, apart from them, the excluded sessions. */
+export const scanStore = async (runtime, termsFile) => {
+    const terms = await loadTerms(termsFile);
+    const raw = paths(runtime.storeDir).raw;
+    // A root that is a link leading nowhere, or to a file, lists as empty: stop with no list, naming no path.
+    for (const root of [runtime.projectsRoot, runtime.storeDir, raw]) {
+        if (await badLink(root, 'directory'))
+            throw new CliError('A folder that holds the projects is a link that could not be followed, so no list was written.', ExitCode.INVALID, 'unreadable');
+    }
+    // A store log that is a link leading nowhere would load as an empty store, so a logged session would drop out of the list: stop instead.
+    if (await badLink(paths(runtime.storeDir).observations, 'file'))
+        throw new CliError('The store log is a link that could not be followed, so no list was written.', ExitCode.INVALID, 'unreadable');
+    // A session the store logged stays listed when its raw is gone everywhere: it has nothing to scan, so it is excluded as no raw.
+    const logged = new Map();
+    for (const session of (await loadStore(runtime.storeDir)).sessions)
+        logged.set(session.project, (logged.get(session.project) ?? new Set()).add(session.session));
+    const projects = new Set(logged.keys());
+    for (const root of [runtime.projectsRoot, raw]) {
+        try {
+            for (const entry of await entriesOf(root)) {
+                // A project folder that is a link to a file was not scanned: stop, as for one that leads nowhere (`stat` throws).
+                if (entry.isSymbolicLink() && (await badLink(join(root, entry.name), 'directory')))
+                    throw new Error('unreadable');
+                if (await leadsToDirectory(join(root, entry.name), entry))
+                    projects.add(entry.name);
+            }
+        }
+        catch {
+            throw new CliError('A folder that holds the projects could not be listed, so no list was written.', ExitCode.INVALID, 'unreadable');
+        }
+    }
+    const counts = {
+        sessions: 0,
+        excluded: 0,
+        kept: 0,
+        reasons: { term: 0, noRaw: 0, noTerms: 0, unreadable: 0 },
+        notSessions: 0,
+        hitFiles: emptyHits(),
+        bySource: { projects: { ...emptyHits(), sessions: 0 }, raw: { ...emptyHits(), sessions: 0 } },
+        folders: [],
+    };
+    const excluded = [];
+    const distinct = new Set();
+    for (const [index, project] of [...projects].sort().entries()) {
+        // The platform's message carries the path, and a folder name can carry the term: name the ordinal only.
+        const listed = async (root) => {
+            try {
+                return await sessionIds(root, project);
+            }
+            catch {
+                throw new CliError(`Project folder ${String(index + 1)} could not be listed, so it was not scanned and no list was written.`, ExitCode.INVALID, 'unreadable');
+            }
+        };
+        const inProjects = await listed(runtime.projectsRoot);
+        const inRaw = await listed(raw);
+        const ids = new Set([...inProjects.ids, ...inRaw.ids, ...(logged.get(project) ?? [])]);
+        counts.notSessions += new Set([...inProjects.others, ...inRaw.others].filter((name) => !ids.has(name))).size;
+        const folder = { folder: index + 1, sessions: 0, excluded: 0, hits: { projects: emptyHits(), raw: emptyHits() } };
+        for (const session of [...ids].sort()) {
+            const verdict = await judge(terms, await filesOf(runtime, project, session));
+            folder.sessions += 1;
+            const sources = new Set();
+            for (const hit of verdict.hits) {
+                const kind = hit.main ? 'main' : 'subagent';
+                counts.bySource[hit.source][kind] += 1;
+                folder.hits[hit.source][kind] += 1;
+                sources.add(hit.source);
+                const key = `${project}/${hit.key}`;
+                if (!distinct.has(key)) {
+                    distinct.add(key);
+                    counts.hitFiles[kind] += 1;
+                }
+            }
+            for (const source of sources)
+                counts.bySource[source].sessions += 1;
+            if (!verdict.excluded)
+                continue;
+            folder.excluded += 1;
+            excluded.push({ project, session });
+            if (verdict.reason === 'term')
+                counts.reasons.term += 1;
+            else if (verdict.reason === 'no-raw')
+                counts.reasons.noRaw += 1;
+            else if (verdict.reason === 'no-terms')
+                counts.reasons.noTerms += 1;
+            else
+                counts.reasons.unreadable += 1;
+        }
+        counts.sessions += folder.sessions;
+        counts.excluded += folder.excluded;
+        counts.folders.push(folder);
+    }
+    counts.kept = counts.sessions - counts.excluded;
+    return { counts, excluded };
+};
+/** `oars sessions exclusions`: writes the excluded sessions to a local file and prints counts only. */
+export const sessionsExclusions = async (runtime, where) => {
+    const { counts, excluded } = await scanStore(runtime, where.terms);
+    await mkdir(dirname(where.list), { recursive: true });
+    // The list holds real folder names, which can carry a term, so it is readable by its owner only (as the store's other local-only files are).
+    // Written through a temp file and renamed, as the store does, so a crash mid-write never leaves a short list that reads as complete.
+    const temp = `${where.list}.tmp`;
+    try {
+        await writeFile(temp, excluded.map((entry) => JSON.stringify(entry)).join('\n') + (excluded.length === 0 ? '' : '\n'), { mode: 0o600 });
+        await rename(temp, where.list);
+    }
+    catch (error) {
+        // The temp file holds real folder names, so a failed write or rename never leaves it behind.
+        await rm(temp, { force: true });
+        throw error;
+    }
+    // `mode` applies only when the file is created, so a list from an earlier run keeps its old one.
+    await chmod(where.list, 0o600);
+    const { projects, raw } = counts.bySource;
+    const lines = [
+        `Scanned ${String(counts.sessions)} sessions in ${String(counts.folders.length)} folders: ${String(counts.excluded)} excluded, ${String(counts.kept)} kept; ${String(counts.notSessions)} directories are not sessions.`,
+        `Excluded for a term: ${String(counts.reasons.term)}; no raw to scan: ${String(counts.reasons.noRaw)}; no term file: ${String(counts.reasons.noTerms)}; unreadable: ${String(counts.reasons.unreadable)}.`,
+        `Files holding a term: ${String(counts.hitFiles.main)} main, ${String(counts.hitFiles.subagent)} subagent (harness folders ${String(projects.main + projects.subagent)} in ${String(projects.sessions)} sessions, raw archive ${String(raw.main + raw.subagent)} in ${String(raw.sessions)} sessions).`,
+        'The excluded list is written to a local file outside the repository.',
+    ];
+    return { document: { ok: true, ...counts }, text: lines.join('\n') };
+};

package/dist/sessions/extract.d.ts

@@ -0,0 +1,181 @@
+import { type RepoSize } from './public-vocabulary.js';
+import { type WordOfCommand } from './identity.js';
+import type { Redactor } from './redact.js';
+import { type ErrorLineObservation, type Harness, type PromptClass, type PromptOpened, type SessionObservation, type ShellIdentity, type ShellSegment, type Skeleton, type TargetBase, type ToolObservation, type ToolPull, type Usage, type UserPromptObservation } from './schema.js';
+export interface Obj {
+    [key: string]: unknown;
+}
+export declare const isObj: (value: unknown) => value is Obj;
+/** Python slices by code point; JavaScript by UTF-16 unit. */
+export declare const cut: (text: string, length: number) => string;
+export declare const EXPLORE: Set<string>;
+export declare const ACT: Set<string>;
+export declare const EDITS: Set<string>;
+export declare const SHELL: Set<string>;
+/** The normalized form of one line: paths, hex, numbers, and quoted strings replaced, cut at 110 characters. */
+export declare const normalize: (line: string) => string;
+/** The first informative line of a tool result: skips blanks, markup lines, "Only you see", and the `Exit code` line. */
+export declare const firstInformative: (text: string) => string;
+/**
+ * The key an error is matched on, by deposit and by recall alike: redact, take the first informative line, normalize, redact again. Redacting
+ * first keeps a secret or an email whole before normalize turns its digits into `<n>`; the second pass catches what only the cut form shows.
+ */
+export declare const errorKey: (text: string, redact: Redactor) => string;
+/** The signature of an error: `<tool> | <errorKey>`. */
+export declare const signatureOf: (tool: string, text: string, redact: Redactor) => string;
+export declare const resultText: (block: Obj) => string;
+export declare const isErrorResult: (block: Obj, text: string) => boolean;
+/**
+ * The `errorCode` of a failed result (spec Section 1.2): an exit-code class from a leading `Exit code N` line, else the harness error class its text
+ * names, else an HTTP status, else `other`. The result is always a member of `ERROR_CODES`, picked by a table, so no word of the error text is kept. A
+ * harness that reports no exit code (a Cursor non-shell call, a Codex call with no status) reaches `other` unless its text names a class.
+ */
+export declare const errorCodeOf: (text: string) => string;
+export declare const shortName: (name: string) => string;
+export declare const compress: (sequence: readonly string[]) => string;
+/** The prompt class rule shared by prompt_graphs.py and cost_per_class.py. */
+export declare const classify: (sequence: readonly string[]) => PromptClass;
+export declare const emptyUsage: () => Usage;
+/** Where a subagent transcript came from: its `.meta.json` and the folder it sits in. */
+export interface SubagentOrigin {
+    parent: string;
+    agentType: string | null;
+    spawnedBy: string | null;
+    /** The `n` of the `spawnedBy` call in the transcript that holds it, when the deposit could read it. */
+    spawnedAt?: number | null;
+    /** The session id of that transcript: the main session, or a sibling subagent's. */
+    spawnedIn?: string | null;
+}
+export interface ExtractInput {
+    text: string;
+    session: string;
+    project: string;
+    rev: number;
+    at: string;
+    bytes: number;
+    redact: Redactor;
+    /** The per-account salt for path targets; the store keeps it beside the log. */
+    salt?: 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. */
+    repoRoot?: (cwd: string) => string | null;
+    /** The identity string of a repository root (`makeRepoIdentity`); absent means the lower-cased root path. */
+    repoIdentity?: (root: string) => string;
+    /** The oars package, Node.js, and OS this capture ran under; absent reads as `0.0.0` and this process. */
+    runtime?: {
+        oars: string;
+        node: string;
+        os: string;
+    };
+    /** The harness this transcript came from; absent means Claude Code. It names the frame and picks the action table. */
+    harness?: Harness;
+    /** How many files a repository root holds; absent reads the root's git index. */
+    repoFiles?: (root: string) => number | null;
+    /** The size bucket an earlier capture of this transcript read, null included; absent on the first capture, which reads it through `repoFiles`. */
+    repoSize?: RepoSize | null;
+    /** Set for a subagent transcript: every line is the agent's own line, so none is read as a sidechain. */
+    subagent?: SubagentOrigin;
+}
+/** What capture writes for one transcript, before any derivation. */
+export interface Capture {
+    session: SessionObservation;
+    prompts: UserPromptObservation[];
+    tools: ToolObservation[];
+    errorLines: ErrorLineObservation[];
+    skeleton: Skeleton;
+}
+export declare const INJECTED_TAGS: ReadonlySet<string>;
+export declare const LEADING_TAG: RegExp;
+export interface PromptOpening {
+    opened: PromptOpened;
+    /** What the operator asked: the line as written, or a command's name and arguments. Not yet redacted. */
+    request: string;
+}
+/**
+ * Whether a main-line user line with text and no tool result opens a prompt in a Claude Code transcript, and how. Capture and the gold reader both number
+ * prompts by this, so a gold entry's index is a capture index. `lines` is the whole transcript and `position` this line's place in it.
+ */
+export declare const promptOpening: (text: string, lines: readonly string[], position: number, subagent?: boolean) => PromptOpening | undefined;
+/**
+ * What a path is hashed as, and from where. Under the repository root of the line's `cwd` it is relative to that root, with a linked
+ * worktree's segment stripped, so one file reads alike from every subdirectory and worktree (base `repo`). A path no repository holds
+ * keeps the version-3 rule: relative to `cwd` when it lies under it, else as written (base `cwd`). A relative path is read from `cwd` first.
+ */
+export declare const pathKey: (path: string, cwd: string | undefined, root: string | null) => {
+    key: string;
+    base: TargetBase;
+};
+/** The per-account salted hash of a file path (16 hex characters, class A). */
+export declare const hashPath: (path: string, cwd: string | undefined, root: string | null, salt: string) => {
+    hash: string;
+    base: TargetBase;
+    key: string;
+};
+/**
+ * A shell call's program and subcommand from its first line (`git push`, `just build`, `npm`), as recovery_episodes.py's
+ * `shell_target` computes it, so a retry of `git push` after a failed `git push` is the same target and `git status` is not.
+ * The program is a basename, lowercased, without `.exe`; the subcommand is the first later token that is not a flag, a path, or
+ * a variable, cut to 30 characters, and there is none when a separator comes first. Empty when the line holds no command.
+ */
+export declare const shellTarget: (command: string) => string;
+type ShellWord = WordOfCommand;
+type ShellLink = 'and' | 'pipe' | 'break' | 'end';
+/** One simple command, after its prelude. */
+export interface ShellCommand {
+    program: string;
+    args: ShellWord[];
+    read: boolean;
+    /** How the next command joins this one. */
+    link: ShellLink;
+    /** A pipe follows the group this command sits in, so its status is hidden whatever its own link says. */
+    hidden: boolean;
+}
+/** One command of a shell call, as its step reads. `run` compares a retry and is not kept. */
+export interface ShellStepRead {
+    identity: ShellIdentity;
+    read: boolean;
+    run: string;
+}
+/** One `git commit` a command holds. */
+export interface PlannedCommit {
+    quiet: boolean;
+    /** A later command of the same list reads this commit back, so the result can name its sha. */
+    readBack: boolean;
+}
+export interface ShellRead {
+    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[];
+}
+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[];
+/** 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;
+/**
+ * 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`.
+ */
+export declare const commitsRead: (plan: readonly PlannedCommit[], result: string) => Array<string | null>;
+/**
+ * The tool name as a record stores it. An MCP name is `mcp__<server>__<tool>` (Cursor: `mcp_<server>_<tool>`) and the server comes from the
+ * operator's config, where a token can sit, so everything after the prefix is redacted wherever the name is kept (the call, its error line,
+ * the skeleton line, and the session's count).
+ */
+export declare const storedToolName: (name: string, redact: Redactor) => string;
+/** An MCP call's full server name, which `shortName` cuts for the tool sequence, redacted because a harness takes it from the operator's config. */
+export declare const pullsOfTool: (name: string, redact: Redactor) => ToolPull[];
+/** The `target` of a tool call (see {@link ToolObservation.target}). A path target also returns the `key` it was hashed on, read for its class and then dropped, never stored. */
+export declare const targetOf: (tool: string, input: Obj, cwd: string | undefined, salt: string, redact: Redactor, root?: string | null) => {
+    target: string | null;
+    base: TargetBase | null;
+    key?: string;
+};
+/** The `n` capture gives each call of a transcript, by tool-use id, the first copy of a repeated id winning; a subagent's steps name their parent by it without capturing the parent again. */
+export declare const callPositions: (text: string) => Map<string, number>;
+/** One pass over a transcript into its capture records and skeleton. Never throws on a malformed line: it counts it and goes on. */
+export declare const captureSession: (input: ExtractInput) => Capture;
+export {};