@meetless/mla 0.1.4

package/dist/commands/internal-capture-decisions.js

@@ -0,0 +1,320 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.normalizePostToolUseInput = normalizePostToolUseInput;
+exports.scanTranscriptForDecisions = scanTranscriptForDecisions;
+exports.toSpoolEvents = toSpoolEvents;
+exports.runCaptureDecisions = runCaptureDecisions;
+const fs = __importStar(require("fs"));
+const agent_decision_1 = require("../lib/agent-decision");
+const normalize_claude_1 = require("../lib/agent-decision/normalize-claude");
+const SOURCES = ["post_tool_use", "stop_transcript_scan"];
+// Strict argv parsing, mirroring the convention in internal-finalize.ts: any
+// unknown flag, a missing required flag, or a bare positional throws (exit 2 in
+// the wrapper). A silent default here would let a flush.sh wiring bug capture
+// decisions under the wrong source or session and never surface.
+function parseArgs(argv) {
+    let source;
+    let session;
+    let transcript;
+    let spool;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "--source":
+                source = argv[++i];
+                break;
+            case "--session":
+                session = argv[++i];
+                break;
+            case "--transcript":
+                transcript = argv[++i];
+                break;
+            case "--spool":
+                spool = argv[++i];
+                break;
+            default:
+                throw new Error(`Unknown argument: ${a}. usage: mla _internal capture-decisions --source <post_tool_use|stop_transcript_scan> --session <id> [--transcript <path>] [--spool <path>]`);
+        }
+    }
+    if (source === undefined || !SOURCES.includes(source)) {
+        throw new Error(`--source must be one of ${SOURCES.join(", ")} (got ${JSON.stringify(source)})`);
+    }
+    if (session === undefined || session.length === 0) {
+        throw new Error("--session <providerSessionId> is required");
+    }
+    if (source === "stop_transcript_scan" && (transcript === undefined || transcript.length === 0)) {
+        throw new Error("--transcript <path> is required when --source stop_transcript_scan");
+    }
+    const out = { source: source, session };
+    if (transcript !== undefined)
+        out.transcript = transcript;
+    if (spool !== undefined)
+        out.spool = spool;
+    return out;
+}
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+// PostToolUse path: one hook payload -> canonical payloads. Returns [] (never
+// throws) when the tool is not AskUserQuestion or the payload is structurally
+// unusable, so the hook it rides on is never crashed by a surprise shape.
+function normalizePostToolUseInput(hookPayload, opts) {
+    if (!isPlainObject(hookPayload))
+        return [];
+    if (hookPayload.tool_name !== normalize_claude_1.CLAUDE_TOOL_NAME)
+        return [];
+    const toolUseId = hookPayload.tool_use_id;
+    const toolInput = hookPayload.tool_input;
+    const toolResponse = hookPayload.tool_response;
+    const questions = isPlainObject(toolInput) ? toolInput.questions : undefined;
+    // tool_response.answers is an object keyed on the EXACT question text (verified
+    // against a real PostToolUse payload and a real transcript sidecar). A missing
+    // or malformed answers map yields no decisions: an unanswered question is not a
+    // captured human decision, which the normalizer already enforces per-question.
+    const answers = isPlainObject(toolResponse) ? toolResponse.answers : undefined;
+    if (typeof toolUseId !== "string" || !Array.isArray(questions) || !isPlainObject(answers)) {
+        return [];
+    }
+    return (0, normalize_claude_1.normalizeClaudeAskUserQuestion)({
+        toolUseId,
+        questions: questions,
+        answers,
+    }, {
+        providerSessionId: opts.providerSessionId,
+        capturedBy: "post_tool_use",
+        occurredAt: opts.occurredAt,
+    });
+}
+// Stop backstop path: scan transcript JSONL for AskUserQuestion tool_use /
+// tool_result pairs. A single forward pass works because an assistant tool_use
+// line always precedes its user tool_result line in chronological JSONL.
+//
+// The tool_use line (assistant) is authoritative for the offered questions +
+// options; the matching user line carries the toolUseResult sidecar with the
+// answers keyed on question text, plus a tool_result block echoing the
+// tool_use_id used to pair them. occurredAt is the user line's recorded
+// timestamp when present (the moment the answer landed); it is stored but is
+// NEVER an identity input, so it may differ from the primary path safely.
+function scanTranscriptForDecisions(lines, opts) {
+    const askQuestions = new Map();
+    const out = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // a truncated / non-JSON line is skipped, not fatal
+        }
+        if (!isPlainObject(obj))
+            continue;
+        const message = obj.message;
+        const content = isPlainObject(message) ? message.content : undefined;
+        if (obj.type === "assistant") {
+            if (!Array.isArray(content))
+                continue;
+            for (const block of content) {
+                if (isPlainObject(block) &&
+                    block.type === "tool_use" &&
+                    block.name === normalize_claude_1.CLAUDE_TOOL_NAME &&
+                    typeof block.id === "string") {
+                    const input = block.input;
+                    const questions = isPlainObject(input) ? input.questions : undefined;
+                    if (Array.isArray(questions)) {
+                        askQuestions.set(block.id, questions);
+                    }
+                }
+            }
+            continue;
+        }
+        if (obj.type === "user") {
+            if (!Array.isArray(content))
+                continue;
+            let toolUseId;
+            for (const block of content) {
+                if (isPlainObject(block) && block.type === "tool_result" && typeof block.tool_use_id === "string") {
+                    toolUseId = block.tool_use_id;
+                    break;
+                }
+            }
+            if (toolUseId === undefined)
+                continue;
+            const questions = askQuestions.get(toolUseId);
+            if (questions === undefined)
+                continue; // not an AskUserQuestion result
+            const sidecar = obj.toolUseResult;
+            const answers = isPlainObject(sidecar) ? sidecar.answers : undefined;
+            if (!isPlainObject(answers))
+                continue; // unanswered / unexpected shape
+            const occurredAt = typeof obj.timestamp === "string" ? obj.timestamp : undefined;
+            const ctx = {
+                providerSessionId: opts.providerSessionId,
+                capturedBy: "stop_transcript_scan",
+            };
+            if (occurredAt !== undefined)
+                ctx.occurredAt = occurredAt;
+            out.push(...(0, normalize_claude_1.normalizeClaudeAskUserQuestion)({ toolUseId, questions, answers }, ctx));
+        }
+    }
+    return out;
+}
+// Wrap validated canonical payloads into spool-event envelopes, deduping against
+// eventKeys already present (the backstop skips what the primary spooled) and
+// within the batch. Validation is fail-soft: a malformed decision is logged and
+// skipped, never crashing the hook (spec: validate-and-skip at capture time).
+function toSpoolEvents(payloads, opts) {
+    const seen = new Set(opts.existingEventKeys ?? []);
+    const out = [];
+    for (const payload of payloads) {
+        const errs = (0, agent_decision_1.validateCanonicalDecisionPayload)(payload);
+        if (errs.length > 0) {
+            opts.logError?.(`[capture-decisions] skipping invalid decision ${String(payload.providerEventId)}: ${errs.join("; ")}`);
+            continue;
+        }
+        const eventKey = (0, agent_decision_1.buildEventKey)(payload.provider, payload.providerEventId);
+        if (seen.has(eventKey))
+            continue;
+        seen.add(eventKey);
+        out.push({
+            ts: opts.ts,
+            event: agent_decision_1.AGENT_DECISION_EVENT,
+            eventKey,
+            sessionId: opts.sessionId,
+            payload,
+        });
+    }
+    return out;
+}
+function readStdinReal() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (c) => chunks.push(c));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        process.stdin.on("error", reject);
+    });
+}
+const defaultDeps = {
+    readStdin: readStdinReal,
+    readFile: (p) => fs.readFileSync(p, "utf8"),
+    now: () => new Date().toISOString(),
+    writeLine: (line) => process.stdout.write(line + "\n"),
+    logError: (msg) => console.error(msg),
+};
+// Read the existing spool (if any) and collect its eventKeys so the backstop
+// does not re-emit a decision the primary path already spooled. A missing file
+// (no spool yet) is an empty set, not an error.
+function readSpoolEventKeys(path, deps) {
+    const keys = new Set();
+    let raw;
+    try {
+        raw = deps.readFile(path);
+    }
+    catch {
+        return keys;
+    }
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const obj = JSON.parse(trimmed);
+            if (typeof obj.eventKey === "string")
+                keys.add(obj.eventKey);
+        }
+        catch {
+            // ignore unparseable spool lines
+        }
+    }
+    return keys;
+}
+async function runCaptureDecisions(argv, deps = defaultDeps) {
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (e) {
+        deps.logError(e.message);
+        return 2;
+    }
+    const ts = deps.now();
+    let payloads;
+    if (parsed.source === "post_tool_use") {
+        const stdin = await deps.readStdin();
+        const trimmed = stdin.trim();
+        if (trimmed.length === 0)
+            return 0; // nothing piped in is a clean no-op
+        let hookPayload;
+        try {
+            hookPayload = JSON.parse(trimmed);
+        }
+        catch (e) {
+            deps.logError(`[capture-decisions] stdin is not valid JSON: ${e.message}`);
+            return 0; // never crash the hook on a malformed payload
+        }
+        payloads = normalizePostToolUseInput(hookPayload, {
+            providerSessionId: parsed.session,
+            occurredAt: ts,
+        });
+    }
+    else {
+        let raw;
+        try {
+            raw = deps.readFile(parsed.transcript);
+        }
+        catch (e) {
+            deps.logError(`[capture-decisions] cannot read transcript ${parsed.transcript}: ${e.message}`);
+            return 0; // a missing transcript is not a hook-crashing error
+        }
+        payloads = scanTranscriptForDecisions(raw.split("\n"), {
+            providerSessionId: parsed.session,
+        });
+    }
+    const existingEventKeys = parsed.spool ? readSpoolEventKeys(parsed.spool, deps) : undefined;
+    const events = toSpoolEvents(payloads, {
+        sessionId: parsed.session,
+        ts,
+        existingEventKeys,
+        logError: deps.logError,
+    });
+    for (const event of events) {
+        deps.writeLine(JSON.stringify(event));
+    }
+    return 0;
+}

