@bli-cockpit/mcp 0.1.8 → 0.1.10

package/README.md

@@ -34,7 +34,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**64 of 66 Tower verbs have an MCP twin.**
+**73 of 76 Tower verbs have an MCP twin.**
 Each tool goes through the SAME door its CLI verb calls, with the same
 collector device token — never a second route and never a service-role
 reader. `src/verb-census.test.ts` fails when a verb is in none of the
@@ -46,6 +46,15 @@ three tables below.
 | `cockpit brief read` | `brief_read` | `GET /api/jarvis/brief` |
 | `cockpit brief rewrite` | `brief_rewrite` | `POST /api/jarvis/recompile` |
 | `cockpit brief status` | `brief_status` | `GET /api/ops/brief-status` |
+| `cockpit cal calendars` | `cal_calendars` | `GET /api/cal/calendars` |
+| `cockpit cal create` | `cal_create` | `POST /api/cal/events` |
+| `cockpit cal detach` | `cal_detach` | `DELETE /api/cal/calendars` |
+| `cockpit cal find` | `cal_find` | `GET /api/cal/find` |
+| `cockpit cal next` | `cal_next` | `GET /api/cal/next` |
+| `cockpit cal share` | `cal_share` | `PATCH /api/cal/calendars` |
+| `cockpit cal sync` | `cal_sync` | `POST /api/cal/calendars/[id]/sync` |
+| `cockpit cal today` | `cal_today` | `GET /api/cal/today` |
+| `cockpit cal week` | `cal_week` | `GET /api/cal/week` |
 | `cockpit correct` | `brief_correct` | `POST /api/jarvis/corrections` |
 | `cockpit docs create` | `docs_create` | `POST /api/docs/documents` |
 | `cockpit docs list` | `docs_list` | `GET /api/docs/documents` |
@@ -120,6 +129,7 @@ A claim about the verb's nature, not a backlog.
 | CLI verb | Why it can never have a twin |
 | --- | --- |
 | `cockpit brief edit` | opens the person's own $EDITOR on this machine and files what they changed; an agent has no editor to open (commands/editor.ts) |
+| `cockpit cal add-ical` | carries a calendar's SECRET iCal ADDRESS — a permanent, unauthenticated, read-anything-on-that-calendar URL. The CLI reads it from STDIN precisely so it never lands in an argument list; an MCP tool argument travels through a model's context window and whatever transcript store sits behind it, so attaching a calendar stays a thing a person does at a terminal (BLI-3709) |
 | `cockpit mail add-imap` | carries a Google app password. The CLI reads it from STDIN precisely so it never lands in an argument list; an MCP tool argument travels through a model's context window and whatever transcript store sits behind it, so attaching a mailbox stays a thing a person does at a terminal (BLI-3708) |
 
 <!-- END GENERATED verb census -->

package/dist/cal-tools.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `cal_*` MCP tools (BLI-3709) — the calendars a person attached, on the
+ * `bli-tower` server, over the same `/api/cal/**` doors `cockpit cal` and the
+ * browser call, authenticated with this machine's collector device token.
+ *
+ * The point, in one sentence: an agent working on somebody's behalf should be
+ * able to see that they are in a meeting at 3pm before it proposes a call at
+ * 3pm, and should answer "when is standup" from the record rather than from
+ * memory.
+ *
+ * TWO DELIBERATE ASYMMETRIES with the CLI, both recorded in `verb-census.ts`:
+ *
+ * - **`cockpit cal add-ical` has NO MCP twin.** It carries a calendar's SECRET
+ *   iCal ADDRESS — a permanent, unauthenticated, read-anything-on-that-calendar
+ *   URL — and the CLI takes it on stdin precisely so it never lands in an
+ *   argument list. An MCP tool argument IS an argument list: it travels through
+ *   a model's context window and whatever transcript store sits behind it.
+ *   Attaching a calendar stays a thing a person does at a terminal.
+ * - **`cal_share` requires `confirm: true`.** Making a calendar readable by
+ *   everyone at BLI is not a read, and it is not something to do because a
+ *   sentence sounded like it.
+ *
+ * EVERY READ SENDS A ZONE. `time_zone` is a required-in-practice argument on
+ * the window tools, because a window computed without one is computed in UTC —
+ * "today" would end at 5pm in Vancouver. When a caller omits it, the tools
+ * send this machine's own zone rather than letting the server guess.
+ *
+ * Same session discipline as `mail-tools.ts`: the session is loaded fresh per
+ * call, so a machine with no `cockpit login` pairing still serves this
+ * server's other tools and only a `cal_` call fails, by name.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type CalDeps = ToolDeps;
+export declare function registerCalTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: CalDeps): void;

