@bli-cockpit/mcp 0.1.1 → 0.1.2

package/README.md

@@ -3,20 +3,76 @@
 Two, deliberately separate, tool families over one MCP server (bin
 `bli-cockpit-mcp`, server id `bli-tower`):
 
-1. **`docs_*`/`msg_*` (BLI-3706)** — the SAME `/api/docs/**` and `/api/msg/**`
-   agent doors `cockpit docs`/`cockpit msg` call, authenticated with this
-   machine's collector device token (`~/.config/bli-cockpit/session.json`,
-   written by `cockpit login`). This is the live, actively-developed half.
+1. **The agent doors** — the SAME routes the `cockpit` CLI and the browser
+   call, authenticated with this machine's collector device token
+   (`~/.config/bli-cockpit/session.json`, written by `cockpit login`). This is
+   the live, actively-developed half: `docs_*`/`msg_*` (BLI-3706),
+   `work_*` (BLI-3716) and `jarvis_*` (BLI-3732).
 2. **`emit_event`/`get_ticket_timeline`/`get_active_tickets`** — the legacy
    event-stream write path, authenticated with `BLI_OPERATOR_TOKEN` or the
    `bli-event` session helper. See "Legacy event-stream tools" below.
 
 The two halves use DIFFERENT credentials and DIFFERENT base URLs on purpose
-(`docs-msg-tools.ts` talks to the production Tower dashboard; the event-stream
+(the agent doors talk to the production Tower dashboard; the event-stream
 tools talk to `BLI_API_BASE_URL`, historically a local worker) — see
-`docs/architecture/cli-caller-identity.md` for why `docs_*`/`msg_*` needed no
-new server-side door: every `/api/docs/**`/`/api/msg/**` route already accepts
-a collector device token.
+`docs/architecture/cli-caller-identity.md` for why they needed no new
+server-side door: every one of those routes already accepts a collector device
+token.
+
+**Every `cockpit <noun> <verb>` that talks to Tower is meant to have a twin
+here** (BLI-3706: "a surface an agent cannot reach conveniently is as good as
+dead"). `src/verb-census.test.ts` is that rule as a test — it reads the CLI's
+own decision tables and fails when a verb is in neither the twin map, the
+terminal-only list, nor the written follow-up queue.
+
+## `jarvis_*` tools (BLI-3732)
+
+JARVIS itself — the same assistant Tower web chat, the Slack DM and
+`cockpit jarvis` reach, over the same two doors with the same device token.
+
+| Tool | Wraps | Notes |
+| --- | --- | --- |
+| `jarvis_ask` | `POST /api/jarvis/cli` | One turn. Returns the answer, its `Source:` lines, `turn_id` and `thread_id`. |
+| `jarvis_trace` | `GET /api/ops/trace/[id]` | That turn's step tree — model steps, tool calls, timings, failures. Metadata only. Takes a `turn_id` or `"last"`. |
+| `jarvis_dispatch` | `POST /api/jarvis/cli` | The coding arm (BLI-2981). Two calls: once for the plan, once with the person's approval code. |
+| `jarvis_check` | `POST /api/jarvis/cli` | Where a dispatched coding task got to. Spends no approval. |
+
+`jarvis_ask` answers with the SAME object `cockpit jarvis --json` prints —
+`answer`, `sources`, `turn_id`, `thread_id`, `trace_thread_id`, `degraded`,
+`degraded_reasons` — so a script and an agent read one contract. A worked
+example:
+
+```
+jarvis_ask  { "question": "what did Brandon ship yesterday?" }
+  -> { "answer": "Two pull requests went in…\n\nSource: BLI-3654 — …",
+       "sources": ["Source: BLI-3654 — …"],
+       "turn_id": "0f3c…", "thread_id": "main",
+       "degraded": false, "degraded_reasons": [] }
+
+jarvis_trace { "turn_id": "0f3c…" }      # or "last"
+  -> Turn 0f3c…
+     6 steps · 4.2 s · 1 failed
+       jarvis-chat  4.2s  openai:gpt-5.6-terra
+         readIssues        0.2s
+         searchMemory      1.1s
+         readScout         0.3s  FAILED
+```
+
+`degraded` is never a failure — the answer is still returned. It names how the
+turn fell short: `model_fallback` (a fallback model answered),
+`answer_revised` (the grounding gate took words back), `tool_step_failed`, or
+`no_turn_id` (no trace id came back, so the tree cannot be opened later).
+
+**The coding arm's approval code.** `jarvis_dispatch` takes `approval_code` as
+a parameter and never derives, guesses or fabricates one. Call it once with no
+code to get the plan and its 8-character code, show both to the person, then
+call it again with the code THEY hand back. The gate's first lock (an HMAC
+over the exact plan, this account and a server secret) is untouched by this
+surface — this server holds no secret and cannot compute a code. Its second
+lock ("the code came from the human's own message") is weaker here than in a
+terminal, because nothing on the wire can tell a person-relayed code from one
+the model lifted out of the previous answer; `src/jarvis-tools.ts` says so in
+full at the top of the file.
 
 ## `docs_*` / `msg_*` tools (BLI-3706)
 

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

@@ -0,0 +1,107 @@
+/**
+ * The ONE shape a JARVIS answer wears when nobody is reading it with their
+ * eyes (BLI-3732).
+ *
+ * `cockpit jarvis --json` and the `bli-tower` MCP server's `jarvis_ask` reach
+ * the same door (`POST /api/jarvis/cli`) with the same device token and get
+ * the same reply body back. Before this file they described that body two
+ * different ways, so a script and an agent read two contracts for one turn.
+ * Now both build this envelope, and the five fields a consumer actually asks
+ * for — the answer, where it came from, which turn it was, which conversation
+ * it belongs to, and whether anything about it was second-rate — have one
+ * spelling each.
+ *
+ * ## Where the other copy is, and why
+ *
+ * This file is a deliberate copy of
+ * `packages/cockpit-local-collector/src/commands/jarvis-answer-envelope.ts`,
+ * which is the original. This package declares no dependency on that one — see
+ * `agent-door-session.ts` next door, whose own header makes the same call for
+ * the same reason — so the shape is duplicated rather than imported. Both
+ * copies are pinned by a test on the same literal key list
+ * (`JARVIS_ANSWER_ENVELOPE_KEYS` below), so a field added on one side and not
+ * the other fails a suite instead of drifting quietly.
+ *
+ * ## What `jarvis_ask` returns beside it
+ *
+ * The MCP tool returns exactly this envelope as its `structuredContent`, plus
+ * a human-readable text block. It does NOT carry the `clientLatency` /
+ * `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.
+ */
+/**
+ * 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", "degraded", "degraded_reasons"];
+/**
+ * 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 —
+ * but the consumer is told which way it fell short rather than being left to
+ * guess from a shorter reply.
+ */
+export type JarvisDegradedReason = 
+/** The requested model refused or failed and a fallback answered instead. */
+"model_fallback"
+/** The grounding gate took back words the model had already produced. */
+ | "answer_revised"
+/** At least one tool the turn reached for came back failed. */
+ | "tool_step_failed"
+/** No trace id came back, so this turn's step tree cannot be opened later. */
+ | "no_turn_id";
+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.
+     */
+    answer: string;
+    /** Every `Source: …` line found in `answer`, in the order it appears. */
+    sources: string[];
+    /**
+     * This turn's trace id — what `cockpit jarvis --trace <id>` and the
+     * `jarvis_trace` MCP tool open. `null` against a dashboard that predates
+     * BLI-3560, which is also a `no_turn_id` degradation.
+     */
+    turn_id: string | null;
+    /**
+     * The conversation NAME to hand back to continue this thread (`--thread`,
+     * or `jarvis_ask`'s `thread`). Not a uuid — `main` is the usual value.
+     */
+    thread_id: string | null;
+    /**
+     * The Mastra thread id the turn's spans were recorded under, which is what
+     * `GET /api/ops/trace?thread=` takes. A different identifier from
+     * `thread_id` above and deliberately named apart from it.
+     */
+    trace_thread_id: string | null;
+    degraded: boolean;
+    degraded_reasons: JarvisDegradedReason[];
+}
+/**
+ * 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
+ * lines the server wrote, so a new citation kind needs no change here.
+ */
+export declare function extractSourceLines(answer: string): string[];
+export interface JarvisAnswerEnvelopeInput {
+    /** The reply text the door returned. */
+    reply: string;
+    /** `body.thread`, or the thread the caller asked for when the door omitted it. */
+    thread?: string | null;
+    /** `body.traceId` — BLI-3560's per-turn id. */
+    traceId?: string | null;
+    /** `body.traceThread` — the Mastra thread the spans landed in. */
+    traceThread?: string | null;
+    /** `body.model.fallback` — whether a fallback model answered. */
+    modelFallback?: boolean;
+    /** `body.revised` — whether the grounding gate took back streamed words. */
+    revised?: boolean;
+    /** The settled trace, for the failed-step check. */
+    trace?: ReadonlyArray<{
+        status?: string;
+    }> | null;
+}
+export declare function buildJarvisAnswerEnvelope(input: JarvisAnswerEnvelopeInput): JarvisAnswerEnvelope;

