@manyoars/oars 0.1.1 → 0.3.0

package/dist/sessions/fold.d.ts

@@ -0,0 +1,17 @@
+import type { ErrorLineObservation, SessionObservation, ToolObservation } from './schema.js';
+/**
+ * One record per `toolUseId`, in the order of the first record of each. The kept record is the first, with the `status` and `durationMs` of the first
+ * record that has a status when its own is `none`, and the `target`, `targetBase`, `ts`, and `harnessVersion` of the first record that has a `ts` when
+ * its own has none, so a call keeps its position and prompt and the result and path it was given. A record with no id is its own call.
+ *
+ * The kept records are renumbered to their place in the array, and each error line's `after` (the count of records written before it) is mapped to the
+ * count of kept records written before it, so `derive.ts`, which slices the calls at `after`, reads the calls capture version 8 would have numbered.
+ * Returns the records dropped too, so the session's own counts can be brought into line.
+ */
+export declare const foldToolRows: (written: readonly ToolObservation[], errorLines: readonly ErrorLineObservation[]) => {
+    tools: ToolObservation[];
+    dropped: ToolObservation[];
+    errorLines: ErrorLineObservation[];
+};
+/** The session with the dropped calls taken out of its per-tool counts and its shell count, the numbers capture version 8 would have written. */
+export declare const withoutReplays: (session: SessionObservation, dropped: readonly ToolObservation[]) => SessionObservation;

package/dist/sessions/fold.js

@@ -0,0 +1,71 @@
+import { SHELL } from './extract.js';
+// One tool call is one observation. Capture version 8 writes a call once; a record set captured before it holds a second `tool` record, status
+// `none`, for every call a resumed transcript replayed. The reader folds those so every count over `store.tools` agrees with the new capture until each
+// transcript is captured again.
+/** The record a folded call keeps when a later copy of it is the one with the real line: its status, duration, and the fields a blob copy cannot know. */
+const settled = (held, later) => {
+    const status = held.status === 'none' && later.status !== 'none' ? { status: later.status, durationMs: later.durationMs } : {};
+    // A copy with no `ts` came from a line with no `cwd` either, so its path hash is against the working directory, not the repository.
+    const line = held.ts === null && later.ts !== null ? { target: later.target, targetBase: later.targetBase, ts: later.ts, harnessVersion: later.harnessVersion } : {};
+    return { ...held, ...status, ...line };
+};
+/**
+ * One record per `toolUseId`, in the order of the first record of each. The kept record is the first, with the `status` and `durationMs` of the first
+ * record that has a status when its own is `none`, and the `target`, `targetBase`, `ts`, and `harnessVersion` of the first record that has a `ts` when
+ * its own has none, so a call keeps its position and prompt and the result and path it was given. A record with no id is its own call.
+ *
+ * The kept records are renumbered to their place in the array, and each error line's `after` (the count of records written before it) is mapped to the
+ * count of kept records written before it, so `derive.ts`, which slices the calls at `after`, reads the calls capture version 8 would have numbered.
+ * Returns the records dropped too, so the session's own counts can be brought into line.
+ */
+export const foldToolRows = (written, errorLines) => {
+    const first = new Map();
+    const kept = [];
+    const dropped = [];
+    const keptAt = [];
+    for (const tool of [...written].sort((a, b) => a.n - b.n)) {
+        const at = tool.toolUseId === null ? undefined : first.get(tool.toolUseId);
+        if (tool.toolUseId !== null && at === undefined)
+            first.set(tool.toolUseId, kept.length);
+        if (at === undefined) {
+            kept.push(tool);
+            keptAt.push(tool.n);
+            continue;
+        }
+        dropped.push(tool);
+        const held = kept[at];
+        if (held !== undefined)
+            kept[at] = settled(held, tool);
+    }
+    // `keptAt` is ascending, so the kept records written before `after` are the ones whose old `n` is below it.
+    const before = (after) => {
+        let low = 0;
+        let high = keptAt.length;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            if ((keptAt[middle] ?? 0) < after)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        return low;
+    };
+    return {
+        tools: kept.map((tool, n) => ({ ...tool, n })),
+        dropped,
+        errorLines: errorLines.map((error) => ({ ...error, after: before(error.after) })),
+    };
+};
+/** The session with the dropped calls taken out of its per-tool counts and its shell count, the numbers capture version 8 would have written. */
+export const withoutReplays = (session, dropped) => {
+    if (dropped.length === 0)
+        return session;
+    const counts = { ...session.tools };
+    let shell = session.bashCmds;
+    for (const tool of dropped) {
+        counts[tool.tool] = Math.max((counts[tool.tool] ?? 0) - 1, 0);
+        if (SHELL.has(tool.tool))
+            shell = Math.max(shell - 1, 0);
+    }
+    return { ...session, tools: Object.fromEntries(Object.entries(counts).filter(([, count]) => count > 0)), bashCmds: shell };
+};

