@jitsusama/agentic-harness.core 0.3.0 → 0.4.0

package/dist/google/apis/calendar.js

@@ -1,7 +1,7 @@
 /**
  * Google Calendar API client.
  */
-import { google } from "googleapis";
+import { google } from "./client.js";
 /**
  * List calendar events in a date range.
  */

package/dist/google/apis/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The googleapis client, loaded on first use.
+ *
+ * googleapis bundles a client for every Google API, about 1,800
+ * modules, and every extension that imports this package would load
+ * all of them at startup. This stands in for its `google` export and
+ * loads the real one the first time any API is asked for.
+ */
+import type { GoogleApis } from "googleapis";
+export declare const google: GoogleApis;

package/dist/google/apis/client.js

@@ -0,0 +1,23 @@
+/**
+ * The googleapis client, loaded on first use.
+ *
+ * googleapis bundles a client for every Google API, about 1,800
+ * modules, and every extension that imports this package would load
+ * all of them at startup. This stands in for its `google` export and
+ * loads the real one the first time any API is asked for.
+ */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+let loaded;
+function load() {
+    loaded ??= require("googleapis").google;
+    return loaded;
+}
+export const google = new Proxy({}, {
+    get(_, property) {
+        const real = load();
+        const value = Reflect.get(real, property);
+        // The API factories read shared options off `this`.
+        return typeof value === "function" ? value.bind(real) : value;
+    },
+});

package/dist/google/apis/docs.js

@@ -1,7 +1,7 @@
 /**
  * Google Docs API client.
  */
-import { google } from "googleapis";
+import { google } from "./client.js";
 /**
  * Get document content, including all tabs.
  */

package/dist/google/apis/drive.js

@@ -1,7 +1,7 @@
 /**
  * Google Drive API client.
  */
-import { google } from "googleapis";
+import { google } from "./client.js";
 /**
  * List Drive files with optional filtering.
  */

package/dist/google/apis/gmail.js

@@ -1,7 +1,7 @@
 /**
  * Gmail API client.
  */
-import { google } from "googleapis";
+import { google } from "./client.js";
 /**
  * Search emails using Gmail query syntax.
  */

package/dist/google/apis/sheets.js

@@ -1,7 +1,7 @@
 /**
  * Google Sheets API client.
  */
-import { google } from "googleapis";
+import { google } from "./client.js";
 /**
  * Get spreadsheet content.
  */

package/dist/google/apis/slides.js

@@ -1,7 +1,7 @@
 /**
  * Google Slides API client.
  */
-import { google } from "googleapis";
+import { google } from "./client.js";
 /**
  * Get presentation content.
  */

package/dist/observability/ledger/scan.d.ts

@@ -0,0 +1,11 @@
+import type { LedgerScan } from "./types.js";
+/**
+ * Read billable turns out of a session log's lines.
+ *
+ * Every line is offered to the parser and every outcome is counted, so a
+ * malformed line costs one entry rather than the remainder of the file.
+ * Both places a turn can carry usage are read: assistant turns hold it
+ * under `message`, and compactions hold it at the top level beside
+ * `type`.
+ */
+export declare function readTurns(sessionId: string, lines: Iterable<string>): LedgerScan;

