@bike4mind/cli 3.4.0 → 4.0.0

package/dist/{serve-zi-B2iUT.mjs → serve-CFxUhjml.mjs}

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { B as CreateArtifactRequestSchema, D as AGENT_QUEST_MANIFEST, E as AGENT_QUEST_ID, Et as joinReplySlots, F as BriefcasePromptIdSchema, Ft as supportedVoiceGenerationVendor, G as GENERATED_IMAGE_EXTENSION_RE, K as ImageModels, Lt as ttsBase64ResponseSchema, M as ArtifactTypeSchema, N as BRIEFCASE_CATALOG_QUERIES, O as AGENT_QUEST_MCP_URI, Ot as questReplyText, Rt as ttsRequestSchema, V as DEFAULT_TTS_PROVIDER, _t as generatedAudioResponseSchema, b as logger, kt as replacePromptVariables, lt as VisibilitySchema, p as requireApiUrl, pt as buildPromptContext, q as ImagePromptResolutionSchema, t as ConfigStore, tt as PROMPT_TEXT_MAX, v as NotAuthenticatedError, y as parseApiUrl, zt as ttsResponseTooLargeSchema } from "./ConfigStore-CbVFLXMH.mjs";
-import { a as ApiClient, i as parseRetryAfterSeconds, o as isProviderKeyFailure, r as createClient, t as B4mApiError } from "./dist-DlBq3wHu.mjs";
+import { Bt as supportedVoiceGenerationVendor, D as AGENT_QUEST_MANIFEST, E as AGENT_QUEST_ID, F as BRIEFCASE_CATALOG_QUERIES, H as CreateArtifactRequestSchema, Ht as ttsBase64ResponseSchema, J as ImageModels, L as BriefcasePromptIdSchema, N as ArtifactTypeSchema, Nt as questReplyText, O as AGENT_QUEST_MCP_URI, Pt as replacePromptVariables, St as generatedAudioResponseSchema, U as DEFAULT_TTS_PROVIDER, Ut as ttsRequestSchema, Wt as ttsResponseTooLargeSchema, Y as ImagePromptResolutionSchema, _t as buildPromptContext, b as logger, j as ApiKeyScope, jt as joinReplySlots, p as requireApiUrl, pt as VisibilitySchema, q as GENERATED_IMAGE_EXTENSION_RE, rt as PROMPT_TEXT_MAX, t as ConfigStore, v as NotAuthenticatedError, y as parseApiUrl } from "./ConfigStore-BwqsQ0U9.mjs";
+import { n as isProviderKeyFailure, t as ApiClient } from "./ApiClient-_JrM_xWw.mjs";
+import { i as parseRetryAfterSeconds, r as createClient, t as B4mApiError } from "./dist-Ul2qwn5x.mjs";
 import { z as z$1 } from "zod";
 import { isAxiosError } from "axios";
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { Writable } from "node:stream";
 import { createServer } from "node:http";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -13,6 +14,82 @@ import { ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, McpError }
 //#region src/mcp/b4mApiClient.ts
 const NOTEBOOK_ID_PATTERN = /^[a-f0-9]{24}$/i;
 const STOP_REPLY_TIMEOUT_MS = 1e4;
