@bike4mind/cli 2.1.0 → 3.1.0

package/dist/{serve-DM7ld3-o.mjs → serve-CAfCQose.mjs}

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { Ct as ttsResponseTooLargeSchema, D as BriefcasePromptIdSchema, F as ImagePromptResolutionSchema, N as GENERATED_IMAGE_EXTENSION_RE, P as ImageModels, St as ttsRequestSchema, T as BRIEFCASE_CATALOG_QUERIES, U as PROMPT_TEXT_MAX, Z as buildPromptContext, _ as requireApiUrl, b as AGENT_QUEST_MANIFEST, ft as questReplyText, g as parseApiUrl, j as DEFAULT_TTS_PROVIDER, n as logger, pt as replacePromptVariables, t as ConfigStore, tt as generatedAudioResponseSchema, ut as joinReplySlots, x as AGENT_QUEST_MCP_URI, xt as ttsBase64ResponseSchema, y as AGENT_QUEST_ID, yt as supportedVoiceGenerationVendor } from "./ConfigStore-BygzEI6H.mjs";
-import { n as NotAuthenticatedError, r as isProviderKeyFailure, t as ApiClient } from "./ApiClient-dIB3YQc2.mjs";
+import { A as BRIEFCASE_CATALOG_QUERIES, B as GENERATED_IMAGE_EXTENSION_RE, C as AGENT_QUEST_ID, Ct as replacePromptVariables, H as ImagePromptResolutionSchema, L as CreateArtifactRequestSchema, M as BriefcasePromptIdSchema, Mt as ttsRequestSchema, Nt as ttsResponseTooLargeSchema, R as DEFAULT_TTS_PROVIDER, St as questReplyText, T as AGENT_QUEST_MCP_URI, V as ImageModels, X as PROMPT_TEXT_MAX, _ as logger, bt as joinReplySlots, dt as generatedAudioResponseSchema, g as parseApiUrl, h as NotAuthenticatedError, jt as ttsBase64ResponseSchema, k as ArtifactTypeSchema, kt as supportedVoiceGenerationVendor, rt as VisibilitySchema, st as buildPromptContext, t as ConfigStore, u as requireApiUrl, w as AGENT_QUEST_MANIFEST } from "./ConfigStore-RHqyXcSS.mjs";
+import { a as ApiClient, i as parseRetryAfterSeconds, o as isProviderKeyFailure, r as createClient, t as B4mApiError } from "./dist-B1bGf-yn.mjs";
 import { z as z$1 } from "zod";
 import { isAxiosError } from "axios";
+import { createHash, randomUUID } from "node:crypto";
 import { Writable } from "node:stream";
 import { createServer } from "node:http";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -11,24 +12,35 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
 //#region src/mcp/b4mApiClient.ts
 const NOTEBOOK_ID_PATTERN = /^[a-f0-9]{24}$/i;
+const STOP_REPLY_TIMEOUT_MS = 1e4;
 /**
 * 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.
 */
