@loompad/cli 0.1.0 → 1.1.2

package/dist/observability/decisions.js

@@ -0,0 +1,377 @@
+/**
+ * Decision capture — the KAIRO-style "what did each agent decide, and why".
+ *
+ * Every substantial agent turn contains deliberate choices (a tech pick, an
+ * approach, a fix). This extracts them into structured AgentDecisions, through
+ * whichever extractor this machine actually has, in descending order of how much
+ * it can be trusted to judge its own certainty:
+ *
+ *   "llm"       the Anthropic API, when ANTHROPIC_API_KEY is set;
+ *   "cli"       a signed-in local agent CLI driven headlessly — `agy --print`
+ *               (Antigravity, cheap Gemini model) or `claude -p`. Same trick
+ *               observability/triage.ts uses to get real prose with no API key;
+ *   "heuristic" a regex over the prose, when there is no model at all.
+ *
+ * That order is also why `confidence` is OPTIONAL. A model reading the turn can
+ * say how sure the agent sounded; a regex matching "I'll use X because Y"
+ * cannot, and the constants it used to stamp (70/75/78/80) were rendered to
+ * users as a measured percentage with a progress bar and averaged into a fleet
+ * "Avg confidence" tile. A heuristic decision now carries no confidence at all,
+ * and `source` says how it was extracted, so nothing downstream has to guess
+ * whether a number was measured or invented.
+ *
+ * The result is persisted per project and surfaced in the Observatory Decision
+ * Explorer, the Timeline, and the Time-Travel Replay.
+ */
+import { spawn } from "../core/process.js";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { agentEnv } from "../adapters/base.js";
+const CATEGORIES = ["architecture", "design", "implementation", "fix", "refactor", "test", "other"];
+const DECISION_MODEL = process.env.LOOM_DECISION_MODEL || "claude-haiku-4-5-20251001";
+const DECISION_EXTRACT_PROMPT = `You are analyzing an AI coding agent's turn output.
+Extract all significant decisions the agent made. A decision is a deliberate choice
+between alternatives — tech choices, architectural decisions, implementation approaches.
+
+For each decision, output JSON with this exact shape:
+{
+  "decisions": [
+    {
+      "category": "architecture|design|implementation|fix|refactor|test|other",
+      "title": "short label under 60 chars",
+      "reasoning": "why the agent chose this (1-2 sentences)",
+      "confidence": 85,
+      "alternatives": ["other option 1", "other option 2"],
+      "filesCreated": ["path/to/file.ts"],
+      "filesModified": ["path/to/existing.ts"],
+      "artifactNames": ["ComponentName", "functionName"]
+    }
+  ]
+}
+
+Rules:
+- Only extract REAL decisions, not descriptions of what was done
+- confidence: how sure the AGENT sounded about this choice, 0-100. 90+ very
+  sure, 70-89 reasonably sure, below 70 uncertain. Judge it from the text; if
+  the text gives you nothing to judge it by, OMIT the field entirely rather
+  than guessing a number
+- alternatives: what the agent explicitly considered OR obvious alternatives
+- If no clear decisions, return {"decisions": []}
+- Output ONLY valid JSON, no markdown, no explanation
+
+Agent turn output to analyze:
+`;
+/**
+ * Truncate to a word boundary with an ellipsis — never mid-word. A decision
+ * title cut at a raw 60 chars reads as broken ("…Redis to store and"); cut at
+ * the last whole word with an ellipsis reads as intentional.
+ */
+function clip(s, max = 60) {
+    const t = String(s ?? "").trim();
+    if (t.length <= max)
+        return t;
+    const cut = t.slice(0, max);
+    const sp = cut.lastIndexOf(" ");
+    return (sp > max * 0.6 ? cut.slice(0, sp) : cut).replace(/[\s,;:.\-]+$/, "") + "…";
+}
+/** Coerce one loose object from the model into a well-formed RawDecision. */
+function normalizeRaw(d) {
+    const cat = String(d.category ?? "other");
+    const arr = (v) => (Array.isArray(v) ? v.map((x) => String(x)).filter(Boolean) : []);
+    const conf = Number(d.confidence);
+    return {
+        category: CATEGORIES.includes(cat) ? cat : "other",
+        title: clip(String(d.title ?? "")) || "decision",
+        reasoning: String(d.reasoning ?? ""),
+        // A model that declined to answer, or answered with junk, gets no
+        // confidence — not a plausible-looking default standing in for one.
+        ...(Number.isFinite(conf) ? { confidence: Math.max(0, Math.min(100, Math.round(conf))) } : {}),
+        alternatives: arr(d.alternatives).slice(0, 6),
+        filesCreated: arr(d.filesCreated),
+        filesModified: arr(d.filesModified),
+        artifactNames: arr(d.artifactNames).slice(0, 12),
+    };
+}
+/** Parse the model's JSON reply (tolerating ```json fences) into RawDecisions. */
+export function parseDecisionsJson(text) {
+    const cleaned = (text || "").replace(/```json|```/g, "").trim();
+    if (!cleaned)
+        return [];
+    try {
+        const parsed = JSON.parse(cleaned);
+        const list = Array.isArray(parsed?.decisions) ? parsed.decisions : [];
+        return list.map((d) => normalizeRaw((d ?? {})));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Regex fallback — pull decisions from natural phrasings ("I'll use X because Y",
+ * "Instead of X, I'll Y") when there is no model of any kind to read the turn.
+ *
+ * It emits NO confidence, deliberately. Matching a sentence shape tells you a
+ * decision was stated; it tells you nothing whatsoever about how sure the agent
+ * was, and the 75/78/80 these branches used to stamp were numbers nobody
+ * measured, shown to users as if somebody had.
+ */
+export function extractDecisionsRegex(text) {
+    const decisions = [];
+    const base = { filesCreated: [], filesModified: [], artifactNames: [] };
+    const usePattern = /I(?:'ll| will) (?:use|implement|create|build|add|go with|adopt) ([^.]+?) (?:because|since|as|so that) ([^.]+)\./gi;
+    let m;
+    while ((m = usePattern.exec(text)) !== null) {
+        decisions.push({ ...base, category: "implementation", title: clip(m[1]), reasoning: m[2].trim(), alternatives: [] });
+    }
+    const insteadPattern = /[Ii]nstead of ([^,]+), I(?:'ll| will) ([^.]+)\./g;
+    while ((m = insteadPattern.exec(text)) !== null) {
+        decisions.push({ ...base, category: "implementation", title: clip(m[2]), reasoning: `Preferred over: ${m[1].trim()}`, alternatives: [m[1].trim()] });
+    }
+    const choosePattern = /I(?:'ve| have)? (?:chose|decided|opted|picked)(?: to| for)? ([^.]+?)(?: (?:because|since|to) ([^.]+))?\./gi;
+    while ((m = choosePattern.exec(text)) !== null) {
+        decisions.push({ ...base, category: "implementation", title: clip(m[1]), reasoning: (m[2] ?? "chosen approach").trim(), alternatives: [] });
+    }
+    return decisions.slice(0, 5);
+}
+/** Call the Anthropic API to extract decisions; empty on any failure. */
+async function llmExtract(turnText, apiKey) {
+    if (typeof globalThis.fetch !== "function")
+        return [];
+    try {
+        const res = await fetch("https://api.anthropic.com/v1/messages", {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-api-key": apiKey, "anthropic-version": "2023-06-01" },
+            body: JSON.stringify({
+                model: DECISION_MODEL,
+                max_tokens: 1000,
+                messages: [{ role: "user", content: DECISION_EXTRACT_PROMPT + turnText.slice(0, 3000) }],
+            }),
+        });
+        if (!res.ok)
+            return [];
+        const j = (await res.json());
+        const text = (j.content ?? []).map((c) => c.text ?? "").join("").trim();
+        return parseDecisionsJson(text);
+    }
+    catch {
+        return [];
+    }
+}
+/** agy's cheap tier; the extraction is a small structured read, not reasoning. */
+const AGY_MODEL = process.env.LOOM_DECISION_AGY_MODEL || "gemini-3.6-flash-low";
+/** The claude alias used when agy isn't installed. Small + fast is right. */
+const CLAUDE_MODEL = process.env.LOOM_DECISION_CLAUDE_MODEL || "haiku";
+/** Where the agy installer drops the binary; it isn't always on the daemon's PATH. */
+const AGY_INSTALLED = path.join(os.homedir(), ".local", "bin", "agy");
+/**
+ * Run one CLI to completion and return its stdout, or null on timeout, crash,
+ * or an empty answer. Deliberately the same shape as triage.ts's `claudeCli`:
+ * neutral cwd (no project trust dialog, no CLAUDE.md dragged into context),
+ * stdin closed (both CLIs stall in print mode with a pipe open), and `agentEnv`
+ * so a daemon started from inside a Claude Code session doesn't hand the child
+ * a session-scoped token that answers with nothing.
+ */
+function runCli(bin, args, timeoutMs) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(bin, args, { stdio: ["ignore", "pipe", "ignore"], cwd: os.tmpdir(), env: agentEnv() });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        let out = "";
+        const kill = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* already gone */
+            }
+            resolve(null);
+        }, timeoutMs);
+        kill.unref?.();
+        child.stdout?.on("data", (d) => (out += d.toString()));
+        child.on("error", () => {
+            clearTimeout(kill);
+            resolve(null);
+        });
+        child.on("close", () => {
+            clearTimeout(kill);
+            resolve(out.trim() || null);
+        });
+    });
+}
+/**
+ * The default CLI extractor: `agy --print` if Antigravity is installed, else
+ * `claude -p`. agy is preferred because a turn handed to it runs on Gemini
+ * rather than spending the orchestrator's Claude budget — the same reason the
+ * antigravity-cli adapter exists.
+ *
+ * Returns null when neither CLI is present, which is what demotes extraction to
+ * the regex (and to no confidence at all).
+ */
+export const defaultCliExtractor = async (prompt) => {
+    if (fs.existsSync(AGY_INSTALLED)) {
+        const out = await runCli(AGY_INSTALLED, ["--print", prompt, "--model", AGY_MODEL, "--dangerously-skip-permissions", "--print-timeout", "90s"], 120_000);
+        if (out)
+            return out;
+    }
+    // `claude -p --output-format json` puts the completion in `.result`; the
+    // parser below tolerates either that wrapper or bare text.
+    return await runCli("claude", ["-p", prompt, "--output-format", "json", "--model", CLAUDE_MODEL], 90_000);
+};
+/**
+ * Pull the completion out of whatever a CLI printed: the `.result` of claude's
+ * JSON wrapper, or the raw text agy prints. Kept separate from
+ * `parseDecisionsJson` because that one is looking for the decisions document,
+ * and one of these two CLIs wraps it in another one.
+ */
+export function unwrapCliOutput(raw) {
+    const text = (raw ?? "").trim();
+    if (!text)
+        return "";
+    try {
+        const j = JSON.parse(text);
+        if (Array.isArray(j?.decisions))
+            return text; // already the document we want
+        if (j?.is_error)
+            return "";
+        return typeof j?.result === "string" ? j.result.trim() : "";
+    }
+    catch {
+        return text; // not JSON — agy's markdown, which parseDecisionsJson defences
+    }
+}
+/** Ask a local CLI to read the turn; empty on any failure. */
+async function cliExtract(turnText, extractor) {
+    const out = await extractor(DECISION_EXTRACT_PROMPT + turnText.slice(0, 3000)).catch(() => null);
+    return parseDecisionsJson(unwrapCliOutput(out));
+}
+/** Extract structured decisions from one completed turn. */
+export async function extractDecisions(opts) {
+    const { turnText, filesChanged, anthropicApiKey } = opts;
+    // Skip trivial turns (greetings, acknowledgements).
+    if ((turnText ?? "").trim().length < 100)
+        return [];
+    let raw = [];
+    let source = "heuristic";
+    if (anthropicApiKey) {
+        raw = await llmExtract(turnText, anthropicApiKey);
+        if (raw.length)
+            source = "llm";
+    }
+    // Deterministic escape hatch (tests, or an operator who wants no shell-outs).
+    if (raw.length === 0 && process.env.LOOM_DECISIONS_NO_CLI !== "1") {
+        raw = await cliExtract(turnText, opts.cliExtractor ?? defaultCliExtractor);
+        if (raw.length)
+            source = "cli";
+    }
+    if (raw.length === 0) {
+        raw = extractDecisionsRegex(turnText);
+        source = "heuristic";
+    }
+    const changed = new Set(filesChanged);
+    const now = Date.now();
+    return raw.map((d, i) => ({
+        id: `${opts.projectId}-${opts.chatId}-t${opts.turnIndex}-d${i}-${now}`,
+        projectId: opts.projectId,
+        chatId: opts.chatId,
+        agentId: opts.agentId,
+        agentRole: opts.agentRole,
+        timestamp: now,
+        turnIndex: opts.turnIndex,
+        // Absent, not "", when this turn has no trace: the difference is a working
+        // link versus one that opens a backend search for nothing.
+        ...(opts.traceId ? { traceId: opts.traceId } : {}),
+        ...(opts.turnId ? { turnId: opts.turnId } : {}),
+        category: d.category,
+        title: d.title,
+        reasoning: d.reasoning,
+        ...(d.confidence !== undefined ? { confidence: d.confidence } : {}),
+        source,
+        alternatives: d.alternatives,
+        // Only keep file claims the turn actually changed (when we know the diff).
+        filesCreated: changed.size ? d.filesCreated.filter((f) => changed.has(f)) : d.filesCreated,
+        filesModified: changed.size ? d.filesModified.filter((f) => changed.has(f)) : d.filesModified,
+        artifactNames: d.artifactNames,
+        memoryKeys: [],
+        upstreamDecisionIds: [],
+        turnTokensUsed: opts.turnTokensUsed,
+        turnCostUsd: opts.turnCostUsd,
+        durationMs: opts.durationMs,
+    }));
+}
+/**
+ * Read one decision back out of the persisted store, in today's shape.
+ *
+ * Records written before `source` existed are the problem this handles. Every
+ * one of them carries a confidence, and on a machine with no ANTHROPIC_API_KEY
+ * — which is the machine most of them were written on — that number came from
+ * the regex's 70/75/78/80 constants. It is not distinguishable from a measured
+ * one, and a number you cannot tell apart from an invented number must not be
+ * rendered as a measurement. So a record with no `source` is read as heuristic
+ * and reports no confidence.
+ *
+ * A projection, not a migration: the file on disk is untouched, and a record
+ * written from here on carries its real source and is passed through as-is.
+ * The old turn-total names are mapped across for the same reason.
+ */
+export function normalizeStoredDecision(raw) {
+    const { tokensUsed, costUsd, confidence, traceId, ...rest } = raw;
+    // A record with a source states how it was extracted and can be believed; one
+    // without predates the distinction and keeps nothing it can't account for.
+    const measured = raw.source !== undefined ? confidence : undefined;
+    return {
+        ...rest,
+        source: raw.source ?? "heuristic",
+        ...(typeof measured === "number" ? { confidence: measured } : {}),
+        // "" was what "no trace" used to look like; it links to nothing.
+        ...(traceId ? { traceId } : {}),
+        turnTokensUsed: raw.turnTokensUsed ?? tokensUsed ?? 0,
+        turnCostUsd: raw.turnCostUsd ?? costUsd ?? 0,
+    };
+}
+/** Roll up decisions for the Explorer header + KAIRO metrics. */
+export function decisionStats(decisions) {
+    const byAgent = {};
+    const byCategory = {};
+    const bySource = { llm: 0, cli: 0, heuristic: 0 };
+    const altCounts = new Map();
+    let confSum = 0;
+    let confSamples = 0;
+    for (const d of decisions) {
+        byAgent[d.agentId] = (byAgent[d.agentId] ?? 0) + 1;
+        byCategory[d.category] = (byCategory[d.category] ?? 0) + 1;
+        // Decisions read off disk predate `source`; count them as what they were.
+        bySource[d.source ?? "heuristic"] += 1;
+        // Only measured confidences are averaged. Treating a missing one as 0 would
+        // drag the fleet average down with a number nobody ever reported.
+        if (typeof d.confidence === "number") {
+            confSum += d.confidence;
+            confSamples += 1;
+        }
+        for (const a of d.alternatives)
+            altCounts.set(a, (altCounts.get(a) ?? 0) + 1);
+    }
+    const topAlternatives = [...altCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([a]) => a);
+    // Critical path = the ordered chain of agents that made decisions (deduped runs).
+    const chain = [];
+    for (const d of [...decisions].sort((a, b) => a.timestamp - b.timestamp)) {
+        if (chain[chain.length - 1] !== d.agentId)
+            chain.push(d.agentId);
+    }
+    return {
+        total: decisions.length,
+        byAgent,
+        byCategory,
+        avgConfidence: confSamples ? Math.round(confSum / confSamples) : null,
+        confidenceSamples: confSamples,
+        bySource,
+        topAlternatives,
+        criticalPath: chain.slice(0, 8),
+    };
+}
+//# sourceMappingURL=decisions.js.map