package/dist/commands/internal-evidence-correlate.js

@@ -0,0 +1,239 @@
+"use strict";
+// `mla _internal evidence-correlate` -- the v1 local correlator (INV-CORRELATOR-1,
+// spec sections 7.4, 10.5). Fired DETACHED from the Stop hook (spawn_evidence_correlate)
+// at the end of every session. It closes every eligible PENDING inject window and
+// appends one mla_evidence_outcome per closed inject to the local events.jsonl, then
+// best-effort forwards when telemetry is on.
+//
+// It processes ALL pending injects across ALL sessions, not just the stopping one:
+// a cross-session inject only closes by time_limit minutes later, and a Stop is the
+// natural recompute tick. Idempotency comes from two guards: a skip-set of inject_ids
+// that already have an outcome line, and the deterministic outcome event_id
+// (sha256(inject_id:outcome_version), event-id.ts) so a re-run cannot inflate counts
+// even across a race. An inject whose window is still open derives no outcome and
+// stays pending (the ABSENCE of an outcome line, never dropped, never counted ignored).
+//
+// The outcome carries the INJECT's trace_id + run_id + workspace_id + session_id
+// (section 11.3: the enrichment-outcome record is keyed by inject_id and stamped with
+// the inject's trace/run), so the outcome joins back to the enrichment that produced
+// it. The correlator is the recompute engine, not a new logical owner (INV-RUN-1: the
+// outcome belongs to the inject's run).
+//
+// Fail-soft: every error is swallowed and the command exits 0 (a strict argv parse
+// error -> 2), so closing windows can never disturb the session it spawned from.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.runInternalEvidenceCorrelate = runInternalEvidenceCorrelate;
+exports.splitEvidenceEvents = splitEvidenceEvents;
+const config_1 = require("../lib/config");
+const coverage_gap_1 = require("../lib/analytics/coverage-gap");
+const evidence_1 = require("../lib/analytics/evidence");
+const followthrough_1 = require("../lib/analytics/followthrough");
+const logs_1 = require("../lib/analytics/logs");
+const recorder_1 = require("../lib/analytics/recorder");
+const store_1 = require("../lib/analytics/store");
+// v1 takes no flags: the correlator always sweeps every pending inject across every
+// session. Any argument is a strict error (exit 2), matching the other _internal
+// commands. The hook calls it with no args.
+function parseArgs(argv) {
+    if (argv.length > 0) {
+        throw new Error(`Unknown flag for \`mla _internal evidence-correlate\`: ${argv[0]}`);
+    }
+}
+// Reconstruct the minimal inject view deriveOutcome needs from a stored
+// mla_evidence_inject jsonl line (the event is flat: payload + envelope at one level).
+function toInjectRecord(ev) {
+    return {
+        inject_id: typeof ev.inject_id === "string" ? ev.inject_id : "",
+        session_id: typeof ev.session_id === "string" ? ev.session_id : "",
+        turn_index: typeof ev.turn_index === "number" && Number.isFinite(ev.turn_index)
+            ? ev.turn_index
+            : null,
+        offered_source_ids: Array.isArray(ev.offered_source_ids)
+            ? ev.offered_source_ids.filter((x) => typeof x === "string")
+            : [],
+        window_deadline: typeof ev.window_deadline === "string" ? ev.window_deadline : "",
+    };
+}
+// Highest turn observed per session, so deriveOutcome can tell whether the full
+// 3-turn window has elapsed (turn_limit). Built from every signal that advances the
+// per-session turn counter: ask-traces (the true counter, every prompt), pulls,
+// citations, and the inject events themselves.
+function buildMaxTurnBySession(asks, calls, citations, injects) {
+    const m = new Map();
+    const bump = (sid, turn) => {
+        if (typeof sid !== "string" || !sid)
+            return;
+        if (typeof turn !== "number" || !Number.isFinite(turn))
+            return;
+        const cur = m.get(sid);
+        if (cur === undefined || turn > cur)
+            m.set(sid, turn);
+    };
+    for (const a of asks)
+        bump(a.session_id, a.turn_index);
+    for (const c of calls)
+        bump(c.session_id, c.turn_index);
+    for (const r of citations)
+        bump(r.session_id, r.turn_index);
+    for (const ev of injects)
+        bump(ev.session_id, ev.turn_index);
+    return m;
+}
+async function runInternalEvidenceCorrelate(argv, deps = {}) {
+    try {
+        parseArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    const env = deps.env ?? process.env;
+    try {
+        const read = deps.read ?? store_1.readEvents;
+        const events = read(env);
+        // Split the local event log into pending injects and the set of inject_ids that
+        // already have an outcome (the idempotency skip-set). `gapInjectIds` is the set
+        // that already carry an inject-time mla_coverage_gap, so the outcome-time
+        // `candidates_found_not_used` gap fires only when the inject surfaced no gap
+        // at inject time (spec §7.5: "emitted only when inject-time emitted nothing").
+        const injectEvents = [];
+        const closed = new Set();
+        const gapInjectIds = new Set();
+        for (const ev of events) {
+            if (ev.event_type === "mla_evidence_inject")
+                injectEvents.push(ev);
+            else if (ev.event_type === "mla_evidence_outcome") {
+                if (typeof ev.inject_id === "string" && ev.inject_id)
+                    closed.add(ev.inject_id);
+            }
+            else if (ev.event_type === "mla_coverage_gap") {
+                if (typeof ev.inject_id === "string" && ev.inject_id)
+                    gapInjectIds.add(ev.inject_id);
+            }
+        }
+        const readLog = deps.readLog ?? logs_1.readLogJsonl;
+        const asks = readLog("ask-traces.jsonl");
+        const calls = (0, followthrough_1.parseMcpCalls)(readLog("mcp-calls.jsonl"));
+        const citations = (0, followthrough_1.parseReportCitations)(readLog("report-citations.jsonl"));
+        const maxTurnBySession = buildMaxTurnBySession(asks, calls, citations, injectEvents);
+        const nowMs = deps.nowMs ?? Date.now();
+        const nowIso = new Date(nowMs).toISOString();
+        const record = deps.record ?? recorder_1.recordAnalyticsEvent;
+        const ctxBase = {
+            nowMs,
+            maxTurnBySession,
+            ...(deps.window !== undefined ? { window: deps.window } : {}),
+        };
+        let closedCount = 0;
+        let pendingCount = 0;
+        for (const ev of injectEvents) {
+            const injectId = typeof ev.inject_id === "string" ? ev.inject_id : "";
+            if (!injectId || closed.has(injectId))
+                continue; // already closed -> skip
+            // A stored inject must carry the run/trace it belongs to; without them the
+            // outcome cannot join back to the enrichment, so leave it pending rather than
+            // fabricate a join from the correlator's own run context.
+            const runId = typeof ev.run_id === "string" && ev.run_id ? ev.run_id : null;
+            const traceId = typeof ev.trace_id === "string" && ev.trace_id ? ev.trace_id : null;
+            if (!runId || !traceId) {
+                pendingCount++;
+                continue;
+            }
+            const inject = toInjectRecord(ev);
+            const derived = (0, evidence_1.deriveOutcome)(inject, calls, citations, ctxBase);
+            if (!derived) {
+                pendingCount++;
+                continue;
+            }
+            const ctx = {
+                workspaceId: typeof ev.workspace_id === "string" ? ev.workspace_id : null,
+                sessionId: inject.session_id || null,
+                distinctId: typeof ev.distinct_id === "string" ? ev.distinct_id : null,
+                runId,
+                traceId,
+                source: "hook",
+                now: nowIso,
+            };
+            record(ctx, {
+                eventType: "mla_evidence_outcome",
+                eventId: derived.event_id,
+                payload: derived.payload,
+            }, env);
+            // Outcome-time coverage gap (spec §7.5, INV-COVERAGE-GAP-1): a confident,
+            // non-empty inject that the agent had its full turn window to use yet
+            // referenced none of is `candidates_found_not_used` (fix retrieval/ranking,
+            // not capture). Only on an `ignored` close (turn_limit, the full opportunity
+            // was observed), only when candidates actually came back (not zero_results),
+            // and only when no inject-time gap already classified this inject. The
+            // deterministic event_id + the once-per-inject close make it idempotent.
+            const hadCandidates = ev.zero_results !== true;
+            if (derived.payload.outcome === "ignored" &&
+                hadCandidates &&
+                !gapInjectIds.has(injectId)) {
+                record(ctx, {
+                    eventType: "mla_coverage_gap",
+                    eventId: (0, coverage_gap_1.coverageGapNotUsedEventId)(injectId),
+                    payload: (0, coverage_gap_1.buildCoverageGapPayload)({
+                        injectId,
+                        coverageGapType: "candidates_found_not_used",
+                        // The correlator cannot recover the original query topic; the
+                        // inject-time gap carries it when known. Default to unknown here.
+                        queryTopicCategory: "unknown",
+                        retrievalConfidence: (0, coverage_gap_1.coerceRetrievalConfidence)(typeof ev.retrieval_confidence === "string"
+                            ? ev.retrieval_confidence
+                            : null),
+                        zeroResults: false,
+                    }),
+                }, env);
+                gapInjectIds.add(injectId);
+            }
+            // Guard against a duplicate (S, inject_id) line in the same sweep; the
+            // deterministic event_id already makes a cross-process race idempotent.
+            closed.add(injectId);
+            closedCount++;
+        }
+        // Best-effort, telemetry-gated forward (the consent gate is inside the
+        // forwarder). Skipped when the run has no control config.
+        const readCfg = deps.readCfg ??
+            (() => {
+                try {
+                    return (0, config_1.readConfig)();
+                }
+                catch {
+                    return null;
+                }
+            });
+        const cfg = readCfg();
+        if (cfg) {
+            const flush = deps.flush ?? recorder_1.flushAnalyticsEvents;
+            await flush(cfg, env);
+        }
+        console.log(JSON.stringify({
+            correlated: true,
+            closed: closedCount,
+            pending: pendingCount,
+            total: injectEvents.length,
+        }));
+        return 0;
+    }
+    catch {
+        // Fail-soft: a correlation failure never disturbs the session that spawned it.
+        console.log(JSON.stringify({ correlated: false, reason: "error" }));
+        return 0;
+    }
+}
+// Exported only so a future reader (mla stats) can reuse the same event-log split.
+function splitEvidenceEvents(events) {
+    const injects = [];
+    const closedInjectIds = new Set();
+    for (const ev of events) {
+        if (ev.event_type === "mla_evidence_inject")
+            injects.push(ev);
+        else if (ev.event_type === "mla_evidence_outcome") {
+            if (typeof ev.inject_id === "string" && ev.inject_id)
+                closedInjectIds.add(ev.inject_id);
+        }
+    }
+    return { injects, closedInjectIds };
+}