@mnemom/mnemom 0.17.34-next.2 → 0.17.34-next.3

package/dist/lib/scan/report-email.d.ts

@@ -1,8 +1,9 @@
+import { type CostPerPr, type CostSpend } from "./cost-per-pr.js";
 import type { ScanResult } from "./scan.js";
 import type { ShareLevel } from "./share.js";
 export declare const REPORT_SCHEMA_VERSION = "org-scan-report/1";
 export declare const ESTIMATE_NAME = "automatable_work_share";
-export declare const METHOD_URL = "https://www.mnemom.ai/method";
+export declare const METHOD_URL = "https://www.mnemom.ai/org-scan-method";
 export interface EmailReport {
     schema_version: typeof REPORT_SCHEMA_VERSION;
     org_id: string;
@@ -39,6 +40,22 @@ export interface EmailReport {
         unit: string;
         method_url: string;
     };
+    /**
+     * Optional, added after org-scan-report/1 shipped; absent whenever it cannot be computed (no spend,
+     * no merged PR in the period, an incomplete scan, an empty bucket). See cost-per-pr.ts.
+     *   cost_per_merged_pr  average cost of one merged PR in the period
+     *   cost_by_pr_size     { small | medium | large }: average cost of ONE PR of that size, per-bucket
+     *                       keys absent when the bucket is empty. small < 50 lines changed, medium 50..500, large > 500.
+     * A figure is { label: "estimate", spend_source, pr_scope, pr_count } (+ spend_scope: "whole_org" on
+     * anthropic_usage) plus { value_cents } (anthropic_usage) or { low_cents, high_cents } (modelled_range). Integer cents.
+     * pr_scope is "ai_assisted" for modelled_range (spend and size buckets split across AI-assisted PRs only;
+     * absent if none) and "all_merged" otherwise; pr_count counts PRs in that scope.
+     * Always attached when present. The API's report validator (mnemom-api src/org-scan/report-schema.ts) is
+     * closed, so an API that does not yet list these keys answers 400 invalid_report; sendReportEmail then
+     * retries once without them so the report email still goes out.
+     */
+    cost_per_merged_pr?: CostPerPr["cost_per_merged_pr"];
+    cost_by_pr_size?: CostPerPr["cost_by_pr_size"];
 }
 export interface ReportEmailBody {
     report: EmailReport;
@@ -56,13 +73,16 @@ export interface ReportEmailBody {
  */
 export declare function buildEmailReport(result: ScanResult, o: {
     orgId: string;
-    period: {
-        start: string;
-        end: string;
-    };
     now: () => number;
     sendSpendRange: boolean;
     scanId?: string;
+    /** The requested scan period (the one the spend covers), not the examined window. */
+    period?: {
+        start: string;
+        end: string;
+    };
+    /** The one spend source the cost figures are split from; null/absent leaves them out. */
+    costSpend?: CostSpend | null;
 }): EmailReport;
 export declare function buildEmailBody(report: EmailReport, level: ShareLevel, complete: boolean, ctoEmail?: string): ReportEmailBody;
 /** Closed set of failure names; each has fixed text. */

package/dist/lib/scan/report-email.js

@@ -13,9 +13,10 @@
  */
 import { randomUUID } from "node:crypto";
 import { MnemomApiError, postApi } from "../api.js";
+import { buildCostPerPr } from "./cost-per-pr.js";
 export const REPORT_SCHEMA_VERSION = "org-scan-report/1";
 export const ESTIMATE_NAME = "automatable_work_share";
-export const METHOD_URL = "https://www.mnemom.ai/method";
+export const METHOD_URL = "https://www.mnemom.ai/org-scan-method";
 const cents = (usd) => Math.max(0, Math.round(usd * 100));
 /**
  * Maps the local scan onto the route's closed report shape. Team totals stay empty (they come only from
@@ -36,11 +37,16 @@ export function buildEmailReport(result, o) {
             .filter(([, n]) => typeof n === "number" && n > 0)
             .map(([tool, count]) => ({ tool, count: count }))
         : [];
+    // Only a scan that read every merged PR in the period gives an average that means anything.
+    const exhaustive = coverage.complete && coverage.prsSkippedLarge === 0 && coverage.prsUnreadable === 0;
+    const cost = buildCostPerPr(result.prSizes, o.period ?? { start: coverage.windowStart, end: coverage.windowEnd }, o.costSpend ?? null, exhaustive);
     return {
         schema_version: REPORT_SCHEMA_VERSION,
         org_id: o.orgId,
         scan_id: o.scanId ?? randomUUID(),
-        period: o.period,
+        // The span the scan actually examined (coverage), never the requested period: with no --period
+        // that defaults to today..today, which is not what was read.
+        period: { start: coverage.windowStart, end: coverage.windowEnd },
         generated_at: new Date(o.now()).toISOString(),
         measured: {
             teams: [],
@@ -65,6 +71,7 @@ export function buildEmailReport(result, o) {
             },
         },
         estimate: { name: ESTIMATE_NAME, value, unit, method_url: METHOD_URL },
+        ...cost,
     };
 }
 export function buildEmailBody(report, level, complete, ctoEmail) {
@@ -111,6 +118,13 @@ function classifyStatus(status) {
         return "report_rejected";
     return "unexpected_response";
 }
+/** The body without the optional cost figures; the same object when it carries none. */
+function withoutCostFigures(body) {
+    const { cost_per_merged_pr: _a, cost_by_pr_size: _b, ...rest } = body.report;
+    return "cost_per_merged_pr" in body.report || "cost_by_pr_size" in body.report
+        ? { ...body, report: rest }
+        : body;
+}
 /** Never throws. The thrown value, the response body and the credential are never surfaced. */
 export async function sendReportEmail(orgId, body, deps = {}) {
     const post = deps.post ?? defaultPost;
@@ -121,6 +135,13 @@ export async function sendReportEmail(orgId, body, deps = {}) {
     catch (e) {
         if (e instanceof MnemomApiError && e.effectiveStatus === 404)
             return { status: "unavailable" };
+        // An API that predates the cost figures rejects the unknown keys with a 400. The email must still
+        // go out, so retry once with the figures left off; any other failure is classified as below.
+        if (e instanceof MnemomApiError && e.effectiveStatus === 400) {
+            const bare = withoutCostFigures(body);
+            if (bare !== body)
+                return sendReportEmail(orgId, bare, deps);
+        }
         if (e instanceof MnemomApiError) {
             // A 4xx that names the runner (the API refuses a send that would skip the runner) gets its own text.
             if (e.effectiveStatus >= 400 && e.effectiveStatus < 500 && /runner/i.test(e.code ?? ""))

package/dist/lib/scan/scan.d.ts

@@ -7,6 +7,7 @@ import { type GitHubCredential } from "./credential.js";
 import { type ScanCaps, type StopReason } from "./caps.js";
 import { type FailureReason } from "./failure.js";
 import { type PrSource } from "./pr-source.js";
+import type { PrSize } from "./cost-per-pr.js";
 import { type SpendEstimate } from "./spend/spend-estimate.js";
 export interface ScanInput {
     repos: string[];
@@ -53,6 +54,8 @@ export interface ScanResult {
     };
     byRepo: RepoTotals[];
     spend: SpendEstimate;
+    /** Every merged PR read in full (reverts and unreadable/oversize PRs excluded): merge day and size. In memory only. */
+    prSizes: PrSize[];
 }
 export type ScanOutcome = {
     status: "done";

package/dist/lib/scan/scan.js

@@ -109,6 +109,7 @@ export async function runLocalScan(deps, input) {
         };
         const totals = { prs: 0, reverts: 0, ciGreen: 0, examined: 0 };
         const spendInputs = [];
+        const prSizes = [];
         let skippedLarge = 0;
         let unreadable = 0;
         for (const { repo, item } of chosen) {
@@ -146,6 +147,11 @@ export async function runLocalScan(deps, input) {
                 totals.ciGreen += 1;
                 bucket(repo).ciGreen += 1;
             }
+            prSizes.push({
+                mergedDay: item.mergedDay,
+                lines: rec.additions + rec.deletions,
+                aiAssisted: (rec.tools?.length ?? 0) > 0,
+            });
             spendInputs.push({
                 additions: rec.additions,
                 deletions: rec.deletions,
@@ -172,7 +178,13 @@ export async function runLocalScan(deps, input) {
         };
         return {
             status: "done",
-            result: { coverage, totals, byRepo: [...byRepo.values()], spend: estimateSpend(spendInputs) },
+            result: {
+                coverage,
+                totals,
+                byRepo: [...byRepo.values()],
+                spend: estimateSpend(spendInputs),
+                prSizes,
+            },
         };
     }
     catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.34-next.2",
+  "version": "0.17.34-next.3",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {

package/dist/lib/durable/first-turn.d.ts

@@ -1,50 +0,0 @@
-/**
- * Lock after the first turn (ruling dogfood B5). A launch that locks a NEW Claude Code session
- * (`durable = always`, or ask answered yes, with no transcript yet) cannot lock before claude has
- * run: the daemon's seat resumes the session's transcript, and there is none until the first turn
- * writes it (host/transcript.ts ensureTranscript answers lost, the session fails transcript_lost).
- *
- * So the launcher spawns claude attended and watches the transcript. Once the first turn has
- * completed it locks, under the running-session handover (C02-R26: freeze, commit, the seat's
- * hello, then the original is killed and the parent attaches to the seat). Never before. A lock
- * refusal at that point leaves the attended session running and prints the refusal with its fix
- * line.
- *
- * No I/O here: lib/durable/live.ts wires the transcript reads, the lock and the clock.
- */
-import type { LockOutcome, TranscriptDirs } from "../../commands/durable-lock.js";
-import { DurableRefusal } from "./refusal.js";
-/** How often the launcher re-reads the transcript while it waits for the first turn. */
-export declare const FIRST_TURN_POLL_MS = 1000;
-/**
- * Whether a Claude Code transcript (JSONL) holds a completed turn: an assistant entry whose
- * stop_reason ends the turn (end_turn, max_tokens, stop_sequence, refusal), or the engine's own
- * turn-end record (system turn_duration or stop_hook_summary). Unparseable lines (a line still
- * being written) are skipped.
- */
-export declare function turnCompleted(jsonl: string): boolean;
-/**
- * Reads `<projects>/<dir>/<cc>.jsonl` from the first project dir that holds it; null while none
- * does, when it cannot be read (it is read again on the next poll), or with no CC session id.
- */
-export declare function transcriptReader(projects: string, dirs: TranscriptDirs, cc: string | null | undefined, read: (path: string) => string): () => string | null;
-export interface FirstTurnLockDeps {
-    /** The session name (the fix line of a lock that could not be sent). */
-    name: string;
-    /** The session's transcript text, or null while Claude Code has written none. */
-    readTranscript(): string | null;
-    /** The attended claude is still running. */
-    childAlive(): boolean;
-    /** The lock of the row under the running-session handover (lockResolvedRow). */
-    lock(): Promise<LockOutcome>;
-    /** Print a lock refusal and its fix line (the session stays attended). */
-    printRefusal(r: DurableRefusal): void;
-    sleep(ms: number): Promise<void>;
-}
-export type FirstTurnLock = "locked" | "refused" | "ended";
-/**
- * Wait for the first completed turn, then lock. "ended": claude exited first, nothing was locked.
- * "locked": the handover took the session (the parent's exit path attaches to the seat).
- * "refused": the refusal was printed and the attended session goes on.
- */
-export declare function lockAfterFirstTurn(d: FirstTurnLockDeps, pollMs?: number): Promise<FirstTurnLock>;

package/dist/lib/durable/first-turn.js

@@ -1,102 +0,0 @@
-/**
- * Lock after the first turn (ruling dogfood B5). A launch that locks a NEW Claude Code session
- * (`durable = always`, or ask answered yes, with no transcript yet) cannot lock before claude has
- * run: the daemon's seat resumes the session's transcript, and there is none until the first turn
- * writes it (host/transcript.ts ensureTranscript answers lost, the session fails transcript_lost).
- *
- * So the launcher spawns claude attended and watches the transcript. Once the first turn has
- * completed it locks, under the running-session handover (C02-R26: freeze, commit, the seat's
- * hello, then the original is killed and the parent attaches to the seat). Never before. A lock
- * refusal at that point leaves the attended session running and prints the refusal with its fix
- * line.
- *
- * No I/O here: lib/durable/live.ts wires the transcript reads, the lock and the clock.
- */
-import { join } from "node:path";
-import { DurableRefusal } from "./refusal.js";
-/** How often the launcher re-reads the transcript while it waits for the first turn. */
-export const FIRST_TURN_POLL_MS = 1000;
-/** An assistant stop that ends the turn: anything but a tool call or a paused turn. */
-const TURN_CONTINUES = new Set(["tool_use", "pause_turn"]);
-/**
- * Whether a Claude Code transcript (JSONL) holds a completed turn: an assistant entry whose
- * stop_reason ends the turn (end_turn, max_tokens, stop_sequence, refusal), or the engine's own
- * turn-end record (system turn_duration or stop_hook_summary). Unparseable lines (a line still
- * being written) are skipped.
- */
-export function turnCompleted(jsonl) {
-    for (const line of jsonl.split("\n")) {
-        let e;
-        try {
-            e = JSON.parse(line);
-        }
-        catch {
-            continue;
-        }
-        if (e === null || typeof e !== "object")
-            continue;
-        const r = e;
-        if (r.type === "system" && (r.subtype === "turn_duration" || r.subtype === "stop_hook_summary"))
-            return true;
-        if (r.type !== "assistant" || r.message === null || typeof r.message !== "object")
-            continue;
-        const stop = r.message.stop_reason;
-        if (typeof stop === "string" && !TURN_CONTINUES.has(stop))
-            return true;
-    }
-    return false;
-}
-/**
- * Reads `<projects>/<dir>/<cc>.jsonl` from the first project dir that holds it; null while none
- * does, when it cannot be read (it is read again on the next poll), or with no CC session id.
- */
-export function transcriptReader(projects, dirs, cc, read) {
-    return () => {
-        if (!cc)
-            return null;
-        const found = dirs(cc)?.[0];
-        if (found === undefined)
-            return null;
-        try {
-            return read(join(projects, found, `${cc}.jsonl`));
-        }
-        catch {
-            return null;
-        }
-    };
-}
-/**
- * Wait for the first completed turn, then lock. "ended": claude exited first, nothing was locked.
- * "locked": the handover took the session (the parent's exit path attaches to the seat).
- * "refused": the refusal was printed and the attended session goes on.
- */
-export async function lockAfterFirstTurn(d, pollMs = FIRST_TURN_POLL_MS) {
-    for (;;) {
-        if (!d.childAlive())
-            return "ended";
-        const t = d.readTranscript();
-        if (t !== null && turnCompleted(t))
-            break;
-        await d.sleep(pollMs);
-    }
-    let o;
-    try {
-        o = await d.lock();
-    }
-    catch (e) {
-        o = {
-            ok: false,
-            refusal: e instanceof DurableRefusal
-                ? e
-                : new DurableRefusal({
-                    code: "session_registry_unavailable",
-                    message: `mnemom agent: the lock after the first turn failed (${e instanceof Error ? e.message : String(e)}); the session stays attended`,
-                    fix: `\`mnemom agent lock ${d.name}\``,
-                }),
-        };
-    }
-    if (o.ok)
-        return "locked";
-    d.printRefusal(o.refusal);
-    return "refused";
-}