@bli-cockpit/mcp 0.1.7 → 0.1.9

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"];
+export declare const JARVIS_ANSWER_ENVELOPE_KEYS: readonly ["ok", "answer", "sources", "turn_id", "thread_id", "trace_thread_id", "proposal_id", "next_action", "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
@@ -85,8 +134,25 @@ export interface JarvisAnswerEnvelope {
      * could approve with, and that is not approval. The person fetches the code
      * on a surface a person reads and hands it back. Null on every turn that
      * proposed no coding task, which is nearly all of them.
+     *
+     * BLI-3787: a null here is never on its own. When the arm ran at all,
+     * `next_action` below says what happened and what a person has to do — the
+     * field was `null` on every proposing turn for two QA ticks while the answer
+     * told the caller to spend an id nothing had issued.
      */
     proposal_id: string | null;
+    /**
+     * BLI-3787: what has to happen next, in a sentence naming an action a
+     * PERSON takes.
+     *
+     * Today only the coding arm produces one, and it is what makes
+     * `proposal_id`'s absence readable: "ask them to fetch the code for proposal
+     * X", "nothing was dispatched and no proposal was recorded, a person has to
+     * approve this where a person reads", "that approval code has already been
+     * used". Null on every turn that never reached the arm, which is nearly all
+     * of them — and never a substitute for the answer itself.
+     */
+    next_action: string | null;
     degraded: boolean;
     degraded_reasons: JarvisDegradedReason[];
 }
@@ -96,6 +162,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 +190,18 @@ export interface JarvisAnswerEnvelopeInput {
     }> | null;
     /** `body.proposalId` — BLI-3755's coding-arm proposal id, when the turn made one. */
     proposalId?: string | null;
+    /**
+     * `body.nextAction` — BLI-3787's sentence for what a person must do next
+     * about the coding arm. Absent from a dashboard that predates it, which is
+     * why an older deployment reads as `next_action: null` rather than as a
+     * turn that said nothing.
+     */
+    nextAction?: 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
@@ -42,11 +61,24 @@ export const JARVIS_ANSWER_ENVELOPE_KEYS = [
     "thread_id",
     "trace_thread_id",
     "proposal_id",
+    "next_action",
     "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 +90,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,14 +186,19 @@ 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,
         proposal_id: input.proposalId ?? null,
+        next_action: input.nextAction ?? null,
         degraded: reasons.length > 0,
         degraded_reasons: reasons,
     };

package/dist/jarvis-door.js

@@ -110,6 +110,11 @@ export async function takeTurn(deps, session, door, body, remember) {
         revised: reply.revised,
         trace: reply.trace,
         proposalId: reply.proposalId,
+        // BLI-3787: the sentence beside it, so a refusal names what a person must
+        // do rather than arriving as a bare `proposal_id: null`.
+        nextAction: reply.nextAction,
+        // 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({
@@ -120,6 +125,9 @@ export async function takeTurn(deps, session, door, body, remember) {
         // BLI-3755: whether this turn left a coding-arm proposal behind. The id
         // itself is in the envelope; this line says one was made.
         proposal_recorded: envelope.proposal_id !== null,
+        // BLI-3787: whether this turn said what to do next. A turn that reached
+        // the coding arm and said nothing is the defect, and it is visible here.
+        next_action_present: envelope.next_action !== null,
         degraded: envelope.degraded,
         degraded_reasons: envelope.degraded_reasons,
         has_turn_id: envelope.turn_id !== null,
@@ -132,6 +140,9 @@ export async function takeTurn(deps, session, door, body, remember) {
             ? `proposal_id: ${envelope.proposal_id} — the person fetches the approval code for it themself, `
                 + `in a Tower tab, their Slack DM, or their own \`cockpit jarvis\` terminal. You were not sent one.`
             : null,
+        // BLI-3787: printed whether or not there is a proposal id, because the
+        // turns that made none are exactly the ones a caller could not read.
+        envelope.next_action ? `next_action: ${envelope.next_action}` : null,
         envelope.degraded ? `degraded: ${envelope.degraded_reasons.join(", ")}` : null,
     ]
         .filter((line) => line !== null)

package/dist/jarvis-tools.js

@@ -78,13 +78,16 @@ export function registerJarvisTools(server, deps) {
     register("jarvis_ask", {
         title: "Ask JARVIS",
         description: "Asks JARVIS one question and returns its answer, the Source: lines behind it, this turn's "
-            + "turn_id and the conversation's thread_id. Same JARVIS, same tool belt and same evidence "
+            + "turn_id, the conversation's thread_id, and — when the turn reached the coding arm — a "
+            + "proposal_id and a next_action sentence. Same JARVIS, same tool belt and same evidence "
             + "rules as Tower web chat, the Slack DM and `cockpit jarvis`. A thread is SINGLE-WRITER: "
             + "omit thread and this turn gets a FRESH conversation of its own, so two questions asked at "
             + "the same time can never read each other's; pass the thread_id the answer returned to "
             + "continue that conversation deliberately. Pass the returned turn_id to jarvis_trace to see "
             + "how the answer was reached. JARVIS speaks as the person this machine is paired to and "
-            + "cannot be made to speak as anyone else.",
+            + "cannot be made to speak as anyone else. proposal_id is null on every turn that proposed no "
+            + "coding task, including one the arm refused; next_action is the sentence saying which it "
+            + "was and what a PERSON has to do about it, so a null proposal_id is never on its own.",
         inputSchema: {
             question: z.string().min(1).max(50_000).describe("What to ask, in plain words."),
             thread: z
@@ -194,10 +197,13 @@ export function registerJarvisTools(server, deps) {
             + "approval_code: you get the plan and a proposal_id back, and DELIBERATELY no code — a code "
             + "you can read is a code you could approve with. Show the person the plan and the "
             + "proposal_id and ask them to fetch the code themself, in a Tower browser tab, their Slack "
-            + "DM with JARVIS, or their own `cockpit jarvis` terminal. Then call this again with the code "
+            + "DM with JARVIS, or their own interactive `cockpit jarvis`. Then call this again with the code "
             + "THEY give you and the same instruction. A code approves exactly ONE run: a reused one is "
             + "refused (approval_code_spent) and the answer is a fresh approval, never a retry. Never "
-            + "derive, guess, or reuse a code the person has not just handed you.",
+            + "derive, guess, or reuse a code the person has not just handed you. If the answer comes "
+            + "back with no proposal_id, read next_action: the arm refused rather than proposed, and it "
+            + "names what a person has to do — never send a proposal_id back to JARVIS yourself, this is "
+            + "the surface it was withheld from and the read-back is refused here.",
         inputSchema: {
             instruction: z
                 .string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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",