package/dist/cal-tools.js

@@ -0,0 +1,265 @@
+/**
+ * `cal_*` MCP tools (BLI-3709) — the calendars a person attached, on the
+ * `bli-tower` server, over the same `/api/cal/**` doors `cockpit cal` and the
+ * browser call, authenticated with this machine's collector device token.
+ *
+ * The point, in one sentence: an agent working on somebody's behalf should be
+ * able to see that they are in a meeting at 3pm before it proposes a call at
+ * 3pm, and should answer "when is standup" from the record rather than from
+ * memory.
+ *
+ * TWO DELIBERATE ASYMMETRIES with the CLI, both recorded in `verb-census.ts`:
+ *
+ * - **`cockpit cal add-ical` has NO MCP twin.** It carries a calendar's SECRET
+ *   iCal ADDRESS — a permanent, unauthenticated, read-anything-on-that-calendar
+ *   URL — and the CLI takes it on stdin precisely so it never lands in an
+ *   argument list. An MCP tool argument IS an argument list: it travels through
+ *   a model's context window and whatever transcript store sits behind it.
+ *   Attaching a calendar stays a thing a person does at a terminal.
+ * - **`cal_share` requires `confirm: true`.** Making a calendar readable by
+ *   everyone at BLI is not a read, and it is not something to do because a
+ *   sentence sounded like it.
+ *
+ * EVERY READ SENDS A ZONE. `time_zone` is a required-in-practice argument on
+ * the window tools, because a window computed without one is computed in UTC —
+ * "today" would end at 5pm in Vancouver. When a caller omits it, the tools
+ * send this machine's own zone rather than letting the server guess.
+ *
+ * Same session discipline as `mail-tools.ts`: the session is loaded fresh per
+ * call, so a machine with no `cockpit login` pairing still serves this
+ * server's other tools and only a `cal_` call fails, by name.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { CONFIRM_INPUT, doorFailureText, errorResult, queryString, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
+/** This machine's zone: what a person means by "today" unless they say otherwise. */
+function localZone() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+    }
+    catch {
+        return "UTC";
+    }
+}
+function eventLine(event) {
+    const when = event.all_day
+        ? `${event.starts_at.slice(0, 10)} (all day)`
+        : `${event.starts_at.slice(0, 16).replace("T", " ")}–${event.ends_at.slice(11, 16)}`;
+    const where = event.location ? `  @ ${event.location}` : "";
+    const who = event.attendee_count > 0 ? `  (${event.attendee_count} attendees)` : "";
+    return `${event.recurring ? "↻" : " "} ${when}  ${event.title}${where}${who}  [${event.calendar_name}]`;
+}
+/** Every window read, so the three named windows cannot drift from each other. */
+function windowRenderer(label) {
+    return (body) => {
+        const events = (Array.isArray(body.events) ? body.events : []);
+        const calendars = (Array.isArray(body.calendars) ? body.calendars : []);
+        const notes = (Array.isArray(body.notes) ? body.notes : []);
+        const window = body.window;
+        if (calendars.length === 0) {
+            return textResult("No calendars are attached. A person attaches one with `cockpit cal add-ical` (personal) or by connecting "
+                + "Google in the browser (work).", body);
+        }
+        if (events.length === 0) {
+            return textResult(`Nothing on ${label} (${window?.time_zone ?? "UTC"}).`, body);
+        }
+        const unexpanded = notes.length > 0
+            ? `\n\nNote: ${notes.map((note) => `"${note.title}" repeats on a rule Tower does not expand (${note.detail.join(", ")}), so only its first occurrence is listed`).join("; ")}.`
+            : "";
+        return textResult(`${events.length} event(s) ${label}, times in ${window?.time_zone ?? "UTC"}:\n${events.map(eventLine).join("\n")}${unexpanded}`, body);
+    };
+}
+export function registerCalTools(server, deps) {
+    const register = registrarFor(server);
+    const windowInput = {
+        time_zone: z.string().min(1).max(80).optional(),
+        calendar_id: z.string().uuid().optional(),
+        limit: z.number().int().min(1).max(750).optional(),
+    };
+    function windowQuery(args) {
+        const query = new URLSearchParams({ tz: String(args.time_zone ?? localZone()) });
+        if (args.calendar_id)
+            query.set("calendar_id", String(args.calendar_id));
+        if (args.limit)
+            query.set("limit", String(args.limit));
+        if (typeof args.offset === "number")
+            query.set("offset", String(args.offset));
+        if (typeof args.hours === "number")
+            query.set("hours", String(args.hours));
+        return query;
+    }
+    register("cal_today", {
+        title: "What is on today",
+        description: "Every event today across every calendar you may read, in the zone you name (default: this machine's). "
+            + "`offset` moves the day — 1 is tomorrow, -1 yesterday. Recurring events are expanded for exactly this day, "
+            + "and a series whose rule Tower will not guess at is named rather than dropped.",
+        inputSchema: { ...windowInput, offset: z.number().int().min(-52).max(52).optional() },
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/cal/today${queryString(windowQuery(args))}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("cal_today", response));
+        return windowRenderer("today")(response.body);
+    }));
+    register("cal_week", {
+        title: "What is on this week",
+        description: "Monday to Sunday, across every calendar you may read. The week starts on MONDAY here. `offset` moves it — 1 "
+            + "is next week.",
+        inputSchema: { ...windowInput, offset: z.number().int().min(-52).max(52).optional() },
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/cal/week${queryString(windowQuery(args))}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("cal_week", response));
+        return windowRenderer("this week")(response.body);
+    }));
+    register("cal_next", {
+        title: "What is coming up",
+        description: "What is next, counted from RIGHT NOW rather than from midnight — at 23:50 the honest answer is tomorrow's "
+            + "09:30, and a day-shaped window would say 'nothing'. Defaults to the next 72 hours; `hours` narrows or widens "
+            + "it. An event already running is included, so this also answers 'what am I in?'.",
+        inputSchema: { ...windowInput, hours: z.number().int().min(1).max(720).optional() },
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/cal/next${queryString(windowQuery(args))}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("cal_next", response));
+        return windowRenderer("coming up")(response.body);
+    }));
+    register("cal_find", {
+        title: "Find an event",
+        description: "Full text over titles, locations and descriptions on every calendar you may read — this is how to answer "
+            + "\"when is standup\". A repeating event is answered with the NEXT time it happens, never with its first "
+            + "occurrence two years ago.",
+        inputSchema: {
+            query: z.string().min(1).max(400),
+            calendar_id: z.string().uuid().optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const query = new URLSearchParams({ q: String(args.query ?? "") });
+        if (args.calendar_id)
+            query.set("calendar_id", String(args.calendar_id));
+        if (args.limit)
+            query.set("limit", String(args.limit));
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/cal/find${queryString(query)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("cal_find", response));
+        const matches = (Array.isArray(response.body.matches) ? response.body.matches : []);
+        return textResult(matches.length === 0
+            ? `Nothing in the calendars you may read matched "${String(args.query)}".`
+            : `${matches.length} match(es):\n${matches
+                .map((match) => `${match.recurring ? "↻" : " "} ${match.next_occurrence ?? match.starts_at}  ${match.title}  [${match.calendar_name}]`)
+                .join("\n")}`, { matches });
+    }));
+    register("cal_calendars", {
+        title: "List attached calendars",
+        description: "Every calendar you may see — its provider (google_oauth or ical_url), whether its owner shared it with the "
+            + "org, and when it last synced. Start here when you need a calendar id.",
+        inputSchema: {},
+    }, async () => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/cal/calendars");
+        if (!response.ok)
+            return errorResult(doorFailureText("cal_calendars", response));
+        const calendars = (Array.isArray(response.body.calendars) ? response.body.calendars : []);
+        return textResult(calendars.length === 0
+            ? "No calendars are attached. A person attaches one with `cockpit cal add-ical` (personal) or by connecting "
+                + "Google in the browser (work)."
+            : `${calendars.length} calendar(s).\n${calendars
+                .map((calendar) => `${calendar.name}  ${calendar.provider}  ${calendar.org_visible ? "shared" : "private"}  ${calendar.status}${calendar.status_reason ? ` (${calendar.status_reason})` : ""}  ${calendar.id}`)
+                .join("\n")}`, { calendars });
+    }));
+    register("cal_create", {
+        title: "Create an event",
+        description: "Creates an event AT GOOGLE and then stores it here, so the people invited actually get the invitation. Only a "
+            + "google_oauth calendar can be written to — a calendar attached by its secret iCal address is read-only and "
+            + "says so by name. Times are ISO instants, or plain dates with all_day. Requires confirm: true, because "
+            + "attendees are emailed by Google the moment this succeeds.",
+        inputSchema: {
+            calendar_id: z.string().uuid(),
+            title: z.string().min(1).max(500),
+            starts_at: z.string().min(4).max(40),
+            ends_at: z.string().min(4).max(40),
+            location: z.string().max(1_000).optional(),
+            all_day: z.boolean().optional(),
+            time_zone: z.string().min(1).max(80).optional(),
+            attendees: z.array(z.string().email()).max(100).optional(),
+            ...CONFIRM_INPUT,
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const refusal = unconfirmed(args, `This would create "${String(args.title)}" and email every attendee from Google.`);
+        if (refusal)
+            return refusal;
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/cal/events", {
+            calendar_id: args.calendar_id,
+            title: args.title,
+            starts_at: args.starts_at,
+            ends_at: args.ends_at,
+            ...(args.location ? { location: args.location } : {}),
+            ...(args.all_day === true ? { all_day: true } : {}),
+            ...(Array.isArray(args.attendees) && args.attendees.length > 0 ? { attendees: args.attendees } : {}),
+            time_zone: args.time_zone ?? localZone(),
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("cal_create", response));
+        const event = response.body.event;
+        return textResult(`Created "${event?.title ?? String(args.title)}" at ${event?.starts_at ?? String(args.starts_at)}.`
+            + (event?.html_link ? `\n${event.html_link}` : ""), { event });
+    }));
+    register("cal_share", {
+        title: "Share a calendar with the org, or take it back",
+        description: "Marks one of YOUR calendars readable by every member of Tower, or private again. Sharing never lets anybody "
+            + "else change it — only the owner writes. Requires confirm: true: making somebody's day visible to nine people "
+            + "is not something to do because a sentence sounded like it.",
+        inputSchema: {
+            calendar_id: z.string().uuid(),
+            org_visible: z.boolean(),
+            ...CONFIRM_INPUT,
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const refusal = unconfirmed(args, args.org_visible === true
+            ? "This would make that calendar readable by everyone at BLI."
+            : "This would make that calendar private again.");
+        if (refusal)
+            return refusal;
+        const query = new URLSearchParams({ calendar_id: String(args.calendar_id) });
+        const response = await callAgentDoor(session, deps.fetchImpl, "PATCH", `/api/cal/calendars${queryString(query)}`, { org_visible: args.org_visible === true });
+        if (!response.ok)
+            return errorResult(doorFailureText("cal_share", response));
+        const calendar = response.body.calendar;
+        return textResult(calendar?.org_visible
+            ? `"${calendar.name}" is now readable by everyone at BLI. Nobody but its owner can change it.`
+            : `"${calendar?.name ?? String(args.calendar_id)}" is private again.`, { calendar });
+    }));
+    register("cal_sync", {
+        title: "Read a calendar now",
+        description: "Runs one sync pass for a calendar you OWN, instead of waiting for the 15-minute cron. `full: true` ignores the "
+            + "sync token / ETag and re-reads everything. The answer is the run's own counts and reason label, which is "
+            + "exactly what the ledger row says.",
+        inputSchema: { calendar_id: z.string().uuid(), full: z.boolean().optional() },
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/cal/calendars/${encodeURIComponent(String(args.calendar_id))}/sync${args.full === true ? "?full=1" : ""}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("cal_sync", response));
+        const run = response.body.run;
+        if (!run)
+            return textResult("Tower answered without a run. Nothing to report.", response.body);
+        return textResult(run.reason === "ok"
+            ? run.detail === "feed_unchanged"
+                ? "Nothing has changed on that calendar since the last read."
+                : `Synced: ${run.eventsAdded} new, ${run.eventsUpdated} updated, ${run.eventsDeleted} gone.`
+            : `That calendar did not sync: ${run.reason}${run.detail ? ` (${run.detail})` : ""}.`, { run });
+    }));
+    register("cal_detach", {
+        title: "Detach a calendar",
+        description: "Removes a calendar and its stored events from Tower. The calendar itself is untouched at Google — this only "
+            + "forgets it here. Requires confirm: true.",
+        inputSchema: { calendar_id: z.string().uuid(), ...CONFIRM_INPUT },
+    }, async (args) => withSession(deps, async (session) => {
+        const refusal = unconfirmed(args, "This would detach that calendar and forget its stored events (the calendar itself is untouched at Google).");
+        if (refusal)
+            return refusal;
+        const query = new URLSearchParams({ calendar_id: String(args.calendar_id) });
+        const response = await callAgentDoor(session, deps.fetchImpl, "DELETE", `/api/cal/calendars${queryString(query)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("cal_detach", response));
+        return textResult(`Detached ${String(args.calendar_id)}. Its stored events went with it; the calendar itself is untouched at Google.`, response.body);
+    }));
+}

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

@@ -53,7 +53,7 @@
  * 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).
  *
@@ -134,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[];
 }
@@ -173,6 +190,13 @@ 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

package/dist/jarvis-answer-envelope.js

@@ -61,6 +61,7 @@ export const JARVIS_ANSWER_ENVELOPE_KEYS = [
     "thread_id",
     "trace_thread_id",
     "proposal_id",
+    "next_action",
     "degraded",
     "degraded_reasons",
 ];
@@ -197,6 +198,7 @@ export function buildJarvisAnswerEnvelope(input) {
         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,9 @@ 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,
     });
@@ -122,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,
@@ -134,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/dist/server.js

@@ -10,6 +10,7 @@ import { registerBriefTools } from "./brief-tools.js";
 import { registerBriefWriteTools } from "./brief-write-tools.js";
 import { registerDocsMsgTools } from "./docs-msg-tools.js";
 import { registerJarvisTools } from "./jarvis-tools.js";
+import { registerCalTools } from "./cal-tools.js";
 import { registerMailTools } from "./mail-tools.js";
 import { registerNotesTools } from "./notes-tools.js";
 import { registerNotesWriteTools } from "./notes-write-tools.js";
@@ -392,6 +393,12 @@ export function createServer(deps) {
     // has no twin (see mail-tools.ts's header — a credential is not a tool
     // argument).
     registerMailTools(server, { fetchImpl: deps.fetchImpl });
+    // BLI-3709: the calendars a person attached. The window reads, a find, a
+    // create and a share over the same /api/cal/** doors `cockpit cal` calls;
+    // `add-ical` deliberately has no twin (see cal-tools.ts's header — a
+    // calendar's secret address is a credential, and a credential is not a tool
+    // argument).
+    registerCalTools(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.

package/dist/verb-census.js

@@ -156,6 +156,15 @@ export const MCP_TWINS = {
     "mail attachment": { tool: "mail_attachment", door: "GET /api/mail/attachments/[id]?meta=1" },
     "mail sync": { tool: "mail_sync", door: "POST /api/mail/accounts/[id]/sync" },
     "mail detach": { tool: "mail_detach", door: "DELETE /api/mail/accounts" },
+    "cal today": { tool: "cal_today", door: "GET /api/cal/today" },
+    "cal week": { tool: "cal_week", door: "GET /api/cal/week" },
+    "cal next": { tool: "cal_next", door: "GET /api/cal/next" },
+    "cal find": { tool: "cal_find", door: "GET /api/cal/find" },
+    "cal calendars": { tool: "cal_calendars", door: "GET /api/cal/calendars" },
+    "cal create": { tool: "cal_create", door: "POST /api/cal/events" },
+    "cal share": { tool: "cal_share", door: "PATCH /api/cal/calendars" },
+    "cal sync": { tool: "cal_sync", door: "POST /api/cal/calendars/[id]/sync" },
+    "cal detach": { tool: "cal_detach", door: "DELETE /api/cal/calendars" },
     "brief read": { tool: "brief_read", door: "GET /api/jarvis/brief" },
     "brief history": { tool: "brief_history", door: "GET /api/jarvis/brief?history=1" },
     "brief status": { tool: "brief_status", door: "GET /api/ops/brief-status" },
@@ -203,6 +212,7 @@ export const MCP_TWINS = {
 /** Verbs that can never have an MCP twin, and why. A claim, not a backlog. */
 export const TERMINAL_ONLY = {
     "mail add-imap": "carries a Google app password. The CLI reads it from STDIN precisely so it never lands in an argument list; an MCP tool argument travels through a model's context window and whatever transcript store sits behind it, so attaching a mailbox stays a thing a person does at a terminal (BLI-3708)",
+    "cal add-ical": "carries a calendar's SECRET iCal ADDRESS — a permanent, unauthenticated, read-anything-on-that-calendar URL. The CLI reads it from STDIN precisely so it never lands in an argument list; an MCP tool argument travels through a model's context window and whatever transcript store sits behind it, so attaching a calendar stays a thing a person does at a terminal (BLI-3709)",
     "brief edit": "opens the person's own $EDITOR on this machine and files what they changed; an agent has no editor to open (commands/editor.ts)",
 };
 /**

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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).",
+  "description": "bli-tower \u2014 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",
   "bin": {
     "bli-cockpit-mcp": "./dist/index.js"