@bli-cockpit/mcp 0.1.0 → 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;