@bli-cockpit/mcp 0.1.116 → 0.1.118

package/README.md

@@ -109,7 +109,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**169 of 174 Tower verbs have an MCP twin.**
+**171 of 176 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
@@ -176,6 +176,8 @@ three tables below.
 | `cockpit glossary add` | `glossary_add` | `POST /api/glossary` |
 | `cockpit glossary list` | `glossary_list` | `GET /api/glossary` |
 | `cockpit glossary remove` | `glossary_remove` | `POST /api/glossary` |
+| `cockpit image describe` | `image_describe` | `POST /api/ambient/images` |
+| `cockpit image show` | `image_show` | `GET /api/ambient/images` |
 | `cockpit issue board` | `work_board` | `GET /api/work/board` |
 | `cockpit issue comment` | `work_comment_issue` | `POST /api/work/issues/[id]/comments` |
 | `cockpit issue create` | `work_create_issue` | `POST /api/work/issues` |

package/dist/image-tools.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDeps } from "./tool-result.js";
+export declare function registerImageTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: ToolDeps): void;

package/dist/image-tools.js

@@ -0,0 +1,114 @@
+/**
+ * Image descriptions over MCP (BLI-16977): the two twins of `cockpit image describe|show`.
+ *
+ * Plain words: Tower swaps the base64 pictures inside collected transcripts for a short written
+ * description kept against the image's sha256. `image_describe` sends one image through that same
+ * door by hand; `image_show` looks a stored description up by the sha256 or the 16-character
+ * prefix a transcript marker carries. Both ride the ONE `/api/ambient/images` door (POST describes,
+ * GET reads) on this machine's device token, never a second route.
+ *
+ * `image_describe` takes an absolute `path` to a local image file OR `content_base64` (the bytes
+ * themselves). It refuses, by name, an image over the door's size limit and bytes that are not a
+ * PNG, JPEG, GIF or WebP (judged by their first bytes, never the name or a declared type), and it
+ * sends nothing in either case. A hosted server has no caller's disk, so `path` is refused there.
+ */
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { IMAGE_DESCRIBE_MAX_BYTES, IMAGE_MEDIA_TYPES, ImageHashQuerySchema, formatImageMarker, imageSizeLabel, sniffImageMediaType, } from "@bli-cockpit/telemetry-core";
+import { callAgentDoor } from "./agent-door.js";
+import { inRemoteAgentDoorScope } from "./agent-door-session.js";
+import { dataResult, doorFailureText, errorResult, queryString, registrarFor, withSession, } from "./tool-result.js";
+const DOOR_PATH = "/api/ambient/images";
+const refuse = (reason, sentence) => ({ ok: false, result: errorResult(`image_describe refused (${reason}): ${sentence} Nothing was sent.`) });
+async function pickBytes(args) {
+    const filePath = typeof args.path === "string" ? args.path : undefined;
+    const base64 = typeof args.content_base64 === "string" ? args.content_base64 : undefined;
+    if ((filePath === undefined) === (base64 === undefined))
+        return refuse("give_path_or_content", "Give exactly one of `path` (an absolute path to an image file) or `content_base64`.");
+    if (base64 !== undefined) {
+        const bytes = Buffer.from(base64, "base64");
+        if (bytes.length === 0)
+            return refuse("invalid_base64", "`content_base64` decoded to nothing.");
+        return { ok: true, bytes };
+    }
+    if (inRemoteAgentDoorScope())
+        return refuse("path_not_available_here", "This server is hosted and has no access to your files; send `content_base64` instead.");
+    if (!path.isAbsolute(filePath))
+        return refuse("path_not_absolute", "`path` must be an absolute path.");
+    try {
+        const info = await stat(filePath);
+        if (!info.isFile())
+            return refuse("not_a_file", "`path` is not a file.");
+        if (info.size > IMAGE_DESCRIBE_MAX_BYTES)
+            return refuse("image_too_large", `That image is ${imageSizeLabel(info.size)}; the describe door takes at most ${imageSizeLabel(IMAGE_DESCRIBE_MAX_BYTES)}.`);
+        return { ok: true, bytes: await readFile(filePath) };
+    }
+    catch {
+        return refuse("file_unreadable", "Could not read the file at `path`.");
+    }
+}
+export function registerImageTools(server, deps) {
+    const register = registrarFor(server);
+    register("image_describe", {
+        title: "Describe an image",
+        description: "Sends ONE image to Tower's describe door and returns its short written description, the way the collector does for every picture in a transcript. Give an absolute `path` to a local "
+            + "PNG, JPEG, GIF or WebP file (up to 3 MB), or `content_base64` with the bytes. An image Tower already described answers from storage (status known). The answer carries the description, "
+            + "the sha256 and the `marker` a transcript would hold in place of the picture. Refuses by name, without sending, an image that is too large or not an image. `cockpit image describe`, same door.",
+        inputSchema: {
+            path: z.string().min(1).max(4096).optional().describe("Absolute path to a local image file. Not available on a hosted server."),
+            content_base64: z.string().min(8).max(Math.ceil((IMAGE_DESCRIBE_MAX_BYTES * 4) / 3) + 16).optional().describe("The image bytes, base64. Use instead of `path`."),
+            media_type: z.enum(IMAGE_MEDIA_TYPES).optional().describe("With content_base64: the type you believe it is. Checked against the bytes; a mismatch is refused."),
+            session_id: z.string().min(1).max(200).optional().describe("The agent session the image came from, an id only."),
+        },
+    }, async (args) => {
+        const picked = await pickBytes(args);
+        if (!picked.ok)
+            return picked.result;
+        const bytes = picked.bytes;
+        if (bytes.length > IMAGE_DESCRIBE_MAX_BYTES)
+            return refuse("image_too_large", `That image is ${imageSizeLabel(bytes.length)}; the describe door takes at most ${imageSizeLabel(IMAGE_DESCRIBE_MAX_BYTES)}.`).result;
+        const mediaType = sniffImageMediaType(bytes);
+        if (!mediaType)
+            return refuse("not_an_image", "Those bytes are not a PNG, JPEG, GIF or WebP image (judged by their first bytes, not the name).").result;
+        if (typeof args.media_type === "string" && args.media_type !== mediaType)
+            return refuse("media_type_mismatch", `You said ${args.media_type} but the bytes are ${mediaType}.`).result;
+        const sha256 = createHash("sha256").update(bytes).digest("hex");
+        const request = {
+            schema_version: "image-describe.v1",
+            sha256,
+            media_type: mediaType,
+            byte_size: bytes.length,
+            content_base64: Buffer.from(bytes).toString("base64"),
+            source: "manual",
+            ...(typeof args.session_id === "string" ? { session_id: args.session_id } : {}),
+        };
+        const marker = formatImageMarker({ sha256, mediaType, byteSize: bytes.length });
+        return withSession(deps, async (session) => {
+            const response = await callAgentDoor(session, deps.fetchImpl, "POST", DOOR_PATH, request);
+            if (!response.ok)
+                return errorResult(doorFailureText("image_describe", response));
+            const description = response.body.description;
+            const said = response.body.status === "known" ? "Tower already had a description for this image." : "Described.";
+            return dataResult(`${said} ${typeof description?.description === "string" ? description.description : ""}`.trim(), { ...response.body, marker });
+        });
+    });
+    register("image_show", {
+        title: "Read an image description",
+        description: "Looks up the stored description of an image by its sha256, or by the first 12 to 64 characters of it (a transcript's `[image sha256:ab12cd34ef567890… png 412KB]` marker carries 16). "
+            + "Answers the descriptions found; an empty list means nothing is stored for that image yet. Read-only. `cockpit image show`, same door.",
+        inputSchema: {
+            sha256: ImageHashQuerySchema.describe("The image's sha256 or a prefix of it: 12 to 64 lowercase hex characters."),
+        },
+    }, async (args) => {
+        const query = new URLSearchParams({ sha256: String(args.sha256) });
+        return withSession(deps, async (session) => {
+            const response = await callAgentDoor(session, deps.fetchImpl, "GET", `${DOOR_PATH}${queryString(query)}`, undefined);
+            if (!response.ok)
+                return errorResult(doorFailureText("image_show", response));
+            const found = Array.isArray(response.body.descriptions) ? response.body.descriptions.length : 0;
+            return dataResult(found === 0 ? "No description stored for that image yet." : `${found} description(s) found.`, response.body);
+        });
+    });
+}

