@jitsusama/agentic-harness.core 0.5.0 → 0.6.1

package/dist/attribution/commit-hook.d.ts

@@ -42,11 +42,14 @@ export interface HookInstall {
 export declare function installCommitHook(repoRoot: string, options: CommitHookOptions): HookInstall;
 /**
  * Ensure the hook is installed in the repo containing dir, at most
- * once per repo root. Resolves the repo, records it in `installed`
- * so later commands in the same repo are skipped, and installs
- * best-effort. A directory outside any git repo is a no-op. This is
- * how hook coverage follows the session into repos it later cds
- * into, rather than only the repo the session started in.
+ * once per repo. Records both dir and its repo root in `installed`,
+ * so a later command from either asks git nothing, and installs
+ * best-effort. A directory outside any git repo is a no-op and is
+ * not remembered, so a repo initialised there later is still
+ * covered. This is how hook coverage follows the session into repos
+ * it later cds into, rather than only the repo the session started
+ * in. Each git call is a synchronous spawn on the command path, so
+ * a first visit costs one and a repeat costs none.
  */
 export declare function ensureCommitHook(dir: string, installed: Set<string>, options: CommitHookOptions): void;
 /** The git repository root containing dir, or null when there is none. */

package/dist/attribution/commit-hook.js

@@ -46,20 +46,20 @@ git interpret-trailers --in-place --trailer ${options.trailerExpr} "$msg_file"
  * hook. A no-op when this adapter's hook is already installed.
  */
 export function installCommitHook(repoRoot, options) {
+    const layout = locateHooks(repoRoot);
+    if (!layout)
+        return { installed: false, reason: "not a git repo" };
+    return installInto(layout, options);
+}
+/** Install the hook into a repo whose hooks have been located. */
+function installInto({ hooksDir, customHooksPath }, options) {
     // A custom core.hooksPath means a hook manager (husky and the
     // like) or a shared, possibly version-controlled hooks directory
     // owns the hooks. Leave it alone rather than write this adapter's
     // hook into a directory it does not own.
-    if (hasCustomHooksPath(repoRoot)) {
+    if (customHooksPath) {
         return { installed: false, reason: "custom core.hooksPath configured" };
     }
-    let hooksDir;
-    try {
-        hooksDir = resolveHooksDir(repoRoot);
-    }
-    catch (error) {
-        return { installed: false, reason: `not a git repo: ${String(error)}` };
-    }
     const target = join(hooksDir, "prepare-commit-msg");
     if (existsSync(target) &&
         readFileSync(target, "utf8").includes(options.marker)) {
@@ -82,41 +82,66 @@ export function installCommitHook(repoRoot, options) {
     chmodSync(target, 0o755);
     return { installed: true };
 }
-/** Whether the repo configures a custom core.hooksPath. */
-function hasCustomHooksPath(repoRoot) {
-    try {
-        const value = execFileSync("git", ["-C", repoRoot, "config", "--get", "core.hooksPath"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-        return value.length > 0;
-    }
-    catch {
-        // git config exits non-zero when the key is unset: no custom path.
-        return false;
-    }
-}
 /**
  * Ensure the hook is installed in the repo containing dir, at most
- * once per repo root. Resolves the repo, records it in `installed`
- * so later commands in the same repo are skipped, and installs
- * best-effort. A directory outside any git repo is a no-op. This is
- * how hook coverage follows the session into repos it later cds
- * into, rather than only the repo the session started in.
+ * once per repo. Records both dir and its repo root in `installed`,
+ * so a later command from either asks git nothing, and installs
+ * best-effort. A directory outside any git repo is a no-op and is
+ * not remembered, so a repo initialised there later is still
+ * covered. This is how hook coverage follows the session into repos
+ * it later cds into, rather than only the repo the session started
+ * in. Each git call is a synchronous spawn on the command path, so
+ * a first visit costs one and a repeat costs none.
  */
 export function ensureCommitHook(dir, installed, options) {
-    const root = repoRootOf(dir);
-    if (!root || installed.has(root))
+    if (installed.has(dir))
+        return;
+    const layout = locateHooks(dir);
+    if (!layout)
         return;
-    installed.add(root);
+    installed.add(dir);
+    if (installed.has(layout.root))
+        return;
+    installed.add(layout.root);
     try {
-        installCommitHook(root, options);
+        installInto(layout, options);
     }
     catch {
         // Best-effort: never let hook installation break a command.
     }
 }
-/** Resolve the active hooks directory, honouring core.hooksPath. */
-function resolveHooksDir(repoRoot) {
-    const path = execFileSync("git", ["-C", repoRoot, "rev-parse", "--git-path", "hooks"], { encoding: "utf8" }).trim();
-    return isAbsolute(path) ? path : join(repoRoot, path);
+/**
+ * Locate the hooks of the repo containing dir with one git call, or
+ * null when dir is in no working tree. Git prints the default hooks
+ * path as the common dir plus `/hooks`, in the same form, so any
+ * other answer means core.hooksPath points somewhere else.
+ */
+function locateHooks(dir) {
+    let answer;
+    try {
+        answer = execFileSync("git", [
+            "-C",
+            dir,
+            "rev-parse",
+            "--show-toplevel",
+            "--git-common-dir",
+            "--git-path",
+            "hooks",
+        ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        // Not in a working tree (or git unavailable): nothing to hook.
+        return null;
+    }
+    const [root, commonDir, hooks] = answer.trimEnd().split("\n");
+    if (!root || !commonDir || !hooks)
+        return null;
+    return {
+        root,
+        // Relative paths are relative to the directory git ran in.
+        hooksDir: isAbsolute(hooks) ? hooks : join(dir, hooks),
+        customHooksPath: hooks !== `${commonDir}/hooks`,
+    };
 }
 /** The git repository root containing dir, or null when there is none. */
 export function repoRootOf(dir) {

package/dist/internal/quest/process-liveness.d.ts

@@ -79,6 +79,11 @@ export declare function identityFromInspection(hostId: string, pid: number, insp
  * read a real start token: a session then carries no process identity
  * and its liveness falls back to recency, rather than a synthetic
  * token that a later probe would read as a dead mismatch.
+ *
+ * A process's own start token cannot change while it runs, so the
+ * first real reading is remembered: a session start attaches more
+ * than once and each reading is a synchronous `ps`. A failed reading
+ * is not remembered, so a transient failure is retried next time.
  */
 export declare function currentProcessIdentity(): ProcessIdentity | undefined;
 /**

package/dist/internal/quest/process-liveness.js

@@ -95,14 +95,26 @@ export function identityFromInspection(hostId, pid, inspection) {
         ? { hostId, pid, startToken: inspection.startToken }
         : undefined;
 }
+/** Memoized identity of this process, once one has been read. */
+let processIdentityCache;
 /**
  * Identity of the currently running pi process, for capture onto the
  * session it is attached to. Undefined when the OS reader could not
  * read a real start token: a session then carries no process identity
  * and its liveness falls back to recency, rather than a synthetic
  * token that a later probe would read as a dead mismatch.
+ *
+ * A process's own start token cannot change while it runs, so the
+ * first real reading is remembered: a session start attaches more
+ * than once and each reading is a synchronous `ps`. A failed reading
+ * is not remembered, so a transient failure is retried next time.
  */
 export function currentProcessIdentity() {
+    processIdentityCache ??= readProcessIdentity();
+    return processIdentityCache;
+}
+/** Read this process's identity from the OS. */
+function readProcessIdentity() {
     const identity = identityFromInspection(hostname(), process.pid, readStartToken(process.pid));
     if (!identity)
         return undefined;

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.5.0",
+	"version": "0.6.1",
 	"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,
-        };
-    }
-}