@multileaf/ai-workflow 0.7.0 → 0.9.0

package/dist/usage-import.js

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+const zeroTiers = () => ({
+    "cache-read": 0,
+    "fresh-input": 0,
+    "cache-write": 0,
+    output: 0,
+});
+const tiersOf = (values) => ({
+    ...zeroTiers(),
+    ...Object.fromEntries(Object.entries(values).filter(([, value]) => value > 0)),
+});
+function event(source, identity, tiers, extra = {}) {
+    if (!USAGE_TIERS_NONZERO(tiers))
+        return undefined;
+    const hash = createHash("sha256").update(identity).digest("hex").slice(0, 12);
+    const imported = {
+        command: `import.${source}.e${hash}`,
+        label: "measured",
+        tiers,
+        harness: source === "gemini" ? "gemini-cli" : source,
+        ...(extra.model ? { model: extra.model } : {}),
+        ...(extra.provider ? { provider: extra.provider } : {}),
+        ...(extra.harnessVersion ? { harnessVersion: extra.harnessVersion } : {}),
+    };
+    return imported;
+}
+function USAGE_TIERS_NONZERO(tiers) {
+    return Object.values(tiers).some((value) => value > 0);
+}
+function safeParse(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return parsed && typeof parsed === "object" ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Claude Code: one JSONL transcript per session; dedupe assistant chunks by message id. */
+export function parseClaudeCodeTranscript(content) {
+    const events = [];
+    const seen = new Set();
+    for (const line of content.split("\n")) {
+        if (!line.includes('"usage"'))
+            continue;
+        const entry = safeParse(line);
+        if (!entry || entry.type !== "assistant")
+            continue;
+        const message = entry.message;
+        const usage = message?.usage;
+        if (!message || !usage)
+            continue;
+        const messageId = String(message.id ?? "");
+        if (!messageId || seen.has(messageId))
+            continue;
+        seen.add(messageId);
+        const parsed = event("claude-code", `${entry.sessionId ?? ""}:${messageId}`, tiersOf({
+            "fresh-input": usage.input_tokens ?? 0,
+            "cache-write": usage.cache_creation_input_tokens ?? 0,
+            "cache-read": usage.cache_read_input_tokens ?? 0,
+            output: usage.output_tokens ?? 0,
+        }), {
+            model: typeof message.model === "string" ? message.model : undefined,
+            harnessVersion: typeof entry.version === "string" ? entry.version : undefined,
+        });
+        if (parsed)
+            events.push(parsed);
+    }
+    return events;
+}
+/** Codex: rollout JSONL; returns undefined when the session belongs to another project. */
+export function parseCodexSession(content, projectRoot) {
+    const events = [];
+    let sessionCwd;
+    let cliVersion;
+    let model;
+    for (const line of content.split("\n")) {
+        const entry = safeParse(line);
+        if (!entry)
+            continue;
+        const payload = (entry.payload ?? {});
+        if (entry.type === "session_meta") {
+            sessionCwd = typeof payload.cwd === "string" ? payload.cwd : undefined;
+            cliVersion = typeof payload.cli_version === "string" ? payload.cli_version : undefined;
+            continue;
+        }
+        if (entry.type === "turn_context" && typeof payload.model === "string")
+            model = payload.model;
+        if (entry.type !== "token_usage_record")
+            continue;
+        const usage = payload.usage;
+        if (!usage)
+            continue;
+        const cached = usage.cached_input_tokens ?? 0;
+        const cacheWrite = usage.cache_write_input_tokens ?? 0;
+        const input = usage.input_tokens ?? 0;
+        const parsed = event("codex", `${payload.response_id ?? createHash("sha256").update(line).digest("hex").slice(0, 16)}:${payload.turn_id ?? ""}:${entry.ordinal ?? ""}`, tiersOf({
+            "cache-read": cached,
+            "cache-write": cacheWrite,
+            "fresh-input": Math.max(0, input - cached - cacheWrite),
+            output: usage.output_tokens ?? 0,
+        }), { model, harnessVersion: cliVersion });
+        if (parsed)
+            events.push(parsed);
+    }
+    if (sessionCwd === undefined)
+        return undefined;
+    if (sessionCwd.replace(/\/+$/, "") !== projectRoot.replace(/\/+$/, ""))
+        return undefined;
+    return events;
+}
+/** Gemini (antigravity-cli): transcript_full JSONL; PLANNER_RESPONSE steps carry token counts. */
+export function parseGeminiTranscript(content) {
+    const events = [];
+    for (const line of content.split("\n")) {
+        if (!line.includes("input_tokens"))
+            continue;
+        const entry = safeParse(line);
+        if (!entry || entry.type !== "PLANNER_RESPONSE")
+            continue;
+        const num = (value) => (typeof value === "number" ? value : 0);
+        const parsed = event("gemini", `${entry.created_at ?? ""}:${entry.step_index ?? ""}:${createHash("sha256").update(line).digest("hex").slice(0, 16)}`, tiersOf({
+            "fresh-input": num(entry.input_tokens),
+            "cache-read": num(entry.cache_read_tokens),
+            output: num(entry.output_tokens),
+        }));
+        if (parsed)
+            events.push(parsed);
+    }
+    return events;
+}
+/** Pi (pi.dev): session JSONL; assistant messages and dedicated usage entries both carry per-message tiers and provider. */
+export function parsePiSession(content) {
+    const events = [];
+    for (const line of content.split("\n")) {
+        if (!line.includes('"usage"'))
+            continue;
+        const entry = safeParse(line);
+        if (!entry)
+            continue;
+        const message = entry.message;
+        const usage = (message?.usage ?? entry.usage);
+        if (!usage)
+            continue;
+        if (entry.type === "message" && message?.role !== "assistant")
+            continue;
+        const parsed = event("pi", String(entry.id ?? createHash("sha256").update(line).digest("hex").slice(0, 16)), tiersOf({
+            "fresh-input": usage.input ?? 0,
+            "cache-read": usage.cacheRead ?? 0,
+            "cache-write": usage.cacheWrite ?? 0,
+            output: usage.output ?? 0,
+        }), {
+            model: typeof message?.model === "string"
+                ? message.model
+                : typeof entry.model === "string"
+                    ? entry.model
+                    : undefined,
+            provider: typeof message?.provider === "string"
+                ? message.provider
+                : typeof entry.provider === "string"
+                    ? entry.provider
+                    : undefined,
+        });
+        if (parsed)
+            events.push(parsed);
+    }
+    return events;
+}
+/** Merge imported events into a ledger idempotently (already-present command ids are skipped). */
+export function mergeImportedEvents(ledger, events) {
+    const existing = new Set(ledger.map((entry) => entry.command));
+    const fresh = events.filter((candidate) => !existing.has(candidate.command));
+    return {
+        ledger: [
+            ...ledger,
+            ...fresh.map((candidate, index) => ({ ...candidate, seq: ledger.length + index + 1 })),
+        ],
+        imported: fresh.length,
+        skipped: events.length - fresh.length,
+    };
+}
+export function summarizeImport(result) {
+    return [
+        `source: ${result.source}`,
+        `files scanned: ${result.files}`,
+        `usage events found: ${result.events}`,
+        `imported: ${result.imported} (label: measured)`,
+        `skipped (already in ledger): ${result.skipped}`,
+    ].join("\n");
+}

package/dist/usage-sidecar.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Usage sidecar (switchboard pattern): per-run token records with billing
+ * tiers, measurement labels, and harness attribution, stored alongside
+ * workflow checkpoints.
+ *
+ * Honest-measurement rules (docs/token-efficiency-study-notes.md):
+ * - every entry carries `measured` or `estimated`; aggregates propagate the
+ *   label pessimistically (any estimated component makes the total estimated);
+ * - no timestamps: entries are ordered by a monotonic sequence number, so
+ *   unchanged input produces byte-identical output;
+ * - naive `tokens x price` accounting overstates savings on cache-heavy
+ *   agents, so tiers are kept separate and cache hit rate is a first-class
+ *   metric. Cost conversion is deliberately not built in: provider prices
+ *   rot, and unlabeled dollars would be dishonest by default.
+ */
+export declare const USAGE_SIDECAR_SCHEMA = 1;
+export declare const USAGE_SIDECAR_PATH = "checkpoints/usage-sidecar.yml";
+export declare const USAGE_SIDECAR_CAP = 500;
+export declare const USAGE_TIERS: readonly ["cache-read", "fresh-input", "cache-write", "output"];
+export type UsageTier = (typeof USAGE_TIERS)[number];
+export type UsageLabel = "measured" | "estimated";
+export type UsageSidecarEntry = {
+    seq: number;
+    command: string;
+    label: UsageLabel;
+    tiers: Record<UsageTier, number>;
+    model?: string;
+    provider?: string;
+    harness?: string;
+    harnessVersion?: string;
+    requirement?: string;
+    /** Correlates entries with one SDD task run (`aiw task start --id=` or ticket), start to merged PR. */
+    workflow?: string;
+};
+export type UsageSidecarSummary = {
+    entries: number;
+    label: UsageLabel;
+    tiers: Record<UsageTier, number>;
+    cacheHitRate?: number;
+    byModel: {
+        model: string;
+        tokens: number;
+        label: UsageLabel;
+    }[];
+    byHarness: {
+        harness: string;
+        tokens: number;
+        label: UsageLabel;
+    }[];
+    byProvider: {
+        provider: string;
+        tokens: number;
+        label: UsageLabel;
+    }[];
+};
+export declare function validateUsageSidecarEntry(entry: UsageSidecarEntry): UsageSidecarEntry;
+export declare function parseUsageSidecar(content: string): UsageSidecarEntry[];
+export declare function serializeUsageSidecar(entries: UsageSidecarEntry[]): string;
+/** Append an entry, assigning the next sequence number. Drops nothing: the ledger is capped by the caller. */
+export declare function appendUsageSidecarEntry(entries: UsageSidecarEntry[], entry: Omit<UsageSidecarEntry, "seq">): UsageSidecarEntry[];
+export declare function summarizeUsageSidecar(entries: UsageSidecarEntry[]): UsageSidecarSummary;
+export declare function serializeUsageSidecarSummary(summary: UsageSidecarSummary): string;

package/dist/usage-sidecar.js

@@ -0,0 +1,200 @@
+import { isSeq, parseDocument } from "yaml";
+/**
+ * Usage sidecar (switchboard pattern): per-run token records with billing
+ * tiers, measurement labels, and harness attribution, stored alongside
+ * workflow checkpoints.
+ *
+ * Honest-measurement rules (docs/token-efficiency-study-notes.md):
+ * - every entry carries `measured` or `estimated`; aggregates propagate the
+ *   label pessimistically (any estimated component makes the total estimated);
+ * - no timestamps: entries are ordered by a monotonic sequence number, so
+ *   unchanged input produces byte-identical output;
+ * - naive `tokens x price` accounting overstates savings on cache-heavy
+ *   agents, so tiers are kept separate and cache hit rate is a first-class
+ *   metric. Cost conversion is deliberately not built in: provider prices
+ *   rot, and unlabeled dollars would be dishonest by default.
+ */
+export const USAGE_SIDECAR_SCHEMA = 1;
+export const USAGE_SIDECAR_PATH = "checkpoints/usage-sidecar.yml";
+export const USAGE_SIDECAR_CAP = 500;
+export const USAGE_TIERS = ["cache-read", "fresh-input", "cache-write", "output"];
+export function validateUsageSidecarEntry(entry) {
+    if (!Number.isInteger(entry.seq) || entry.seq < 1)
+        throw new Error("Usage sidecar seq must be a positive integer.");
+    if (!entry.command.trim())
+        throw new Error("Usage sidecar command must not be empty.");
+    for (const tier of USAGE_TIERS) {
+        const value = entry.tiers[tier];
+        if (!Number.isInteger(value) || value < 0)
+            throw new Error(`Usage sidecar tier ${tier} must be a non-negative integer.`);
+    }
+    if (!USAGE_TIERS.some((tier) => entry.tiers[tier] > 0))
+        throw new Error("Usage sidecar entry needs at least one non-zero tier.");
+    if (entry.model !== undefined && !entry.model.trim())
+        throw new Error("Usage sidecar model must be a non-empty string when present.");
+    if (entry.provider !== undefined && !entry.provider.trim())
+        throw new Error("Usage sidecar provider must be a non-empty string when present.");
+    if (entry.requirement !== undefined && !/^REQ-\d+$/.test(entry.requirement))
+        throw new Error("Usage sidecar requirement must use the REQ-### identifier format.");
+    if (entry.workflow !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(entry.workflow))
+        throw new Error("Usage sidecar workflow must be a workflow id or ticket identifier without spaces.");
+    for (const [name, value] of [
+        ["harness", entry.harness],
+        ["harnessVersion", entry.harnessVersion],
+    ])
+        if (value !== undefined && !value.trim())
+            throw new Error(`Usage sidecar ${name} must be a non-empty string when present.`);
+    return entry;
+}
+export function parseUsageSidecar(content) {
+    if (!content.trim())
+        return [];
+    const document = parseDocument(content);
+    if (document.errors.length)
+        throw new Error("Usage sidecar is not valid YAML.");
+    const node = document.get("entries");
+    if (node === null || node === undefined)
+        throw new Error("Usage sidecar is missing entries.");
+    if (!isSeq(node))
+        throw new Error("Usage sidecar entries must be a list.");
+    const schema = document.get("schema");
+    if (schema !== USAGE_SIDECAR_SCHEMA)
+        throw new Error(`Usage sidecar schema must be version ${USAGE_SIDECAR_SCHEMA}.`);
+    const entries = node.items.map((raw) => {
+        const pick = (key) => typeof raw.get === "function"
+            ? raw.get(key)
+            : raw[key];
+        const tiers = {};
+        const rawTiers = pick("tiers");
+        if (rawTiers === null || typeof rawTiers !== "object")
+            throw new Error("Usage sidecar entry is missing tiers.");
+        const readTier = (tier) => typeof rawTiers.get === "function"
+            ? rawTiers.get(tier)
+            : rawTiers[tier];
+        for (const tier of USAGE_TIERS) {
+            const value = readTier(tier);
+            if (value !== null && value !== undefined)
+                tiers[tier] = value;
+        }
+        const optional = (key) => {
+            const value = pick(key);
+            return value === null || value === undefined ? undefined : String(value);
+        };
+        return validateUsageSidecarEntry({
+            seq: pick("seq"),
+            command: String(pick("command")),
+            label: pick("label"),
+            tiers: Object.fromEntries(USAGE_TIERS.map((tier) => [tier, tiers[tier] ?? 0])),
+            ...(optional("model") === undefined ? {} : { model: optional("model") }),
+            ...(optional("provider") === undefined ? {} : { provider: optional("provider") }),
+            ...(optional("harness") === undefined ? {} : { harness: optional("harness") }),
+            ...(optional("harness_version") === undefined
+                ? {}
+                : { harnessVersion: optional("harness_version") }),
+            ...(optional("requirement") === undefined ? {} : { requirement: optional("requirement") }),
+            ...(optional("workflow") === undefined ? {} : { workflow: optional("workflow") }),
+        });
+    });
+    const sequences = entries.map((entry) => entry.seq);
+    if (new Set(sequences).size !== sequences.length)
+        throw new Error("Usage sidecar sequence numbers must be unique.");
+    return entries;
+}
+export function serializeUsageSidecar(entries) {
+    const lines = [`schema: ${USAGE_SIDECAR_SCHEMA}`, "entries:"];
+    for (const entry of entries) {
+        lines.push(`  - seq: ${entry.seq}`, `    command: ${entry.command}`, `    label: ${entry.label}`, "    tiers:", ...USAGE_TIERS.map((tier) => `      ${tier}: ${entry.tiers[tier]}`), ...(entry.model === undefined ? [] : [`    model: ${entry.model}`]), ...(entry.provider === undefined ? [] : [`    provider: ${entry.provider}`]), ...(entry.harness === undefined ? [] : [`    harness: ${entry.harness}`]), ...(entry.harnessVersion === undefined
+            ? []
+            : [`    harness_version: ${entry.harnessVersion}`]), ...(entry.requirement === undefined ? [] : [`    requirement: ${entry.requirement}`]), ...(entry.workflow === undefined ? [] : [`    workflow: ${entry.workflow}`]));
+    }
+    return lines.join("\n") + "\n";
+}
+/** Append an entry, assigning the next sequence number. Drops nothing: the ledger is capped by the caller. */
+export function appendUsageSidecarEntry(entries, entry) {
+    validateUsageSidecarEntry({ ...entry, seq: 1 });
+    const nextSeq = entries.reduce((max, existing) => Math.max(max, existing.seq), 0) + 1;
+    const recorded = [...entries, { ...entry, seq: nextSeq }];
+    return recorded.length > USAGE_SIDECAR_CAP
+        ? recorded.slice(recorded.length - USAGE_SIDECAR_CAP)
+        : recorded;
+}
+const totalTokens = (entry) => USAGE_TIERS.reduce((total, tier) => total + entry.tiers[tier], 0);
+export function summarizeUsageSidecar(entries) {
+    if (!entries.length)
+        return {
+            entries: 0,
+            label: "measured",
+            tiers: Object.fromEntries(USAGE_TIERS.map((tier) => [tier, 0])),
+            cacheHitRate: undefined,
+            byModel: [],
+            byProvider: [],
+            byHarness: [],
+        };
+    const tiers = Object.fromEntries(USAGE_TIERS.map((tier) => [
+        tier,
+        entries.reduce((total, entry) => total + entry.tiers[tier], 0),
+    ]));
+    const billableInput = tiers["cache-read"] + tiers["fresh-input"];
+    const group = (key) => {
+        const map = new Map();
+        for (const entry of entries) {
+            const name = entry[key] ?? "unattributed";
+            const bucket = map.get(name) ?? { tokens: 0, measured: true };
+            bucket.tokens += totalTokens(entry);
+            bucket.measured = bucket.measured && entry.label === "measured";
+            map.set(name, bucket);
+        }
+        return [...map]
+            .map(([name, { tokens, measured }]) => ({
+            name,
+            tokens,
+            label: measured ? "measured" : "estimated",
+        }))
+            .sort((a, b) => b.tokens - a.tokens || a.name.localeCompare(b.name));
+    };
+    return {
+        entries: entries.length,
+        label: entries.every((entry) => entry.label === "measured") ? "measured" : "estimated",
+        tiers,
+        ...(billableInput > 0 ? { cacheHitRate: tiers["cache-read"] / billableInput } : {}),
+        byModel: group("model").map(({ name, tokens, label }) => ({ model: name, tokens, label })),
+        byProvider: group("provider")
+            .filter(({ name }) => name !== "unattributed")
+            .map(({ name, tokens, label }) => ({ provider: name, tokens, label })),
+        byHarness: group("harness").map(({ name, tokens, label }) => ({
+            harness: name,
+            tokens,
+            label,
+        })),
+    };
+}
+export function serializeUsageSidecarSummary(summary) {
+    if (!summary.entries)
+        return "No usage sidecar entries recorded.";
+    const percent = summary.cacheHitRate === undefined ? undefined : `${Math.round(summary.cacheHitRate * 100)}%`;
+    return [
+        `entries: ${summary.entries} (label: ${summary.label})`,
+        ...USAGE_TIERS.map((tier) => `  ${tier}: ${summary.tiers[tier].toLocaleString("en-US")} tokens`),
+        ...(percent === undefined
+            ? []
+            : [`  cache_hit_rate: ${percent} (cache-read / billable input)`]),
+        ...(summary.byModel.length
+            ? [
+                "by model:",
+                ...summary.byModel.map(({ model, tokens, label }) => `  - ${model}: ${tokens.toLocaleString("en-US")} (${label})`),
+            ]
+            : []),
+        ...(summary.byHarness.length
+            ? [
+                "by harness:",
+                ...summary.byHarness.map(({ harness, tokens, label }) => `  - ${harness}: ${tokens.toLocaleString("en-US")} (${label})`),
+            ]
+            : []),
+        ...(summary.byProvider.length
+            ? [
+                "by provider:",
+                ...summary.byProvider.map(({ provider, tokens, label }) => `  - ${provider}: ${tokens.toLocaleString("en-US")} (${label})`),
+            ]
+            : []),
+    ].join("\n");
+}