package/dist/observability/ledger/scan.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import { SessionCollector } from "./session.js";
+/** Width of a stored content address. 96 bits is ample for a corpus of
+ * a few million turns and keeps the index small. */
+const DIGEST_CHARS = 24;
+/**
+ * Read billable turns out of a session log's lines.
+ *
+ * Every line is offered to the parser and every outcome is counted, so a
+ * malformed line costs one entry rather than the remainder of the file.
+ * Both places a turn can carry usage are read: assistant turns hold it
+ * under `message`, and compactions hold it at the top level beside
+ * `type`.
+ */
+export function readTurns(sessionId, lines) {
+    const turns = [];
+    const session = new SessionCollector(sessionId);
+    let count = 0;
+    let parsed = 0;
+    let unparseable = 0;
+    let billable = 0;
+    let unmetered = 0;
+    for (const line of lines) {
+        count += 1;
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            const value = JSON.parse(line);
+            if (typeof value !== "object" || value === null) {
+                unparseable += 1;
+                continue;
+            }
+            entry = value;
+        }
+        catch {
+            // A truncated or interleaved write. Counted, never fatal: one
+            // unreadable line once reduced a corpus-wide total to a tenth
+            // of the truth by aborting the pipeline that met it.
+            unparseable += 1;
+            continue;
+        }
+        parsed += 1;
+        if (entry.type === "session") {
+            session.observeHeader(entry);
+            continue;
+        }
+        if (entry.customType === "quest-workflow") {
+            const data = asRecord(entry.data);
+            if (data)
+                session.observeWorkflow(data);
+            continue;
+        }
+        const turn = turnFrom(sessionId, entry);
+        if (!turn)
+            continue;
+        session.observeTurn(turn.timestamp);
+        turns.push(turn);
+        if (turn.cost)
+            billable += 1;
+        else
+            unmetered += 1;
+    }
+    return {
+        turns,
+        coverage: { lines: count, parsed, unparseable, billable, unmetered },
+        session: session.record(),
+    };
+}
+function turnFrom(sessionId, entry) {
+    const kind = kindOf(entry);
+    if (!kind)
+        return null;
+    const message = asRecord(entry.message);
+    const usage = asRecord(kind === "compaction" ? entry.usage : message?.usage);
+    const entryId = typeof entry.id === "string" ? entry.id : "";
+    const timestamp = typeof entry.timestamp === "string" ? entry.timestamp : "";
+    const model = typeof message?.model === "string" ? message.model : "";
+    return {
+        entryId,
+        sessionId,
+        timestamp,
+        kind,
+        model,
+        tokens: tokensFrom(usage),
+        cost: costFrom(usage),
+        cacheWrite1h: usage?.cacheWrite1h ?? 0,
+        droppedBefore: kind === "compaction" && typeof entry.tokensBefore === "number"
+            ? entry.tokensBefore
+            : null,
+        firstKeptEntryId: typeof entry.firstKeptEntryId === "string"
+            ? entry.firstKeptEntryId
+            : null,
+        digest: digestOf(entryId, timestamp, kind, usage),
+    };
+}
+/**
+ * Which turns are billable at all. An assistant turn and a compaction
+ * both cost money; a user message, a tool result and a state change do
+ * not. Enumerated rather than filtered, so a new entry type is ignored
+ * by omission instead of silently swept into a total.
+ */
+function kindOf(entry) {
+    if (entry.type === "compaction")
+        return "compaction";
+    const message = asRecord(entry.message);
+    if (message?.role === "assistant")
+        return "assistant";
+    return null;
+}
+function tokensFrom(usage) {
+    const input = usage?.input ?? 0;
+    const output = usage?.output ?? 0;
+    const cacheRead = usage?.cacheRead ?? 0;
+    const cacheWrite = usage?.cacheWrite ?? 0;
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        total: usage?.totalTokens ?? input + output + cacheRead + cacheWrite,
+    };
+}
+/** Null when the entry reported no cost, which is not the same as free. */
+function costFrom(usage) {
+    const cost = usage?.cost;
+    if (!cost || typeof cost.total !== "number")
+        return null;
+    return {
+        input: cost.input ?? 0,
+        output: cost.output ?? 0,
+        cacheRead: cost.cacheRead ?? 0,
+        cacheWrite: cost.cacheWrite ?? 0,
+        total: cost.total,
+    };
+}
+/**
+ * Address a turn by what it is rather than where it was found. Forking a
+ * session copies entries verbatim, ids included, so the same turn appears
+ * in several files and a naive count bills it more than once.
+ */
+function digestOf(entryId, timestamp, kind, usage) {
+    const canonical = JSON.stringify([
+        entryId,
+        timestamp,
+        kind,
+        usage?.cost?.total ?? null,
+        usage?.totalTokens ?? null,
+    ]);
+    return createHash("sha256")
+        .update(canonical)
+        .digest("hex")
+        .slice(0, DIGEST_CHARS);
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : null;
+}

package/dist/observability/ledger/session.d.ts

@@ -0,0 +1,38 @@
+import type { SessionRecord } from "./types.js";
+/**
+ * Name the repo a working directory belongs to, or nothing when the path
+ * names none.
+ *
+ * A monorepo zone is named by the zone rather than the worktree it was
+ * cut into, because two trees of the same zone are the same subject and
+ * naming the tree would split one zone's spend across every tree ever
+ * cut for it.
+ */
+export declare function repoOf(cwd: string | null): string | null;
+/**
+ * Accumulates what a log says about its session as the log is read, so
+ * one pass serves both the turns and their attribution.
+ */
+export declare class SessionCollector {
+    private readonly sessionId;
+    private cwd;
+    private quest;
+    private first;
+    private last;
+    constructor(sessionId: string);
+    /**
+     * Take the working directory from a session's header entry. Every log
+     * opens with one, which is what makes attribution complete rather than
+     * limited to the quarter of sessions that also name a quest.
+     */
+    observeHeader(entry: Record<string, unknown>): void;
+    /**
+     * Take the working directory and quest a workflow entry names. The
+     * last one wins, because a session can be re-pointed at another quest
+     * part way through and the later statement is the current one.
+     */
+    observeWorkflow(data: Record<string, unknown>): void;
+    /** Widen the span to include a billed turn. */
+    observeTurn(timestamp: string): void;
+    record(): SessionRecord;
+}