package/dist/jarvis-answer-envelope.js

@@ -0,0 +1,82 @@
+/**
+ * The ONE shape a JARVIS answer wears when nobody is reading it with their
+ * eyes (BLI-3732).
+ *
+ * `cockpit jarvis --json` and the `bli-tower` MCP server's `jarvis_ask` reach
+ * the same door (`POST /api/jarvis/cli`) with the same device token and get
+ * the same reply body back. Before this file they described that body two
+ * different ways, so a script and an agent read two contracts for one turn.
+ * Now both build this envelope, and the five fields a consumer actually asks
+ * for — the answer, where it came from, which turn it was, which conversation
+ * it belongs to, and whether anything about it was second-rate — have one
+ * spelling each.
+ *
+ * ## Where the other copy is, and why
+ *
+ * This file is a deliberate copy of
+ * `packages/cockpit-local-collector/src/commands/jarvis-answer-envelope.ts`,
+ * which is the original. This package declares no dependency on that one — see
+ * `agent-door-session.ts` next door, whose own header makes the same call for
+ * the same reason — so the shape is duplicated rather than imported. Both
+ * copies are pinned by a test on the same literal key list
+ * (`JARVIS_ANSWER_ENVELOPE_KEYS` below), so a field added on one side and not
+ * the other fails a suite instead of drifting quietly.
+ *
+ * ## What `jarvis_ask` returns beside it
+ *
+ * The MCP tool returns exactly this envelope as its `structuredContent`, plus
+ * a human-readable text block. It does NOT carry the `clientLatency` /
+ * `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.
+ */
+/**
+ * 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 const JARVIS_ANSWER_ENVELOPE_KEYS = [
+    "ok",
+    "answer",
+    "sources",
+    "turn_id",
+    "thread_id",
+    "trace_thread_id",
+    "degraded",
+    "degraded_reasons",
+];
+/** A `Source:` line, as the grounding gate renders it into the answer. */
+const SOURCE_LINE = /^\s*Source:\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
+ * lines the server wrote, so a new citation kind needs no change here.
+ */
+export function extractSourceLines(answer) {
+    return answer
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => SOURCE_LINE.test(line));
+}
+export function buildJarvisAnswerEnvelope(input) {
+    const reasons = [];
+    if (input.modelFallback === true)
+        reasons.push("model_fallback");
+    if (input.revised === true)
+        reasons.push("answer_revised");
+    if ((input.trace ?? []).some((step) => step?.status === "failed")) {
+        reasons.push("tool_step_failed");
+    }
+    const turnId = input.traceId ?? null;
+    if (!turnId)
+        reasons.push("no_turn_id");
+    return {
+        ok: true,
+        answer: input.reply,
+        sources: extractSourceLines(input.reply),
+        turn_id: turnId,
+        thread_id: input.thread ?? null,
+        trace_thread_id: input.traceThread ?? null,
+        degraded: reasons.length > 0,
+        degraded_reasons: reasons,
+    };
+}

package/dist/jarvis-door.d.ts

