@xopcai/xopc 0.0.313 → 0.0.314

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

@@ -1,38 +1,55 @@
-import { createLogger } from "../../../utils/logger/index.js";
-import { init_logger } from "../../../utils/logger.js";
 import { getSqliteDatabase } from "../../../storage/sqlite/transaction.js";
+import { ProductReadContracts, ProjectDeleteOutputSchema, ProjectMilestoneDeleteOutputSchema, ProjectMilestoneOutputSchema, ProjectMutationOutputSchema, ProjectResolveWorkspaceOutputSchema, ProjectUpdateOutputSchema } from "../../../../packages/gateway-contract/src/capabilities.js";
+import { init_src } from "../../../../packages/gateway-contract/src/index.js";
+import { TaskRepository } from "../../../tasks/task-repository.js";
 import { getSessionMetadata } from "../../../storage/sqlite/session-read-repository.js";
 import { loadTranscriptRowsForSession } from "../../../storage/sqlite/transcript-repository.js";
 import "../../../storage/sqlite/index.js";
 import { ActivityService } from "../../../activity/service.js";
 import "../../../activity/index.js";
 import { resolveEffectiveAgentProfile } from "../../../config/agent-profile.js";
-import { ExecutionEnvironmentStore } from "../../../execution-environments/store.js";
+import { TaskReadModelProjector } from "../../../tasks/task-read-model-projector.js";
 import { listKnowledgeItems, writeKnowledgeItem } from "../../../knowledge-memory/repository.js";
 import "../../../knowledge-memory/index.js";
-import { TaskRepository } from "../../../tasks/task-repository.js";
-import { TaskReadModelProjector } from "../../../tasks/task-read-model-projector.js";
-import { TaskApplicationService } from "../../../tasks/task-application-service.js";
+import { CapabilityError } from "../../../capabilities/runtime/errors.js";
+import "../../../capabilities/runtime/dispatcher.js";
 import { ProjectWorkspaceConflictError, ProjectWorkspaceMissingError } from "../../../projects/workspace-project.js";
 import { inferProjectExecutionMode, inferProjectKind } from "../../../projects/project-kind.js";
-import { isValidProjectAgentId, normalizeProjectAgentId, resolveProjectAgentId } from "../../../projects/project-agent.js";
+import { ProjectDeletionBlockedError, ProjectWorkspaceInUseError } from "../../../projects/project-service.js";
+import { resolveProjectAgentId } from "../../../projects/project-agent.js";
 import { inferSuggestedProjectDefaultAgentId } from "../../../projects/project-agent-suggestion.js";
 import { buildProjectLoopOverview } from "../../../projects/project-loop.js";
 import "../../../projects/index.js";
-import { getProjectUnderstandingRun } from "../../../work-discovery/repository.js";
+import { TaskApplicationService } from "../../../tasks/task-application-service.js";
+import { createProductDispatcher } from "../../../capabilities/runtime/product.js";
 import { defineTaskContract } from "../../../tasks/task-contract-definition.js";
 import { ProjectOperatingViewService, summarizeProjectOperatingView } from "../../../tasks/project-operating-view-service.js";
 import "../../../tasks/index.js";
 import { parseActivityIncludeRelated, parseActivityQuery } from "./activity.js";
+import { capabilityHttpContext, capabilityHttpError } from "../../../capabilities/adapters/http.js";
 import { randomUUID } from "node:crypto";
 //#region src/gateway/hono/routes/projects.ts