package/dist/observability/ledger/session.js

@@ -0,0 +1,89 @@
+/** Where a per-host checkout tree begins, as `src/{host}/{owner}/{repo}`. */
+const CHECKOUT_MARKER = "/src/";
+/** Where a monorepo worktree begins, as `world/trees/{tree}/src/{zone}`. */
+const MONOREPO_MARKER = "/world/trees/";
+/** Segments naming a repo under the checkout marker: host, owner, name. */
+const REPO_SEGMENTS = 3;
+/**
+ * Name the repo a working directory belongs to, or nothing when the path
+ * names none.
+ *
+ * A monorepo zone is named by the zone rather than the worktree it was
+ * cut into, because two trees of the same zone are the same subject and
+ * naming the tree would split one zone's spend across every tree ever
+ * cut for it.
+ */
+export function repoOf(cwd) {
+    if (!cwd)
+        return null;
+    const monorepo = cwd.indexOf(MONOREPO_MARKER);
+    if (monorepo >= 0) {
+        const tail = cwd.slice(monorepo + MONOREPO_MARKER.length);
+        const zone = tail.split("/src/")[1];
+        return zone ? `world/${zone}` : null;
+    }
+    const checkout = cwd.indexOf(CHECKOUT_MARKER);
+    if (checkout >= 0) {
+        const parts = cwd
+            .slice(checkout + CHECKOUT_MARKER.length)
+            .split("/")
+            .filter(Boolean);
+        if (parts.length >= REPO_SEGMENTS) {
+            return parts.slice(0, REPO_SEGMENTS).join("/");
+        }
+    }
+    return null;
+}
+/**
+ * Accumulates what a log says about its session as the log is read, so
+ * one pass serves both the turns and their attribution.
+ */
+export class SessionCollector {
+    sessionId;
+    cwd = null;
+    quest = null;
+    first = null;
+    last = null;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    /**
+     * Take the working directory from a session's header entry. Every log
+     * opens with one, which is what makes attribution complete rather than
+     * limited to the quarter of sessions that also name a quest.
+     */
+    observeHeader(entry) {
+        if (typeof entry.cwd === "string")
+            this.cwd = entry.cwd;
+    }
+    /**
+     * Take the working directory and quest a workflow entry names. The
+     * last one wins, because a session can be re-pointed at another quest
+     * part way through and the later statement is the current one.
+     */
+    observeWorkflow(data) {
+        if (typeof data.cwd === "string")
+            this.cwd = data.cwd;
+        if (typeof data.questId === "string")
+            this.quest = data.questId;
+    }
+    /** Widen the span to include a billed turn. */
+    observeTurn(timestamp) {
+        if (!timestamp)
+            return;
+        if (!this.first || timestamp < this.first)
+            this.first = timestamp;
+        if (!this.last || timestamp > this.last)
+            this.last = timestamp;
+    }
+    record() {
+        return {
+            sessionId: this.sessionId,
+            cwd: this.cwd,
+            repo: repoOf(this.cwd),
+            quest: this.quest,
+            firstSeen: this.first,
+            lastSeen: this.last,
+        };
+    }
+}

package/dist/observability/ledger/store.d.ts

@@ -21,7 +21,7 @@ export interface RecordOutcome {
     readonly duplicates: number;
 }
 /** What a total or a slice may be narrowed to. */