@@ -0,0 +1,95 @@
+/**
+ * One JARVIS turn, and one trace read, for the `jarvis_*` MCP tools
+ * (BLI-3732). Everything the four tools in `jarvis-tools.ts` share lives here
+ * and nothing else does: the session gate, the request the dashboard actually
+ * receives, the envelope it becomes, and what `last` resolves to.
+ *
+ * The split exists so `jarvis-tools.ts` reads as four tool descriptions —
+ * which is the part a person and a model both have to understand — and the
+ * wire mechanics have one owner. Both halves talk to the same doors
+ * `cockpit jarvis` calls, with this machine's device token.
+ */
+import { loadAgentDoorSession } from "./agent-door-session.js";
+import { type FetchImpl } from "./agent-door.js";
+import { type JarvisAnswerEnvelope } from "./jarvis-answer-envelope.js";
+import { readCollectorTurnBookmark } from "./jarvis-turn-bookmark.js";
+/** The dashboard's own turn ceiling is 120 s; this is `TURN_DEADLINE_MS` from the CLI, verbatim. */
+export declare const TURN_TIMEOUT_MS = 125000;
+/** A trace read touches no model. Same 30 s the CLI gives it. */
+export declare const READ_TIMEOUT_MS = 30000;
+/**
+ * Hex, 8 characters — `CONFIRMATION_CODE_PATTERN` in
+ * `apps/dashboard/src/lib/jarvis/dispatch/proposal.ts`, anchored here because
+ * this side validates a whole argument rather than scanning a sentence.
+ */
+export declare const APPROVAL_CODE: RegExp;
+export interface JarvisDeps {
+    fetchImpl: FetchImpl;
+    /** Injectable for tests; defaults to reading `~/.config/bli-cockpit/session.json`. */
+    loadSession?: typeof loadAgentDoorSession;
+    /** Injectable for tests; defaults to the collector's own `--trace last` bookmark. */
+    readBookmark?: typeof readCollectorTurnBookmark;
+    /** Metadata-only, stderr. stdout belongs to the MCP transport. */
+    log?: (line: string) => void;
+}
+export declare const TAG = "[bli-cockpit-mcp jarvis]";
+export declare function defaultLog(line: string): void;
+export declare function textResult(text: string, structured?: Record<string, unknown>): {
+    structuredContent?: Record<string, unknown> | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function errorResult(text: string): {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export type ToolResult = ReturnType<typeof textResult> | ReturnType<typeof errorResult>;
+export declare function withSession(deps: JarvisDeps, run: (session: {
+    dashboardUrl: string;
+    deviceToken: string;
+}) => Promise<ToolResult>): Promise<ToolResult>;
+export declare function doorFailureText(door: string, response: {
+    transportError: string | null;
+    status: number;
+    body: Record<string, unknown>;
+}): string;
+/** What the last successful turn on THIS server was, for `jarvis_trace last`. */
+export interface LastTurn {
+    turnId: string | null;
+    traceThreadId: string | null;
+}
+/**
+ * One turn, and the envelope it becomes. Every `jarvis_*` tool that talks to a
+ * model goes through here, so the ask, the dispatch and the check cannot drift
+ * into three different request shapes.
+ */
+export declare function takeTurn(deps: JarvisDeps, session: {
+    dashboardUrl: string;
+    deviceToken: string;
+}, door: string, body: Record<string, unknown>, remember: (turn: LastTurn) => void): Promise<{
+    result: ToolResult;
+    envelope: JarvisAnswerEnvelope | null;
+}>;
+/**
+ * Which turn `last` means. Three sources, newest knowledge first: this
+ * server's own memory of the turn it just took, then the bookmark
+ * `cockpit jarvis` writes on the same machine, then — when the bookmark knew
+ * only the conversation — that conversation's newest recorded turn.
+ */
+export declare function resolveLastTurn(deps: JarvisDeps, session: {
+    dashboardUrl: string;
+    deviceToken: string;
+}, lastTurn: LastTurn): Promise<{
+    ok: true;
+    traceId: string;
+    from: "server_memory" | "bookmark" | "thread";
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+}>;

package/dist/jarvis-door.js

@@ -0,0 +1,163 @@
+/**
+ * One JARVIS turn, and one trace read, for the `jarvis_*` MCP tools
+ * (BLI-3732). Everything the four tools in `jarvis-tools.ts` share lives here
+ * and nothing else does: the session gate, the request the dashboard actually
+ * receives, the envelope it becomes, and what `last` resolves to.
+ *
+ * The split exists so `jarvis-tools.ts` reads as four tool descriptions —
+ * which is the part a person and a model both have to understand — and the
+ * wire mechanics have one owner. Both halves talk to the same doors
+ * `cockpit jarvis` calls, with this machine's device token.
+ */
+import { loadAgentDoorSession } from "./agent-door-session.js";
+import { callAgentDoor } from "./agent-door.js";
+import { buildJarvisAnswerEnvelope, } from "./jarvis-answer-envelope.js";
+import { readCollectorTurnBookmark } from "./jarvis-turn-bookmark.js";
+/** The dashboard's own turn ceiling is 120 s; this is `TURN_DEADLINE_MS` from the CLI, verbatim. */
+export const TURN_TIMEOUT_MS = 125_000;
+/** A trace read touches no model. Same 30 s the CLI gives it. */
+export const READ_TIMEOUT_MS = 30_000;
+/**
+ * Hex, 8 characters — `CONFIRMATION_CODE_PATTERN` in
+ * `apps/dashboard/src/lib/jarvis/dispatch/proposal.ts`, anchored here because
+ * this side validates a whole argument rather than scanning a sentence.
+ */
+export const APPROVAL_CODE = /^[0-9a-f]{8}$/i;
+export const TAG = "[bli-cockpit-mcp jarvis]";
+export function defaultLog(line) {
+    process.stderr.write(`${line}\n`);
+}
+export function textResult(text, structured) {
+    return {
+        content: [{ type: "text", text }],
+        ...(structured ? { structuredContent: structured } : {}),
+    };
+}
+export function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+export async function withSession(deps, run) {
+    const loadSession = deps.loadSession ?? loadAgentDoorSession;
+    const loaded = loadSession();
+    if (!loaded.ok) {
+        (deps.log ?? defaultLog)(`${TAG} refused ${JSON.stringify({ reason: loaded.reason })}`);
+        return errorResult(`This machine is not paired with Tower (${loaded.reason}). ${loaded.message}`);
+    }
+    return run(loaded.session);
+}
+export function doorFailureText(door, response) {
+    if (response.transportError) {
+        return `Tower could not be reached for ${door} (${response.transportError}). Nothing was asked or written.`;
+    }
+    const reason = typeof response.body.error === "string"
+        ? response.body.error
+        : typeof response.body.reason === "string"
+            ? response.body.reason
+            : "unknown_error";
+    const message = typeof response.body.reply === "string"
+        ? response.body.reply
+        : typeof response.body.message === "string"
+            ? response.body.message
+            : `Tower answered ${response.status}.`;
+    return `Tower refused ${door} (${reason}): ${message}`;
+}
+/**
+ * One turn, and the envelope it becomes. Every `jarvis_*` tool that talks to a
+ * model goes through here, so the ask, the dispatch and the check cannot drift
+ * into three different request shapes.
+ */
+export async function takeTurn(deps, session, door, body, remember) {
+    const log = deps.log ?? defaultLog;
+    const startedAt = Date.now();
+    // `accept: application/json` (which `callAgentDoor` always sends) is what
+    // makes the dashboard answer one JSON body instead of the NDJSON stream the
+    // terminal takes — an MCP tool has nobody to show live trace lines to.
+    const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/jarvis/cli", body, TURN_TIMEOUT_MS);
+    if (!response.ok) {
+        log(`${TAG} turn failed ${JSON.stringify({
+            door,
+            status: response.status,
+            transport: response.transportError !== null,
+            elapsed_ms: Date.now() - startedAt,
+        })}`);
+        return { result: errorResult(doorFailureText(door, response)), envelope: null };
+    }
+    const reply = response.body;
+    if (reply.ok === false || typeof reply.reply !== "string" || reply.reply.length === 0) {
+        log(`${TAG} turn empty ${JSON.stringify({
+            door,
+            reason: reply.error ?? "no_reply",
+            elapsed_ms: Date.now() - startedAt,
+        })}`);
+        return {
+            result: errorResult(`JARVIS did not answer ${door} (${reply.error ?? "no_reply"}). ${reply.reply ?? "Tower returned no text."}`),
+            envelope: null,
+        };
+    }
+    const envelope = buildJarvisAnswerEnvelope({
+        reply: reply.reply,
+        thread: reply.thread ?? (typeof body.thread === "string" ? body.thread : null),
+        traceId: reply.traceId,
+        traceThread: reply.traceThread,
+        modelFallback: reply.model?.fallback,
+        revised: reply.revised,
+        trace: reply.trace,
+    });
+    remember({ turnId: envelope.turn_id, traceThreadId: envelope.trace_thread_id });
+    log(`${TAG} answered ${JSON.stringify({
+        door,
+        reply_chars: envelope.answer.length,
+        sources: envelope.sources.length,
+        trace_steps: reply.trace?.length ?? 0,
+        degraded: envelope.degraded,
+        degraded_reasons: envelope.degraded_reasons,
+        has_turn_id: envelope.turn_id !== null,
+        elapsed_ms: Date.now() - startedAt,
+    })}`);
+    const footer = [
+        envelope.turn_id ? `turn_id: ${envelope.turn_id} (open it with jarvis_trace)` : null,
+        envelope.thread_id ? `thread_id: ${envelope.thread_id}` : null,
+        envelope.degraded ? `degraded: ${envelope.degraded_reasons.join(", ")}` : null,
+    ]
+        .filter((line) => line !== null)
+        .join("\n");
+    return {
+        result: textResult(`${envelope.answer}\n\n---\n${footer}`, { ...envelope }),
+        envelope,
+    };
+}
+/**
+ * Which turn `last` means. Three sources, newest knowledge first: this
+ * server's own memory of the turn it just took, then the bookmark
+ * `cockpit jarvis` writes on the same machine, then — when the bookmark knew
+ * only the conversation — that conversation's newest recorded turn.
+ */
+export async function resolveLastTurn(deps, session, lastTurn) {
+    if (lastTurn.turnId)
+        return { ok: true, traceId: lastTurn.turnId, from: "server_memory" };
+    const bookmark = await (deps.readBookmark ?? readCollectorTurnBookmark)();
+    const threadId = lastTurn.traceThreadId ?? bookmark?.threadId ?? null;
+    if (bookmark?.traceId)
+        return { ok: true, traceId: bookmark.traceId, from: "bookmark" };
+    if (threadId) {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/ops/trace?thread=${encodeURIComponent(threadId)}&limit=1`, undefined, READ_TIMEOUT_MS);
+        const traces = response.ok
+            ? (response.body.traces ?? [])
+            : [];
+        const newest = traces[0]?.traceId;
+        if (newest)
+            return { ok: true, traceId: newest, from: "thread" };
+        return {
+            ok: false,
+            reason: "no_traces_in_thread",
+            message: "That conversation has no recorded turns inside the 30-day retention. Ask something with "
+                + "jarvis_ask and trace that turn, or pass a turn_id.",
+        };
+    }
+    return {
+        ok: false,
+        reason: "no_remembered_turn",
+        message: 'Nothing has been asked on this machine yet, so "last" names no turn. Call jarvis_ask first, '
+            + "then pass the turn_id it returns.",
+    };
+}

package/dist/jarvis-tools.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `jarvis_*` MCP tools (BLI-3732) — JARVIS on the `bli-tower` server, over the
+ * exact doors `cockpit jarvis` calls with this machine's device token.
+ *
+ * The point of this file in one sentence: an agent on Codex or Claude Code
+ * should be able to ask JARVIS a question, read how it answered, and spend a
+ * human's coding-arm approval, without a browser and without a second
+ * vocabulary. Four tools, three doors, no new server-side surface:
+ *
+ *   jarvis_ask       POST /api/jarvis/cli      one turn, the same one
+ *                                              `cockpit jarvis` takes
+ *   jarvis_trace     GET  /api/ops/trace/<id>  that turn's step tree, rendered
+ *                                              SERVER-side and printed verbatim
+ *   jarvis_dispatch  POST /api/jarvis/cli      a coding-arm turn, carrying the
+ *   jarvis_check                               person's own approval code
+ *
+ * The wire mechanics they share — the session gate, the request the dashboard
+ * actually receives, the envelope it becomes, and what `last` resolves to —
+ * live in `jarvis-door.ts`, so this file reads as four tool descriptions,
+ * which is the part a person and a model both have to understand.
+ *
+ * ## The one contract
+ *
+ * `jarvis_ask` answers with `jarvis-answer-envelope.ts` — the same object
+ * `cockpit jarvis --json` prints. A script and an agent read one shape.
+ *
+ * ## The approval code, and what this surface can and cannot prove
+ *
+ * The coding arm's gate (BLI-2981) has two locks: the code is an HMAC over the
+ * exact plan folded with the asking account, and it must have come out of the
+ * HUMAN's own message. Lock 1 is untouched here — this server holds no secret
+ * and cannot compute a code for any plan, so an invented code is refused by
+ * the dashboard exactly as it always was.
+ *
+ * Lock 2 is weaker on THIS surface than it is in a terminal, and saying so is
+ * the honest thing to do. In a terminal the person types the code themselves.
+ * Through MCP the code arrives as a tool argument, and the dashboard cannot
+ * tell a code a person handed their agent from one the agent lifted out of the
+ * previous answer by itself. So: this tool takes the code as a parameter, it
+ * NEVER derives, guesses or fabricates one, its description tells the model in
+ * plain words that the code must come from the person, and every relay is
+ * logged (presence and length only, never the code). Anything stronger — a
+ * per-code single use, an out-of-band confirmation — is a server-side change
+ * to the gate itself and belongs with the gate, not here.
+ */
+import { type JarvisDeps } from "./jarvis-door.js";
+export type { JarvisDeps } from "./jarvis-door.js";
+export declare function registerJarvisTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: JarvisDeps): void;

package/dist/jarvis-tools.js

@@ -0,0 +1,248 @@
+/**
+ * `jarvis_*` MCP tools (BLI-3732) — JARVIS on the `bli-tower` server, over the
+ * exact doors `cockpit jarvis` calls with this machine's device token.
+ *
+ * The point of this file in one sentence: an agent on Codex or Claude Code
+ * should be able to ask JARVIS a question, read how it answered, and spend a
+ * human's coding-arm approval, without a browser and without a second
+ * vocabulary. Four tools, three doors, no new server-side surface:
+ *
+ *   jarvis_ask       POST /api/jarvis/cli      one turn, the same one
+ *                                              `cockpit jarvis` takes
+ *   jarvis_trace     GET  /api/ops/trace/<id>  that turn's step tree, rendered
+ *                                              SERVER-side and printed verbatim
+ *   jarvis_dispatch  POST /api/jarvis/cli      a coding-arm turn, carrying the
+ *   jarvis_check                               person's own approval code
+ *
+ * The wire mechanics they share — the session gate, the request the dashboard
+ * actually receives, the envelope it becomes, and what `last` resolves to —
+ * live in `jarvis-door.ts`, so this file reads as four tool descriptions,
+ * which is the part a person and a model both have to understand.
+ *
+ * ## The one contract
+ *
+ * `jarvis_ask` answers with `jarvis-answer-envelope.ts` — the same object
+ * `cockpit jarvis --json` prints. A script and an agent read one shape.
+ *
+ * ## The approval code, and what this surface can and cannot prove
+ *
+ * The coding arm's gate (BLI-2981) has two locks: the code is an HMAC over the
+ * exact plan folded with the asking account, and it must have come out of the
+ * HUMAN's own message. Lock 1 is untouched here — this server holds no secret
+ * and cannot compute a code for any plan, so an invented code is refused by
+ * the dashboard exactly as it always was.
+ *
+ * Lock 2 is weaker on THIS surface than it is in a terminal, and saying so is
+ * the honest thing to do. In a terminal the person types the code themselves.
+ * Through MCP the code arrives as a tool argument, and the dashboard cannot
+ * tell a code a person handed their agent from one the agent lifted out of the
+ * previous answer by itself. So: this tool takes the code as a parameter, it
+ * NEVER derives, guesses or fabricates one, its description tells the model in
+ * plain words that the code must come from the person, and every relay is
+ * logged (presence and length only, never the code). Anything stronger — a
+ * per-code single use, an out-of-band confirmation — is a server-side change
+ * to the gate itself and belongs with the gate, not here.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { APPROVAL_CODE, defaultLog, doorFailureText, errorResult, READ_TIMEOUT_MS, resolveLastTurn, TAG, takeTurn, textResult, withSession, } from "./jarvis-door.js";
+export function registerJarvisTools(server, deps) {
+    const register = server.registerTool.bind(server);
+    // The newest turn this SERVER took, so `jarvis_trace last` works in a fresh
+    // process that has asked something but never opened a terminal. It is only
+    // ever read here; the collector's own bookmark file is read as a fallback
+    // and deliberately never written, so a background agent cannot clobber the
+    // turn a person is in the middle of tracing.
+    let lastTurn = { turnId: null, traceThreadId: null };
+    const remember = (turn) => {
+        if (turn.turnId || turn.traceThreadId)
+            lastTurn = turn;
+    };
+    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 "
+            + "rules as Tower web chat, the Slack DM and `cockpit jarvis`. Pass thread to continue an "
+            + "earlier conversation; 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.",
+        inputSchema: {
+            question: z.string().min(1).max(50_000).describe("What to ask, in plain words."),
+            thread: z
+                .string()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe('The conversation to continue. Omit for "main", the default terminal thread.'),
+            subject: z
+                .string()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("Whose person page the question is ABOUT (a name or email). Never who is authenticated — "
+                + "the server decides what this caller may read about them."),
+            date: z
+                .string()
+                .min(1)
+                .max(20)
+                .optional()
+                .describe('YYYY-MM-DD, "today" or "yesterday" — binds that day\'s page. Sent verbatim.'),
+            model: z
+                .string()
+                .min(1)
+                .max(120)
+                .optional()
+                .describe("A provider:model key to request. An unknown key is refused by the dashboard."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const { result } = await takeTurn(deps, session, "jarvis_ask", {
+            question: String(args.question ?? ""),
+            thread: typeof args.thread === "string" ? args.thread : "main",
+            ...(typeof args.subject === "string" ? { subject: args.subject } : {}),
+            ...(typeof args.date === "string" ? { date: args.date } : {}),
+            ...(typeof args.model === "string" ? { model: args.model } : {}),
+        }, remember);
+        return result;
+    }));
+    register("jarvis_trace", {
+        title: "How JARVIS answered",
+        description: "The step tree of one JARVIS turn — every model step, tool call and server-side memory step, "
+            + "with how long each took, which model ran it, what it spent and what failed. This is the "
+            + "same tree `cockpit jarvis --trace` prints, rendered by the server and relayed verbatim. "
+            + 'Metadata only: no prompt, no answer, no tool argument. Pass "last" for the newest turn '
+            + "this server asked, or the turn_id jarvis_ask returned.",
+        inputSchema: {
+            turn_id: z
+                .string()
+                .min(1)
+                .max(200)
+                .describe('A turn_id from jarvis_ask, or "last".'),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const log = deps.log ?? defaultLog;
+        const requested = String(args.turn_id ?? "");
+        let traceId = requested;
+        let resolvedFrom = "argument";
+        if (requested.toLowerCase() === "last") {
+            const resolved = await resolveLastTurn(deps, session, lastTurn);
+            if (!resolved.ok) {
+                log(`${TAG} trace unavailable ${JSON.stringify({ reason: resolved.reason })}`);
+                return errorResult(resolved.message);
+            }
+            traceId = resolved.traceId;
+            resolvedFrom = resolved.from;
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/ops/trace/${encodeURIComponent(traceId)}`, undefined, READ_TIMEOUT_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("jarvis_trace", response));
+        const body = response.body;
+        if (body.ok === false) {
+            log(`${TAG} trace unavailable ${JSON.stringify({ reason: body.error ?? "trace_unavailable" })}`);
+            return errorResult(`Tower has no step tree for that turn (${body.error ?? "trace_unavailable"}). `
+                + (body.message ?? "Traces are kept for 30 days."));
+        }
+        const lines = body.lines ?? [];
+        log(`${TAG} trace read ${JSON.stringify({
+            resolved_from: resolvedFrom,
+            lines: lines.length,
+            truncated: body.truncated ?? false,
+        })}`);
+        const rendered = [
+            `Turn ${traceId}`,
+            ...(body.headline ? [body.headline] : []),
+            "",
+            ...(lines.length > 0 ? lines : ["That turn recorded no steps."]),
+            ...(body.truncated ? ["", "Only the first 1000 spans of this turn are shown."] : []),
+        ].join("\n");
+        return textResult(rendered, {
+            turn_id: traceId,
+            resolved_from: resolvedFrom,
+            headline: body.headline ?? null,
+            lines,
+            truncated: body.truncated ?? false,
+            ...(body.trace ? { trace: body.trace } : {}),
+        });
+    }));
+    register("jarvis_dispatch", {
+        title: "Dispatch a coding task to JARVIS's coding arm",
+        description: "Asks JARVIS to run a coding task on the runner: it clones the repo, works, pushes a branch "
+            + "and opens a pull request. It never merges. TWO CALLS, always. Call this once WITHOUT "
+            + "approval_code to get the plan and the 8-character confirmation code back; show both to the "
+            + "person; call it again with the code THEY give you and the same instruction. Never derive, "
+            + "guess, or reuse a code the person has not just handed you — a code you produce yourself is "
+            + "exactly what the approval gate exists to refuse.",
+        inputSchema: {
+            instruction: z
+                .string()
+                .min(1)
+                .max(50_000)
+                .describe("What the coding task should do, in full. This is the birth prompt the arm runs."),
+            repo: z
+                .string()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("Which repo, if the instruction does not already name one. Server-side allowlist applies."),
+            approval_code: z
+                .string()
+                .min(1)
+                .max(64)
+                .optional()
+                .describe("The 8-character hex confirmation code THE PERSON read back to you from the previous "
+                + "call's plan. Omit it on the first call."),
+            thread: z.string().min(1).max(200).optional().describe('Defaults to "main".'),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const log = deps.log ?? defaultLog;
+        const code = typeof args.approval_code === "string" ? args.approval_code.trim() : "";
+        if (code.length > 0 && !APPROVAL_CODE.test(code)) {
+            // Refused HERE rather than relayed: a malformed code cannot be the
+            // one JARVIS issued, and pasting it into the question would put
+            // unvalidated text where the server scans for approvals.
+            log(`${TAG} dispatch refused ${JSON.stringify({ reason: "approval_code_malformed", chars: code.length })}`);
+            return errorResult("That approval code is not a confirmation code (it must be exactly 8 hex characters, "
+                + "e.g. 3f9c1a02). Ask the person for the code JARVIS printed with the plan — do not "
+                + "construct one.");
+        }
+        log(`${TAG} dispatch relay ${JSON.stringify({
+            approval_code_present: code.length > 0,
+            instruction_chars: String(args.instruction ?? "").length,
+            repo_named: typeof args.repo === "string",
+        })}`);
+        const question = [
+            code.length > 0
+                ? "Dispatch this coding task to the coding arm now."
+                : "Propose a coding task for the coding arm. Do not dispatch it yet — read back the plan and the confirmation code so the person can approve it.",
+            ...(typeof args.repo === "string" ? [`Repo: ${args.repo}`] : []),
+            "",
+            String(args.instruction ?? ""),
+            ...(code.length > 0
+                ? ["", `The person approved this plan. Confirmation code: ${code.toLowerCase()}`]
+                : []),
+        ].join("\n");
+        const { result } = await takeTurn(deps, session, "jarvis_dispatch", { question, thread: typeof args.thread === "string" ? args.thread : "main" }, remember);
+        return result;
+    }));
+    register("jarvis_check", {
+        title: "Check a dispatched coding task",
+        description: "Asks JARVIS where a coding task it dispatched has got to — queued, running, pushed, or "
+            + "failed, and the pull request when there is one. Takes no approval: reading a task's state "
+            + "starts nothing.",
+        inputSchema: {
+            task: z
+                .string()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("The task id JARVIS named when it dispatched. Omit to ask about the recent ones."),
+            thread: z.string().min(1).max(200).optional().describe('Defaults to "main".'),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const task = typeof args.task === "string" ? args.task.trim() : "";
+        const question = task.length > 0
+            ? `Check the coding task ${task} and tell me its status, its branch and its pull request if it has one.`
+            : "Check the coding tasks dispatched for me recently and tell me the status of each.";
+        const { result } = await takeTurn(deps, session, "jarvis_check", { question, thread: typeof args.thread === "string" ? args.thread : "main" }, remember);
+        return result;
+    }));
+}

