@xopcai/xopc 0.0.313 → 0.0.315

package/dist/src/gateway/hono/routes/local-apps.js

@@ -1,8 +1,13 @@
+import { CapabilityError } from "../../../capabilities/runtime/errors.js";
+import "../../../capabilities/runtime/dispatcher.js";
 import { readLocalAppAcceptanceConfig } from "../../../local-apps/acceptance.js";
+import { createProductDispatcher } from "../../../capabilities/runtime/product.js";
 import { extensionAssetMimeType } from "../lib/extension-assets.js";
+import { capabilityHttpContext, capabilityHttpError } from "../../../capabilities/adapters/http.js";
 import { LOCAL_APP_RUNTIME_BRIDGE_HASH, injectLocalAppRuntimeBridge } from "../../../local-apps/preview-runtime-bridge.js";
 import { relative, resolve } from "node:path";
 import { existsSync, readFileSync, statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 //#region src/gateway/hono/routes/local-apps.ts
 const LOCAL_APP_PREVIEW_CSP = `default-src 'self'; script-src 'self' 'sha256-${LOCAL_APP_RUNTIME_BRIDGE_HASH}'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; connect-src 'none'; frame-ancestors 'self'; frame-src 'none'; base-uri 'none'; object-src 'none'; form-action 'none'`;
 function registerPublicLocalAppPreviewRoutes(app, service) {
@@ -49,7 +54,14 @@ function registerPublicLocalAppPreviewRoutes(app, service) {
 	});
 }
 function registerLocalAppsRoutes(app, deps) {
-	app.get("/api/local-apps", (c) => c.json({ apps: deps.service.localApps.list() }));
+	const capabilities = createProductDispatcher(void 0, { getLocalApps: () => deps.service.localApps });
+	app.get("/api/local-apps", async (c) => {
+		try {
+			return c.json(await capabilities.call("xopc.local_apps.list", {}, capabilityHttpContext(c)));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
+	});
 	app.post("/api/local-apps", async (c) => {
 		const body = await c.req.json();
 		if (typeof body.name !== "string" || typeof body.idea !== "string") return c.json({ error: "name and idea are required" }, 400);
@@ -60,17 +72,37 @@ function registerLocalAppsRoutes(app, deps) {
 		});
 		return c.json({ app: appDetail }, 201);
 	});
-	app.get("/api/local-apps/:id", (c) => {
-		const appDetail = deps.service.localApps.get(c.req.param("id"));
-		return appDetail ? c.json({ app: appDetail }) : c.json({ error: "Local app not found" }, 404);
+	app.get("/api/local-apps/:id", async (c) => {
+		try {
+			return c.json(await capabilities.call("xopc.local_apps.get", { id: c.req.param("id") }, capabilityHttpContext(c)));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
-	app.post("/api/local-apps/:id/validate", (c) => {
-		return c.json({ validation: deps.service.localApps.validate(c.req.param("id")) });
+	app.post("/api/local-apps/:id/validate", async (c) => {
+		try {
+			return c.json(await capabilities.call("xopc.local_apps.validate", { id: c.req.param("id") }, capabilityHttpContext(c)));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	app.post("/api/local-apps/:id/acceptance-runs", async (c) => {
-		const body = await c.req.json();
-		const acceptance = deps.service.localApps.recordAcceptance(c.req.param("id"), body);
-		return c.json({ acceptance }, 201);
+		try {
+			const body = await c.req.json().catch(() => {
+				throw new CapabilityError("INVALID_INPUT", "Invalid JSON body");
+			});
+			const caller = capabilityHttpContext(c);
+			const operation = "xopc.local_apps.record_acceptance";
+			return c.json(await capabilities.call(operation, {
+				...body,
+				id: c.req.param("id")
+			}, caller, {
+				...capabilities.describe(operation, caller),
+				idempotencyKey: c.req.header("idempotency-key") ?? randomUUID()
+			}), 201);
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	app.post("/api/local-apps/:id/install", async (c) => {
 		const appDetail = await deps.service.localApps.install(c.req.param("id"));

package/dist/src/gateway/hono/routes/mcp.js

@@ -1,9 +1,9 @@
 import { isManagedConnectorServer } from "../../../connectors/materialize.js";
-import { getWorkspacePath } from "../../../config/workspace-path-helpers.js";
 import { canonicalizeConfiguredMcpServer, normalizeConfiguredMcpServers } from "../../../config/mcp-config-normalize.js";
 import { loadMergedBundleMcpConfig } from "../../../agent/mcp/bundle-mcp-config.js";
+import { getWorkspacePath } from "../../../config/workspace-path-helpers.js";
 import { getMcpOAuthManager } from "../../../agent/mcp/oauth/mcp-oauth-manager.js";
-import { listBundleMcpServerCapabilitiesForGateway, listBundleMcpServerToolsForGateway } from "../../../agent/mcp/bundle-mcp-gateway.js";
+import { listBundleMcpResourcesForGateway, listBundleMcpServerCapabilitiesForGateway, listBundleMcpServerToolsForGateway } from "../../../agent/mcp/bundle-mcp-gateway.js";
 //#region src/gateway/hono/routes/mcp.ts
 function registerMcpRoutes(authenticated, deps) {
 	const resolveServer = (id) => {
@@ -36,6 +36,37 @@ function registerMcpRoutes(authenticated, deps) {
 			}
 		});
 	});
+	authenticated.get("/api/mcp/resources", async (c) => {
+		const cfg = deps.service.currentConfig;
+		const workspaceDir = getWorkspacePath(cfg) || "./workspace";
+		const query = (c.req.query("q") ?? "").trim().toLocaleLowerCase();
+		const serverId = (c.req.query("serverId") ?? "").trim();
+		try {
+			const items = (await listBundleMcpResourcesForGateway({
+				workspaceDir,
+				cfg
+			})).filter((resource) => {
+				if (serverId && resource.serverId !== serverId) return false;
+				if (!query) return true;
+				return [
+					resource.name,
+					resource.title,
+					resource.description,
+					resource.uri,
+					resource.serverId
+				].some((value) => value?.toLocaleLowerCase().includes(query));
+			}).slice(0, 20);
+			return c.json({
+				ok: true,
+				payload: { resources: items }
+			});
+		} catch (err) {
+			return c.json({
+				ok: false,
+				error: err instanceof Error ? err.message : String(err)
+			}, 500);
+		}
+	});
 	authenticated.get("/api/mcp/servers/:id/oauth", async (c) => {
 		const id = c.req.param("id");
 		const server = resolveServer(id);

package/dist/src/gateway/hono/routes/media.js

@@ -1,6 +1,6 @@
-import { MAX_WEBCHAT_ATTACHMENT_FILE_BYTES } from "../../chat-limits.js";
 import { mimeTypeFromMediaPath, saveMediaBuffer } from "../../../media/store.js";
 import { readMediaReference } from "../../../media/media-reference.js";
+import { MAX_WEBCHAT_ATTACHMENT_FILE_BYTES } from "../../chat-limits.js";
 import { createGatewayRouteLogger } from "../lib/route-logger.js";
 import { resolveScopedMediaReference } from "../../media-access.js";
 //#region src/gateway/hono/routes/media.ts

package/dist/src/gateway/hono/routes/models.js

@@ -1,6 +1,6 @@
-import { init_resolve_config_value, testApiKeyResolution } from "../../../config/resolve-config-value.js";
 import { resolveModelsJsonPath } from "../../../config/paths.js";
-import { computerModelProfile, init_model_policy } from "../../../computer/model-policy.js";
+import { init_resolve_config_value, testApiKeyResolution } from "../../../config/resolve-config-value.js";
+import { computerModelProfile, init_model_policy, isDedicatedComputerModel } from "../../../computer/model-policy.js";
 import { init_models_json, loadModelsJson, saveModelsJson, validateModelsConfig } from "../../../config/models-json.js";
 import { getModelCatalogStore, init_model_catalog_store } from "../../../providers/model-catalog-store.js";
 import { getModelRegistry } from "../../../providers/model-registry.js";
@@ -8,13 +8,13 @@ import { CredentialResolver, init_credentials } from "../../../auth/credentials.
 import "../../../providers/constants.js";
 import { getProviderRegistry, init_plugin_registry } from "../../../providers/plugin-registry.js";
 import { PROVIDER_META, getAllModels, getAllProviders, getAvailableModels, getProviderAuthState, init_providers, isProviderConfigured, isProviderConfiguredSync } from "../../../providers/index.js";
-import { deleteCustomImageProvider, listCustomImageProviders, upsertCustomImageProvider } from "../../custom-image-providers.js";
-import { getImageGenerationProvider, reloadImageGenerationProviders, resolveImageGenerationCredentialMode } from "../../../agent/image/generation/provider-registry.js";
-import { getAgentImageGenerationConfig, getDefaultImageGenerationConfig, getImageGenerationCatalog, prepareDefaultImageGenerationSetup, prepareImageGenerationSetup, verifyImageGenerationCredential } from "../../image-generation-setup.js";
-import { SessionConfigStore } from "../../../session/config-store.js";
 import { buildCapabilityPlansForConfig } from "../../../capabilities/readiness/from-config.js";
 import "../../../capabilities/readiness/index.js";
+import { getImageGenerationProvider, reloadImageGenerationProviders, resolveImageGenerationCredentialMode } from "../../../agent/image/generation/provider-registry.js";
+import { SessionConfigStore } from "../../../session/config-store.js";
 import { getModelThinking } from "../../../providers/model-thinking.js";
+import { deleteCustomImageProvider, listCustomImageProviders, upsertCustomImageProvider } from "../../custom-image-providers.js";
+import { getAgentImageGenerationConfig, getDefaultImageGenerationConfig, getImageGenerationCatalog, prepareDefaultImageGenerationSetup, prepareImageGenerationSetup, verifyImageGenerationCredential } from "../../image-generation-setup.js";
 import { discoverProviderModels, isProviderApiDiscoverable } from "../../../providers/model-discovery.js";
 import { getXopcCloudCatalogCoordinator } from "../../../providers/xopc-cloud-catalog-coordinator.js";
 import { respondStartupUnavailable } from "../lib/startup-unavailable.js";
@@ -306,7 +306,7 @@ function registerModelsRoutes(authenticated, deps) {
 			reasoning: m.reasoning ?? false,
 			thinking: getModelThinking(m),
 			vision: m.input?.includes("image") ?? false,
-			recommended: !computerModelProfile(m) && isRecommendedModel(m.provider, m.id),
+			recommended: !isDedicatedComputerModel(m) && isRecommendedModel(m.provider, m.id),
 			cost: {
 				input: m.cost?.input ?? 0,
 				output: m.cost?.output ?? 0

package/dist/src/gateway/hono/routes/notes.js

@@ -1,18 +1,24 @@
-import { ObjectLinkService } from "../../../activity/service.js";
+import { NoteDeleteOutputSchema, NoteGetOutputSchema, ProductReadContracts } from "../../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { init_session_key, resolveConversationId } from "../../../routing/session-key.js";
 import { agentExists, getDefaultAgentId, init_resolve_route } from "../../../routing/resolve-route.js";
+import { CapabilityError } from "../../../capabilities/runtime/errors.js";
+import "../../../capabilities/runtime/dispatcher.js";
 import { resolveGatewayEffectiveHost } from "../../../config/gateway-bind.js";
-import { resolveReverseProxyPublicUrl } from "../../public-url.js";
 import { getShareStore } from "../../../share/share-store.js";
 import { resolveShareUrl } from "../../../share/share-url.js";
+import { resolveReverseProxyPublicUrl } from "../../public-url.js";
+import { createProductDispatcher } from "../../../capabilities/runtime/product.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
+import { capabilityHttpContext, capabilityHttpError } from "../../../capabilities/adapters/http.js";
 import { NoteShareService, NoteShareVersionConflictError } from "../../../share/note-share-service.js";
 import { createReadStream } from "node:fs";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { access, stat } from "node:fs/promises";
 import { Readable } from "node:stream";
 import { stream } from "hono/streaming";
 //#region src/gateway/hono/routes/notes.ts
+init_src();
 init_session_key();
 init_resolve_route();
 const VALID_KINDS = new Set([
@@ -72,7 +78,15 @@ function noteThreadName(note) {
 }
 function registerNotesRoutes(authenticated, deps) {
 	const { service } = deps;
-	const objectLinks = new ObjectLinkService();
+	const capabilities = createProductDispatcher(() => service.notesServiceInstance, { getProjects: () => service.projects });
+	const invokeRead = async (c, operation, input) => ProductReadContracts[operation].output.parse(await capabilities.call(operation, input, capabilityHttpContext(c)));
+	const invokeNote = async (c, operation, input, key) => {
+		const context = capabilityHttpContext(c);
+		return NoteGetOutputSchema.parse(await capabilities.call(operation, input, context, {
+			...capabilities.describe(operation, context),
+			idempotencyKey: key ?? randomUUID()
+		}));
+	};
 	const shareConfig = () => {
 		const raw = (service.currentConfig?.gateway)?.share;
 		return raw && typeof raw === "object" ? raw : {};
@@ -88,26 +102,6 @@ function registerNotesRoutes(authenticated, deps) {
 		gatewayPort: service.currentConfig?.gateway?.port ?? 18790,
 		reverseProxyPublicUrl: resolveReverseProxyPublicUrl(service.currentConfig)
 	});
-	const linkNoteToProject = (note, projectId) => {
-		if (!projectId) return;
-		const project = service.projects.get(projectId);
-		if (!project) return;
-		objectLinks.create({
-			id: `note:${note.id}:project:${project.id}`,
-			from: {
-				kind: "note",
-				id: note.id,
-				title: note.title
-			},
-			to: {
-				kind: "project",
-				id: project.id,
-				title: project.name
-			},
-			relation: "belongs_to",
-			source: "user"
-		});
-	};
 	authenticated.post("/api/notes/quick-capture", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
 		const text = typeof body.text === "string" ? body.text.trim() : "";
@@ -115,106 +109,110 @@ function registerNotesRoutes(authenticated, deps) {
 		const source = parseCaptureSource(body);
 		const idempotencyKey = readIdempotencyKey(c.req.header("idempotency-key"));
 		if (idempotencyKey && idempotencyKey.length > 200) return c.json({ error: "Idempotency-Key is too long" }, 400);
-		const note = await service.notesServiceInstance.quickCapture(text, source, idempotencyKey || void 0);
-		return c.json({ note }, 201);
+		try {
+			return c.json(await invokeNote(c, "xopc.notes.capture", {
+				text,
+				capturedVia: source
+			}, idempotencyKey), 201);
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.get("/api/notes", async (c) => {
-		const status = c.req.query("status");
-		const kind = c.req.query("kind");
-		const tag = c.req.query("tag");
-		const projectId = c.req.query("projectId")?.trim();
-		const search = c.req.query("search");
-		const pinnedRaw = c.req.query("pinned");
-		const limitRaw = c.req.query("limit");
-		const offsetRaw = c.req.query("offset");
-		const sortBy = c.req.query("sortBy");
-		const sortOrder = c.req.query("sortOrder");
-		const result = await service.notesServiceInstance.listNotes({
-			status: status && VALID_STATUSES.has(status) ? status : void 0,
-			kind: kind && VALID_KINDS.has(kind) ? kind : void 0,
-			tag: tag || void 0,
-			projectId: projectId || void 0,
-			unassigned: c.req.query("unassigned") === "true" || void 0,
-			agentEdited: c.req.query("agentEdited") === "true" || void 0,
-			search: search || void 0,
-			pinned: pinnedRaw === "true" ? true : pinnedRaw === "false" ? false : void 0,
-			limit: limitRaw ? parseInt(limitRaw, 10) : void 0,
-			offset: offsetRaw ? parseInt(offsetRaw, 10) : void 0,
-			sortBy: sortBy === "createdAt" || sortBy === "updatedAt" || sortBy === "lastOpenedAt" ? sortBy : void 0,
-			sortOrder: sortOrder === "asc" || sortOrder === "desc" ? sortOrder : void 0
-		});
-		return c.json(result);
+		try {
+			const input = { ...c.req.query() };
+			for (const key of ["limit", "offset"]) if (input[key] !== void 0) input[key] = Number(input[key]);
+			for (const key of [
+				"pinned",
+				"unassigned",
+				"agentEdited"
+			]) {
+				if (input[key] === "true") input[key] = true;
+				if (input[key] === "false") input[key] = false;
+			}
+			return c.json(await capabilities.call("xopc.notes.list", input, capabilityHttpContext(c)));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
-	authenticated.get("/api/notes/project-summaries", (c) => {
-		return c.json({ items: service.notesServiceInstance.listProjectSummaries() });
+	authenticated.get("/api/notes/project-summaries", async (c) => {
+		try {
+			return c.json(await invokeRead(c, "xopc.notes.project_summaries", {}));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.post("/api/notes", async (c) => {
-		const contentType = c.req.header("content-type") || "";
-		const idempotencyKey = readIdempotencyKey(c.req.header("idempotency-key"));
-		if (idempotencyKey && idempotencyKey.length > 200) return c.json({ error: "Idempotency-Key is too long" }, 400);
-		if (contentType.includes("multipart/form-data")) {
-			let body;
-			try {
-				body = await c.req.parseBody({ all: true });
-			} catch {
-				return c.json({ error: "Invalid multipart body" }, 400);
+		try {
+			const contentType = c.req.header("content-type") || "";
+			const idempotencyKey = readIdempotencyKey(c.req.header("idempotency-key"));
+			if (idempotencyKey && idempotencyKey.length > 200) return c.json({ error: "Idempotency-Key is too long" }, 400);
+			if (contentType.includes("multipart/form-data")) {
+				let body;
+				try {
+					body = await c.req.parseBody({ all: true });
+				} catch {
+					return c.json({ error: "Invalid multipart body" }, 400);
+				}
+				const markdown = typeof body.markdown === "string" ? body.markdown.trim() : void 0;
+				const kindRaw = typeof body.kind === "string" ? body.kind : void 0;
+				const tagsRaw = typeof body.tags === "string" ? body.tags : void 0;
+				const source = parseCaptureSource(body);
+				const projectId = typeof body.projectId === "string" && body.projectId.trim() ? body.projectId.trim() : void 0;
+				if (projectId && !service.projects.get(projectId)) return c.json({ error: "Project not found" }, 400);
+				const { note } = await invokeNote(c, "xopc.notes.create", {
+					markdown,
+					kind: kindRaw && VALID_KINDS.has(kindRaw) ? kindRaw : void 0,
+					tags: tagsRaw ? tagsRaw.split(",").map((t) => t.trim()).filter(Boolean) : void 0,
+					capturedVia: source,
+					projectId
+				}, idempotencyKey);
+				const file = body.file;
+				if (file && typeof file === "object") {
+					let buf = null;
+					let fileName = "upload";
+					let mimeType = "application/octet-stream";
+					if (file instanceof File) {
+						buf = Buffer.from(await file.arrayBuffer());
+						fileName = file.name || fileName;
+						mimeType = file.type || mimeType;
+					} else if (typeof file.arrayBuffer === "function") buf = Buffer.from(await file.arrayBuffer());
+					if (buf) {
+						const durationRaw = body.duration;
+						const duration = typeof durationRaw === "string" ? parseInt(durationRaw, 10) : typeof durationRaw === "number" ? durationRaw : void 0;
+						await service.notesServiceInstance.addAttachment(note.id, {
+							name: fileName,
+							buffer: buf,
+							mimeType,
+							duration: Number.isFinite(duration) ? duration : void 0,
+							retainWithoutReference: kindRaw === "voice"
+						}, idempotencyKey);
+					}
+				}
+				const full = await service.notesServiceInstance.getNote(note.id);
+				return c.json({ note: full }, 201);
 			}
+			const body = await c.req.json().catch(() => ({}));
+			const title = typeof body.title === "string" ? body.title.trim() : void 0;
 			const markdown = typeof body.markdown === "string" ? body.markdown.trim() : void 0;
 			const kindRaw = typeof body.kind === "string" ? body.kind : void 0;
-			const tagsRaw = typeof body.tags === "string" ? body.tags : void 0;
+			const tagsRaw = Array.isArray(body.tags) ? body.tags.filter((t) => typeof t === "string") : void 0;
 			const source = parseCaptureSource(body);
 			const projectId = typeof body.projectId === "string" && body.projectId.trim() ? body.projectId.trim() : void 0;
 			if (projectId && !service.projects.get(projectId)) return c.json({ error: "Project not found" }, 400);
-			const note = await service.notesServiceInstance.createNote({
+			const { note } = await invokeNote(c, "xopc.notes.create", {
+				title,
 				markdown,
 				kind: kindRaw && VALID_KINDS.has(kindRaw) ? kindRaw : void 0,
-				tags: tagsRaw ? tagsRaw.split(",").map((t) => t.trim()).filter(Boolean) : void 0,
-				capturedVia: source
+				tags: tagsRaw,
+				capturedVia: source,
+				pinned: body.pinned === true,
+				projectId
 			}, idempotencyKey);
-			linkNoteToProject(note, projectId);
-			const file = body.file;
-			if (file && typeof file === "object") {
-				let buf = null;
-				let fileName = "upload";
-				let mimeType = "application/octet-stream";
-				if (file instanceof File) {
-					buf = Buffer.from(await file.arrayBuffer());
-					fileName = file.name || fileName;
-					mimeType = file.type || mimeType;
-				} else if (typeof file.arrayBuffer === "function") buf = Buffer.from(await file.arrayBuffer());
-				if (buf) {
-					const durationRaw = body.duration;
-					const duration = typeof durationRaw === "string" ? parseInt(durationRaw, 10) : typeof durationRaw === "number" ? durationRaw : void 0;
-					await service.notesServiceInstance.addAttachment(note.id, {
-						name: fileName,
-						buffer: buf,
-						mimeType,
-						duration: Number.isFinite(duration) ? duration : void 0,
-						retainWithoutReference: kindRaw === "voice"
-					}, idempotencyKey);
-				}
-			}
-			const full = await service.notesServiceInstance.getNote(note.id);
-			return c.json({ note: full }, 201);
+			return c.json({ note }, 201);
+		} catch (error) {
+			return capabilityHttpError(c, error);
 		}
-		const body = await c.req.json().catch(() => ({}));
-		const title = typeof body.title === "string" ? body.title.trim() : void 0;
-		const markdown = typeof body.markdown === "string" ? body.markdown.trim() : void 0;
-		const kindRaw = typeof body.kind === "string" ? body.kind : void 0;
-		const tagsRaw = Array.isArray(body.tags) ? body.tags.filter((t) => typeof t === "string") : void 0;
-		const source = parseCaptureSource(body);
-		const projectId = typeof body.projectId === "string" && body.projectId.trim() ? body.projectId.trim() : void 0;
-		if (projectId && !service.projects.get(projectId)) return c.json({ error: "Project not found" }, 400);
-		const note = await service.notesServiceInstance.createNote({
-			title,
-			markdown,
-			kind: kindRaw && VALID_KINDS.has(kindRaw) ? kindRaw : void 0,
-			tags: tagsRaw,
-			capturedVia: source,
-			pinned: body.pinned === true
-		}, idempotencyKey);
-		linkNoteToProject(note, projectId);
-		return c.json({ note }, 201);
 	});
 	authenticated.post("/api/notes/sync", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
@@ -367,15 +365,23 @@ function registerNotesRoutes(authenticated, deps) {
 		const content = typeof body.content === "string" ? body.content.trim() : "";
 		const heading = typeof body.heading === "string" && body.heading.trim() ? body.heading.trim() : void 0;
 		if (!content) return c.json({ error: "Missing required field: content" }, 400);
-		const note = await service.notesServiceInstance.appendTextToNote(c.req.param("id"), content, heading);
-		if (!note) return c.json(noteNotFound(), 404);
-		return c.json({ note });
+		try {
+			return c.json(await invokeNote(c, "xopc.notes.append", {
+				id: c.req.param("id"),
+				content,
+				heading,
+				expectedRevision: body.expectedRevision
+			}, readIdempotencyKey(c.req.header("idempotency-key"))));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.get("/api/notes/:id", async (c) => {
-		const id = c.req.param("id");
-		const note = await service.notesServiceInstance.getNote(id);
-		if (!note) return c.json(noteNotFound(), 404);
-		return c.json({ note });
+		try {
+			return c.json(await capabilities.call("xopc.notes.get", { id: c.req.param("id") }, capabilityHttpContext(c)));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.get("/api/notes/:id/shares", async (c) => {
 		const note = await service.notesServiceInstance.getNote(c.req.param("id"));
@@ -499,51 +505,114 @@ function registerNotesRoutes(authenticated, deps) {
 		const body = await c.req.json().catch(() => ({}));
 		const patch = buildNotePatch(body);
 		const trigger = body.trigger === "ai_edit" || body.trigger === "sync" || body.trigger === "restore" ? body.trigger : "edit";
-		const updated = await service.notesServiceInstance.updateNote(id, patch, trigger);
-		if (!updated) return c.json(noteNotFound(), 404);
-		return c.json({ note: updated });
+		const current = await service.notesServiceInstance.getNote(id);
+		if (!current) return c.json(noteNotFound(), 404);
+		if (c.req.header("idempotency-key") && body.expectedRevision === void 0) return c.json({
+			ok: false,
+			error: {
+				code: "INVALID_INPUT",
+				message: "Idempotent note updates require expectedRevision from the original read"
+			}
+		}, 400);
+		try {
+			return c.json(await invokeNote(c, "xopc.notes.update", {
+				id,
+				patch,
+				trigger,
+				expectedRevision: body.expectedRevision ?? current.remoteVersion ?? 1
+			}, readIdempotencyKey(c.req.header("idempotency-key"))));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.delete("/api/notes/:id", async (c) => {
-		const id = c.req.param("id");
-		const body = await c.req.json().catch(() => ({}));
-		if (!await service.notesServiceInstance.deleteNote(id)) return c.json(noteNotFound(), 404);
-		const revokedShares = body.revokeShares === false ? 0 : await noteShares().revokeForNote(id);
-		return c.json({
-			deleted: true,
-			revokedShares
-		});
+		try {
+			const id = c.req.param("id");
+			const raw = await c.req.text();
+			let body = {};
+			if (raw) {
+				try {
+					body = JSON.parse(raw);
+				} catch {
+					throw new CapabilityError("INVALID_INPUT", "Invalid JSON body");
+				}
+				if (!body || typeof body !== "object" || Array.isArray(body)) throw new CapabilityError("INVALID_INPUT", "Expected an object");
+			}
+			const key = readIdempotencyKey(c.req.header("idempotency-key"));
+			if (key && body.expectedRevision === void 0) throw new CapabilityError("INVALID_INPUT", "Stable retries require the original expectedRevision");
+			let expectedRevision = body.expectedRevision;
+			if (expectedRevision === void 0) {
+				const note = await service.notesServiceInstance.getNote(id);
+				if (!note) throw new CapabilityError("NOT_FOUND", "Note not found");
+				expectedRevision = note.remoteVersion ?? 1;
+			}
+			const caller = capabilityHttpContext(c);
+			const operation = "xopc.notes.delete";
+			return c.json(NoteDeleteOutputSchema.parse(await capabilities.call(operation, {
+				...body,
+				id,
+				expectedRevision
+			}, caller, {
+				...capabilities.describe(operation, caller),
+				idempotencyKey: key ?? randomUUID()
+			})));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.get("/api/notes/:id/history", async (c) => {
-		const id = c.req.param("id");
-		const entries = await service.notesServiceInstance.listNoteHistory(id);
-		return c.json({ entries });
+		try {
+			return c.json(await invokeRead(c, "xopc.notes.history", { id: c.req.param("id") }));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.get("/api/notes/:id/history/:timestamp", async (c) => {
-		const id = c.req.param("id");
-		const timestamp = parseInt(c.req.param("timestamp"), 10);
-		if (!Number.isFinite(timestamp)) return c.json({ error: "Invalid timestamp" }, 400);
-		const snapshot = await service.notesServiceInstance.getNoteSnapshot(id, timestamp);
-		if (!snapshot) return c.json({ error: "Snapshot not found" }, 404);
-		return c.json({ snapshot });
+		try {
+			return c.json(await invokeRead(c, "xopc.notes.snapshot", {
+				id: c.req.param("id"),
+				timestamp: Number(c.req.param("timestamp"))
+			}));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.post("/api/notes/:id/history/restore", async (c) => {
 		const id = c.req.param("id");
 		const body = await c.req.json().catch(() => ({}));
 		const timestamp = typeof body.timestamp === "number" ? body.timestamp : 0;
 		if (!timestamp) return c.json({ error: "Missing required field: timestamp" }, 400);
-		const note = await service.notesServiceInstance.restoreNoteSnapshot(id, timestamp);
-		if (!note) return c.json({ error: "Snapshot or note not found" }, 404);
-		return c.json({ note });
+		const current = await service.notesServiceInstance.getNote(id);
+		if (!current) return c.json(noteNotFound(), 404);
+		if (c.req.header("idempotency-key") && body.expectedRevision === void 0) return c.json({
+			ok: false,
+			error: {
+				code: "INVALID_INPUT",
+				message: "Idempotent restore requires expectedRevision from the original read"
+			}
+		}, 400);
+		try {
+			return c.json(await invokeNote(c, "xopc.notes.restore", {
+				id,
+				timestamp,
+				expectedRevision: body.expectedRevision ?? current.remoteVersion ?? 1
+			}, readIdempotencyKey(c.req.header("idempotency-key"))));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.post("/api/notes/:id/ai/edit", async (c) => {
-		const id = c.req.param("id");
-		const body = await c.req.json().catch(() => ({}));
-		const instruction = typeof body.instruction === "string" ? body.instruction.trim() : "";
-		if (!instruction) return c.json({ error: "Missing required field: instruction" }, 400);
-		const markdown = typeof body.markdown === "string" ? body.markdown : void 0;
-		const result = await service.notesServiceInstance.createAiEditPatch(id, instruction, markdown);
-		if (!result) return c.json(noteNotFound(), 404);
-		return c.json(result);
+		try {
+			const body = await c.req.json().catch(() => {
+				throw new CapabilityError("INVALID_INPUT", "Invalid JSON body");
+			});
+			return c.json(await capabilities.call("xopc.notes.preview_edit", {
+				...body,
+				id: c.req.param("id")
+			}, capabilityHttpContext(c)));
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.post("/api/notes/:id/media", async (c) => {
 		const noteId = c.req.param("id");