-function notebookPath(notebookId) {
+function writableNotebookId(notebookId) {
 	if (!NOTEBOOK_ID_PATTERN.test(notebookId)) throw new Error(`Invalid notebook id: ${JSON.stringify(notebookId)}`);
-	return `/api/sessions/${notebookId}`;
+	return notebookId;
 }
 /**
 * Typed wrapper over {@link ApiClient} exposing exactly the Bike4Mind REST
 * endpoints the MCP tools call. All routes are `baseApi()` routes that accept
 * either an OAuth JWT or an instance API key, so a caller supplies whichever it
 * has via the underlying ApiClient.
+*
+* Operations with a public contract go through `@bike4mind/sdk` (`this.sdk`), whose fetch is the
+* ApiClient's, so auth and refresh are shared. The axios `this.client` calls are routes with no public
+* contract, plus four that do have one but whose v1 shape would change the MCP output: the session and
+* project lists (v1 pages by cursor, the tools by page number) and getFile/getProject (the tools return the
+* whole document; v1 is a narrower snake_case resource).
 */
 var B4mApiClient = class {
 	constructor(baseURL, configStore, apiKey) {
 		this.baseURL = baseURL;
 		this.client = new ApiClient(baseURL, configStore, apiKey);
+		this.sdk = createClient({
+			baseUrl: baseURL,
+			fetch: this.client.fetch
+		});
 	}
 	toList(result) {
 		if (Array.isArray(result)) return {
@@ -51,31 +63,37 @@ var B4mApiClient = class {
 		return this.toList(result);
 	}
 	async getNotebook(notebookId) {
-		return this.client.get(`/api/sessions/${encodeURIComponent(notebookId)}`);
+		return this.sdk.call("getSession", { params: { id: notebookId } });
 	}
 	async createNotebook(args) {
-		return this.client.post("/api/sessions/create", {
-			...args.name ? { name: args.name } : {},
+		return this.sdk.call("createSession", { body: {
+			name: args.name,
 			...args.projectId ? { projectId: args.projectId } : {},
 			...args.dataLakeId ? { dataLakeId: args.dataLakeId } : {}
-		});
+		} });
 	}
 	async renameNotebook(notebookId, name) {
-		return this.client.put(notebookPath(notebookId), { name });
+		return this.sdk.call("updateSession", {
+			params: { id: writableNotebookId(notebookId) },
+			body: { name }
+		});
 	}
 	/** Returns the new (cloned) notebook. */
 	async cloneNotebook(notebookId) {
-		return this.client.post(`${notebookPath(notebookId)}/clone`, {});
+		return this.sdk.call("cloneSession", {
+			params: { id: writableNotebookId(notebookId) },
+			body: {}
+		});
 	}
 	async deleteNotebook(notebookId) {
-		return this.client.delete(notebookPath(notebookId), { maxRedirects: 0 });
+		return this.sdk.call("deleteSession", {
+			params: { id: writableNotebookId(notebookId) },
+			redirect: "manual"
+		});
 	}
-	/**
-	* GET /api/v1/data-lakes is cursor-paginated (flat `limit`/`cursor` params,
-	* `{ data, next_cursor }` body), so `toList` does not apply.
-	*/
+	/** GET /api/v1/data-lakes is cursor-paginated (`{ data, next_cursor }` body), so `toList` does not apply. */
 	async listDataLakes(args) {
-		const result = await this.client.get("/api/v1/data-lakes", { params: {
+		const result = await this.sdk.call("listDataLakes", { query: {
 			limit: args.limit,
 			...args.cursor ? { cursor: args.cursor } : {}
 		} });
@@ -85,16 +103,21 @@ var B4mApiClient = class {
 		};
 	}
 	async sendChat(args) {
-		return this.client.post("/api/chat", {
+		const body = {
 			...args.notebookId ? { sessionId: args.notebookId } : { newConversation: true },
 			message: args.message,
 			...args.model ? { model: args.model } : {},
 			...args.systemPrompt ? { systemPrompt: args.systemPrompt } : {},
 			wait: false
-		});
+		};
+		return this.sdk.call("sendChatMessage", { body });
 	}
 	async getQuest(questId) {
-		return this.client.get(`/api/quests/${encodeURIComponent(questId)}`);
+		return await this.sdk.call("getQuest", { params: { id: questId } });
+	}
+	/** Stop one generating turn. A server that predates `questId` stops the notebook's latest turn. */
+	async stopReply(notebookId, questId) {
+		return this.client.post(`/api/sessions/${writableNotebookId(notebookId)}/chat/stop-reply`, { questId }, { timeout: STOP_REPLY_TIMEOUT_MS });
 	}
 	async searchKnowledgeBase(args) {
 		return (await this.client.post("/api/sessions/semantic-search", {
@@ -116,81 +139,44 @@ var B4mApiClient = class {
 	async getFile(fileId) {
 		return this.client.get(`/api/files/${encodeURIComponent(fileId)}`);
 	}
-	/** Generate a sound effect; see {@link postGeneratedAudio} for the normalized response. */
+	/** Generate a sound effect. The SDK requests base64 and rebuilds an old server's raw-bytes answer. */
 	async generateSoundEffect(args) {
-		return this.postGeneratedAudio("/api/ai/sound-effects", {
+		const body = {
 			provider: args.provider,
 			text: args.text,
 			...args.durationSeconds !== void 0 ? { durationSeconds: args.durationSeconds } : {},
 			...args.promptInfluence !== void 0 ? { promptInfluence: args.promptInfluence } : {},
 			...args.format ? { format: args.format } : {}
-		}, generatedAudioResponseSchema);
+		};
+		return generatedAudioResponseSchema.parse(await this.sdk.soundEffects(body));
 	}
 	async synthesizeSpeech(args) {
-		try {
-			return {
-				kind: "audio",
-				data: await this.postGeneratedAudio("/api/ai/tts", args, ttsBase64ResponseSchema)
-			};
-		} catch (error) {
-			if (isAxiosError(error) && error.response?.status === 413) {
-				const oversized = ttsResponseTooLargeSchema.safeParse(error.response.data);
-				if (oversized.success && oversized.data.saved && oversized.data.fabFileId) {
-					const fallbackFrom = supportedVoiceGenerationVendor.safeParse(error.response.headers?.["x-b4m-tts-provider-fallback-from"]);
-					return {
-						kind: "saved-too-large",
-						data: {
-							...oversized.data,
-							fabFileId: oversized.data.fabFileId
-						},
-						...fallbackFrom.success ? { fallbackFrom: fallbackFrom.data } : {}
-					};
-				}
-			}
-			throw error;
-		}
+		const result = await this.sdk.tts(args);
+		if (result.kind === "audio") return {
+			kind: "audio",
+			data: ttsBase64ResponseSchema.parse(result.data)
+		};
+		const oversized = ttsResponseTooLargeSchema.parse(result.data);
+		const fallbackFrom = supportedVoiceGenerationVendor.safeParse(result.fallbackFrom);
+		return {
+			kind: "saved-too-large",
+			data: {
+				...oversized,
+				fabFileId: result.data.fabFileId
+			},
+			...fallbackFrom.success ? { fallbackFrom: fallbackFrom.data } : {}
+		};
 	}
 	async generateImage(args) {
-		return this.client.post("/api/ai/generate-image", {
+		const body = {
 			prompt: args.prompt,
 			model: args.model,
 			...args.size ? { size: args.size } : {},
 			...args.notebookId ? { sessionId: args.notebookId } : {},
 			...args.projectId ? { projectId: args.projectId } : {},
 			...args.promptResolution ? { prompt_resolution: args.promptResolution } : {}
-		});
-	}
-	/**
-	* POST a generated-audio request with `encoding: 'base64'` and normalize any
-	* server's answer into the JSON shape `schema` describes. Base64 (never binary)
-	* because an oversized result is a 303 in binary mode, and axios drops the
-	* X-B4M headers when following it. A server predating the `encoding` field
-	* ignores it and streams raw bytes with the save result in X-B4M-Audio-* headers;
-	* those are rebuilt into the inline variant. The request is arraybuffer-typed, so
-	* a failure body arrives as bytes; {@link decodeArrayBufferErrorBody} restores
-	* its JSON shape for {@link mapApiError}.
-	*/
-	async postGeneratedAudio(path, body, schema) {
-		const response = await this.client.getAxiosInstance().post(path, {
-			...body,
-			encoding: "base64"
-		}, { responseType: "arraybuffer" }).catch((error) => {
-			throw decodeArrayBufferErrorBody(error);
-		});
-		const contentType = String(response.headers["content-type"] ?? "application/octet-stream");
-		const bytes = Buffer.from(response.data);
-		if (/json/i.test(contentType)) return schema.parse(JSON.parse(bytes.toString("utf8")));
-		const headerString = (value) => typeof value === "string" ? value : void 0;
-		const saved = String(response.headers["x-b4m-audio-saved"] ?? "") === "true";
-		return schema.parse({
-			delivery: "inline",
-			audio: bytes.toString("base64"),
-			contentType,
-			saved,
-			fabFileId: saved ? headerString(response.headers["x-b4m-audio-fab-file-id"]) : void 0,
-			fileName: saved ? headerString(response.headers["x-b4m-audio-file-name"]) : void 0,
-			fileUrl: saved ? headerString(response.headers["x-b4m-audio-file-url"]) : void 0
-		});
+		};
+		return await this.sdk.call("generateImage", { body });
 	}
 	async listProjects(args) {
 		const result = await this.client.get("/api/projects", { params: {
@@ -206,12 +192,21 @@ var B4mApiClient = class {
 		return this.client.get(`/api/projects/${encodeURIComponent(projectId)}`);
 	}
 	async createProject(args) {
-		return this.client.post("/api/projects", {
+		const project = await this.sdk.call("createProject", { body: {
 			name: args.name,
 			description: args.description,
-			...args.sessionIds?.length ? { sessionIds: args.sessionIds } : {},
-			...args.fileIds?.length ? { fileIds: args.fileIds } : {}
-		});
+			...args.sessionIds?.length ? { session_ids: args.sessionIds } : {},
+			...args.fileIds?.length ? { file_ids: args.fileIds } : {}
+		} });
+		return {
+			id: project.id,
+			name: project.name,
+			description: project.description,
+			sessionIds: project.session_ids,
+			fileIds: project.file_ids,
+			createdAt: project.created_at ?? void 0,
+			updatedAt: project.updated_at ?? void 0
+		};
 	}
 	/**
 	* GET /api/artifacts takes flat `limit`/`offset` params (not the nested
@@ -232,6 +227,58 @@ var B4mApiClient = class {
 	async getArtifact(artifactId) {
 		return this.client.get(`/api/artifacts/${encodeURIComponent(artifactId)}`, { params: { includeContent: "true" } });
 	}
+	/** POST /api/v1/artifacts: creates a private artifact at version 1. */
+	async createArtifact(args) {
+		const artifact = await this.sdk.call("createArtifact", { body: {
+			type: args.type,
+			title: args.title,
+			content: args.content,
+			...args.description !== void 0 ? { description: args.description } : {},
+			...args.notebookId ? { session_id: args.notebookId } : {},
+			...args.projectId ? { project_id: args.projectId } : {},
+			...args.tags?.length ? { tags: args.tags } : {}
+		} });
+		return {
+			id: artifact.id,
+			type: artifact.type,
+			title: artifact.title,
+			version: artifact.version,
+			notebookId: artifact.session_id ?? void 0,
+			projectId: artifact.project_id ?? void 0,
+			createdAt: artifact.created_at
+		};
+	}
+	/**
+	* The caller's own most recent publication of an artifact, or null. The route is
+	* owner-scoped for `sourceArtifactId`, so another user's page never matches.
+	*/
+	async findPublishedArtifact(artifactId) {
+		return (await this.client.get("/api/publish/artifacts", { params: {
+			sourceArtifactId: artifactId,
+			limit: 1
+		} })).artifacts?.[0] ?? null;
+	}
+	/** POST /api/publish/artifact/upload-url: opens a publish draft and mints one upload URL per file. */
+	async requestPublishUpload(request) {
+		return this.client.post("/api/publish/artifact/upload-url", request);
+	}
+	/**
+	* PUT one draft file to the URL upload-url minted. Plain fetch, never the app
+	* client: that client injects auth headers, which break an S3 presigned
+	* signature. Self-host mints a relative proxy URL, so resolve against baseURL.
+	*/
+	async uploadPublishDraftFile(uploadUrl, body, mimeType) {
+		const res = await fetch(new URL(uploadUrl, this.baseURL), {
+			method: "PUT",
+			headers: { "Content-Type": mimeType },
+			body
+		});
+		if (!res.ok) throw new Error(`publish upload failed (${res.status})`);
+	}
+	/** POST /api/publish/artifact/finalize: validates the uploaded draft and makes it live. */
+	async finalizePublish(draftId) {
+		return this.client.post("/api/publish/artifact/finalize", { draftId });
+	}
 	/**
 	* POST /api/briefcase/catalog: a key -> prompts map, one entry per query key.
 	*
@@ -256,67 +303,67 @@ var B4mApiClient = class {
 */
 function mapApiError(error, baseURL, scope) {
 	if (error instanceof NotAuthenticatedError) return "not authenticated: no credential configured (set B4M_API_KEY or run `b4m login`)";
+	const failure = httpFailure(error);
+	if (!failure) return error instanceof Error ? error.message : String(error);
+	const { status, data } = failure;
+	if (status === 401) {
+		const providerKeyMessage = providerKeyFailureMessage(data);
+		if (providerKeyMessage) return providerKeyMessage;
+		return "authentication failed (run `b4m login` or set B4M_API_KEY)";
+	}
+	if (status === 403) {
+		if (data?.code === "FEATURE_DISABLED") return "feature disabled on this Bike4Mind instance (ask an admin to enable it)";
+		if (apiErrorCode(error) === "slug_owned_by_other") return extractServerMessage(data) ?? "this publish slug belongs to another publisher";
+		const serverMessage = extractServerMessage(data);
+		if (serverMessage && /CSRF|request origin/i.test(serverMessage)) return serverMessage;
+		if (serverMessage && /own user scope/i.test(serverMessage)) return `${serverMessage} (publish_artifact only publishes artifacts you own)`;
+		const base = "API key forbidden: check the key's scopes and account access";
+		return scope ? `${base} (recommended scope: ${scope})` : base;
+	}
+	if (status === 404 && error instanceof B4mApiError && !extractServerMessage(data)) return `the Bike4Mind server at ${baseURL} does not have this API route; it likely predates this CLI (upgrade the server or use an older CLI)`;
+	if (status === 429) {
+		const retryAfterSeconds = apiErrorRetryAfterSeconds(error);
+		const base = extractServerMessage(data) || "rate limit exceeded";
+		return retryAfterSeconds !== void 0 ? `${base} (retry after ${retryAfterSeconds}s)` : base;
+	}
 	if (isAxiosError(error)) {
-		const status = error.response?.status;
-		if (status === 401) {
-			const providerKeyMessage = providerKeyFailureMessage(error.response?.data);
-			if (providerKeyMessage) return providerKeyMessage;
-			return "authentication failed (run `b4m login` or set B4M_API_KEY)";
-		}
-		if (status === 403) {
-			if ((error.response?.data)?.code === "FEATURE_DISABLED") return "feature disabled on this Bike4Mind instance (ask an admin to enable it)";
-			const csrfMessage = extractServerMessage(error.response?.data);
-			if (csrfMessage && /CSRF|request origin/i.test(csrfMessage)) return csrfMessage;
-			const base = "API key forbidden: check the key's scopes and account access";
-			return scope ? `${base} (recommended scope: ${scope})` : base;
-		}
-		if (status === 429) {
-			const retryAfterSeconds = parseRetryAfterSeconds(error.response?.headers?.["retry-after"]);
-			const base = extractServerMessage(error.response?.data) || "rate limit exceeded";
-			return retryAfterSeconds !== void 0 ? `${base} (retry after ${retryAfterSeconds}s)` : base;
-		}
 		if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT" || /timeout/i.test(error.message)) return `request to Bike4Mind at ${baseURL} timed out`;
 		if (error.code === "ECONNREFUSED" || error.message.includes("ECONNREFUSED")) return `cannot reach Bike4Mind at ${baseURL}`;
-		const serverMsg = extractServerMessage(error.response?.data);
-		if (serverMsg) return serverMsg;
-		return error.message;
 	}
+	const serverMsg = extractServerMessage(data);
+	if (serverMsg) return serverMsg;
 	return error instanceof Error ? error.message : String(error);
 }
 /**
-* A request made with `responseType: 'arraybuffer'` also decodes its error body
-* as bytes, so a JSON `{ error }` payload reaches us as a Buffer that
-* {@link mapApiError} can't read. Decode it back to a parsed object in place so
-* the server's message survives; leave a non-JSON body untouched.
+* 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.
 */
-function decodeArrayBufferErrorBody(error) {
-	if (!isAxiosError(error) || !error.response) return error;
-	const { data } = error.response;
-	if (typeof data === "string") {
-		try {
-			error.response.data = JSON.parse(data);
-		} catch {}
-		return error;
-	}
-	const bytes = Buffer.isBuffer(data) ? data : data instanceof ArrayBuffer ? Buffer.from(data) : ArrayBuffer.isView(data) ? Buffer.from(data.buffer, data.byteOffset, data.byteLength) : void 0;
-	if (!bytes) return error;
-	try {
-		error.response.data = JSON.parse(bytes.toString("utf8"));
-	} catch {}
-	return error;
+function httpFailure(error) {
+	if (error instanceof B4mApiError) return {
+		status: error.status,
+		data: error.body
+	};
+	if (isAxiosError(error)) return {
+		status: error.response?.status,
+		data: error.response?.data
+	};
 }
-/**
-* Normalize a Retry-After header (RFC 7231: either delta-seconds or an HTTP-date)
-* to a whole, non-negative number of seconds. Returns undefined when the header is
-* absent or parses as neither, so callers can omit the retry hint entirely.
-*/
-function parseRetryAfterSeconds(value) {
-	if (value === void 0 || value === null) return void 0;
-	const raw = String(value).trim();
-	if (/^\d+$/.test(raw)) return Number(raw);
-	const dateMs = Date.parse(raw);
-	if (Number.isNaN(dateMs)) return void 0;
-	return Math.max(0, Math.ceil((dateMs - Date.now()) / 1e3));
+/** The machine-readable `code` a route put on its error body, when it set one. */
+function apiErrorCode(error) {
+	const data = httpFailure(error)?.data;
+	if (!data || typeof data !== "object") return void 0;
+	const code = data.code;
+	return typeof code === "string" ? code : void 0;
+}
+/** The HTTP status of a failed API call from either transport. */
+function apiErrorStatus(error) {
+	return httpFailure(error)?.status;
+}
+/** The Retry-After of a failed API call from either transport, in seconds. */
+function apiErrorRetryAfterSeconds(error) {
+	if (error instanceof B4mApiError) return error.retryAfterSeconds;
+	return isAxiosError(error) ? parseRetryAfterSeconds(error.response?.headers?.["retry-after"]) : void 0;
 }
 /** Pull a human-readable message out of a JSON error body (`error` or `message` field). */
 function extractServerMessage(data) {
@@ -390,7 +437,7 @@ const TOOL_META = [
 	{
 		name: "send_message",
 		title: "Send message",
-		description: "Send a chat message and wait for the assistant reply, reporting progress while it is generated; returns the cited sources (citables) the answer was grounded in.",
+		description: "Send a chat message and wait for the assistant reply, reporting progress while it is generated; returns the cited sources (citables) the answer was grounded in. Fails on an errored or stopped turn, and stops the turn when the call is cancelled.",
 		scope: "ai:chat"
 	},
 	{
@@ -434,6 +481,18 @@ const TOOL_META = [
 		title: "Generate image",
 		description: "Generate an image from a text prompt and wait for the render. Returns the quest and notebook ids plus each image's file name and download URL. Image names are not file ids and do not work with get_file.",
 		scope: "ai:generate"
+	},
+	{
+		name: "create_artifact",
+		title: "Create artifact",
+		description: "Create a private artifact (diagram, chart, code, page) and return its id. There is no markdown type: put a written document in type 'html'. Pass the returned id to publish_artifact to share it.",
+		scope: "notebooks:write"
+	},
+	{
+		name: "publish_artifact",
+		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"
 	}
 ];
 TOOL_META.map((t) => t.name);
@@ -506,6 +565,21 @@ const generateImageShape = {
 	projectId: z$1.string().optional().describe("Project for the new notebook when notebookId is omitted"),
 	promptResolution: ImagePromptResolutionSchema.optional().describe("'auto' (default) rewrites the prompt against the notebook history; 'literal' sends it as written")
 };
+const publishVisibilitySchema = VisibilitySchema.extract(["public", "private"]);
+const publishArtifactShape = {
+	artifactId: z$1.string().min(1).describe("The artifact id"),
+	visibility: publishVisibilitySchema.optional().describe("Who can open the link: 'public' (anyone) or 'private' (only you); omit to keep an existing page's visibility (a first publish is public)"),
+	title: z$1.string().min(1).max(200).optional().describe("Page title; defaults to the artifact's title")
+};
+const createArtifactShape = {
+	type: CreateArtifactRequestSchema.shape.type.describe("Artifact type: 'html' for a written document or web page, 'mermaid' for a diagram, 'recharts' for a chart, 'svg', 'react', 'python' or 'code' for source"),
+	title: CreateArtifactRequestSchema.shape.title.describe("Artifact title"),
+	content: CreateArtifactRequestSchema.shape.content.describe("The artifact's source: HTML, Mermaid, SVG, code and so on, matching type"),
+	description: CreateArtifactRequestSchema.shape.description.describe("Short description"),
+	notebookId: notebookId("A notebook (session) you can edit, to file the artifact under").optional(),
+	projectId: CreateArtifactRequestSchema.shape.project_id.describe("A project you can read, to file the artifact under"),
+	tags: CreateArtifactRequestSchema.shape.tags.describe("Up to 20 tags")
+};
 const textToSpeechShape = {
 	...ttsRequestSchema.omit({ encoding: true }).shape,
 	text: ttsRequestSchema.shape.text.describe("Text to speak"),
@@ -584,24 +658,38 @@ async function createProject(client, args) {
 	return projectSummary(await client.createProject(args));
 }
 /**
-* Queue a chat turn and poll its quest to completion. A failed turn ends `type: 'error'` with its
-* explanation as the reply, which is returned as-is like any other reply.
+* Queue a chat turn and poll its quest to completion. A failed (`type: 'error'`) or stopped turn
+* throws, so the tool reports `isError`; a cancelled call makes a best-effort stop of its quest.
 */
 async function sendMessage(client, args, { intervalMs = CHAT_POLL_INTERVAL_MS, timeoutMs = CHAT_POLL_TIMEOUT_MS, ...poll } = {}) {
 	const ack = await client.sendChat(args);
 	const questId = ack.id;
-	const quest = await pollQuest(client, {
-		questId,
-		ref: questRef(questId, ack.sessionId),
-		task: "chat completion",
-		scope: "ai:chat",
-		isFinished: isSettled
-	}, {
-		...poll,
-		timeoutMs,
-		interval: (elapsedMs) => chatPollInterval(elapsedMs, intervalMs)
-	});
-	const notebookId = args.notebookId ?? ack.sessionId ?? quest.sessionId;
+	const sessionId = args.notebookId ?? ack.sessionId;
+	const ref = questRef(questId, sessionId);
+	let quest;
+	try {
+		quest = await pollQuest(client, {
+			questId,
+			ref,
+			task: "chat completion",
+			scope: "ai:chat",
+			isFinished: isSettled
+		}, {
+			...poll,
+			timeoutMs,
+			interval: (elapsedMs) => chatPollInterval(elapsedMs, intervalMs)
+		});
+	} catch (err) {
+		if (poll.signal?.aborted && sessionId) await client.stopReply(sessionId, questId).catch((stopErr) => logger.warn(`mcp: stopping the cancelled turn failed (${ref}): ${stopErr instanceof Error ? stopErr.message : String(stopErr)}`));
+		throw err;
+	}
+	const reply = replyText(quest);
+	if (quest.status === "stopped") throw new Error(`chat completion was stopped (${ref})${reply ? `: ${reply}` : ""}`);
+	if (quest.type === "error") {
+		const code = quest.errorCode ? `${quest.errorCode}: ` : "";
+		throw new Error(`${code}${reply || "chat completion failed"} (${ref})`);
+	}
+	const notebookId = sessionId ?? quest.sessionId;
 	const citables = (quest.promptMeta?.citables ?? []).map((c) => ({
 		id: c.id,
 		type: c.type,
@@ -612,7 +700,7 @@ async function sendMessage(client, args, { intervalMs = CHAT_POLL_INTERVAL_MS, t
 	return {
 		notebookId,
 		questId,
-		reply: replyText(quest),
+		reply,
 		model: ack.model,
 		citables
 	};
@@ -653,9 +741,9 @@ const isSettled = (q) => q.status === "done" || q.status === "stopped" || q.type
 const isImageSettled = (q) => isSettled(q) || !q.status && !!q.images?.length;
 const replyText = (q) => questReplyText(q, joinReplySlots) ?? "";
 const questRef = (questId, notebookId) => `quest ${questId}${notebookId ? `, notebook ${notebookId}` : ""}`;
-const isRateLimited = (err) => isAxiosError(err) && err.response?.status === 429;
+const isRateLimited = (err) => apiErrorStatus(err) === 429;
 const isPermanentApiError = (err) => {
-	const status = isAxiosError(err) ? err.response?.status : void 0;
+	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. */
@@ -671,7 +759,7 @@ async function pollQuest(client, { questId, ref, task, scope, isFinished }, { in
 			failures = 0;
 			if (isFinished(quest)) return quest;
 		} catch (err) {
-			if (isRateLimited(err)) retryAfterMs = (parseRetryAfterSeconds(isAxiosError(err) && err.response?.headers?.["retry-after"]) ?? 0) * 1e3;
+			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)`);
@@ -695,7 +783,7 @@ async function pollQuest(client, { questId, ref, task, scope, isFinished }, { in
 * resolves `status: 'done'`, so `type: 'error'` (reason in `reply`) is the failure signal.
 * Generated images are not FabFiles, so there is no file id: the quest id is the handle,
 * and each image is its generated-file name plus the URL the quest poll resolves for it
-* (`fileUrl` is absent when the server has no CDN configured).
+* (`fileUrl` is a short-lived presigned URL, valid for about an hour).
 */
 async function generateImage(client, args, { intervalMs = IMAGE_POLL_INTERVAL_MS, timeoutMs = IMAGE_POLL_TIMEOUT_MS, ...poll } = {}) {
 	const ack = await client.generateImage(args);
@@ -731,6 +819,98 @@ async function generateImage(client, args, { intervalMs = IMAGE_POLL_INTERVAL_MS
 		images
 	};
 }
+const PUBLISH_INDEX_PATH = "index.html";
+const PUBLISH_INDEX_MIME = "text/html";
+const PUBLISH_TITLE_MAX = 200;
+const PUBLISH_FALLBACK_TITLE = "Shared artifact";
+const PUBLISH_DEFAULT_VISIBILITY = "public";
+const SLUG_TITLE_MAX = 48;
+const SLUG_ARTIFACT_HASH_LENGTH = 8;
+const SLUG_DISCRIMINATOR_LENGTH = 6;
+function slugify(text) {
+	return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, SLUG_TITLE_MAX).replace(/-+$/, "");
+}
+/**
+* Stable per artifact, so republishing updates the same page in place. Artifact
+* ids all share an `artifact_` prefix, so the suffix hashes the whole id rather
+* than taking a prefix of it.
+*/
+function artifactSlug(title, artifactId) {
+	const hash = createHash("sha256").update(artifactId).digest("hex").slice(0, SLUG_ARTIFACT_HASH_LENGTH);
+	return `${slugify(title) || "artifact"}-${hash}`;
+}
+/** The artifact-content doc carries the body as `content`; anything else has none to publish. */
+function artifactContentText(content) {
+	if (!content || typeof content !== "object") return void 0;
+	const text = content.content;
+	return typeof text === "string" && text.trim() ? text : void 0;
+}
+/**
+* Open the draft, retrying once under a discriminated slug when the derived slug
+* already belongs to another publisher (the same fallback the web Share flow uses).
+*/
+async function openPublishDraft(client, request) {
+	try {
+		return await client.requestPublishUpload(request);
+	} catch (err) {
+		if (apiErrorCode(err) !== "slug_owned_by_other") throw err;
+		const discriminator = randomUUID().replace(/-/g, "").slice(0, SLUG_DISCRIMINATOR_LENGTH);
+		return client.requestPublishUpload({
+			...request,
+			slug: `${request.slug}-${discriminator}`
+		});
+	}
+}
+async function createArtifact(client, args) {
+	return client.createArtifact(args);
+}
+/**
+* Publish an artifact: upload its RAW content and let finalize render it
+* (source.artifactType), so the page matches an in-app publish byte for byte with
+* no CLI-side renderer. An artifact the caller already published (from the app or
+* here) is republished in place at its existing tier/scope/slug, as the in-app
+* update flow does; otherwise it becomes a new user-tier page.
+*/
+async function publishArtifact(client, args) {
+	const { artifact, content } = await client.getArtifact(args.artifactId);
+	const body = artifactContentText(content);
+	if (!body) throw new Error(`artifact ${artifact.id} has no content to publish`);
+	const artifactType = ArtifactTypeSchema.safeParse(artifact.type);
+	if (!artifactType.success) throw new Error(`artifact ${artifact.id} has an unsupported type (${String(artifact.type)})`);
+	if (typeof artifact.userId !== "string") throw new Error(`artifact ${artifact.id} has no owner to publish under`);
+	const storedTitle = typeof artifact.title === "string" ? artifact.title : "";
+	const title = (args.title ?? storedTitle).trim().slice(0, PUBLISH_TITLE_MAX) || PUBLISH_FALLBACK_TITLE;
+	const existing = await client.findPublishedArtifact(artifact.id);
+	const request = {
+		tier: existing?.tier ?? "user",
+		scopeId: existing?.scopeId ?? artifact.userId,
+		slug: existing?.slug ?? artifactSlug(title, artifact.id),
+		title,
+		visibility: args.visibility ?? existing?.visibility ?? PUBLISH_DEFAULT_VISIBILITY,
+		...existing?.description !== void 0 && { description: existing.description },
+		...existing?.commentPolicy !== void 0 && { commentPolicy: existing.commentPolicy },
+		source: {
+			kind: "bundle",
+			artifactId: artifact.id,
+			artifactType: artifactType.data
+		},
+		files: [{
+			path: PUBLISH_INDEX_PATH,
+			size: Buffer.byteLength(body),
+			mimeType: PUBLISH_INDEX_MIME
+		}]
+	};
+	const draft = existing ? await client.requestPublishUpload(request) : await openPublishDraft(client, request);
+	const upload = draft.uploadUrls.find((u) => u.path === PUBLISH_INDEX_PATH);
+	if (!upload) throw new Error(`publish draft ${draft.draftId} returned no upload URL for ${PUBLISH_INDEX_PATH}`);
+	await client.uploadPublishDraftFile(upload.url, body, PUBLISH_INDEX_MIME);
+	const published = await client.finalizePublish(draft.draftId);
+	return {
+		publicId: published.publicId,
+		url: new URL(published.url, client.baseURL).toString(),
+		visibility: published.visibility
+	};
+}
 function toResult(value) {
 	const structuredContent = value && typeof value === "object" && !Array.isArray(value) ? value : { result: value };
 	return {
@@ -977,6 +1157,16 @@ function registerTools(server, client) {
 		baseURL,
 		onProgress: progressReporter(extra, () => "rendering image")
 	})));
+	server.registerTool("create_artifact", {
+		title: meta("create_artifact").title,
+		description: meta("create_artifact").description,
+		inputSchema: createArtifactShape
+	}, (args) => run("notebooks:write", () => createArtifact(client, args)));
+	server.registerTool("publish_artifact", {
+		title: meta("publish_artifact").title,
+		description: meta("publish_artifact").description,
+		inputSchema: publishArtifactShape
+	}, (args) => run("files:write", () => publishArtifact(client, args)));
 }
 //#endregion
 //#region src/mcp/resources.ts