package/dist/jarvis-turn-bookmark.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The turn `cockpit jarvis --trace last` would open, read from the same
+ * bookmark the collector writes (BLI-3560, read here for BLI-3732).
+ *
+ * `jarvis_trace last` prefers the turn THIS server just took. This file is the
+ * fallback for the other case: a fresh MCP process that has asked nothing yet,
+ * on a machine where the person has been talking to JARVIS in a terminal. Both
+ * surfaces then mean the same turn by "last", which is the whole point.
+ *
+ * READ ONLY, deliberately. A background agent asking questions must not
+ * overwrite the bookmark a person is in the middle of tracing, so this server
+ * never writes the file — only `cockpit jarvis` does.
+ *
+ * The file holds two opaque ids and a timestamp. No question, no answer, no
+ * name. Nothing here ever throws: a missing or unreadable bookmark is "nothing
+ * is remembered", which is a real answer and the caller says so in a sentence.
+ */
+/** The collector's own name for it — `jarvis-trace.ts` `LAST_TURN_FILE`. */
+export declare const LAST_TURN_FILE = "last-turn-trace.json";
+export interface CollectorTurnBookmark {
+    traceId: string | null;
+    threadId: string | null;
+}
+export declare function collectorTurnBookmarkPath(homeDir?: string): string;
+export declare function readCollectorTurnBookmark(homeDir?: string): Promise<CollectorTurnBookmark | null>;