-init_logger();
-const log = createLogger("Projects");
-function parseProjectStatus(raw) {
-	return raw === "planned" || raw === "active" || raw === "paused" || raw === "completed" || raw === "cancelled" || raw === "archived" ? raw : void 0;
-}
-function parseProjectExecutionMode(raw) {
-	return raw === "local_checkout" || raw === "managed_worktree" ? raw : void 0;
+init_src();
+function projectWriteError(c, error) {
+	const cause = error instanceof CapabilityError ? error.cause : error;
+	if (cause instanceof ProjectWorkspaceConflictError) return c.json({
+		ok: false,
+		code: "workspace_already_bound",
+		error: cause.message,
+		project: cause.project
+	}, 409);
+	if (cause instanceof ProjectWorkspaceMissingError) return c.json({
+		ok: false,
+		code: "workspace_root_missing",
+		error: cause.message,
+		workspaceRoot: cause.workspaceRoot
+	}, 409);
+	if (cause instanceof ProjectWorkspaceInUseError || cause instanceof ProjectDeletionBlockedError) return c.json({
+		ok: false,
+		code: "execution_environments_exist",
+		error: cause.message
+	}, 409);
+	return capabilityHttpError(c, error);
 }
 function parseLimit(raw, fallback = 50) {
 	if (!raw) return void 0;
@@ -43,36 +60,6 @@ function textField(body, key) {
 	const value = body[key];
 	return typeof value === "string" ? value : void 0;
 }
-function optionalTextField(body, key) {
-	if (!(key in body)) return void 0;
-	const value = body[key];
-	return typeof value === "string" ? value : null;
-}
-function stringListField(body, key) {
-	const value = body[key];
-	if (value === void 0) return void 0;
-	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`${key} must be an array of strings`);
-	return value.map((item) => item.trim()).filter(Boolean);
-}
-function objectField(body, key) {
-	const value = body[key];
-	if (value === void 0) return void 0;
-	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${key} must be an object`);
-	return value;
-}
-function optionalNumberField(body, key) {
-	const value = body[key];
-	if (value === void 0) return void 0;
-	if (value === null) return null;
-	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a finite number`);
-	return value;
-}
-function projectHealth(value) {
-	return value === "unknown" || value === "on_track" || value === "at_risk" || value === "off_track" ? value : void 0;
-}
-function milestoneStatus(value) {
-	return value === "planned" || value === "active" || value === "completed" || value === "cancelled" ? value : void 0;
-}
 function resolveEffectiveWorkspaceRoot(service, project) {
 	const fixedRoot = project.workspaceRoot?.trim();
 	if (fixedRoot) return fixedRoot;
@@ -146,113 +133,82 @@ function buildProjectDigestKnowledgeContent(input) {
 }
 function registerProjectsRoutes(authenticated, deps) {
 	const { service } = deps;
+	const capabilities = createProductDispatcher(void 0, {
+		getProjects: () => service.projects,
+		getConfig: () => service.currentConfig,
+		getWorkDiscovery: () => service.workDiscovery
+	});
+	const invokeWrite = (c, operation, input) => {
+		const caller = capabilityHttpContext(c);
+		return capabilities.call(operation, input, caller, {
+			...capabilities.describe(operation, caller),
+			idempotencyKey: c.req.header("idempotency-key") ?? randomUUID()
+		});
+	};
+	const readBody = async (c) => {
+		const body = await c.req.json().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");
+		return body;
+	};
+	const readOptionalBody = async (c) => {
+		const text = await c.req.text();
+		if (!text.length) return {};
+		let body;
+		try {
+			body = JSON.parse(text);
+		} 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");
+		return body;
+	};
+	const milestoneRevision = (c, revision) => {
+		if (revision !== void 0) return revision;
+		if (c.req.header("idempotency-key")) throw new CapabilityError("INVALID_INPUT", "Stable retries require the original expectedRevision");
+		const milestone = service.projects.listMilestones(c.req.param("id")).find((item) => item.id === c.req.param("milestoneId"));
+		if (!milestone) throw new CapabilityError("NOT_FOUND", "Milestone not found");
+		return milestone.updatedAt;
+	};
 	const activity = new ActivityService();
 	const operatingViews = new ProjectOperatingViewService(service.projects);
-	const environments = new ExecutionEnvironmentStore();
 	authenticated.post("/api/projects", async (c) => {
-		const body = await c.req.json().catch(() => ({}));
-		const name = textField(body, "name")?.trim();
-		const workspaceRoot = textField(body, "workspaceRoot")?.trim();
-		if (body.autoUnderstand !== void 0 && typeof body.autoUnderstand !== "boolean") return c.json({
-			ok: false,
-			error: "autoUnderstand must be a boolean"
-		}, 400);
-		if (!name && !workspaceRoot) return c.json({
-			ok: false,
-			error: "Missing name"
-		}, 400);
-		const executionMode = parseProjectExecutionMode(body.executionMode);
-		if (body.executionMode !== void 0 && !executionMode) return c.json({
-			ok: false,
-			error: "Invalid project execution mode"
-		}, 400);
-		const hasDefaultAgentPatch = Object.hasOwn(body, "defaultAgentId");
-		const explicitDefaultAgentId = normalizeProjectAgentId(textField(body, "defaultAgentId"));
-		const defaultAgentId = hasDefaultAgentPatch ? explicitDefaultAgentId : inferSuggestedProjectDefaultAgentId({
-			config: service.currentConfig,
-			name,
-			description: textField(body, "description"),
-			workspaceRoot,
-			projectKind: textField(body, "projectKind")
-		});
-		if (!isValidProjectAgentId(service.currentConfig, defaultAgentId)) return c.json({
-			ok: false,
-			error: "Default agent not found"
-		}, 400);
 		try {
-			const project = service.projects.create({
-				name,
-				description: textField(body, "description"),
-				defaultAgentId,
-				workspaceRoot,
-				createWorkspaceRoot: body.createWorkspaceRoot === true,
-				projectKind: textField(body, "projectKind"),
-				executionMode,
-				brief: textField(body, "brief"),
-				instructions: textField(body, "instructions"),
-				outcome: textField(body, "outcome"),
-				successCriteria: stringListField(body, "successCriteria"),
-				scope: objectField(body, "scope"),
-				nonGoals: stringListField(body, "nonGoals"),
-				health: projectHealth(body.health),
-				ownerId: textField(body, "ownerId"),
-				targetAt: optionalNumberField(body, "targetAt") ?? void 0
-			});
-			if (body.autoUnderstand === true) try {
-				deps.service.workDiscovery.startProjectUnderstanding(project.id);
-			} catch (err) {
-				log.warn({
-					err,
-					projectId: project.id
-				}, "Project created but understanding could not be queued");
-			}
+			const { project } = ProjectMutationOutputSchema.parse(await invokeWrite(c, "xopc.projects.create", await readBody(c)));
 			return c.json({
 				ok: true,
 				project: enrichProjectWorkspace(service, project)
 			}, 201);
 		} catch (error) {
-			if (error instanceof ProjectWorkspaceConflictError) return c.json({
-				ok: false,
-				code: "workspace_already_bound",
-				error: error.message,
-				project: error.project
-			}, 409);
-			if (error instanceof ProjectWorkspaceMissingError) return c.json({
-				ok: false,
-				code: "workspace_root_missing",
-				error: error.message,
-				workspaceRoot: error.workspaceRoot
-			}, 409);
-			return c.json({
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			}, 400);
+			return projectWriteError(c, error);
 		}
 	});
 	authenticated.get("/api/projects", async (c) => {
-		const status = parseProjectStatus(c.req.query("status"));
-		const result = service.projects.list({
-			...status ? { status } : {},
-			search: c.req.query("search"),
-			sortBy: c.req.query("sortBy"),
-			sortOrder: c.req.query("sortOrder"),
-			limit: parseLimit(c.req.query("limit")),
-			offset: c.req.query("offset") ? Math.max(0, Number.parseInt(c.req.query("offset"), 10) || 0) : void 0
-		});
-		const includeOperating = c.req.query("includeOperating") === "true";
-		return c.json({
-			ok: true,
-			...result,
-			items: result.items.map((project) => {
-				const enriched = enrichProjectWorkspace(service, project);
-				if (!includeOperating) return enriched;
-				const view = operatingViews.get(project.id);
-				return {
-					...enriched,
-					operating: view ? summarizeProjectOperatingView(view) : void 0
-				};
-			})
-		});
+		try {
+			const { includeOperating: _includeOperating, ...input } = c.req.query();
+			const result = ProductReadContracts["xopc.projects.list"].output.parse(await capabilities.call("xopc.projects.list", {
+				...input,
+				limit: input.limit === void 0 ? void 0 : Number(input.limit),
+				offset: input.offset === void 0 ? void 0 : Number(input.offset)
+			}, capabilityHttpContext(c)));
+			const includeOperating = c.req.query("includeOperating") === "true";
+			return c.json({
+				ok: true,
+				...result,
+				items: result.items.map((project) => {
+					const enriched = enrichProjectWorkspace(service, project);
+					if (!includeOperating) return enriched;
+					const view = operatingViews.get(project.id);
+					return {
+						...enriched,
+						operating: view ? summarizeProjectOperatingView(view) : void 0
+					};
+				})
+			});
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.get("/api/projects/suggestions", async (c) => {
 		const conversationId = c.req.query("conversationId")?.trim();
@@ -283,61 +239,16 @@ function registerProjectsRoutes(authenticated, deps) {
 		});
 	});
 	authenticated.post("/api/projects/resolve-workspace", async (c) => {
-		const body = await c.req.json().catch(() => ({}));
-		const workspacePath = textField(body, "workspacePath")?.trim();
-		if (!workspacePath) return c.json({
-			ok: false,
-			error: "Missing workspacePath"
-		}, 400);
-		const agentId = textField(body, "agentId")?.trim() || "main";
-		const suggestedDefaultAgentId = inferSuggestedProjectDefaultAgentId({
-			config: service.currentConfig,
-			workspaceRoot: workspacePath,
-			projectKind: textField(body, "projectKind")
-		});
-		let match;
 		try {
-			match = service.projects.resolveOrCreateForWorkspacePath({
-				workspacePath,
-				agentId,
-				defaultAgentId: suggestedDefaultAgentId,
-				autoCreate: body.autoCreate !== false
-			});
+			const body = await readBody(c);
+			return c.json(ProjectResolveWorkspaceOutputSchema.parse(await invokeWrite(c, "xopc.projects.resolve_workspace", {
+				...body,
+				agentId: body.agentId ?? "main",
+				autoCreate: body.autoCreate ?? true
+			})));
 		} catch (error) {
-			if (error instanceof ProjectWorkspaceConflictError) match = {
-				project: error.project,
-				reason: "exact",
-				created: false
-			};
-			else throw error;
-		}
-		if (!match) return c.json({
-			ok: true,
-			project: null
-		});
-		const conversationId = textField(body, "conversationId")?.trim();
-		const projectDefaultAgentId = normalizeProjectAgentId(match.project.defaultAgentId);
-		const shouldBindRequestedSession = !projectDefaultAgentId || projectDefaultAgentId === normalizeProjectAgentId(agentId);
-		if (conversationId && shouldBindRequestedSession) {
-			if (!getSessionMetadata(conversationId)) await service.sessionIndexInstance.saveMessages(conversationId, [], { metadata: {
-				sourceChannel: "tui",
-				sourceChatId: `default:direct:${conversationId}`,
-				sessionType: "chat",
-				projectId: match.project.id,
-				routing: {
-					agentId,
-					source: "tui",
-					accountId: "default",
-					peerKind: "direct",
-					peerId: conversationId
-				}
-			} });
-			service.projects.attachSession(conversationId, match.project.id);
+			return projectWriteError(c, error);
 		}
-		return c.json({
-			ok: true,
-			...match
-		});
 	});
 	authenticated.get("/api/projects/:id/activity", (c) => {
 		const project = service.projects.get(c.req.param("id"));
@@ -474,245 +385,177 @@ function registerProjectsRoutes(authenticated, deps) {
 			blocker: blocked.ok ? blocked.model : created.model
 		}, 201);
 	});
-	authenticated.post("/api/projects/:id/pin", async (c) => {
+	for (const [action, pinned] of [["pin", true], ["unpin", false]]) authenticated.post(`/api/projects/:id/${action}`, async (c) => {
 		try {
-			const project = service.projects.pin(c.req.param("id"));
+			const body = await readOptionalBody(c);
+			if (Object.keys(body).some((key) => key !== "expectedVersion")) throw new CapabilityError("INVALID_INPUT", "Unexpected pin input");
+			if (body.expectedVersion === void 0 && c.req.header("idempotency-key")) throw new CapabilityError("INVALID_INPUT", "Stable retries require the original expectedVersion");
+			const id = c.req.param("id");
+			const project = body.expectedVersion === void 0 ? service.projects.get(id) : void 0;
+			if (body.expectedVersion === void 0 && !project) throw new CapabilityError("NOT_FOUND", "Project not found");
+			const result = ProjectMutationOutputSchema.parse(await invokeWrite(c, "xopc.projects.set_pinned", {
+				id,
+				pinned,
+				expectedVersion: body.expectedVersion ?? project?.version
+			}));
 			return c.json({
 				ok: true,
-				project: enrichProjectWorkspace(service, project)
+				project: enrichProjectWorkspace(service, result.project)
 			});
 		} catch (error) {
-			return c.json({
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			}, 404);
+			return capabilityHttpError(c, error);
 		}
 	});
-	authenticated.post("/api/projects/:id/unpin", async (c) => {
+	authenticated.get("/api/projects/:id", async (c) => {
 		try {
-			const project = service.projects.unpin(c.req.param("id"));
+			const { project } = ProductReadContracts["xopc.projects.get"].output.parse(await capabilities.call("xopc.projects.get", { id: c.req.param("id") }, capabilityHttpContext(c)));
 			return c.json({
 				ok: true,
 				project: enrichProjectWorkspace(service, project)
 			});
 		} catch (error) {
-			return c.json({
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			}, 404);
+			return capabilityHttpError(c, error);
 		}
 	});
-	authenticated.get("/api/projects/:id", async (c) => {
-		const project = service.projects.getWithDetails(c.req.param("id"));
-		if (!project) return c.json({
-			ok: false,
-			error: "Project not found"
-		}, 404);
-		return c.json({
-			ok: true,
-			project: enrichProjectWorkspace(service, project)
-		});
-	});
-	authenticated.get("/api/projects/:id/milestones", (c) => {
-		const project = service.projects.get(c.req.param("id"));
-		if (!project) return c.json({
-			ok: false,
-			error: "Project not found"
-		}, 404);
-		return c.json({
-			ok: true,
-			items: service.projects.listMilestones(project.id)
-		});
+	authenticated.get("/api/projects/:id/milestones", async (c) => {
+		try {
+			const { items } = ProductReadContracts["xopc.projects.list_milestones"].output.parse(await capabilities.call("xopc.projects.list_milestones", { id: c.req.param("id") }, capabilityHttpContext(c)));
+			return c.json({
+				ok: true,
+				items
+			});
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.post("/api/projects/:id/milestones", async (c) => {
-		const body = await c.req.json().catch(() => ({}));
-		const title = textField(body, "title")?.trim();
-		if (!title) return c.json({
-			ok: false,
-			error: "Missing title"
-		}, 400);
-		if (body.status !== void 0 && !milestoneStatus(body.status)) return c.json({
-			ok: false,
-			error: "Invalid milestone status"
-		}, 400);
 		try {
-			const milestone = service.projects.createMilestone(c.req.param("id"), {
-				title,
-				description: textField(body, "description"),
-				status: milestoneStatus(body.status),
-				targetAt: optionalNumberField(body, "targetAt") ?? void 0,
-				sortOrder: optionalNumberField(body, "sortOrder") ?? void 0
-			});
+			const body = await readBody(c);
+			const { milestone } = ProjectMilestoneOutputSchema.parse(await invokeWrite(c, "xopc.projects.create_milestone", {
+				...body,
+				projectId: c.req.param("id")
+			}));
 			return c.json({
 				ok: true,
 				milestone
 			}, 201);
 		} catch (error) {
-			return c.json({
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			}, 400);
+			return capabilityHttpError(c, error);
 		}
 	});
 	authenticated.patch("/api/projects/:id/milestones/:milestoneId", async (c) => {
-		const body = await c.req.json().catch(() => ({}));
-		if (body.status !== void 0 && !milestoneStatus(body.status)) return c.json({
-			ok: false,
-			error: "Invalid milestone status"
-		}, 400);
 		try {
-			const milestone = service.projects.updateMilestone(c.req.param("id"), c.req.param("milestoneId"), {
-				...textField(body, "title") !== void 0 ? { title: textField(body, "title") } : {},
-				...optionalTextField(body, "description") !== void 0 ? { description: optionalTextField(body, "description") } : {},
-				...body.status !== void 0 ? { status: milestoneStatus(body.status) } : {},
-				...body.targetAt !== void 0 ? { targetAt: optionalNumberField(body, "targetAt") } : {},
-				...body.sortOrder !== void 0 ? { sortOrder: optionalNumberField(body, "sortOrder") } : {}
-			});
+			const { expectedRevision, ...patch } = await readBody(c);
+			const { milestone } = ProjectMilestoneOutputSchema.parse(await invokeWrite(c, "xopc.projects.update_milestone", {
+				projectId: c.req.param("id"),
+				id: c.req.param("milestoneId"),
+				expectedRevision: milestoneRevision(c, expectedRevision),
+				patch
+			}));
 			return c.json({
 				ok: true,
 				milestone
 			});
 		} catch (error) {
-			return c.json({
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			}, 404);
+			return capabilityHttpError(c, error);
 		}
 	});
-	authenticated.delete("/api/projects/:id/milestones/:milestoneId", (c) => {
-		return service.projects.deleteMilestone(c.req.param("id"), c.req.param("milestoneId")) ? c.json({ ok: true }) : c.json({
-			ok: false,
-			error: "Milestone not found"
-		}, 404);
+	authenticated.delete("/api/projects/:id/milestones/:milestoneId", async (c) => {
+		try {
+			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");
+			}
+			ProjectMilestoneDeleteOutputSchema.parse(await invokeWrite(c, "xopc.projects.delete_milestone", {
+				projectId: c.req.param("id"),
+				id: c.req.param("milestoneId"),
+				expectedRevision: milestoneRevision(c, body.expectedRevision)
+			}));
+			return c.json({ ok: true });
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
-	authenticated.get("/api/projects/:id/updates", (c) => {
-		const project = service.projects.get(c.req.param("id"));
-		if (!project) return c.json({
-			ok: false,
-			error: "Project not found"
-		}, 404);
-		return c.json({
-			ok: true,
-			items: service.projects.listUpdates(project.id, parseLimit(c.req.query("limit"), 20))
-		});
+	authenticated.get("/api/projects/:id/updates", async (c) => {
+		try {
+			const { items } = ProductReadContracts["xopc.projects.list_updates"].output.parse(await capabilities.call("xopc.projects.list_updates", {
+				id: c.req.param("id"),
+				limit: c.req.query("limit") === void 0 ? void 0 : Number(c.req.query("limit"))
+			}, capabilityHttpContext(c)));
+			return c.json({
+				ok: true,
+				items
+			});
+		} catch (error) {
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.post("/api/projects/:id/updates", async (c) => {
-		const body = await c.req.json().catch(() => ({}));
-		const summary = textField(body, "summary")?.trim();
-		const health = projectHealth(body.health);
-		if (!summary || !health) return c.json({
-			ok: false,
-			error: "Missing summary or valid health"
-		}, 400);
 		try {
-			const update = service.projects.createUpdate(c.req.param("id"), {
-				health,
-				summary,
-				progress: stringListField(body, "progress"),
-				risks: stringListField(body, "risks"),
-				nextSteps: stringListField(body, "nextSteps"),
-				actor: objectField(body, "actor") ?? { kind: "user" }
-			});
+			const body = await readBody(c);
+			if (c.req.header("idempotency-key") && body.expectedVersion === void 0) throw new CapabilityError("INVALID_INPUT", "Stable retries require the original expectedVersion");
+			const project = service.projects.get(c.req.param("id"));
+			if (!project && body.expectedVersion === void 0) throw new CapabilityError("NOT_FOUND", "Project not found");
+			const { update } = ProjectUpdateOutputSchema.parse(await invokeWrite(c, "xopc.projects.create_update", {
+				...body,
+				projectId: c.req.param("id"),
+				expectedVersion: body.expectedVersion === void 0 ? project?.version : body.expectedVersion
+			}));
 			return c.json({
 				ok: true,
 				update
 			}, 201);
 		} catch (error) {
-			return c.json({
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			}, 400);
+			return capabilityHttpError(c, error);
 		}
 	});
 	authenticated.patch("/api/projects/:id", async (c) => {
-		const body = await c.req.json().catch(() => ({}));
-		const projectId = c.req.param("id");
-		const status = parseProjectStatus(body.status);
-		const defaultAgentPatch = optionalTextField(body, "defaultAgentId");
-		const defaultAgentId = defaultAgentPatch === void 0 ? void 0 : normalizeProjectAgentId(defaultAgentPatch);
-		if (body.status !== void 0 && !status) return c.json({
-			ok: false,
-			error: "Invalid project status"
-		}, 400);
-		if (body.health !== void 0 && !projectHealth(body.health)) return c.json({
-			ok: false,
-			error: "Invalid project health"
-		}, 400);
-		const executionMode = parseProjectExecutionMode(body.executionMode);
-		if (body.executionMode !== void 0 && !executionMode) return c.json({
-			ok: false,
-			error: "Invalid project execution mode"
-		}, 400);
-		if (defaultAgentId && !isValidProjectAgentId(service.currentConfig, defaultAgentId)) return c.json({
-			ok: false,
-			error: "Default agent not found"
-		}, 400);
-		const currentProject = service.projects.get(projectId);
-		const requestedWorkspaceRoot = optionalTextField(body, "workspaceRoot");
-		if (currentProject && requestedWorkspaceRoot !== void 0 && requestedWorkspaceRoot !== (currentProject.workspaceRoot ?? null) && environments.list({
-			projectId,
-			limit: 1
-		}).length > 0) return c.json({
-			ok: false,
-			code: "execution_environments_exist",
-			error: "Delete the project execution environments before changing its workspace"
-		}, 409);
 		try {
-			const project = service.projects.update(projectId, {
-				...textField(body, "name") !== void 0 ? { name: textField(body, "name") } : {},
-				...optionalTextField(body, "description") !== void 0 ? { description: optionalTextField(body, "description") } : {},
-				...status ? { status } : {},
-				...defaultAgentPatch !== void 0 ? { defaultAgentId: defaultAgentId ?? null } : {},
-				...optionalTextField(body, "workspaceRoot") !== void 0 ? { workspaceRoot: optionalTextField(body, "workspaceRoot") } : {},
-				createWorkspaceRoot: body.createWorkspaceRoot === true,
-				...executionMode ? { executionMode } : {},
-				...optionalTextField(body, "brief") !== void 0 ? { brief: optionalTextField(body, "brief") } : {},
-				...optionalTextField(body, "instructions") !== void 0 ? { instructions: optionalTextField(body, "instructions") } : {},
-				...optionalTextField(body, "outcome") !== void 0 ? { outcome: optionalTextField(body, "outcome") } : {},
-				...body.successCriteria !== void 0 ? { successCriteria: stringListField(body, "successCriteria") } : {},
-				...body.scope !== void 0 ? { scope: objectField(body, "scope") } : {},
-				...body.nonGoals !== void 0 ? { nonGoals: stringListField(body, "nonGoals") } : {},
-				...body.health !== void 0 ? { health: projectHealth(body.health) } : {},
-				...optionalTextField(body, "ownerId") !== void 0 ? { ownerId: optionalTextField(body, "ownerId") } : {},
-				...body.targetAt !== void 0 ? { targetAt: optionalNumberField(body, "targetAt") } : {}
-			});
+			const { expectedVersion, ...patch } = await readBody(c);
+			if (expectedVersion === void 0 && c.req.header("idempotency-key")) throw new CapabilityError("INVALID_INPUT", "Stable retries require the original expectedVersion");
+			const id = c.req.param("id");
+			const current = expectedVersion === void 0 ? service.projects.get(id) : void 0;
+			if (expectedVersion === void 0 && !current) throw new CapabilityError("NOT_FOUND", "Project not found");
+			const { project } = ProjectMutationOutputSchema.parse(await invokeWrite(c, "xopc.projects.update", {
+				id,
+				expectedVersion: expectedVersion === void 0 ? current?.version : expectedVersion,
+				patch
+			}));
 			return c.json({
 				ok: true,
 				project: enrichProjectWorkspace(service, project)
 			});
 		} catch (error) {
-			if (error instanceof ProjectWorkspaceConflictError) return c.json({
-				ok: false,
-				code: "workspace_already_bound",
-				error: error.message,
-				project: error.project
-			}, 409);
-			if (error instanceof ProjectWorkspaceMissingError) return c.json({
-				ok: false,
-				code: "workspace_root_missing",
-				error: error.message,
-				workspaceRoot: error.workspaceRoot
-			}, 409);
-			return c.json({
-				ok: false,
-				error: error instanceof Error ? error.message : String(error)
-			}, 404);
+			return projectWriteError(c, error);
 		}
 	});
 	authenticated.delete("/api/projects/:id", async (c) => {
-		const projectId = c.req.param("id");
-		if (environments.list({
-			projectId,
-			limit: 1
-		}).length > 0) return c.json({
-			ok: false,
-			code: "execution_environments_exist",
-			error: "Delete the project execution environments before deleting the project"
-		}, 409);
-		const understandingRun = getProjectUnderstandingRun(projectId);
-		if (understandingRun) deps.service.workDiscovery.cancelRun(understandingRun.id);
-		service.projects.delete(projectId);
-		return c.json({ ok: true });
+		try {
+			const body = await readOptionalBody(c);
+			if (Object.keys(body).some((key) => key !== "expectedVersion")) throw new CapabilityError("INVALID_INPUT", "Unexpected delete input");
+			if (body.expectedVersion === void 0 && c.req.header("idempotency-key")) throw new CapabilityError("INVALID_INPUT", "Stable retries require the original expectedVersion");
+			const id = c.req.param("id");
+			const project = body.expectedVersion === void 0 ? service.projects.get(id) : void 0;
+			if (body.expectedVersion === void 0 && !project) throw new CapabilityError("NOT_FOUND", "Project not found");
+			const result = ProjectDeleteOutputSchema.parse(await invokeWrite(c, "xopc.projects.delete", {
+				id,
+				expectedVersion: body.expectedVersion === void 0 ? project?.version : body.expectedVersion
+			}));
+			return c.json(result);
+		} catch (error) {
+			if (error instanceof CapabilityError && error.cause instanceof ProjectDeletionBlockedError) return c.json({
+				ok: false,
+				code: "execution_environments_exist",
+				error: error.message
+			}, 409);
+			return capabilityHttpError(c, error);
+		}
 	});
 	authenticated.get("/api/projects/:id/sessions", async (c) => {
 		try {