package/dist/memory-twins.d.ts

@@ -4,6 +4,8 @@
  * BLI Memory ships its own MCP server, so its store verbs are twinned against
  * tools on THAT server, over the same `/api/memory/*` doors the CLI verbs call.
  * Split out of `verb-census.ts` to keep that file under the readability band.
+ * The image door's two twins (BLI-16977) sit here for the same reason.
  */
 import type { McpTwin } from "./verb-census.js";
 export declare const MEMORY_STORE_TWINS: Record<string, McpTwin>;
+export declare const IMAGE_TWINS: Record<string, McpTwin>;

package/dist/memory-twins.js

@@ -4,6 +4,7 @@
  * BLI Memory ships its own MCP server, so its store verbs are twinned against
  * tools on THAT server, over the same `/api/memory/*` doors the CLI verbs call.
  * Split out of `verb-census.ts` to keep that file under the readability band.
+ * The image door's two twins (BLI-16977) sit here for the same reason.
  */
 export const MEMORY_STORE_TWINS = {
     "memory search": { tool: "search_memory", door: "POST /api/memory/search", server: "bli-memory" },
@@ -15,3 +16,7 @@ export const MEMORY_STORE_TWINS = {
     "memory private": { tool: "set_memory_visibility", door: "POST /api/memory/visibility", server: "bli-memory" },
     "memory public": { tool: "set_memory_visibility", door: "POST /api/memory/visibility", server: "bli-memory" },
 };
+export const IMAGE_TWINS = {
+    "image describe": { tool: "image_describe", door: "POST /api/ambient/images" },
+    "image show": { tool: "image_show", door: "GET /api/ambient/images" },
+};

package/dist/server.js

@@ -43,6 +43,7 @@ import { registerUsageTools } from "./usage-tools.js";
 import { registerLogsTools } from "./logs-tools.js";
 import { registerBrainTools } from "./brain-tools.js";
 import { registerApprovalsTools } from "./approvals-tools.js";
+import { registerImageTools } from "./image-tools.js";
 import { registerSourcesTools } from "./sources-tools.js";
 import { TOWER_SERVER_ICONS } from "./server-icons.js";
 import { installToolRegistration } from "./tool-registration.js";
@@ -525,5 +526,7 @@ export function createServer(deps, options = {}) {
     registerBrainTools(server, { fetchImpl: deps.fetchImpl });
     // BLI-16945: the approvals inbox, over the same /api/approvals doors the page and `cockpit approvals` call.
     registerApprovalsTools(server, { fetchImpl: deps.fetchImpl });
+    // BLI-16977: image descriptions, over the same /api/ambient/images door `cockpit image` calls.
+    registerImageTools(server, { fetchImpl: deps.fetchImpl });
     return server;
 }

package/dist/tool-catalog.d.ts

@@ -10,7 +10,7 @@
  * from `src/` under Node's type stripping, so it may import nothing.
  */
 /** Tools that change nothing. The smoke calls every one. */
-export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "docs_sync_status", "msg_channels", "msg_read", "msg_thread", "work_board", "work_list_issues", "work_get_issue", "work_issue_history", "work_list_projects", "careers_list", "careers_show", "careers_resume_url", "careers_takehome_show", "careers_settings_show", "rename_pending", "github_pr", "setup_read", "speed_read", "speed_seen", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "mail_sync_status", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "cal_sync_status", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "brief_missed", "notes_folders", "notes_list", "glossary_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "notes_recordings", "notes_recording", "notes_sync_status", "notes_granola_status", "notes_bot_upcoming", "ops_status", "slack_coverage", "slack_connect", "slack_disconnect", "slack_read", "memory_map", "memory_rules", "memory_knowledge", "memory_profile", "memory_consolidation", "memory_chain", "settings_show", "settings_list", "model_show", "team_members", "team_github_login_add", "team_github_login_remove", "team_github_login_list", "team_device_list", "scout_board", "workbook_read", "tower_search", "sources_check", "logs_digest", "brain_status", "approvals_list", "approvals_show", "approvals_rules"];
+export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "docs_sync_status", "msg_channels", "msg_read", "msg_thread", "work_board", "work_list_issues", "work_get_issue", "work_issue_history", "work_list_projects", "careers_list", "careers_show", "careers_resume_url", "careers_takehome_show", "careers_settings_show", "rename_pending", "github_pr", "setup_read", "speed_read", "speed_seen", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "mail_sync_status", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "cal_sync_status", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "brief_missed", "notes_folders", "notes_list", "glossary_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "notes_recordings", "notes_recording", "notes_sync_status", "notes_granola_status", "notes_bot_upcoming", "ops_status", "slack_coverage", "slack_connect", "slack_disconnect", "slack_read", "memory_map", "memory_rules", "memory_knowledge", "memory_profile", "memory_consolidation", "memory_chain", "settings_show", "settings_list", "model_show", "team_members", "team_github_login_add", "team_github_login_remove", "team_github_login_list", "team_device_list", "scout_board", "workbook_read", "tower_search", "sources_check", "logs_digest", "brain_status", "approvals_list", "approvals_show", "approvals_rules", "image_show"];
 /**
  * Tools that write, but answer a dry run that writes nothing. The smoke calls
  * each one ONLY with its dry-run flag set (`scripts/smoke.ts` says which).
@@ -21,7 +21,7 @@ export declare const DRY_RUN_TOOLS: readonly ["ops_recompile", "memory_requeue"]
  * candidates, share calendars. Never called by the smoke; covered by the unit
  * suites (`write-tools.test.ts` and each family's own).
  */
-export declare const WRITE_TOOLS: readonly ["approvals_create", "approvals_approve", "approvals_edit", "approvals_reject", "approvals_rules_create", "approvals_rules_revoke", "logs_key_mint", "brain_retry", "emit_event", "docs_create", "docs_update", "docs_delete", "docs_link", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_followup", "careers_interview", "careers_takehome_set", "careers_settings_set", "rename_resolve", "github_merge", "github_retitle", "github_rerun", "mail_send", "mail_draft", "mail_rename", "mail_enable", "mail_disable", "mail_default", "mail_remove", "cal_change", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "cal_delete", "jarvis_dispatch", "glossary_add", "glossary_remove", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_grant", "team_revoke", "team_device_revoke", "team_device_doctor"];
+export declare const WRITE_TOOLS: readonly ["image_describe", "approvals_create", "approvals_approve", "approvals_edit", "approvals_reject", "approvals_rules_create", "approvals_rules_revoke", "logs_key_mint", "brain_retry", "emit_event", "docs_create", "docs_update", "docs_delete", "docs_link", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_followup", "careers_interview", "careers_takehome_set", "careers_settings_set", "rename_resolve", "github_merge", "github_retitle", "github_rerun", "mail_send", "mail_draft", "mail_rename", "mail_enable", "mail_disable", "mail_default", "mail_remove", "cal_change", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "cal_delete", "jarvis_dispatch", "glossary_add", "glossary_remove", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_grant", "team_revoke", "team_device_revoke", "team_device_doctor"];
 /** Reads that spend a model turn. The smoke's `--no-model` leaves these out. */
 export declare const MODEL_SPENDING_TOOLS: readonly ["jarvis_ask", "jarvis_check"];
 /**

package/dist/tool-catalog.js

@@ -105,6 +105,8 @@ export const READ_TOOLS = [
     "approvals_list",
     "approvals_show",
     "approvals_rules",
+    // BLI-16977: a stored image description, by sha256. Reads only.
+    "image_show",
 ];
 /**
  * Tools that write, but answer a dry run that writes nothing. The smoke calls
@@ -117,6 +119,8 @@ export const DRY_RUN_TOOLS = ["ops_recompile", "memory_requeue"];
  * suites (`write-tools.test.ts` and each family's own).
  */
 export const WRITE_TOOLS = [
+    // BLI-16977: sends one image to the describe door (a vision-model call, stored against its sha256). Never smoked.
+    "image_describe",
     // BLI-16945: approve runs the guarded act; a rule sends without asking. Never smoked.
     "approvals_create",
     "approvals_approve",

package/dist/verb-census.js

@@ -29,7 +29,7 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { MEMORY_STORE_TWINS } from "./memory-twins.js";
+import { IMAGE_TWINS, MEMORY_STORE_TWINS } from "./memory-twins.js";
 const HERE = dirname(fileURLToPath(import.meta.url));
 export const COLLECTOR_COMMANDS_DIR = resolve(HERE, "../../cockpit-local-collector/src/commands");
 function read(file) {
@@ -350,8 +350,8 @@ export const MCP_TWINS = {
     "notes granola-status": { tool: "notes_granola_status", door: "GET /api/notes/granola-status" },
     "memory log": { tool: "memory_experience", door: "POST /api/memory/experience" },
     // BLI-4047, BLI-12927: the memory STORE at a terminal. Its twins live on the
-    // second server, `bli-memory` (see `memory-twins.ts`).
-    ...MEMORY_STORE_TWINS,
+    // second server, `bli-memory` (see `memory-twins.ts`, which also holds the image twins).
+    ...MEMORY_STORE_TWINS, ...IMAGE_TWINS,
     // BLI-4533: the compiled one-page profile. Its twin is on `bli-tower`, not
     // `bli-memory`: that server's four tools are the vendor-compatible set the
     // Claude Code plugin expects, and this page is ours.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.116",
+  "version": "0.1.118",
   "private": false,
   "description": "bli-tower: an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",
@@ -37,7 +37,7 @@
     "readme": "npm run build && node scripts/write-readme-census.mjs"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.70",
+    "@bli-cockpit/telemetry-core": "0.1.72",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6"
   },