package/dist/jarvis-turn-bookmark.js

@@ -0,0 +1,43 @@
+/**
+ * The turn `cockpit jarvis --trace last` would open, read from the same
+ * bookmark the collector writes (BLI-3560, read here for BLI-3732).
+ *
+ * `jarvis_trace last` prefers the turn THIS server just took. This file is the
+ * fallback for the other case: a fresh MCP process that has asked nothing yet,
+ * on a machine where the person has been talking to JARVIS in a terminal. Both
+ * surfaces then mean the same turn by "last", which is the whole point.
+ *
+ * READ ONLY, deliberately. A background agent asking questions must not
+ * overwrite the bookmark a person is in the middle of tracing, so this server
+ * never writes the file — only `cockpit jarvis` does.
+ *
+ * The file holds two opaque ids and a timestamp. No question, no answer, no
+ * name. Nothing here ever throws: a missing or unreadable bookmark is "nothing
+ * is remembered", which is a real answer and the caller says so in a sentence.
+ */
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { getUserLocalCockpitPaths } from "@bli-cockpit/telemetry-core";
+/** The collector's own name for it — `jarvis-trace.ts` `LAST_TURN_FILE`. */
+export const LAST_TURN_FILE = "last-turn-trace.json";
+export function collectorTurnBookmarkPath(homeDir = os.homedir()) {
+    return path.join(getUserLocalCockpitPaths(homeDir).state_dir, LAST_TURN_FILE);
+}
+export async function readCollectorTurnBookmark(homeDir) {
+    try {
+        const raw = await readFile(collectorTurnBookmarkPath(homeDir), "utf8");
+        const parsed = JSON.parse(raw);
+        const traceId = typeof parsed.traceId === "string" ? parsed.traceId : null;
+        const threadId = typeof parsed.threadId === "string" ? parsed.threadId : null;
+        if (!traceId && !threadId)
+            return null;
+        return { traceId, threadId };
+    }
+    catch {
+        // Missing, unreadable, or not JSON — all three mean the same thing to the
+        // one caller, which names it (`no_remembered_turn`) rather than printing
+        // nothing.
+        return null;
+    }
+}