package/dist/sessions/frame.d.ts

@@ -0,0 +1,24 @@
+import { type RepoSize } from './public-vocabulary.js';
+import type { Frame, FrameStack } from './schema.js';
+/** The UTC day of a timestamp, whatever offset it was written in; null when there is none or it does not parse. */
+export declare const utcDay: (ts: string | null | undefined) => string | null;
+/** A stack holding only closed-vocabulary values, sorted; anything else is dropped, not masked, because the stack has no room for an unknown. */
+export declare const closedStack: (raw: {
+    languages: readonly string[];
+    frameworks: readonly string[];
+    size: string | null;
+}) => FrameStack;
+/** The bucket of a repository's tracked-file count; null when the count is not known. */
+export declare const repoSizeOf: (files: number | null) => RepoSize | null;
+/** The stack a file's evidence shows. Only names from the vocabulary come out, so a path or a program name can never pass through. */
+export declare const stackOf: (evidence: {
+    paths: readonly string[];
+    programs: readonly string[];
+    size: RepoSize | null;
+}) => FrameStack;
+/** The frame with every free-standing name held to the public vocabulary. */
+export declare const closedFrame: (raw: Frame) => Frame;
+/** The frame's hash: unsalted, so one frame reads alike across accounts (D1's `hP`), 16 hex characters, over the fields in a fixed order. */
+export declare const frameIdOf: (frame: Frame) => string;
+/** How many files a repository tracks, from its git index's header: no git process, and null when there is no readable index. */
+export declare const repoFilesFromIndex: (root: string) => number | null;

package/dist/sessions/frame.js

