@bli-cockpit/mcp 0.1.7 → 0.1.8

package/dist/jarvis-answer-envelope.d.ts

@@ -29,12 +29,55 @@
  * `latency` / `model` keys `cockpit jarvis --json` also prints: those describe
  * a terminal process's own stopwatch, and this server has no such stopwatch to
  * report honestly.
+ *
+ * ## Where `sources` comes from (BLI-3770)
+ *
+ * From the DOOR, as objects, when the door sends them: `POST /api/jarvis/cli`
+ * carries `sources` built from the citations the grounding layer minted, and
+ * the `Source:` lines inside `answer` are rendered from that same array. The
+ * older derivation — a line-anchored regex over the finished prose — could
+ * only find a citation the renderer happened to put on its own line, so QA
+ * tick 16's c9, c9b and n9 (all off `searchEverything`) ended *"…Source:
+ * issue, at /work/BLI-3706, by …"* INSIDE the final sentence and returned
+ * `"sources": []`: the person saw a citation, the machine did not.
+ *
+ * The prose derivation survives as the FALLBACK, for a dashboard deployed
+ * before that door field existed, and it is wider than it was: a whole
+ * `Sources:` line (plural, any case, bulleted) counts — that is what the
+ * server itself treats as provenance — and so does a citation that begins a
+ * sentence inside a paragraph. A `Source:` in the MIDDLE of a sentence ("the
+ * Source: field on that row was blank") is prose about a source, not a
+ * source, and is deliberately not matched.
  */
 /**
  * Every key of the envelope, in the order it is written. The literal list IS
  * the contract: both copies assert against it, so a drift is a red suite.
  */
 export declare const JARVIS_ANSWER_ENVELOPE_KEYS: readonly ["ok", "answer", "sources", "turn_id", "thread_id", "trace_thread_id", "proposal_id", "degraded", "degraded_reasons"];
+/**
+ * One thing that backed the answer (BLI-3770).
+ *
+ * Minted by the grounding layer with its `kind` already decided, so a caller
+ * can tell an issue from a document from a live tool read without parsing the
+ * words back apart. `kind: "prose"` means this envelope recovered the line
+ * from the answer itself because the door sent no structured sources — an
+ * older dashboard, or a citation the model wrote that nothing minted.
+ *
+ * The same shape is declared by `apps/dashboard/src/lib/jarvis/chat-v2/
+ * answer-sources.ts`, which is where the array is built.
+ */
+export interface JarvisAnswerSource {
+    /** `issue`, `doc`, `channel`, `memory`, `session`, `note`, `linear`, `web`, `live_read`, `conversation`, `brief`, `correction`, or `prose`. */
+    kind: string;
+    /** The words the citation carries, without its link. */
+    label: string;
+    /** The durable link, when the receipt has one. */
+    href: string | null;
+    /** The thing cited, when it has an identifier a caller could fetch again. */
+    id: string | null;
+    /** The belt tool the evidence came off, when one did. */
+    tool: string | null;
+}
 /**
  * The closed set of ways an answer can be second-rate without being a failure.
  * A degraded answer is still an answer — it is printed, returned and counted —
@@ -54,12 +97,18 @@ export interface JarvisAnswerEnvelope {
     ok: true;
     /**
      * The answer verbatim, exactly as the terminal prints it — `Source:` lines
-     * included. Nothing is stripped: `sources` below is an index into this
-     * string, not a slice taken out of it.
+     * included. Nothing is stripped, and nothing is derived from it either:
+     * since BLI-3770 `sources` below is the array those lines were RENDERED
+     * FROM, not a reading taken back out of this string.
      */
     answer: string;
-    /** Every `Source: …` line found in `answer`, in the order it appears. */
-    sources: string[];
+    /**
+     * What backed the answer, in the order the grounding layer minted it.
+     *
+     * BLI-3770: these are objects, not lines. Empty means this turn cited
+     * nothing — never "the citation was on a line this side could not parse".
+     */
+    sources: JarvisAnswerSource[];
     /**
      * This turn's trace id — what `cockpit jarvis --trace <id>` and the
      * `jarvis_trace` MCP tool open. `null` against a dashboard that predates
@@ -96,6 +145,15 @@ export interface JarvisAnswerEnvelope {
  * lines the server wrote, so a new citation kind needs no change here.
  */
 export declare function extractSourceLines(answer: string): string[];
+/**
+ * The fallback derivation: what this side can tell from the answer alone.
+ *
+ * Only reached when the door sent no structured `sources` — a dashboard
+ * deployed before BLI-3770, or a turn whose citation nothing minted. Every
+ * row it produces is labelled `kind: "prose"` so a consumer can tell a
+ * recovered line from a minted receipt.
+ */
+export declare function sourcesFromAnswer(answer: string): JarvisAnswerSource[];
 export interface JarvisAnswerEnvelopeInput {
     /** The reply text the door returned. */
     reply: string;
@@ -115,5 +173,11 @@ export interface JarvisAnswerEnvelopeInput {
     }> | null;
     /** `body.proposalId` — BLI-3755's coding-arm proposal id, when the turn made one. */
     proposalId?: string | null;
+    /**
+     * `body.sources` — BLI-3770's structured citations, straight from the door.
+     * Typed as `unknown` on purpose: this is another process's JSON, and the
+     * one place it is shaped is `doorSources` above.
+     */
+    sources?: unknown;
 }
 export declare function buildJarvisAnswerEnvelope(input: JarvisAnswerEnvelopeInput): JarvisAnswerEnvelope;

package/dist/jarvis-answer-envelope.js

@@ -29,6 +29,25 @@
  * `latency` / `model` keys `cockpit jarvis --json` also prints: those describe
  * a terminal process's own stopwatch, and this server has no such stopwatch to
  * report honestly.
+ *
+ * ## Where `sources` comes from (BLI-3770)
+ *
+ * From the DOOR, as objects, when the door sends them: `POST /api/jarvis/cli`
+ * carries `sources` built from the citations the grounding layer minted, and
+ * the `Source:` lines inside `answer` are rendered from that same array. The
+ * older derivation — a line-anchored regex over the finished prose — could
+ * only find a citation the renderer happened to put on its own line, so QA
+ * tick 16's c9, c9b and n9 (all off `searchEverything`) ended *"…Source:
+ * issue, at /work/BLI-3706, by …"* INSIDE the final sentence and returned
+ * `"sources": []`: the person saw a citation, the machine did not.
+ *
+ * The prose derivation survives as the FALLBACK, for a dashboard deployed
+ * before that door field existed, and it is wider than it was: a whole
+ * `Sources:` line (plural, any case, bulleted) counts — that is what the
+ * server itself treats as provenance — and so does a citation that begins a
+ * sentence inside a paragraph. A `Source:` in the MIDDLE of a sentence ("the
+ * Source: field on that row was blank") is prose about a source, not a
+ * source, and is deliberately not matched.
  */
 /**
  * Every key of the envelope, in the order it is written. The literal list IS
@@ -45,8 +64,20 @@ export const JARVIS_ANSWER_ENVELOPE_KEYS = [
     "degraded",
     "degraded_reasons",
 ];
-/** A `Source:` line, as the grounding gate renders it into the answer. */
-const SOURCE_LINE = /^\s*Source:\s*\S/;
+/**
+ * A citation line, in every shape the server itself treats as one.
+ *
+ * BLI-3770 widened this from `/^\s*Source:\s*\S/` to mirror
+ * `apps/dashboard/src/lib/jarvis/chat-v2/provenance-lines.ts`, which matches
+ * `sources?` case-insensitively with an optional bullet. The narrow version
+ * meant a `Sources: …` line the server had already lifted out of the body as
+ * provenance, and put straight back under the answer, was not a source to
+ * this side: one thing, two definitions, in two packages.
+ */
+const SOURCE_LINE = /^\s*(?:[-*\u2022]\s+)?sources?\s*:\s*\S/i;
+/** The receipt's link, as `appendCitations` lays it out: `<url>` after the words. */
+const BRACKETED_LINK = /\s*<(https?:\/\/[^>\s]+)>\s*$/;
+const TRAILING_LINK = /\s+(https?:\/\/\S+)\s*$/;
 /**
  * The `Source:` lines inside an answer. Pure string work on what the server
  * already sent — this side never decides what a source IS, it only finds the
@@ -58,6 +89,90 @@ export function extractSourceLines(answer) {
         .map((line) => line.trim())
         .filter((line) => SOURCE_LINE.test(line));
 }
+/** The words and the link, kept apart, the way every surface renders them. */
+function splitLink(line) {
+    const trimmed = line.trim().replace(/^[-*\u2022]\s+/, "");
+    const bracketed = trimmed.match(BRACKETED_LINK);
+    if (bracketed)
+        return { label: trimmed.slice(0, bracketed.index).trim(), href: bracketed[1] ?? null };
+    const trailing = trimmed.match(TRAILING_LINK);
+    if (trailing)
+        return { label: trimmed.slice(0, trailing.index).trim(), href: trailing[1] ?? null };
+    return { label: trimmed, href: null };
+}
+/**
+ * A citation the model wrote INSIDE a paragraph (BLI-3770).
+ *
+ * It counts when it begins a sentence, which is the shape QA tick 16 caught
+ * three times. It deliberately does not count in the middle of one — "the
+ * Source: field on that row was blank" is a sentence about a field, and
+ * treating it as a receipt would put prose in a contract that is supposed to
+ * carry evidence.
+ */
+function inlineSourceFragments(line) {
+    return line
+        .split(/(?<=[.!?])\s+/)
+        .map((part) => part.trim())
+        .filter((part) => SOURCE_LINE.test(part));
+}
+/**
+ * The fallback derivation: what this side can tell from the answer alone.
+ *
+ * Only reached when the door sent no structured `sources` — a dashboard
+ * deployed before BLI-3770, or a turn whose citation nothing minted. Every
+ * row it produces is labelled `kind: "prose"` so a consumer can tell a
+ * recovered line from a minted receipt.
+ */
+export function sourcesFromAnswer(answer) {
+    const found = [];
+    const seen = new Set();
+    const add = (text) => {
+        const { label, href } = splitLink(text);
+        if (!label || seen.has(label))
+            return;
+        seen.add(label);
+        found.push({ kind: "prose", label, href, id: null, tool: null });
+    };
+    for (const raw of answer.split("\n")) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        if (SOURCE_LINE.test(line)) {
+            add(line);
+            continue;
+        }
+        for (const fragment of inlineSourceFragments(line))
+            add(fragment);
+    }
+    return found;
+}
+/**
+ * The door's own `sources`, checked rather than trusted. A field that arrives
+ * as something other than a list of labelled objects is treated as absent, so
+ * a malformed body degrades to the prose fallback instead of putting
+ * `[object Object]` in front of an agent.
+ */
+function doorSources(sent) {
+    if (!Array.isArray(sent))
+        return [];
+    const rows = [];
+    for (const entry of sent) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const row = entry;
+        const label = typeof row.label === "string" ? row.label.trim() : "";
+        if (!label)
+            continue;
+        rows.push({
+            kind: typeof row.kind === "string" && row.kind ? row.kind : "unknown",
+            label,
+            href: typeof row.href === "string" ? row.href : null,
+            id: typeof row.id === "string" ? row.id : null,
+            tool: typeof row.tool === "string" ? row.tool : null,
+        });
+    }
+    return rows;
+}
 export function buildJarvisAnswerEnvelope(input) {
     const reasons = [];
     if (input.modelFallback === true)
@@ -70,10 +185,14 @@ export function buildJarvisAnswerEnvelope(input) {
     const turnId = input.traceId ?? null;
     if (!turnId)
         reasons.push("no_turn_id");
+    const sent = doorSources(input.sources);
     return {
         ok: true,
         answer: input.reply,
-        sources: extractSourceLines(input.reply),
+        // BLI-3770: the door's own citations when it sent them, and only then the
+        // prose fallback. Never both — a turn's receipts have one origin, and
+        // merging the two would double-count the lines the door already described.
+        sources: sent.length > 0 ? sent : sourcesFromAnswer(input.reply),
         turn_id: turnId,
         thread_id: input.thread ?? null,
         trace_thread_id: input.traceThread ?? null,

package/dist/jarvis-door.js

@@ -110,6 +110,8 @@ export async function takeTurn(deps, session, door, body, remember) {
         revised: reply.revised,
         trace: reply.trace,
         proposalId: reply.proposalId,
+        // BLI-3770: the door's own structured citations, when it sent them.
+        sources: reply.sources,
     });
     remember({ turnId: envelope.turn_id, traceThreadId: envelope.trace_thread_id });
     log(`${TAG} answered ${JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "private": false,
   "description": "bli-tower — an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",