@jitsusama/agentic-harness.core 0.4.0 → 0.6.0

package/dist/observability/ledger/store.js

@@ -52,6 +52,8 @@ CREATE TABLE IF NOT EXISTS tool_calls (
 CREATE INDEX IF NOT EXISTS tool_calls_verifier ON tool_calls (verifier_kind);
 CREATE INDEX IF NOT EXISTS tool_calls_args ON tool_calls (session_id, args_digest);
 CREATE INDEX IF NOT EXISTS tool_calls_path ON tool_calls (path);
+CREATE INDEX IF NOT EXISTS tool_calls_session_verifier
+	ON tool_calls (session_id, timestamp) WHERE verifier_kind IS NOT NULL;
 CREATE TABLE IF NOT EXISTS dropped_calls (
 	digest TEXT PRIMARY KEY,
 	session_id TEXT NOT NULL,
@@ -301,18 +303,32 @@ class SqliteTurnStore {
         const changed = writtenBetween("o", "o.previous_at", "o.timestamp", scope.writers);
         const rows = await this.db.all(`WITH ordered AS (
 				SELECT c.session_id, c.args_digest, c.name, c.path,
-					c.timestamp, c.result_chars,
+					c.timestamp, c.result_chars, c.verifier_kind,
 					LAG(c.timestamp) OVER (
 						PARTITION BY c.session_id, c.args_digest
 						ORDER BY c.timestamp, c.digest
 					) AS previous_at
 				FROM tool_calls AS c
 				WHERE ${retrieval.sql}
+			),
+			repeats AS (
+				SELECT o.session_id, o.args_digest, o.name, o.result_chars,
+					(o.verifier_kind IS NOT NULL OR EXISTS (
+						SELECT 1 FROM tool_calls AS v
+						WHERE v.session_id = o.session_id
+							AND v.verifier_kind IS NOT NULL
+							AND v.timestamp > o.previous_at
+							AND v.timestamp < o.timestamp
+					)) AS is_appraisal
+				FROM ordered AS o
+				WHERE o.previous_at IS NOT NULL AND NOT (${changed.sql})
 			)
 			SELECT args_digest, name, COUNT(*) AS repeated,
-				SUM(COALESCE(result_chars, 0)) AS repeated_chars
-			FROM ordered AS o
-			WHERE o.previous_at IS NOT NULL AND NOT (${changed.sql})
+				SUM(COALESCE(result_chars, 0)) AS repeated_chars,
+				SUM(is_appraisal) AS appraisal,
+				SUM(CASE WHEN is_appraisal THEN COALESCE(result_chars, 0) ELSE 0 END)
+					AS appraisal_chars
+			FROM repeats
 			GROUP BY session_id, args_digest
 			ORDER BY repeated_chars DESC`, [...retrieval.params, ...changed.params]);
         return rows.map((row) => ({
@@ -321,6 +337,10 @@ class SqliteTurnStore {
             asked: row.repeated + 1,
             repeated: row.repeated,
             repeatedChars: row.repeated_chars ?? 0,
+            rework: row.repeated - row.appraisal,
+            reworkChars: (row.repeated_chars ?? 0) - (row.appraisal_chars ?? 0),
+            appraisal: row.appraisal,
+            appraisalChars: row.appraisal_chars ?? 0,
         }));
     }
     async recordDropped(dropped) {

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

@@ -181,6 +181,18 @@ export interface RepeatedCall {
     readonly repeated: number;
     /** Characters the repeats re-admitted to the context. */
     readonly repeatedChars: number;
+    /** Repeats with no verifier since the last ask: the waste bucket. */
+    readonly rework: number;
+    /** Characters the rework repeats re-admitted. */
+    readonly reworkChars: number;
+    /**
+     * Repeats that are themselves a verifier, or that follow one run
+     * since the last ask: the model checking its work, which is cost of
+     * quality rather than waste.
+     */
+    readonly appraisal: number;
+    /** Characters the appraisal repeats re-admitted. */
+    readonly appraisalChars: number;
 }
 /**
  * What a session log says about itself.

package/dist/observability/recorder.d.ts

@@ -13,9 +13,16 @@ export interface RunRecordInput {
     readonly kind: string;
     readonly model: string;
     readonly persona: string;
+    /** The thinking level the run was launched at, null when unknown. */
+    readonly thinkingLevel: string | null;
     readonly startedAt: number;
     readonly result: {
         readonly exitCode: number;
+        /**
+         * The session ids the run's child processes announced, in order.
+         * Empty when there was no child process, null when not known.
+         */
+        readonly sessionIds: readonly string[] | null;
         readonly warnings: readonly string[];
         readonly usage?: {
             readonly tokens: RunTokens;

package/dist/observability/recorder.js

@@ -34,6 +34,8 @@ export function runRecordFrom(input) {
         tokens: result.usage?.tokens ?? null,
         cost: result.usage?.cost ?? null,
         startedAt: input.startedAt,
+        thinkingLevel: input.thinkingLevel,
+        subagentSessionIds: result.sessionIds,
     };
 }
 // Process-global so a producer extension's recordRunEverywhere

package/dist/observability/store.js

@@ -77,7 +77,7 @@ async function migrate(db) {
         // a later metered run cannot be reclassified.
         await db.exec("UPDATE runs SET metered = 0 WHERE tokens_total = 0 AND cost_total = 0");
     }
-    for (const [name, type] of ATTRIBUTION_COLUMNS) {
+    for (const [name, type] of [...ATTRIBUTION_COLUMNS, ...LAUNCH_COLUMNS]) {
         if (!columns.has(name)) {
             await db.exec(`ALTER TABLE runs ADD COLUMN ${name} ${type}`);
         }
@@ -110,6 +110,15 @@ const ATTRIBUTION_COLUMNS = [
     ["repo", "TEXT"],
     ["ended_at", "INTEGER"],
 ];
+/**
+ * How a run was launched, nullable for the same reason: rows written
+ * before these existed never said.
+ */
+const LAUNCH_COLUMNS = [
+    ["thinking_level", "TEXT"],
+    // A JSON array of session ids; null when not known.
+    ["subagent_session_ids", "TEXT"],
+];
 class SqliteRunStore {
     db;
     constructor(db) {
@@ -121,8 +130,9 @@ class SqliteRunStore {
 				retries_to_valid, warning_count, exit_code,
 				tokens_input, tokens_output, tokens_cache_read, tokens_cache_write, tokens_total,
 				cost_input, cost_output, cost_cache_read, cost_cache_write, cost_total,
-				started_at, metered, session_id, cwd, repo, ended_at
-			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+				started_at, metered, session_id, cwd, repo, ended_at,
+				thinking_level, subagent_session_ids
+			) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
 			ON CONFLICT (run_id, subagent_id) DO UPDATE SET
 				kind = excluded.kind, model = excluded.model,
 				persona = excluded.persona, verify_outcome = excluded.verify_outcome,
@@ -141,7 +151,9 @@ class SqliteRunStore {
 				cost_total = excluded.cost_total,
 				started_at = excluded.started_at, metered = excluded.metered,
 				session_id = excluded.session_id, cwd = excluded.cwd,
-				repo = excluded.repo, ended_at = excluded.ended_at`, [
+				repo = excluded.repo, ended_at = excluded.ended_at,
+				thinking_level = excluded.thinking_level,
+				subagent_session_ids = excluded.subagent_session_ids`, [
             record.runId,
             record.subagentId,
             record.kind,
@@ -170,6 +182,10 @@ class SqliteRunStore {
             record.cwd ?? null,
             record.repo ?? null,
             record.endedAt ?? null,
+            record.thinkingLevel ?? null,
+            record.subagentSessionIds
+                ? JSON.stringify(record.subagentSessionIds)
+                : null,
         ]);
     }
     async queryRuns(filter = {}) {
@@ -272,6 +288,27 @@ class SqliteRunStore {
         await this.db.close();
     }
 }
+/**
+ * Read the stored session list back. Anything that is not an array of
+ * strings reads as unknown rather than as a partial list, since a list
+ * with a session missing would join a job to less of its bill without
+ * saying so.
+ */
+function sessionIdsFrom(stored) {
+    if (stored === null)
+        return null;
+    try {
+        const parsed = JSON.parse(stored);
+        return Array.isArray(parsed) &&
+            parsed.every((id) => typeof id === "string")
+            ? parsed
+            : null;
+    }
+    catch {
+        // Not JSON, so not something this store wrote: unknown.
+        return null;
+    }
+}
 function rowToRecord(row) {
     return {
         runId: row.run_id,
@@ -306,5 +343,7 @@ function rowToRecord(row) {
         cwd: row.cwd ?? null,
         repo: row.repo ?? null,
         endedAt: row.ended_at ?? null,
+        thinkingLevel: row.thinking_level ?? null,
+        subagentSessionIds: sessionIdsFrom(row.subagent_session_ids),
     };
 }

package/dist/observability/types.d.ts

@@ -59,6 +59,22 @@ export interface RunRecord {
     readonly cost: RunCost | null;
     /** When the run started, epoch milliseconds. */
     readonly startedAt: number;
+    /**
+     * The thinking level the run was launched at, or null when the
+     * launch did not name one and the level it inherited is not known.
+     * Required so a producer has to say, since a level left out reads
+     * the same as one nobody knew.
+     */
+    readonly thinkingLevel: string | null;
+    /**
+     * Every pi session the run's own processes announced, in order,
+     * which are the ids billing rows carry. Usually one; a stopped
+     * reviewer asked for its findings is a second process with a second
+     * session. Distinct from {@link sessionId}, the parent that
+     * dispatched the run. Empty when the run had no child process, as an
+     * in-process run does not; null when nobody knows.
+     */
+    readonly subagentSessionIds: readonly string[] | null;
     /**
      * The parent session that dispatched the run, the directory it was
      * working in and the repo that directory belongs to. Stamped by the

package/package.json

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

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

@@ -1,11 +0,0 @@
-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

@@ -1,159 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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

@@ -1,89 +0,0 @@
-/** 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,
-        };
-    }
-}