-export type CostDimension = "model" | "session" | "kind" | "day" | "repo" | "quest";
+export type CostDimension = "model" | "session" | "kind" | "day" | "repo" | "quest" | "thinking";
 /** A content-addressed store of billable turns. */
 export interface TurnStore {
     recordTurns(turns: readonly TurnRecord[]): Promise<RecordOutcome>;
@@ -40,6 +40,8 @@ export interface TurnStore {
     paybackReplay(): Promise<PaybackReplay>;
     total(): Promise<LedgerTotal>;
     costBy(dimension: CostDimension): Promise<CostSlice[]>;
+    /** Every session the ledger holds, for another store to join to. */
+    sessions(): Promise<SessionRecord[]>;
     close(): Promise<void>;
 }
 /**

package/dist/observability/ledger/store.js

@@ -80,6 +80,7 @@ const GROUP_BY = {
     // that quietly excluded most of the money.
     repo: "COALESCE(sessions.repo, '')",
     quest: "COALESCE(sessions.quest, '')",
+    thinking: "COALESCE(turns.thinking_level, '')",
 };
 /**
  * Open (creating if needed) a turn ledger at the given path. Safe to
@@ -90,8 +91,22 @@ export async function openTurnStore(dbPath) {
     const db = await openDb(dbPath);
     await db.exec("PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000;");
     await db.exec(SCHEMA);
+    await migrate(db);
     return new SqliteTurnStore(db);
 }
+/**
+ * Bring a ledger written at an older shape up to this one. A new ledger
+ * is created at the original shape and migrated like any other, so every
+ * test that opens a fresh store also exercises the path an existing file
+ * meets. Every step is additive, so nothing a ledger holds can be lost by
+ * opening it.
+ */
+async function migrate(db) {
+    const columns = new Set((await db.all("PRAGMA table_info(turns)")).map((column) => column.name));
+    if (!columns.has("thinking_level")) {
+        await db.exec("ALTER TABLE turns ADD COLUMN thinking_level TEXT");
+    }
+}
 class SqliteTurnStore {
     db;
     constructor(db) {
@@ -128,6 +143,7 @@ class SqliteTurnStore {
                 // Seen before, so not billed again, but the sighting is still
                 // recorded: deduplicating must not hide that it happened.
                 await this.sight(t);
+                await this.fillThinkingLevel(t);
                 continue;
             }
             inserted += 1;
@@ -136,8 +152,8 @@ class SqliteTurnStore {
 					tokens_input, tokens_output, tokens_cache_read,
 					tokens_cache_write, tokens_total, cache_write_1h,
 					cost_input, cost_output, cost_cache_read, cost_cache_write,
-					cost_total, dropped_before, first_kept_entry_id
-				) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+					cost_total, dropped_before, first_kept_entry_id, thinking_level
+				) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
                 t.digest,
                 t.entryId,
                 t.sessionId,
@@ -157,6 +173,7 @@ class SqliteTurnStore {
                 t.cost?.total ?? null,
                 t.droppedBefore,
                 t.firstKeptEntryId,
+                t.thinkingLevel,
             ]);
             await this.sight(t);
         }
@@ -498,9 +515,32 @@ class SqliteTurnStore {
             turns: r.turns,
         }));
     }
+    async sessions() {
+        const rows = await this.db.all(`SELECT session_id, cwd, repo, quest, first_seen, last_seen
+			FROM sessions ORDER BY session_id`);
+        return rows.map((r) => ({
+            sessionId: r.session_id,
+            cwd: r.cwd,
+            repo: r.repo,
+            quest: r.quest,
+            firstSeen: r.first_seen,
+            lastSeen: r.last_seen,
+        }));
+    }
     async close() {
         await this.db.close();
     }
+    /**
+     * Give a held turn the thinking level a later scan learned, when it
+     * had none. This is how a ledger indexed before the column existed
+     * gets it on the next rescan, without billing anything twice. A level
+     * already known is left alone: the same entry cannot have run at two.
+     */
+    async fillThinkingLevel(t) {
+        if (t.thinkingLevel === null)
+            return;
+        await this.db.run("UPDATE turns SET thinking_level = ? WHERE digest = ? AND thinking_level IS NULL", [t.thinkingLevel, t.digest]);
+    }
     async sight(t) {
         await this.db.run("INSERT OR IGNORE INTO sightings (digest, session_id) VALUES (?, ?)", [t.digest, t.sessionId]);
     }

package/dist/observability/ledger/types.d.ts