+/** Only the route is known here: the solver roster and limits are fetched at runtime. */
+const SOLVER_ROUTE = "/api/premium-optihashi/quantum/solve";
+/**
+* The catalog and the key-scope lookup run before the stdio handshake completes, so they must not
+* inherit the client's 10-minute default: a hung backend would otherwise stall `initialize` for every
+* user, entitled or not.
+*/
+const SOLVER_CATALOG_TIMEOUT_MS = 5e3;
+/** Bob's routes. Bob is deployed apart from the host, so a server may not serve them. */
+const BOB_ROUTE = "/api/premium-bob";
+/**
+* One Bob run as `GET bob-run?id=&view=agent` answers it. Every field the tools read is required or
+* nullable here, so a server that ignores `view=agent` (and answers the app's own shape) fails the
+* parse rather than reading as a run with no report.
+*/
+const bobAgentRunSchema = z$1.looseObject({
+	runId: z$1.string(),
+	url: z$1.string(),
+	status: z$1.enum([
+		"reading",
+		"ok",
+		"failed"
+	]),
+	progress: z$1.object({
+		done: z$1.number(),
+		total: z$1.number()
+	}).nullish(),
+	createdAt: z$1.string(),
+	settledAt: z$1.string().nullish(),
+	error: z$1.string().nullish(),
+	scanOnly: z$1.string().nullish(),
+	reportMarkdown: z$1.string().nullish(),
+	appPath: z$1.string(),
+	publishedPath: z$1.string().nullish(),
+	visibility: z$1.string().nullish()
+});
+const bobAgentComparisonSchema = z$1.looseObject({
+	comparisonId: z$1.string(),
+	status: z$1.enum([
+		"reading",
+		"ok",
+		"failed"
+	]),
+	you: bobAgentRunSchema.nullable(),
+	them: bobAgentRunSchema.nullable(),
+	summaryMarkdown: z$1.string().nullish(),
+	appPath: z$1.string()
+});
+/**
+* One row of `GET bob-run?list=recent`: a single-site run or a two-site comparison (`you` and
+* `them` are the two URLs). A server that predates comparison rows sends runs with no `kind`.
+*/
+const bobRecentRowSchema = z$1.union([z$1.looseObject({
+	kind: z$1.literal("run").optional(),
+	runId: z$1.string(),
+	url: z$1.string(),
+	createdAt: z$1.string().nullish()
+}), z$1.looseObject({
+	kind: z$1.literal("comparison"),
+	comparisonId: z$1.string(),
+	you: z$1.string(),
+	them: z$1.string(),
+	createdAt: z$1.string().nullish()
+})]);
+const bobRecentListSchema = z$1.object({ runs: z$1.array(z$1.unknown()) });
+/** A start's 200 refusal: the daily cap or a credits refusal, in Bob's words. */
+const bobRefusalSchema = z$1.object({
+	ok: z$1.literal(false),
+	error: z$1.string()
+});
+const bobOrganizationField = (organizationId) => organizationId === void 0 ? {} : { organizationId };
+const keyScopeListSchema = z$1.array(z$1.object({
+	keyPrefix: z$1.string().optional(),
+	scopes: z$1.array(z$1.string()).optional(),
+	status: z$1.string().optional()
+}));
 /**
 * An empty or dot-segment id collapses `/api/sessions/{id}` to `/api/sessions`, whose DELETE wipes every
 * notebook the caller owns, so write paths refuse anything that is not an ObjectId before any request.
@@ -36,6 +113,7 @@ function writableNotebookId(notebookId) {
 var B4mApiClient = class {
 	constructor(baseURL, configStore, apiKey) {
 		this.baseURL = baseURL;
+		this.apiKey = apiKey;
 		this.client = new ApiClient(baseURL, configStore, apiKey);
 		this.sdk = createClient({
 			baseUrl: baseURL,
@@ -293,7 +371,99 @@ var B4mApiClient = class {
 	async getBriefcasePrompt(promptId) {
 		return (await this.client.get(`/api/briefcase/prompts/${encodeURIComponent(promptId)}`)).prompt;
 	}
+	/**
+	* Scopes held by the API key this client authenticates with, read from the caller's own key list by
+	* matching the key's stored prefix. Undefined for a login (JWT) caller, who has no scopes to check;
+	* an empty list when the key is not found or cannot be told apart from another, so a caller that cannot be
+	* identified is never treated as scoped. Stored prefixes differ in length (older keys keep a shorter one),
+	* and the list can include other keys, so the longest matching prefix wins and a tie at that length is refused.
+	*/
+	async getOwnKeyScopes() {
+		const apiKey = this.apiKey;
+		if (!apiKey) return void 0;
+		const matches = keyScopeListSchema.parse(await this.client.get("/api/user-api-keys", { timeout: SOLVER_CATALOG_TIMEOUT_MS })).filter((k) => k.status === "active" && !!k.keyPrefix && apiKey.startsWith(k.keyPrefix));
+		const longest = matches.reduce((length, key) => Math.max(length, key.keyPrefix?.length ?? 0), 0);
+		const best = matches.filter((k) => k.keyPrefix?.length === longest);
+		return best.length === 1 ? best[0].scopes ?? [] : [];
+	}
+	/** GET on the entitlement-gated solver route: the runnable rosters and limits for this caller. */
+	async getSolverCatalog() {
+		return this.client.get(SOLVER_ROUTE, { timeout: SOLVER_CATALOG_TIMEOUT_MS });
+	}
+	/** POST on the same route: run a bounded solver race. The body is validated server-side. */
+	async runSolverRace(body) {
+		return this.client.post(SOLVER_ROUTE, body);
+	}
+	/** POST bob-run: start one site read under a caller-minted run id. Throws Bob's words on a refusal. */
+	async startBobRun(args) {
+		const body = {
+			url: args.url,
+			runId: args.runId,
+			...bobOrganizationField(args.organizationId)
+		};
+		throwBobRefusal(await this.client.post(`${BOB_ROUTE}/bob-run`, body));
+	}
+	async getBobRun(runId) {
+		const result = await this.client.get(`${BOB_ROUTE}/bob-run`, { params: {
+			id: runId,
+			view: "agent"
+		} });
+		return this.parseBobView(z$1.object({ run: bobAgentRunSchema }), result, "run").run;
+	}
+	/** POST bob-compare: start a read of each site, linked as one comparison. Throws Bob's words on a refusal. */
+	async startBobComparison(args) {
+		const { organizationId, ...ids } = args;
+		const body = {
+			...ids,
+			...bobOrganizationField(organizationId)
+		};
+		throwBobRefusal(await this.client.post(`${BOB_ROUTE}/bob-compare`, body));
+	}
+	async getBobComparison(comparisonId) {
+		const result = await this.client.get(`${BOB_ROUTE}/bob-compare`, { params: {
+			id: comparisonId,
+			view: "agent"
+		} });
+		return this.parseBobView(z$1.object({ comparison: bobAgentComparisonSchema }), result, "comparison").comparison;
+	}
+	/** POST bob-recheck: re-run one check of a run against its site. Answers with the new reading. */
+	async recheckBob(args) {
+		const result = await this.client.post(`${BOB_ROUTE}/bob-recheck`, args);
+		throwBobRefusal(result);
+		return result.recheck;
+	}
+	/**
+	* GET bob-run?list=recent: the caller's finished runs and comparisons, newest first. The server caps
+	* `limit`. A row of a kind this CLI does not know is dropped, so a newer server cannot break the list.
+	*/
+	async listBobReports(limit) {
+		const result = await this.client.get(`${BOB_ROUTE}/bob-run`, { params: {
+			list: "recent",
+			...limit !== void 0 ? { limit } : {}
+		} });
+		return bobRecentListSchema.parse(result).runs.flatMap((row) => {
+			const parsed = bobRecentRowSchema.safeParse(row);
+			return parsed.success ? [parsed.data] : [];
+		});
+	}
+	/** GET bob-run?quota: runs left under the daily cap, for the account a start would bill. */
+	async getBobQuota(organizationId) {
+		return (await this.client.get(`${BOB_ROUTE}/bob-run`, { params: {
+			quota: "",
+			...organizationId === void 0 ? {} : { organizationId: organizationId ?? "" }
+		} })).quota ?? {};
+	}
+	parseBobView(schema, body, what) {
+		const parsed = schema.safeParse(body);
+		if (!parsed.success) throw new Error(`the Bike4Mind server at ${this.baseURL} answered the Bob ${what} without its agent view; it likely predates these tools`);
+		return parsed.data;
+	}
 };