package/dist/observability/decisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions.js","sourceRoot":"","sources":["../../src/observability/decisions.ts"],"names":[],"mappings":"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"}

package/dist/observability/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The Loom observability layer: folds LoomEvents into OpenTelemetry signals
+ * and ships them over OTLP. One process-wide config, three exporters.
+ *
+ * Mapping (LoomEvent → span, GenAI semantic conventions where they apply):
+ *   run_complete            → gen_ai.agent.turn   (duration, cost, tokens, model)
+ *   tool_call               → gen_ai.tool.call
+ *   handoff                 → loom.baton.handoff
+ *   route_*                 → loom.route.<phase>
+ *   memory_add/update/forget→ loom.memory.<op>
+ *   error                   → span with ERROR status
+ *
+ * Metrics (LoomEvent → datapoint, see ./metrics.ts for names and temporality):
+ *   run_complete            → gen_ai.client.token.usage, gen_ai.client.operation.duration,
+ *                             loom.turns, loom.cost.usd (only if reported)
+ *   status turn_started     → loom.agents.active
+ *   handoff                 → loom.handoffs
+ *
+ * Logs (LoomEvent → log record, see ./logs.ts): the event stream itself,
+ * correlated to the turn's trace so a span links to what the agent said.
+ *
+ * One event can produce all three. Callers still only call recordAgentEvent().
+ */
+import type { LoomEvent } from "../types.js";
+import { LoomTelemetry, type SpanInput } from "./otlp.js";
+import { LoomMetrics, type MetricAttributes } from "./metrics.js";
+import { LoomLogs } from "./logs.js";
+/**
+ * The trace id of an agent's in-flight turn, or the one that just finished.
+ *
+ * Undefined when telemetry is off, because then no trace was ever minted and
+ * there is nothing in the backend to link to. Callers must leave the field out
+ * rather than substituting "" — an empty trace id renders as a link that opens
+ * a search for nothing, which reads as a broken feature rather than an absent
+ * one.
+ */
+export declare function turnTraceId(agentId: string): string | undefined;
+export declare function telemetry(): LoomTelemetry;
+export declare function metrics(): LoomMetrics;
+export declare function logs(): LoomLogs;
+/** Push every buffered signal now — for shutdown, and for tests that assert. */
+export declare function flushTelemetry(): void;
+export type EventContext = {
+    project?: string;
+};
+/**
+ * Pure mapper: a LoomEvent → the span it should emit, or null for kinds that
+ * aren't telemetry-worthy. Exported so the mapping is unit-testable without a
+ * live exporter or collector.
+ */
+export declare function eventToSpan(event: LoomEvent, ctx?: EventContext): SpanInput | null;
+/**
+ * One metric write, as data. Returned by the pure mapper below so the
+ * event → datapoint decisions can be unit-tested without an exporter — the same
+ * reason `eventToSpan` exists.
+ */
+export type MetricOp = {
+    op: "count";
+    name: string;
+    value: number;
+    attributes: MetricAttributes;
+    isInt: boolean;
+} | {
+    op: "histogram";
+    name: string;
+    value: number;
+    attributes: MetricAttributes;
+};
+/**
+ * Pure mapper: a LoomEvent → the datapoints it should produce.
+ *
+ * The rule that governs every branch: a number goes out only if the event
+ * carried it. An adapter that reports tokens but no cost produces token
+ * datapoints and no cost datapoint — not a cost datapoint of 0. Codex is
+ * exactly this case, and the reasoning is written out at the top of
+ * src/adapters/codex.ts: a fake $0.001 presented as fact is worse than a blank.
+ * On a counter it is worse still, because zeros are indistinguishable from real
+ * cheap turns once summed, and the total then reads as authoritative.
+ */
+export declare function eventToMetrics(event: LoomEvent): MetricOp[];
+/**
+ * Record one live agent event, fanning it out to every enabled signal.
+ *
+ * Best-effort and non-throwing: observability must never break the agent loop.
+ * The three signals are independent — logs off still means traces and metrics —
+ * so each checks its own switch, and the shared trace id is minted once so a
+ * log record can point at the span covering the same event.
+ */
+export declare function recordAgentEvent(event: LoomEvent, ctx?: EventContext): void;