@@ -0,0 +1,95 @@
+// The frame (recall spec Section 2.1): where and when a prompt ran, as public names only, and its hash. A step takes its prompt's frame,
+// and reading one motif across frames is how the record compares models, harnesses, versions, and dates.
+import { createHash } from 'node:crypto';
+import { closeSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { FRAMEWORK_OF_FILE, FRAMEWORK_OF_PROGRAM, FRAMEWORKS, LANGUAGE_OF_EXTENSION, LANGUAGES, publicEffort, publicModel, publicVersion, REPO_SIZES } from './public-vocabulary.js';
+/** The language mix keeps this many languages, so a frame stays a coordinate and not a fingerprint of one repository. */
+const LANGUAGES_PER_STACK = 3;
+/** The UTC day of a timestamp, whatever offset it was written in; null when there is none or it does not parse. */
+export const utcDay = (ts) => {
+    if (ts === null || ts === undefined || ts === '')
+        return null;
+    const millis = Date.parse(ts);
+    return Number.isNaN(millis) ? null : new Date(millis).toISOString().slice(0, 10);
+};
+/** A stack holding only closed-vocabulary values, sorted; anything else is dropped, not masked, because the stack has no room for an unknown. */
+export const closedStack = (raw) => ({
+    languages: [...new Set(raw.languages)].filter((language) => LANGUAGES.has(language)).sort(),
+    frameworks: [...new Set(raw.frameworks)].filter((framework) => FRAMEWORKS.has(framework)).sort(),
+    size: REPO_SIZES.find((size) => size === raw.size) ?? null,
+});
+/** The bucket of a repository's tracked-file count; null when the count is not known. */
+export const repoSizeOf = (files) => {
+    if (files === null)
+        return null;
+    if (files < 100)
+        return 'xs';
+    if (files < 1000)
+        return 's';
+    if (files < 10000)
+        return 'm';
+    return files < 100000 ? 'l' : 'xl';
+};
+const baseName = (path) => path.replace(/\\/g, '/').split('/').pop() ?? path;
+/** The stack a file's evidence shows. Only names from the vocabulary come out, so a path or a program name can never pass through. */
+export const stackOf = (evidence) => {
+    const counts = new Map();
+    const frameworks = [];
+    for (const path of evidence.paths) {
+        const base = baseName(path);
+        const language = LANGUAGE_OF_EXTENSION.get(base.split('.').pop()?.toLowerCase() ?? '');
+        if (base.includes('.') && language !== undefined)
+            counts.set(language, (counts.get(language) ?? 0) + 1);
+        for (const [pattern, name] of FRAMEWORK_OF_FILE)
+            if (pattern.test(base))
+                frameworks.push(name);
+    }
+    for (const program of evidence.programs) {
+        const name = FRAMEWORK_OF_PROGRAM.get(program);
+        if (name !== undefined)
+            frameworks.push(name);
+    }
+    // Most touched first, a tie by name, so the mix does not depend on the order the files were touched in.
+    const languages = [...counts].sort(([a, one], [b, two]) => two - one || a.localeCompare(b)).slice(0, LANGUAGES_PER_STACK).map(([language]) => language);
+    return closedStack({ languages, frameworks, size: evidence.size });
+};
+/** The frame with every free-standing name held to the public vocabulary. */
+export const closedFrame = (raw) => ({
+    ...raw,
+    harnessVersion: publicVersion(raw.harnessVersion),
+    model: publicModel(raw.model),
+    effort: publicEffort(raw.effort),
+});
+/** The frame's hash: unsalted, so one frame reads alike across accounts (D1's `hP`), 16 hex characters, over the fields in a fixed order. */
+export const frameIdOf = (frame) => {
+    const { harness, harnessVersion, model, effort, day, platform, shell, stack } = frame;
+    const canonical = JSON.stringify([harness, harnessVersion, model, effort, day, platform, shell, stack.languages, stack.frameworks, stack.size]);
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+};
+const INDEX_HEADER_BYTES = 12;
+/** Where a checkout's git index is. In a linked worktree or a submodule `.git` is a file whose `gitdir:` line names the real git folder, absolute or relative to the checkout. */
+const indexPathOf = (root) => {
+    const dotGit = join(root, '.git');
+    if (statSync(dotGit).isDirectory())
+        return join(dotGit, 'index');
+    const pointer = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotGit, 'utf8'))?.[1];
+    return pointer === undefined ? join(dotGit, 'index') : join(resolve(root, pointer), 'index');
+};
+/** How many files a repository tracks, from its git index's header: no git process, and null when there is no readable index. */
+export const repoFilesFromIndex = (root) => {
+    let descriptor;
+    try {
+        descriptor = openSync(indexPathOf(root), 'r');
+        const header = Buffer.alloc(INDEX_HEADER_BYTES);
+        const read = readSync(descriptor, header, 0, INDEX_HEADER_BYTES, 0);
+        return read === INDEX_HEADER_BYTES && header.toString('latin1', 0, 4) === 'DIRC' ? header.readUInt32BE(8) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+};

package/dist/sessions/gemini.d.ts

@@ -0,0 +1,37 @@
+/** The Gemini folder for an environment; a test passes its own so it never reads the real one. */
+export declare const geminiRoot: (env: {
+    [name: string]: string | undefined;
+}, home?: string) => string;
+type Obj = {
+    [key: string]: unknown;
+};
+/** A session found in the store, before its records are read. */
+export interface GeminiSession {
+    /** The head's `sessionId` (else the file's name); a subagent's is `<parent>-<file name>`. It names the skeleton. */
+    id: string;
+    /** What `.project_root` names, or for a hash-named folder a path that hashes to its name; null when neither gives one. */
+    folder: string | null;
+    file: string;
+    size: number;
+    mtimeMs: number;
+    /** The parent session's id for a subagent's file; null for a main session. */
+    parent: string | null;
+}
+export interface GeminiStore {
+    sessions: GeminiSession[];
+    /** The session as transcript text for `captureSession`; throws when the file cannot be read or holds no parseable line. */
+    transcript: (session: GeminiSession) => Promise<string>;
+    /** Sessions skipped because their id is not a safe file name (it names a skeleton), counted so the skip is never silent. */
+    rejected: number;
+    /** Items that could not be inspected, reported once each and never fatal; the reason names no path. */
+    unreadable: {
+        file: string;
+        reason: string;
+    }[];
+}
+/** The non-blank lines that are not JSON (a torn write), kept so `captureSession` counts them and the deposit line reports them. */
+export declare const chatBadLines: (text: string) => string[];
+/** The chat file as the lines `captureSession` reads; `cwd` is the project folder: the marker (`.project_root`), or for a hash-named folder a path that hashes to its name. Gemini CLI records no other working directory. */
+export declare const chatLines: (text: string, fallbackId: string, cwd: string | null) => Obj[];
+export declare const openGeminiStore: (root: string) => Promise<GeminiStore | undefined>;
+export {};