+/** A 2xx `{ ok: false, error }` from Bob is a refusal (the daily cap, credits), not a transport error. */
+function throwBobRefusal(body) {
+	const refusal = bobRefusalSchema.safeParse(body);
+	if (refusal.success) throw new Error(refusal.data.error);
+}
 /**
 * Turn an API failure into an actionable, transport-agnostic message. `scope` is
 * the recommended API-key scope for the failing tool. A 403 can come from a
@@ -335,6 +505,20 @@ function mapApiError(error, baseURL, scope) {
 	return error instanceof Error ? error.message : String(error);
 }
 /**
+* {@link mapApiError} for Bob's routes, which do enforce their scopes. A scope 403 (Bob's own
+* `missing_scope`, or the host gate's `required_scopes`) names the scope to grant; a 429 or 503 that
+* carries `retryAfterMs` says how long to wait; a 404 with no error body means the server has no Bob.
+*/
+function mapBobApiError(error, baseURL, scope) {
+	const failure = httpFailure(error);
+	const message = extractServerMessage(failure?.data);
+	const body = failure?.data && typeof failure.data === "object" ? failure.data : {};
+	if (failure?.status === 403 && (body.code === "missing_scope" || Array.isArray(body.required_scopes))) return `${message ?? "API key forbidden"} (grant the key ${scope})`;
+	if ((failure?.status === 429 || failure?.status === 503) && typeof body.retryAfterMs === "number") return `${message ?? "Bob is busy"} (retry after ${Math.ceil(body.retryAfterMs / 1e3)}s)`;
+	if (failure?.status === 404 && !message) return `Bob is not available on the Bike4Mind server at ${baseURL}`;
+	return mapApiError(error, baseURL, scope);
+}
+/**
 * Status and body of an HTTP failure from either transport: a `B4mApiError` from the SDK calls or an
 * AxiosError from the axios ones (with no status when the request never got a response). Undefined for
 * anything else.
@@ -493,6 +677,48 @@ const TOOL_META = [
 		title: "Publish artifact",
 		description: "Publish an artifact you own to a shareable /p/... link and return its absolute URL. Republishing an artifact updates its existing page and keeps that page's visibility unless you pass one; a first publish defaults to public.",
 		scope: "files:write"
+	},
+	{
+		name: "bob_read_site",
+		title: "Read a site with Bob",
+		description: "Have Bob read a website: a panel of synthetic personas reads it and reports where visitors get lost. Spends the key owner's credits and publishes the report as them, as a run started in the app does. Waits for the report, reporting progress, and returns it as Markdown with links to the in-app and published reports; fails with Bob's reason when the read fails. If Bob is still reading when waitSeconds runs out, returns the runId to pass to get_bob_report later.",
+		scope: "bob:run"
+	},
+	{
+		name: "bob_compare_sites",
+		title: "Compare two sites with Bob",
+		description: "Have Bob read your site and another one side by side. Spends the key owner's credits for both reads and publishes each report as them. Waits for both, reporting progress, and returns the comparison summary as Markdown with each side's status and links, plus each side's full report when includeReports is true. If Bob is still reading when waitSeconds runs out, returns the comparisonId to pass to get_bob_comparison later.",
+		scope: "bob:run"
+	},
+	{
+		name: "bob_recheck",
+		title: "Re-check a Bob finding",
+		description: "Re-scan one check from a Bob report against the live site, e.g. after a fix, and return the new reading. Costs no credits and adds the reading to the existing report beside the original; no new report is published. checkId is the id the report shows in backticks beside the check. Re-checks are rate-limited, and a refusal says how long to wait.",
+		scope: "bob:run"
+	},
+	{
+		name: "get_bob_report",
+		title: "Get a Bob report",
+		description: "Fetch one Bob run by runId: its status (reading, ok or failed), its progress while reading, and once it is ok the report as Markdown with links to the in-app and published reports.",
+		scope: "bob:read"
+	},
+	{
+		name: "get_bob_comparison",
+		title: "Get a Bob comparison",
+		description: "Fetch one Bob comparison by comparisonId: its status, the summary as Markdown once both sides are read, and each side's status and links. Pass a side's runId to get_bob_report for its full report.",
+		scope: "bob:read"
+	},
+	{
+		name: "list_bob_reports",
+		title: "List Bob reports",
+		description: "List the key owner's recent finished Bob reports, newest first: single-site runs (kind 'run') and two-site comparisons (kind 'comparison'), each with its in-app link. Read a run with get_bob_report and its runId, and a comparison with get_bob_comparison and its comparisonId.",
+		scope: "bob:read"
+	},
+	{
+		name: "bob_runs_left",
+		title: "Bob runs left",
+		description: "How many Bob runs the key owner can start now under the daily limit, when the next one frees up, and whether the account's credits cover a full read. A comparison uses two runs.",
+		scope: "bob:read"
 	}
 ];
 TOOL_META.map((t) => t.name);
@@ -586,6 +812,32 @@ const textToSpeechShape = {
 	provider: ttsRequestSchema.shape.provider.describe(`Speech provider; defaults to ${DEFAULT_TTS_PROVIDER}`),
 	preview: ttsRequestSchema.shape.preview.describe("Skip saving a copy to the file browser")
 };
+const BOB_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const BOB_WAIT_DEFAULT_SECONDS = 600;
+const BOB_WAIT_MAX_SECONDS = 900;
+const bobId = (description) => z$1.string().regex(BOB_ID_PATTERN, "must be a UUID").describe(description);
+const bobOrganizationId = z$1.string().min(1).nullable().optional().describe("Organization whose credits pay for the run: an organization id, or null for the key owner's personal account; omit for their home organization");
+const bobWaitSeconds = z$1.number().int().min(0).max(BOB_WAIT_MAX_SECONDS).default(BOB_WAIT_DEFAULT_SECONDS).describe(`How long to wait for the result, in seconds (0-${BOB_WAIT_MAX_SECONDS}, default ${BOB_WAIT_DEFAULT_SECONDS}); a read takes about 1 to 5 minutes and Bob keeps reading after the wait ends`);
+const bobReadSiteShape = {
+	url: z$1.string().min(1).describe("The site to read, e.g. acme.io or acme.io/pricing"),
+	organizationId: bobOrganizationId,
+	waitSeconds: bobWaitSeconds
+};
+const bobCompareSitesShape = {
+	yourUrl: z$1.string().min(1).describe("Your site, e.g. acme.io"),
+	theirUrl: z$1.string().min(1).describe("The site to compare yours with"),
+	organizationId: bobOrganizationId,
+	waitSeconds: bobWaitSeconds,
+	includeReports: z$1.boolean().default(false).describe("Also return each side's full report as Markdown")
+};
+const bobRecheckShape = {
+	runId: bobId("The run the check belongs to"),
+	checkId: z$1.string().min(1).describe("The check id, as the report shows it in backticks beside the check")
+};
+const getBobReportShape = { runId: bobId("The run id") };
+const getBobComparisonShape = { comparisonId: bobId("The comparison id") };
+const listBobReportsShape = { limit: z$1.number().int().min(1).max(100).optional().describe("Maximum reports to return; the server caps the list") };
+const bobRunsLeftShape = { organizationId: bobOrganizationId.describe("Account whose credits to check: an organization id, or null for the key owner's personal account; omit for their home organization") };
 function notebookSummary(n) {
 	return {
 		id: n.id,
@@ -746,30 +998,38 @@ const isPermanentApiError = (err) => {
 	const status = apiErrorStatus(err);
 	return status === 401 || status === 403 || status === 404;
 };
-/** Poll a queued quest until `isFinished`, the timeout, a permanent poll failure, or an abort. */
-async function pollQuest(client, { questId, ref, task, scope, isFinished }, { interval, timeoutMs, sleep = defaultSleep, signal, onProgress, baseURL = "" }) {
+/** Poll `read` until `isFinished`, the timeout, a permanent poll failure, or an abort. */
+async function pollUntil({ read, ref, task, isFinished, describeError }, { interval, timeoutMs, sleep = defaultSleep, signal, onProgress }) {
 	const started = Date.now();
 	let failures = 0;
 	let retryAfterMs = 0;
+	let latest;
 	for (;;) {
 		signal?.throwIfAborted();
-		let quest;
+		let value;
 		try {
-			quest = await client.getQuest(questId);
+			value = await read();
+			latest = value;
 			failures = 0;
-			if (isFinished(quest)) return quest;
+			if (isFinished(value)) return {
+				finished: true,
+				value
+			};
 		} catch (err) {
 			if (isRateLimited(err)) retryAfterMs = (apiErrorRetryAfterSeconds(err) ?? 0) * 1e3;
 			else {
 				failures += 1;
-				if (isPermanentApiError(err) || failures >= MAX_CONSECUTIVE_POLL_FAILURES) throw new Error(`${mapApiError(err, baseURL, scope)} (${ref}; the ${task} may still complete)`);
+				if (isPermanentApiError(err) || failures >= MAX_CONSECUTIVE_POLL_FAILURES) throw new Error(`${describeError(err)} (${ref}; the ${task} may still complete)`);
 			}
 		}
 		const elapsed = Date.now() - started;
-		if (elapsed >= timeoutMs) throw new Error(`${task} did not finish within ${Math.round(timeoutMs / 1e3)}s (${ref})`);
+		if (elapsed >= timeoutMs) return {
+			finished: false,
+			latest
+		};
 		signal?.throwIfAborted();
 		try {
-			await onProgress?.(elapsed, quest);
+			await onProgress?.(elapsed, value);
 		} catch (err) {
 			logger.warn(`mcp: progress notification failed (${ref}): ${err instanceof Error ? err.message : String(err)}`);
 		}
@@ -778,6 +1038,18 @@ async function pollQuest(client, { questId, ref, task, scope, isFinished }, { in
 		retryAfterMs = 0;
 	}
 }
+/** Poll a queued quest until `isFinished`, the timeout, a permanent poll failure, or an abort. */
+async function pollQuest(client, { questId, ref, task, scope, isFinished }, { baseURL = "", ...timing }) {
+	const outcome = await pollUntil({
+		read: () => client.getQuest(questId),
+		ref,
+		task,
+		isFinished,
+		describeError: (err) => mapApiError(err, baseURL, scope)
+	}, timing);
+	if (!outcome.finished) throw new Error(`${task} did not finish within ${Math.round(timing.timeoutMs / 1e3)}s (${ref})`);
+	return outcome.value;
+}
 /**
 * Queue an image render and poll its quest to completion. A failed render still
 * resolves `status: 'done'`, so `type: 'error'` (reason in `reply`) is the failure signal.
@@ -1016,19 +1288,19 @@ async function textToSpeech(client, args) {
 	});
 }
 /**
-* Turn a quest poll's progress callback into MCP `notifications/progress`, or nothing when the
-* client sent no progressToken. Progress also lets a client that resets its request timeout on
-* progress wait out a slow quest.
+* Turn a poll's progress callback into MCP `notifications/progress`, or nothing when the client
+* sent no progressToken. Progress counts elapsed seconds, so it rises on every poll, and that lets a
+* client that resets its request timeout on progress wait out slow work.
 */
 function progressReporter({ _meta, sendNotification }, describe) {
 	const progressToken = _meta?.progressToken;
 	if (progressToken === void 0) return void 0;
-	return (elapsedMs, quest) => sendNotification({
+	return (elapsedMs, latest) => sendNotification({
 		method: "notifications/progress",
 		params: {
 			progressToken,
 			progress: Math.floor(elapsedMs / 1e3),
-			message: describe(quest)
+			message: describe(latest)
 		}
 	});
 }
@@ -1038,6 +1310,188 @@ function chatProgress(quest) {
 	return characters > 0 ? `generating reply (${characters} characters so far)` : "generating reply";
 }
 /**
+* Bob's own done/total count goes in the progress message, not in `progress`: a count can stay flat
+* for a while, and MCP needs `progress` to rise on every notification (see {@link progressReporter}).
+*/
+function bobProgressMessage(what, count) {
+	return count && count.total > 0 ? `${what} (${count.done} of ${count.total})` : what;
+}
+function bobComparisonCount(comparison) {
+	const counts = [comparison.you?.progress, comparison.them?.progress].filter((c) => !!c);
+	if (counts.length === 0) return null;
+	return counts.reduce((sum, c) => ({
+		done: sum.done + c.done,
+		total: sum.total + c.total
+	}));
+}
+/** send_message's cadence (fast for the first 30s, then slower), bounded by the caller's wait. */
+function bobPollTiming({ intervalMs = CHAT_POLL_INTERVAL_MS, ...poll }, waitSeconds) {
+	return {
+		...poll,
+		timeoutMs: waitSeconds * 1e3,
+		interval: (elapsedMs) => chatPollInterval(elapsedMs, intervalMs)
+	};
+}
+/** Bob's views carry app paths; a link is the API base URL plus one. */
+const bobLink = (baseURL, path) => path ? `${baseURL.replace(/\/+$/, "")}${path}` : null;
+function bobRunSummary(run, baseURL) {
+	return {
+		runId: run.runId,
+		url: run.url,
+		status: run.status,
+		progress: run.progress ?? null,
+		createdAt: run.createdAt,
+		settledAt: run.settledAt ?? null,
+		error: run.error ?? null,
+		scanOnly: run.scanOnly ?? null,
+		appUrl: bobLink(baseURL, run.appPath),
+		publishedUrl: bobLink(baseURL, run.publishedPath),
+		visibility: run.visibility ?? null
+	};
+}
+function bobComparisonSummary(comparison, baseURL) {
+	return {
+		comparisonId: comparison.comparisonId,
+		status: comparison.status,
+		you: comparison.you && bobRunSummary(comparison.you, baseURL),
+		them: comparison.them && bobRunSummary(comparison.them, baseURL),
+		appUrl: bobLink(baseURL, comparison.appPath)
+	};
+}
+/**
+* The summary as JSON (and as structuredContent), then each Markdown document as a text block of its
+* own. The documents stay out of structuredContent so a long report is not sent twice, as the audio
+* tools keep their bytes out.
+*/
+function bobResult(summary, documents) {
+	const result = toResult(summary);
+	for (const text of documents) if (text) result.content.push({
+		type: "text",
+		text
+	});
+	return result;
+}
+function bobComparisonResult(comparison, baseURL, includeReports) {
+	const reports = includeReports ? [comparison.you, comparison.them].map((side) => side?.reportMarkdown && `Report for ${side.url}:\n\n${side.reportMarkdown}`) : [];
+	return bobResult(bobComparisonSummary(comparison, baseURL), [comparison.summaryMarkdown, ...reports]);
+}
+const bobStillReading = (waitSeconds, readBack) => `Bob is still reading after ${waitSeconds}s and carries on without this call; use ${readBack} later.`;
+/**
+* Start a Bob read of one site and poll it until it settles or `waitSeconds` passes. A refusal or a
+* failed read throws, so the tool reports isError in Bob's words. A read still going at the deadline
+* is not an error: the result carries the runId to read it back with.
+*/
+async function bobReadSite(client, args, poll = {}) {
+	const runId = randomUUID();
+	await client.startBobRun({
+		url: args.url,
+		runId,
+		organizationId: args.organizationId
+	});
+	const ref = `run ${runId}`;
+	const outcome = await pollUntil({
+		read: () => client.getBobRun(runId),
+		ref,
+		task: "site read",
+		isFinished: (run) => run.status !== "reading",
+		describeError: (err) => mapBobApiError(err, client.baseURL, "bob:run")
+	}, bobPollTiming(poll, args.waitSeconds));
+	if (!outcome.finished) return toResult({
+		...outcome.latest ? bobRunSummary(outcome.latest, client.baseURL) : {
+			runId,
+			url: args.url,
+			status: "reading"
+		},
+		note: bobStillReading(args.waitSeconds, "get_bob_report with this runId")
+	});
+	const run = outcome.value;
+	if (run.status === "failed") throw new Error(`Bob could not read ${run.url}: ${run.error || "the read failed"} (${ref})`);
+	return bobResult(bobRunSummary(run, client.baseURL), [run.reportMarkdown]);
+}
+/** {@link bobReadSite} for two sites started as one comparison; fails only when neither side could be read. */
+async function bobCompareSites(client, args, poll = {}) {
+	const comparisonId = randomUUID();
+	const you = {
+		url: args.yourUrl,
+		runId: randomUUID()
+	};
+	const them = {
+		url: args.theirUrl,
+		runId: randomUUID()
+	};
+	await client.startBobComparison({
+		comparisonId,
+		you,
+		them,
+		organizationId: args.organizationId
+	});
+	const ref = `comparison ${comparisonId}`;
+	const outcome = await pollUntil({
+		read: () => client.getBobComparison(comparisonId),
+		ref,
+		task: "comparison",
+		isFinished: (comparison) => comparison.status !== "reading",
+		describeError: (err) => mapBobApiError(err, client.baseURL, "bob:run")
+	}, bobPollTiming(poll, args.waitSeconds));
+	if (!outcome.finished) return toResult({
+		...outcome.latest ? bobComparisonSummary(outcome.latest, client.baseURL) : {
+			comparisonId,
+			status: "reading",
+			you,
+			them
+		},
+		note: bobStillReading(args.waitSeconds, "get_bob_comparison with this comparisonId")
+	});
+	const comparison = outcome.value;
+	if (comparison.status === "failed") {
+		const reasons = [comparison.you, comparison.them].map((side) => side ? `${side.url}: ${side.error || "the read failed"}` : "one side has no run").join("; ");
+		throw new Error(`Bob could not read either site: ${reasons} (${ref})`);
+	}
+	return bobComparisonResult(comparison, client.baseURL, args.includeReports === true);
+}
+async function bobRecheck(client, args) {
+	return toResult({
+		runId: args.runId,
+		recheck: await client.recheckBob(args)
+	});
+}
+async function getBobReport(client, args) {
+	const run = await client.getBobRun(args.runId);
+	return bobResult(bobRunSummary(run, client.baseURL), [run.reportMarkdown]);
+}
+async function getBobComparison(client, args) {
+	return bobComparisonResult(await client.getBobComparison(args.comparisonId), client.baseURL, false);
+}
+/** A recent-list row in compact form, with the in-app link its kind opens at. */
+function bobReportRow(row, baseURL) {
+	if (row.kind === "comparison") {
+		const { comparisonId, you, them } = row;
+		const appUrl = bobLink(baseURL, `/bob?compare=${encodeURIComponent(comparisonId)}`);
+		return {
+			kind: "comparison",
+			comparisonId,
+			you,
+			them,
+			createdAt: row.createdAt ?? null,
+			appUrl
+		};
+	}
+	const appUrl = bobLink(baseURL, `/bob?run=${encodeURIComponent(row.runId)}`);
+	return {
+		kind: "run",
+		runId: row.runId,
+		url: row.url,
+		createdAt: row.createdAt ?? null,
+		appUrl
+	};
+}
+async function listBobReports(client, args) {
+	return toResult({ reports: (await client.listBobReports(args.limit)).map((row) => bobReportRow(row, client.baseURL)) });
+}
+async function bobRunsLeft(client, args) {
+	return toResult(await client.getBobQuota(args.organizationId));
+}
+/**
 * Register the Bike4Mind MCP tools on `server`. Each handler is wrapped so an
 * API failure becomes a structured `isError` result carrying a friendly message
 * (see {@link mapApiError}) rather than throwing across the transport.
@@ -1167,6 +1621,135 @@ function registerTools(server, client) {
 		description: meta("publish_artifact").description,
 		inputSchema: publishArtifactShape
 	}, (args) => run("files:write", () => publishArtifact(client, args)));
+	const runBob = async (scope, fn) => {
+		try {
+			return await fn();
+		} catch (err) {
+			return errorResult(mapBobApiError(err, baseURL, scope));
+		}
+	};
+	server.registerTool("bob_read_site", {
+		title: meta("bob_read_site").title,
+		description: meta("bob_read_site").description,
+		inputSchema: bobReadSiteShape
+	}, (args, extra) => runBob("bob:run", () => bobReadSite(client, args, {
+		signal: extra.signal,
+		onProgress: progressReporter(extra, (run) => bobProgressMessage(`reading ${args.url}`, run?.progress))
+	})));
+	server.registerTool("bob_compare_sites", {
+		title: meta("bob_compare_sites").title,
+		description: meta("bob_compare_sites").description,
+		inputSchema: bobCompareSitesShape
+	}, (args, extra) => runBob("bob:run", () => bobCompareSites(client, args, {
+		signal: extra.signal,
+		onProgress: progressReporter(extra, (comparison) => bobProgressMessage("reading both sites", comparison && bobComparisonCount(comparison)))
+	})));
+	server.registerTool("bob_recheck", {
+		title: meta("bob_recheck").title,
+		description: meta("bob_recheck").description,
+		inputSchema: bobRecheckShape
+	}, (args) => runBob("bob:run", () => bobRecheck(client, args)));
+	server.registerTool("get_bob_report", {
+		title: meta("get_bob_report").title,
+		description: meta("get_bob_report").description,
+		inputSchema: getBobReportShape
+	}, (args) => runBob("bob:read", () => getBobReport(client, args)));
+	server.registerTool("get_bob_comparison", {
+		title: meta("get_bob_comparison").title,
+		description: meta("get_bob_comparison").description,
+		inputSchema: getBobComparisonShape
+	}, (args) => runBob("bob:read", () => getBobComparison(client, args)));
+	server.registerTool("list_bob_reports", {
+		title: meta("list_bob_reports").title,
+		description: meta("list_bob_reports").description,
+		inputSchema: listBobReportsShape
+	}, (args) => runBob("bob:read", () => listBobReports(client, args)));
+	server.registerTool("bob_runs_left", {
+		title: meta("bob_runs_left").title,
+		description: meta("bob_runs_left").description,
+		inputSchema: bobRunsLeftShape
+	}, (args) => runBob("bob:read", () => bobRunsLeft(client, args)));
+}
+//#endregion
+//#region src/mcp/solverTools.ts
+/** Both scopes the tools need; named in a 403 so callers know what to grant. */
+const REQUIRED_SCOPES = [ApiKeyScope.OPTIHASHI_READ, ApiKeyScope.OPTIHASHI_COMPUTE];
+const SOLVER_SCOPES = REQUIRED_SCOPES.join(" and ");
+const SOLVER_DISCOVERY_TIMEOUT_MS = 5e3;
+/**
+* The route's GET answer, trusted only as far as the tool schemas need. Everything beyond these
+* fields passes through to the agent untouched, so a roster or limit the server adds later needs
+* no CLI release.
+*/
+const catalogSchema = z$1.looseObject({
+	family: z$1.looseObject({
+		familyIds: z$1.array(z$1.string()),
+		solverIds: z$1.array(z$1.string())
+	}),
+	scheduling: z$1.looseObject({ solverIds: z$1.array(z$1.string()) }),
+	defaultSolverIds: z$1.array(z$1.string()),
+	limits: z$1.looseObject({
+		maxSolversPerRequest: z$1.number().int().positive(),
+		defaultTimeoutMs: z$1.number().int().positive(),
+		maxTimeoutMs: z$1.number().int().positive()
+	})
+});
+const oneOf = (ids) => ids.length > 0 ? [ids[0], ...ids.slice(1)] : void 0;
+function solveInputShape(catalog) {
+	const solverIds = oneOf([.../* @__PURE__ */ new Set([...catalog.family.solverIds, ...catalog.scheduling.solverIds])]);
+	const familyIds = oneOf(catalog.family.familyIds);
+	const { limits } = catalog;
+	return {
+		familyId: (familyIds ? z$1.enum(familyIds) : z$1.string()).optional().describe("Problem family. Omit for a scheduling brief; the problem must then be a scheduling problem."),
+		problem: z$1.record(z$1.string(), z$1.unknown()).describe("The problem instance. The server validates it and names what is wrong on a 400."),
+		solverIds: z$1.array(solverIds ? z$1.enum(solverIds) : z$1.string()).min(1).max(limits.maxSolversPerRequest).optional().describe(`Solvers to race. Defaults to ${catalog.defaultSolverIds.join(", ")}.`),
+		timeoutMs: z$1.number().int().min(100).max(limits.maxTimeoutMs).optional().describe(`Per-solver time budget in ms (default ${limits.defaultTimeoutMs}).`),
+		includeTrace: z$1.boolean().optional().describe("Include a truncated convergence trace per solver.")
+	};
+}
+/**
+* Register the solver tools an entitled caller may use, built from what the server reports at
+* startup. Stdio only: the HTTP transport has no per-request auth, so it never calls this.
+*
+* Offering nothing is the normal outcome for a caller without the feature, the scopes or the
+* entitlement (the route answers 403/404), so any failure here leaves the server's other tools
+* untouched instead of failing the session. Only the free classical race is exposed; no tool here
+* commissions paid compute.
+*/
+async function registerSolverTools(server, client) {
+	let catalog;
+	let discoveryTimer;
+	try {
+		const [rawCatalog, scopes] = await Promise.race([Promise.all([client.getSolverCatalog(), client.getOwnKeyScopes()]), new Promise((_resolve, reject) => {
+			discoveryTimer = setTimeout(() => reject(/* @__PURE__ */ new Error("solver discovery timed out")), SOLVER_DISCOVERY_TIMEOUT_MS);
+		})]);
+		if (scopes && !REQUIRED_SCOPES.every((scope) => scopes.includes(scope))) {
+			logger.debug(`mcp: solver tools not offered: key lacks ${SOLVER_SCOPES}`);
+			return;
+		}
+		catalog = catalogSchema.parse(rawCatalog);
+	} catch (err) {
+		logger.debug(`mcp: solver tools not offered: ${mapApiError(err, client.baseURL, SOLVER_SCOPES)}`);
+		return;
+	} finally {
+		clearTimeout(discoveryTimer);
+	}
+	const run = async (fn) => {
+		try {
+			return toResult(await fn());
+		} catch (err) {
+			return errorResult(mapApiError(err, client.baseURL, SOLVER_SCOPES));
+		}
+	};
+	server.registerTool("optihashi_solvers", {
+		title: "List OptiHashi solvers",
+		description: "List the problem families, solvers, default race and limits available to the caller. Call before optihashi_solve."
+	}, () => run(async () => catalogSchema.parse(await client.getSolverCatalog())));
+	server.registerTool("optihashi_solve", {
+		title: "Solve with OptiHashi",
+		description: "Race classical solvers on an optimization problem and return the ranked results and the winner. Bounded and synchronous; no credits are spent.",
+		inputSchema: solveInputShape(catalog)
+	}, (args) => run(() => client.runSolverRace(args)));
 }
 //#endregion
 //#region src/mcp/resources.ts
@@ -1408,8 +1991,7 @@ function registerPrompts(server, client, now = () => /* @__PURE__ */ new Date())
 * network - only tool/resource *calls* and prompt listing/gets hit the API - so a
 * server built with an unreachable endpoint still advertises its full capability set.
 */
-function buildMcpServer(options) {
-	const client = new B4mApiClient(options.baseURL, options.configStore, options.apiKey);
+function buildMcpServer(options, client = new B4mApiClient(options.baseURL, options.configStore, options.apiKey)) {
 	const server = new McpServer({
 		name: "bike4mind",
 		version: options.version
@@ -1423,6 +2005,17 @@ function buildMcpServer(options) {
 	registerPrompts(server, client);
 	return server;
 }
+/**
+* {@link buildMcpServer} plus the tools only an authenticated, entitled caller gets, which the server
+* reports at startup. Stdio only: the HTTP transport trusts anything that can reach its socket, so
+* it uses the plain builder and never offers these.
+*/
+async function buildStdioMcpServer(options) {
+	const client = new B4mApiClient(options.baseURL, options.configStore, options.apiKey);
+	const server = buildMcpServer(options, client);
+	await registerSolverTools(server, client);
+	return server;
+}
 //#endregion
 //#region src/mcp/serve.ts
 /**
@@ -1437,10 +2030,9 @@ function buildMcpServer(options) {
 * NOTHING else, so all diagnostics are forced to stderr before ANY other work
 * runs (mirrors the acp command's captureStdout - see src/commands/acpCommand.ts).
 *
-* HTTP mode is deliberately loopback-only (binds 127.0.0.1) with no per-request
-* auth of its own - it trusts anything that can reach the socket, so it must not
-* be exposed on a routable interface. DNS-rebinding protection is on as defense
-* in depth against a browser being tricked into posting to the local port.
+* HTTP mode binds loopback only (127.0.0.1) and requires `Authorization: Bearer
+* <token>` on every request. Token precedence is `--token` > `B4M_MCP_TOKEN` >
+* one generated at startup. DNS-rebinding protection (Host/Origin checks) stays on.
 */
 const HTTP_PATH = "/mcp";
 /**
@@ -1470,7 +2062,7 @@ function resolveBaseURL(options, configStore) {
 	return configStore.getApiConfig().then((apiConfig) => requireApiUrl(apiConfig));
 }
 async function serveStdio(buildOptions, writeFrame) {
-	const server = buildMcpServer(buildOptions);
+	const server = await buildStdioMcpServer(buildOptions);
 	const stdout = new Writable({ write(chunk, _encoding, callback) {
 		if (writeFrame(chunk)) {
 			callback();
@@ -1485,6 +2077,30 @@ async function serveStdio(buildOptions, writeFrame) {
 		process.stdin.once("close", resolve);
 	});
 }
+function resolveHttpToken(flag, env) {
+	if (flag) return {
+		token: flag,
+		source: "flag"
+	};
+	if (env) return {
+		token: env,
+		source: "env"
+	};
+	return {
+		token: randomBytes(32).toString("base64url"),
+		source: "generated"
+	};
+}
+function isAuthorized(header, token) {
+	const match = /^Bearer (.+)$/i.exec(header ?? "");
+	if (!match) return false;
+	const given = Buffer.from(match[1]);
+	const expected = Buffer.from(token);
+	return given.length === expected.length && timingSafeEqual(given, expected);
+}
+function maskToken(token) {
+	return token.length > 8 ? `${token.slice(0, 4)}...` : "****";
+}
 async function handleHttpRequest(req, res, buildOptions, port) {
 	const server = buildMcpServer(buildOptions);
 	const transport = new StreamableHTTPServerTransport({
@@ -1506,13 +2122,21 @@ async function handleHttpRequest(req, res, buildOptions, port) {
 	await server.connect(transport);
 	await transport.handleRequest(req, res);
 }
-async function serveHttp(buildOptions, port) {
-	const httpServer = createServer((req, res) => {
+function createHttpHandler(buildOptions, port, token) {
+	return (req, res) => {
 		if (new URL(req.url ?? "/", `http://localhost:${port}`).pathname !== HTTP_PATH) {
 			res.writeHead(404, { "Content-Type": "application/json" });
 			res.end(JSON.stringify({ error: `Not found. The MCP endpoint is ${HTTP_PATH}.` }));
 			return;
 		}
+		if (!isAuthorized(req.headers.authorization, token)) {
+			res.writeHead(401, {
+				"Content-Type": "application/json",
+				"WWW-Authenticate": "Bearer"
+			});
+			res.end(JSON.stringify({ error: "Unauthorized. Send an Authorization: Bearer <token> header." }));
+			return;
+		}
 		handleHttpRequest(req, res, buildOptions, port).catch((err) => {
 			logger.error("MCP HTTP request failed", err);
 			if (!res.headersSent) {
@@ -1527,12 +2151,18 @@ async function serveHttp(buildOptions, port) {
 				}));
 			}
 		});
-	});
+	};
+}
+async function serveHttp(buildOptions, port, resolved) {
+	const httpServer = createServer(createHttpHandler(buildOptions, port, resolved.token));
 	await new Promise((resolve, reject) => {
 		httpServer.once("error", reject);
 		httpServer.listen(port, "127.0.0.1", () => resolve());
 	});
 	process.stderr.write(`Bike4Mind MCP server listening on http://127.0.0.1:${port}${HTTP_PATH}\n`);
+	const shown = resolved.source === "generated" ? resolved.token : maskToken(resolved.token);
+	process.stderr.write(`Authorization: Bearer ${shown}\n`);
+	process.stderr.write("Set a fixed token with --token or B4M_MCP_TOKEN.\n");
 	await new Promise((resolve) => {
 		const shutdown = () => httpServer.close(() => resolve());
 		process.once("SIGINT", shutdown);
@@ -1549,7 +2179,7 @@ async function handleMcpServeCommand(options) {
 		version: options.version
 	};
 	if (writeFrame) await serveStdio(buildOptions, writeFrame);
-	else await serveHttp(buildOptions, options.port ?? 7e3);
+	else await serveHttp(buildOptions, options.port ?? 7e3, resolveHttpToken(options.token, process.env.B4M_MCP_TOKEN));
 }
 //#endregion
 export { handleMcpServeCommand };