package/dist/server.d.ts

@@ -19,7 +19,7 @@ export interface ServerDeps {
     fetchImpl: FetchImpl;
 }
 export declare const PACKAGE_NAME = "@bli-cockpit/mcp";
-export declare const PACKAGE_VERSION = "0.1.0";
+export declare const PACKAGE_VERSION = "0.1.2";
 export declare const emitEventInput: {
     ticket_id: z.ZodString;
     event_type: z.ZodString;

package/dist/server.js

@@ -7,9 +7,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { registerDocsMsgTools } from "./docs-msg-tools.js";
+import { registerJarvisTools } from "./jarvis-tools.js";
 import { registerWorkTools } from "./work-tools.js";
 export const PACKAGE_NAME = "@bli-cockpit/mcp";
-export const PACKAGE_VERSION = "0.1.0";
+export const PACKAGE_VERSION = "0.1.2";
 // ---- input schemas (Zod raw shapes) -----------------------------------------
 export const emitEventInput = {
     ticket_id: z
@@ -375,5 +376,9 @@ export function createServer(deps) {
     // the docs/msg tools above, for the same reason: a coding session should
     // file and move a Tower issue the way it files and moves a Linear one.
     registerWorkTools(server, { fetchImpl: deps.fetchImpl });
+    // BLI-3732: `jarvis_*` — the assistant itself, on the same device-token path
+    // as the three families above, over the doors `cockpit jarvis` already
+    // calls. It is the last Tower surface that had a CLI door and no MCP one.
+    registerJarvisTools(server, { fetchImpl: deps.fetchImpl });
     return server;
 }

package/dist/verb-census.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Every `cockpit <noun> <verb>` that talks to Tower, read off the collector's
+ * own decision tables (BLI-3732).
+ *
+ * This is a test helper with no runtime consumer, kept out of the suite file
+ * so the census itself — the three lists a person actually reviews — reads as
+ * a list and not as a parser. It reads SOURCE TEXT rather than importing the
+ * collector, because this package declares no dependency on it (the same
+ * reason `agent-door-session.ts` copies a session reader instead of importing
+ * one).
+ *
+ * ## Where each half comes from
+ *
+ * - The NOUNS are the `parse<Noun>Args` functions `local-args-tower.ts`
+ *   re-exports. That file is the authoritative "these are the commands that
+ *   talk to Tower" table — its siblings are a filing decision, not a contract.
+ * - The VERBS are each noun's `action:` union in `LocalCommand`
+ *   (`local-args.ts`), with an `XAction` alias resolved from whichever
+ *   `local-args-tower-*.ts` declares it. A noun with no `action` field is one
+ *   verb wearing the noun's own name (`jarvis`, `correct`, `workbook`).
+ *
+ * ## What it deliberately does NOT see
+ *
+ * Mode FLAGS. `cockpit jarvis --trace`, `--threads` and `--history` are three
+ * different acts behind one noun, and no decision table calls them verbs, so
+ * the mechanical rule cannot find them. They are covered by hand in the
+ * census's own twin map (`jarvis --trace` → `jarvis_trace`); a flag that grows
+ * into a verb will show up here the moment it becomes an `action`.
+ */
+export declare const COLLECTOR_COMMANDS_DIR: string;
+export interface TowerVerb {
+    noun: string;
+    /** The action word, or "" for a noun that is its own single verb. */
+    action: string;
+    /** How a person types it: `docs read`, or just `jarvis`. */
+    spelling: string;
+}
+/** `parseJarvisArgs` → `jarvis`. The re-export table IS the noun list. */
+export declare function towerNouns(): string[];
+/** Every Tower verb a person may type today. */
+export declare function towerVerbs(): TowerVerb[];

package/dist/verb-census.js

@@ -0,0 +1,108 @@
+/**
+ * Every `cockpit <noun> <verb>` that talks to Tower, read off the collector's
+ * own decision tables (BLI-3732).
+ *
+ * This is a test helper with no runtime consumer, kept out of the suite file
+ * so the census itself — the three lists a person actually reviews — reads as
+ * a list and not as a parser. It reads SOURCE TEXT rather than importing the
+ * collector, because this package declares no dependency on it (the same
+ * reason `agent-door-session.ts` copies a session reader instead of importing
+ * one).
+ *
+ * ## Where each half comes from
+ *
+ * - The NOUNS are the `parse<Noun>Args` functions `local-args-tower.ts`
+ *   re-exports. That file is the authoritative "these are the commands that
+ *   talk to Tower" table — its siblings are a filing decision, not a contract.
+ * - The VERBS are each noun's `action:` union in `LocalCommand`
+ *   (`local-args.ts`), with an `XAction` alias resolved from whichever
+ *   `local-args-tower-*.ts` declares it. A noun with no `action` field is one
+ *   verb wearing the noun's own name (`jarvis`, `correct`, `workbook`).
+ *
+ * ## What it deliberately does NOT see
+ *
+ * Mode FLAGS. `cockpit jarvis --trace`, `--threads` and `--history` are three
+ * different acts behind one noun, and no decision table calls them verbs, so
+ * the mechanical rule cannot find them. They are covered by hand in the
+ * census's own twin map (`jarvis --trace` → `jarvis_trace`); a flag that grows
+ * into a verb will show up here the moment it becomes an `action`.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const COLLECTOR_COMMANDS_DIR = resolve(HERE, "../../cockpit-local-collector/src/commands");
+function read(file) {
+    return readFileSync(join(COLLECTOR_COMMANDS_DIR, file), "utf8");
+}
+/** Every `local-args-tower*.ts` in the collector, so a new sibling is read too. */
+function towerFiles() {
+    return readdirSync(COLLECTOR_COMMANDS_DIR).filter((name) => name.startsWith("local-args-tower") && name.endsWith(".ts") && !name.includes(".test."));
+}
+/** `parseJarvisArgs` → `jarvis`. The re-export table IS the noun list. */
+export function towerNouns() {
+    const source = read("local-args-tower.ts");
+    const nouns = new Set();
+    for (const match of source.matchAll(/\bparse([A-Z][A-Za-z]*)Args\b/g)) {
+        nouns.add(match[1].replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase());
+    }
+    return [...nouns].sort();
+}
+/** `export type NotesAction = "list" | "show" | …` across every tower sibling. */
+function actionAliases() {
+    const aliases = new Map();
+    for (const file of towerFiles()) {
+        const source = read(file);
+        for (const match of source.matchAll(/export type (\w+Action)\s*=\s*([\s\S]*?);/g)) {
+            aliases.set(match[1], [...match[2].matchAll(/"([a-z-]+)"/g)].map((m) => m[1]));
+        }
+    }
+    return aliases;
+}
+/**
+ * The `LocalCommand` variants, split the way the union is written: one chunk
+ * per `  | {` at the top level of the type.
+ */
+function commandVariants() {
+    const source = readFileSync(join(COLLECTOR_COMMANDS_DIR, "local-args.ts"), "utf8");
+    const start = source.indexOf("export type LocalCommand =");
+    if (start < 0)
+        throw new Error("LocalCommand union not found in local-args.ts");
+    const end = source.indexOf("\nexport ", start + 10);
+    return source.slice(start, end < 0 ? undefined : end).split(/\n\s{2}\|\s/);
+}
+/** Every Tower verb a person may type today. */
+export function towerVerbs() {
+    const nouns = new Set(towerNouns());
+    const aliases = actionAliases();
+    const verbs = [];
+    const seenNouns = new Set();
+    for (const variant of commandVariants()) {
+        const kind = /kind:\s*"([a-z-]+)"/.exec(variant)?.[1];
+        if (!kind || !nouns.has(kind) || seenNouns.has(kind))
+            continue;
+        seenNouns.add(kind);
+        const action = /\n\s*action:\s*([^;]+);/.exec(variant)?.[1]?.trim();
+        if (!action) {
+            verbs.push({ noun: kind, action: "", spelling: kind });
+            continue;
+        }
+        const words = action.endsWith("Action")
+            ? (aliases.get(action) ?? [])
+            : [...action.matchAll(/"([a-z-]+)"/g)].map((m) => m[1]);
+        if (words.length === 0) {
+            throw new Error(`No action vocabulary found for cockpit ${kind} (read "${action}")`);
+        }
+        for (const word of words) {
+            verbs.push({ noun: kind, action: word, spelling: `${kind} ${word}` });
+        }
+    }
+    const missing = [...nouns].filter((noun) => !seenNouns.has(noun));
+    if (missing.length > 0) {
+        // A parser with no `LocalCommand` variant means the extraction has drifted
+        // from the source, and a census that quietly reads fewer verbs than exist
+        // is worse than no census at all.
+        throw new Error(`Tower nouns with no LocalCommand variant: ${missing.join(", ")}`);
+    }
+    return verbs.sort((a, b) => a.spelling.localeCompare(b.spelling));
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
-  "description": "bli-tower — an MCP server over BLI Cockpit's docs/msg agent doors (docs_*, msg_*), plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
+  "description": "bli-tower — an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",
   "bin": {
     "bli-cockpit-mcp": "./dist/index.js"