@@ -17,6 +17,13 @@ export interface TurnRecord {
     readonly kind: TurnKind;
     /** Resolved model id, or empty when the entry did not say. */
     readonly model: string;
+    /**
+     * The thinking level the turn ran at, as the log last set it before
+     * the turn, or null when the log never said. Unknown is not a level:
+     * guessing the harness default would put spend on a setting that may
+     * not have been in force.
+     */
+    readonly thinkingLevel: string | null;
     readonly tokens: RunTokens;
     /** Null when unmetered. Never coerced to zero. */
     readonly cost: RunCost | null;

package/dist/slack/auth/browser-extract.js

@@ -11,7 +11,6 @@
  * with web-search-integration.
  */
 import * as fs from "node:fs";
-import puppeteer from "puppeteer-core";
 /**
  * Default Slack URL to navigate to: the dedicated sign-in entry
  * point, not the marketing homepage. app.slack.com used to be here
@@ -76,6 +75,9 @@ function findChrome() {
  */
 export async function extractFromBrowser(slackUrl = DEFAULT_SLACK_URL, timeoutMs = DEFAULT_TIMEOUT_MS, onStep) {
     const chromePath = findChrome();
+    // Loaded here rather than at import, since this runs once per
+    // Slack setup and the module is imported on every start.
+    const { default: puppeteer } = await import("puppeteer-core");
     const browser = await puppeteer.launch({
         executablePath: chromePath,
         headless: false,

package/dist/web/browser.d.ts

@@ -11,7 +11,7 @@
  * plus a shared in-flight launch promise, means one browser and
  * one profile no matter how many extensions reach for it.
  */
-import { type Browser, type BrowserContext, type Page } from "puppeteer-core";
+import type { Browser, BrowserContext, Page } from "puppeteer-core";
 /** Diagnostic detail teased out of a failed Chrome launch. */
 export interface LaunchFailureInfo {
     exitCode?: number;

package/dist/web/browser.js

@@ -17,8 +17,15 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { clearTimeout, setTimeout } from "node:timers";
-import puppeteer from "puppeteer-core";
 import { processGlobal } from "../internal/process-global.js";
+/**
+ * puppeteer, loaded when a browser is first launched or joined rather
+ * than whenever this module is imported, since most sessions never
+ * open one.
+ */
+async function puppeteer() {
+    return (await import("puppeteer-core")).default;
+}
 /** How many times to try launching Chrome before giving up. */
 const LAUNCH_ATTEMPTS = 3;
 /** Backoff before each retry, in milliseconds. The array length is
@@ -507,7 +514,7 @@ async function launchOnce(executablePath) {
     // prior attempt cannot poison this one.
     fs.rmSync(profileDir, { recursive: true, force: true });
     fs.mkdirSync(profileDir, { recursive: true });
-    const browser = await puppeteer.launch({
+    const browser = await (await puppeteer()).launch({
         executablePath,
         headless: true,
         userDataDir: profileDir,
@@ -594,7 +601,7 @@ export async function connectShared() {
         if (!owner?.browserWSEndpoint || !isPidAlive(owner.ownerPid))
             continue;
         try {
-            return await puppeteer.connect({
+            return await (await puppeteer()).connect({
                 browserWSEndpoint: owner.browserWSEndpoint,
             });
         }

package/dist/web/reader.js

@@ -13,8 +13,6 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { Defuddle } from "defuddle/node";
-import { JSDOM, VirtualConsole } from "jsdom";
 import { isPidAlive, newPage } from "./browser.js";
 import { injectCookies, isSetUp } from "./cookies/index.js";
 import { BUNDLE_ROOT, diskSink, LEGACY_BUNDLE_ROOTS, sessionDir, } from "./envelope/sink.js";
@@ -145,8 +143,8 @@ function cleanText(text) {
  * Create a jsdom VirtualConsole that suppresses CSS parse warnings
  * without affecting process.stderr globally.
  */
-function quietVirtualConsole() {
-    const vc = new VirtualConsole();
+function quietVirtualConsole(Console) {
+    const vc = new Console();
     vc.on("error", (msg) => {
         if (!msg.includes("Could not parse CSS stylesheet")) {
             console.error(msg);
@@ -163,7 +161,14 @@ function quietVirtualConsole() {
  */
 async function extractArticle(html, url) {
     try {
-        const dom = new JSDOM(html, { url, virtualConsole: quietVirtualConsole() });
+        // jsdom and defuddle load on the first page read rather than at
+        // import: jsdom alone is a full browser DOM, over 100 MB.
+        const { JSDOM, VirtualConsole } = await import("jsdom");
+        const { Defuddle } = await import("defuddle/node");
+        const dom = new JSDOM(html, {
+            url,
+            virtualConsole: quietVirtualConsole(VirtualConsole),
+        });
         const result = await Defuddle(dom.window.document, url, {
             markdown: true,
             useAsync: false,

package/dist/web/session/emulation.js

@@ -7,7 +7,9 @@
  * Applying, observing and diverging all live here so the one
  * piece of state has one keeper.
  */
-import { KnownDevices } from "puppeteer-core";
+// The catalogue's own module, rather than puppeteer's root, which
+// would load all of puppeteer to read one table.
+import { KnownDevices } from "puppeteer-core/internal/common/Device.js";
 import { deviceEmulation, noSuchDevice } from "../environment/devices.js";
 import { divergences, ENVIRONMENT_PROBE, mediaFeaturesOf, mergeEmulation, refusedFeature, unsupportedFields, withoutFeature, } from "../environment/index.js";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jitsusama/agentic-harness.core",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Pi-agnostic business logic for agentic-harness: state machines, guardian decisions, quest/TDD domain model.",
 	"license": "MIT",
 	"type": "module",