@xopcai/xopc 0.0.123 → 0.0.125

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

@@ -1,3 +1,4 @@
+import { buildSessionKey, init_session_key } from "../../../routing/session-key.js";
 import { getSqliteDatabase } from "../../../storage/sqlite/transaction.js";
 import { GoalService } from "../../../goals/goal-service.js";
 import "../../../goals/index.js";
@@ -7,12 +8,18 @@ import { listMemoryRecords, upsertMemoryRecord } from "../../../storage/sqlite/m
 import "../../../storage/sqlite/index.js";
 import { ProjectWorkspaceConflictError, ProjectWorkspaceMissingError } from "../../../projects/workspace-project.js";
 import { isValidProjectAgentId, normalizeProjectAgentId, resolveProjectAgentId } from "../../../projects/project-agent.js";
+import { inferProjectKind } from "../../../projects/project-kind.js";
+import { inferSuggestedProjectDefaultAgentId } from "../../../projects/project-agent-suggestion.js";
 import { buildProjectLoopOverview } from "../../../projects/project-loop.js";
 import "../../../projects/index.js";
+import { WORK_ITEM_ATTACHMENT_MAX_BYTES, WorkItemService } from "../../../work-items/work-item-service.js";
+import { buildWorkItemAgentContext } from "../../../work-items/agent-context.js";
+import "../../../work-items/index.js";
 import { createGatewayRouteLogger } from "../lib/route-logger.js";
 import * as path$1 from "node:path";
-import { readdir, realpath, stat } from "node:fs/promises";
+import { readFile, readdir, realpath, stat, writeFile } from "node:fs/promises";
 //#region src/gateway/hono/routes/projects.ts
+init_session_key();
 const log = createGatewayRouteLogger("Projects");
 function parseProjectStatus(raw) {
 	return raw === "active" || raw === "paused" || raw === "archived" ? raw : void 0;
@@ -22,6 +29,9 @@ function parseLimit(raw, fallback = 50) {
 	const n = Number.parseInt(raw, 10);
 	return Number.isFinite(n) ? Math.min(500, Math.max(1, n)) : fallback;
 }
+function isHiddenEmptyProjectChatShell(session) {
+	return session.hiddenFromSessionList === true && session.messageCount === 0 && session.customData?.genericNewChatShell !== false && Boolean(session.routing?.peerId?.startsWith("chat_"));
+}
 function textField(body, key) {
 	const value = body[key];
 	return typeof value === "string" ? value : void 0;
@@ -31,7 +41,87 @@ function optionalTextField(body, key) {
 	const value = body[key];
 	return typeof value === "string" ? value : null;
 }
+function finiteNumberField(value) {
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (typeof value === "string" && value.trim()) {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+function collectUploadedFiles(body) {
+	const raw = body.file ?? body.files ?? body.attachments;
+	return (Array.isArray(raw) ? raw : raw ? [raw] : []).filter((value) => value instanceof File);
+}
+function validateUploadedWorkItemFiles(files) {
+	if (files.length > 10) return `Too many attachments (max 10)`;
+	for (const file of files) if (file.size > 26214400) return `Attachment ${JSON.stringify(file.name || "upload")} exceeds ${Math.floor(WORK_ITEM_ATTACHMENT_MAX_BYTES / (1024 * 1024))}MB limit`;
+	return null;
+}
+async function uploadedFileToBuffer(file) {
+	return {
+		name: file.name || "upload",
+		buffer: Buffer.from(await file.arrayBuffer()),
+		mimeType: file.type || "application/octet-stream"
+	};
+}
+function parseCsvEnum(raw, values) {
+	if (!raw) return void 0;
+	const allowed = new Set(values);
+	const parsed = raw.split(",").map((item) => item.trim()).filter((item) => allowed.has(item));
+	return parsed.length > 0 ? [...new Set(parsed)] : void 0;
+}
+function parseEnumValue(raw, values) {
+	if (typeof raw !== "string") return void 0;
+	return values.includes(raw) ? raw : void 0;
+}
+const WORK_ITEM_STATUSES = [
+	"backlog",
+	"todo",
+	"in_progress",
+	"blocked",
+	"needs_input",
+	"in_review",
+	"done",
+	"cancelled"
+];
+const WORK_ITEM_PRIORITIES = [
+	"urgent",
+	"high",
+	"normal",
+	"low"
+];
+const WORK_ITEM_SUGGESTION_STATUSES = [
+	"pending",
+	"applied",
+	"dismissed"
+];
 const SKIP_FILE_NAMES = new Set([".git", "node_modules"]);
+const PROJECT_FILE_MIME_BY_EXT = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	webp: "image/webp",
+	bmp: "image/bmp",
+	svg: "image/svg+xml",
+	pdf: "application/pdf",
+	docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+	xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+	pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+	txt: "text/plain",
+	md: "text/markdown",
+	json: "application/json",
+	html: "text/html",
+	css: "text/css",
+	js: "text/javascript",
+	ts: "text/typescript",
+	mp3: "audio/mpeg",
+	wav: "audio/wav",
+	ogg: "audio/ogg",
+	webm: "video/webm",
+	mp4: "video/mp4",
+	mov: "video/quicktime"
+};
 function normalizeRelativePath(raw) {
 	return (raw ?? "").trim().replaceAll("\\", "/").replace(/^\/+/, "");
 }
@@ -39,6 +129,136 @@ function isWithinDirectory(root, target) {
 	const relativePath = path$1.relative(root, target);
 	return relativePath === "" || !relativePath.startsWith("..") && !path$1.isAbsolute(relativePath);
 }
+async function resolveProjectWorkspaceRoot(service, projectId) {
+	const project = service.projects.get(projectId);
+	if (!project) return {
+		ok: false,
+		status: 404,
+		error: "Project not found"
+	};
+	if (!project.workspaceRoot?.trim()) return {
+		ok: false,
+		status: 400,
+		error: "Project workspace root is not set"
+	};
+	try {
+		const root = await realpath(project.workspaceRoot);
+		if (!(await stat(root)).isDirectory()) return {
+			ok: false,
+			status: 400,
+			error: "Project workspace root is not a directory"
+		};
+		return {
+			ok: true,
+			projectId: project.id,
+			root
+		};
+	} catch (err) {
+		log.warn({
+			err,
+			projectId: project.id,
+			path: project.workspaceRoot
+		}, "project workspace root unavailable");
+		return {
+			ok: false,
+			status: 404,
+			error: "Project workspace root is unavailable"
+		};
+	}
+}
+async function resolveProjectWorkspacePath(service, projectId, rawPath) {
+	const rootResult = await resolveProjectWorkspaceRoot(service, projectId);
+	if (rootResult.ok === false) return {
+		ok: false,
+		status: rootResult.status,
+		error: rootResult.error
+	};
+	const requestedPath = normalizeRelativePath(rawPath);
+	const candidate = path$1.resolve(rootResult.root, requestedPath);
+	if (!isWithinDirectory(rootResult.root, candidate)) return {
+		ok: false,
+		status: 400,
+		error: "Path is outside project workspace"
+	};
+	const relativePath = path$1.relative(rootResult.root, candidate).split(path$1.sep).join("/");
+	return {
+		ok: true,
+		projectId: rootResult.projectId,
+		root: rootResult.root,
+		requestedPath,
+		absolutePath: candidate,
+		relativePath: relativePath === "." ? "" : relativePath
+	};
+}
+async function resolveExistingProjectWorkspacePath(service, projectId, rawPath) {
+	const resolved = await resolveProjectWorkspacePath(service, projectId, rawPath);
+	if (resolved.ok === false) return resolved;
+	if (!resolved.requestedPath.trim()) return {
+		ok: false,
+		status: 400,
+		error: "Missing path"
+	};
+	let realTarget;
+	try {
+		realTarget = await realpath(resolved.absolutePath);
+	} catch {
+		return {
+			ok: false,
+			status: 404,
+			error: "Not found"
+		};
+	}
+	if (!isWithinDirectory(resolved.root, realTarget)) return {
+		ok: false,
+		status: 400,
+		error: "Path is outside project workspace"
+	};
+	const targetStat = await stat(realTarget);
+	return {
+		...resolved,
+		absolutePath: realTarget,
+		stat: targetStat
+	};
+}
+async function resolveProjectWorkspaceWritePath(service, projectId, rawPath) {
+	const resolved = await resolveProjectWorkspacePath(service, projectId, rawPath);
+	if (resolved.ok === false) return resolved;
+	if (!resolved.requestedPath.trim()) return {
+		ok: false,
+		status: 400,
+		error: "Missing path"
+	};
+	try {
+		const realTarget = await realpath(resolved.absolutePath);
+		if (!isWithinDirectory(resolved.root, realTarget)) return {
+			ok: false,
+			status: 400,
+			error: "Path is outside project workspace"
+		};
+		return {
+			...resolved,
+			absolutePath: realTarget,
+			existingStat: await stat(realTarget)
+		};
+	} catch {
+		const parentPath = path$1.dirname(resolved.absolutePath);
+		try {
+			const realParent = await realpath(parentPath);
+			if (!isWithinDirectory(resolved.root, realParent)) return {
+				ok: false,
+				status: 400,
+				error: "Path is outside project workspace"
+			};
+		} catch {
+			return {
+				ok: false,
+				status: 404,
+				error: "Parent directory not found"
+			};
+		}
+		return resolved;
+	}
+}
 function textFromTranscriptContent(content) {
 	if (typeof content === "string") return content;
 	if (!Array.isArray(content)) return "";
@@ -64,6 +284,36 @@ function buildSessionSummaryMemoryContent(sessionKey, explicitSummary) {
 	}).filter(Boolean);
 	return lines.length > 0 ? [`Session summary for ${sessionKey}:`, ...lines].join("\n") : `Session summary for ${sessionKey}: no transcript content available.`;
 }
+function buildWorkItemChatSessionMetadata(params) {
+	return {
+		name: params.title,
+		tags: ["work-item"],
+		sourceChannel: "webchat",
+		sourceChatId: [
+			params.accountId,
+			"direct",
+			params.peerId
+		].join(":"),
+		sessionType: "chat",
+		hiddenFromSessionList: true,
+		routing: {
+			agentId: params.agentId,
+			source: "webchat",
+			accountId: params.accountId,
+			peerKind: "direct",
+			peerId: params.peerId
+		},
+		customData: {
+			genericNewChatShell: false,
+			sourceBinding: {
+				kind: "work_item",
+				sourceId: params.workItemId,
+				version: String(params.updatedAt),
+				attachedAt: Date.now()
+			}
+		}
+	};
+}
 function listFailedProjectWorkflowRuns(projectId, limit = 5) {
 	return getSqliteDatabase().prepare(`SELECT run_id, definition_id, status, created_at_ms, error_message
        FROM workflow_runs
@@ -99,6 +349,7 @@ function projectDigestMemoryRecordId(projectId) {
 function registerProjectsRoutes(authenticated, deps) {
 	const { service } = deps;
 	const goals = new GoalService();
+	const workItems = new WorkItemService();
 	authenticated.post("/api/projects", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
 		const name = textField(body, "name")?.trim();
@@ -107,7 +358,15 @@ function registerProjectsRoutes(authenticated, deps) {
 			ok: false,
 			error: "Missing name"
 		}, 400);
-		const defaultAgentId = normalizeProjectAgentId(textField(body, "defaultAgentId"));
+		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"
@@ -119,6 +378,7 @@ function registerProjectsRoutes(authenticated, deps) {
 				defaultAgentId,
 				workspaceRoot,
 				createWorkspaceRoot: body.createWorkspaceRoot === true,
+				projectKind: textField(body, "projectKind"),
 				brief: textField(body, "brief"),
 				instructions: textField(body, "instructions")
 			});
@@ -167,6 +427,25 @@ function registerProjectsRoutes(authenticated, deps) {
 			suggestions: sessionKey ? service.projects.suggestProjectsForSession(sessionKey) : []
 		});
 	});
+	authenticated.post("/api/projects/infer-defaults", async (c) => {
+		const body = await c.req.json().catch(() => ({}));
+		const input = {
+			name: textField(body, "name"),
+			description: textField(body, "description"),
+			workspaceRoot: textField(body, "workspaceRoot"),
+			projectKind: textField(body, "projectKind")
+		};
+		const inference = inferProjectKind(input);
+		const defaultAgentId = inferSuggestedProjectDefaultAgentId({
+			config: service.currentConfig,
+			...input
+		});
+		return c.json({
+			ok: true,
+			inference,
+			defaultAgentId
+		});
+	});
 	authenticated.post("/api/projects/resolve-workspace", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
 		const workspacePath = textField(body, "workspacePath")?.trim();
@@ -175,11 +454,17 @@ function registerProjectsRoutes(authenticated, deps) {
 			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
 			});
 		} catch (error) {
@@ -195,7 +480,9 @@ function registerProjectsRoutes(authenticated, deps) {
 			project: null
 		});
 		const sessionKey = textField(body, "sessionKey")?.trim();
-		if (sessionKey) {
+		const projectDefaultAgentId = normalizeProjectAgentId(match.project.defaultAgentId);
+		const shouldBindRequestedSession = !projectDefaultAgentId || projectDefaultAgentId === normalizeProjectAgentId(agentId);
+		if (sessionKey && shouldBindRequestedSession) {
 			if (!getSessionMetadata(sessionKey)) await service.sessionIndexInstance.saveMessages(sessionKey, [], { metadata: {
 				sourceChannel: "tui",
 				sourceChatId: `default:direct:${sessionKey}`,
@@ -260,6 +547,413 @@ function registerProjectsRoutes(authenticated, deps) {
 			}
 		});
 	});
+	authenticated.get("/api/projects/:id/work-items", async (c) => {
+		const project = service.projects.get(c.req.param("id"));
+		if (!project) return c.json({
+			ok: false,
+			error: "Project not found"
+		}, 404);
+		const result = workItems.listProjectWorkItems(project.id, {
+			status: parseCsvEnum(c.req.query("status"), WORK_ITEM_STATUSES),
+			priority: parseCsvEnum(c.req.query("priority"), WORK_ITEM_PRIORITIES),
+			includeArchived: c.req.query("includeArchived") === "true",
+			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
+		});
+		return c.json({
+			ok: true,
+			...result
+		});
+	});
+	authenticated.post("/api/projects/:id/work-items", async (c) => {
+		const project = service.projects.get(c.req.param("id"));
+		if (!project) return c.json({
+			ok: false,
+			error: "Project not found"
+		}, 404);
+		const contentType = c.req.header("content-type") || "";
+		let body;
+		let files = [];
+		if (contentType.includes("multipart/form-data")) {
+			try {
+				body = await c.req.parseBody({ all: true });
+			} catch {
+				return c.json({
+					ok: false,
+					error: "Invalid multipart body"
+				}, 400);
+			}
+			files = collectUploadedFiles(body);
+		} else body = await c.req.json().catch(() => ({}));
+		const attachmentError = validateUploadedWorkItemFiles(files);
+		if (attachmentError) return c.json({
+			ok: false,
+			error: attachmentError
+		}, 413);
+		const title = textField(body, "title")?.trim();
+		if (!title) return c.json({
+			ok: false,
+			error: "Work item title is required"
+		}, 400);
+		const status = parseEnumValue(body.status, WORK_ITEM_STATUSES);
+		const priority = parseEnumValue(body.priority, WORK_ITEM_PRIORITIES);
+		const dueAt = finiteNumberField(body.dueAt);
+		if (Object.hasOwn(body, "status") && !status) return c.json({
+			ok: false,
+			error: "Invalid work item status"
+		}, 400);
+		if (Object.hasOwn(body, "priority") && !priority) return c.json({
+			ok: false,
+			error: "Invalid work item priority"
+		}, 400);
+		if (Object.hasOwn(body, "dueAt") && dueAt === void 0 && body.dueAt !== null) return c.json({
+			ok: false,
+			error: "Invalid dueAt"
+		}, 400);
+		const uploads = [];
+		for (const file of files) uploads.push(await uploadedFileToBuffer(file));
+		const item = workItems.createProjectWorkItem(project.id, {
+			title,
+			description: textField(body, "description"),
+			status,
+			priority,
+			ownerAgentId: textField(body, "ownerAgentId") || project.defaultAgentId || void 0,
+			nextAction: textField(body, "nextAction"),
+			blockedReason: textField(body, "blockedReason"),
+			dueAt
+		});
+		for (const upload of uploads) await workItems.addAttachment(item.id, upload);
+		const created = files.length > 0 ? workItems.getWorkItem(item.id) ?? item : item;
+		return c.json({
+			ok: true,
+			item: created
+		}, 201);
+	});
+	authenticated.get("/api/work-items/:id", async (c) => {
+		const item = workItems.getWorkItem(c.req.param("id"));
+		if (!item) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			item
+		});
+	});
+	authenticated.get("/api/work-items/:id/attachments", async (c) => {
+		const attachments = workItems.listAttachments(c.req.param("id"));
+		if (!attachments) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			attachments
+		});
+	});
+	authenticated.post("/api/work-items/:id/attachments", async (c) => {
+		const item = workItems.getWorkItem(c.req.param("id"));
+		if (!item) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		let body;
+		try {
+			body = await c.req.parseBody({ all: true });
+		} catch {
+			return c.json({
+				ok: false,
+				error: "Invalid multipart body"
+			}, 400);
+		}
+		const files = collectUploadedFiles(body);
+		if (!files.length) return c.json({
+			ok: false,
+			error: "Missing file field"
+		}, 400);
+		const attachmentError = validateUploadedWorkItemFiles(files);
+		if (attachmentError) return c.json({
+			ok: false,
+			error: attachmentError
+		}, 413);
+		const attachments = [];
+		for (const file of files) {
+			const upload = await uploadedFileToBuffer(file);
+			const attachment = await workItems.addAttachment(item.id, upload);
+			if (attachment) attachments.push(attachment);
+		}
+		return c.json({
+			ok: true,
+			attachments,
+			item: workItems.getWorkItem(item.id)
+		}, 201);
+	});
+	authenticated.get("/api/work-items/:id/attachments/:attachmentId/content", async (c) => {
+		const result = await workItems.readAttachment(c.req.param("id"), c.req.param("attachmentId"));
+		if (!result) return c.json({
+			ok: false,
+			error: "Attachment not found"
+		}, 404);
+		return new Response(result.buffer, { headers: {
+			"Content-Type": result.attachment.mimeType,
+			"Content-Length": String(result.attachment.size),
+			"Content-Disposition": `inline; filename="${encodeURIComponent(result.attachment.fileName)}"`,
+			"Cache-Control": "private, max-age=31536000, immutable"
+		} });
+	});
+	authenticated.delete("/api/work-items/:id/attachments/:attachmentId", async (c) => {
+		const attachment = await workItems.removeAttachment(c.req.param("id"), c.req.param("attachmentId"));
+		if (!attachment) return c.json({
+			ok: false,
+			error: "Attachment not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			attachment,
+			item: workItems.getWorkItem(c.req.param("id"))
+		});
+	});
+	authenticated.patch("/api/work-items/:id", async (c) => {
+		const body = await c.req.json().catch(() => ({}));
+		const status = Object.hasOwn(body, "status") ? parseEnumValue(body.status, WORK_ITEM_STATUSES) : void 0;
+		const priority = Object.hasOwn(body, "priority") ? parseEnumValue(body.priority, WORK_ITEM_PRIORITIES) : void 0;
+		const dueAt = Object.hasOwn(body, "dueAt") ? body.dueAt === null ? null : typeof body.dueAt === "number" && Number.isFinite(body.dueAt) ? body.dueAt : void 0 : void 0;
+		const archivedAt = Object.hasOwn(body, "archivedAt") ? body.archivedAt === null ? null : typeof body.archivedAt === "number" && Number.isFinite(body.archivedAt) ? body.archivedAt : void 0 : void 0;
+		if (status === void 0 && Object.hasOwn(body, "status")) return c.json({
+			ok: false,
+			error: "Invalid work item status"
+		}, 400);
+		if (priority === void 0 && Object.hasOwn(body, "priority")) return c.json({
+			ok: false,
+			error: "Invalid work item priority"
+		}, 400);
+		if (dueAt === void 0 && Object.hasOwn(body, "dueAt")) return c.json({
+			ok: false,
+			error: "Invalid dueAt"
+		}, 400);
+		if (archivedAt === void 0 && Object.hasOwn(body, "archivedAt")) return c.json({
+			ok: false,
+			error: "Invalid archivedAt"
+		}, 400);
+		const item = workItems.updateWorkItem(c.req.param("id"), {
+			...Object.hasOwn(body, "title") ? { title: textField(body, "title") ?? "" } : {},
+			...Object.hasOwn(body, "description") ? { description: optionalTextField(body, "description") } : {},
+			...Object.hasOwn(body, "status") ? { status } : {},
+			...Object.hasOwn(body, "priority") ? { priority } : {},
+			...Object.hasOwn(body, "ownerAgentId") ? { ownerAgentId: optionalTextField(body, "ownerAgentId") } : {},
+			...Object.hasOwn(body, "nextAction") ? { nextAction: optionalTextField(body, "nextAction") } : {},
+			...Object.hasOwn(body, "blockedReason") ? { blockedReason: optionalTextField(body, "blockedReason") } : {},
+			...Object.hasOwn(body, "dueAt") ? { dueAt } : {},
+			...Object.hasOwn(body, "archivedAt") ? { archivedAt } : {}
+		});
+		if (!item) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			item
+		});
+	});
+	authenticated.delete("/api/work-items/:id", async (c) => {
+		const item = workItems.updateWorkItem(c.req.param("id"), { archivedAt: Date.now() });
+		if (!item) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			item
+		});
+	});
+	authenticated.get("/api/work-items/:id/events", async (c) => {
+		const item = workItems.getWorkItem(c.req.param("id"));
+		if (!item) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			events: workItems.listEvents(item.id)
+		});
+	});
+	authenticated.get("/api/work-items/:id/update-suggestions", async (c) => {
+		const item = workItems.getWorkItem(c.req.param("id"));
+		if (!item) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		const status = parseEnumValue(c.req.query("status"), WORK_ITEM_SUGGESTION_STATUSES);
+		if (c.req.query("status") && !status) return c.json({
+			ok: false,
+			error: "Invalid suggestion status"
+		}, 400);
+		return c.json({
+			ok: true,
+			suggestions: workItems.listUpdateSuggestions(item.id, status)
+		});
+	});
+	authenticated.post("/api/work-items/:id/update-suggestions", async (c) => {
+		const item = workItems.getWorkItem(c.req.param("id"));
+		if (!item) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		const body = await c.req.json().catch(() => ({}));
+		const sourceKind = parseEnumValue(body.sourceKind, [
+			"chat",
+			"goal",
+			"workflow_run",
+			"automation"
+		]);
+		const sourceId = textField(body, "sourceId")?.trim();
+		if (!sourceKind) return c.json({
+			ok: false,
+			error: "Invalid sourceKind"
+		}, 400);
+		if (!sourceId) return c.json({
+			ok: false,
+			error: "sourceId is required"
+		}, 400);
+		const patchBody = body.patch && typeof body.patch === "object" && !Array.isArray(body.patch) ? body.patch : {};
+		const status = Object.hasOwn(patchBody, "status") ? parseEnumValue(patchBody.status, WORK_ITEM_STATUSES) : void 0;
+		if (Object.hasOwn(patchBody, "status") && !status) return c.json({
+			ok: false,
+			error: "Invalid work item status"
+		}, 400);
+		const confidence = typeof body.confidence === "number" && Number.isFinite(body.confidence) ? Math.max(0, Math.min(1, body.confidence)) : void 0;
+		const suggestion = workItems.createUpdateSuggestion(item.id, {
+			sourceKind,
+			sourceId,
+			patch: {
+				...Object.hasOwn(patchBody, "status") ? { status } : {},
+				...Object.hasOwn(patchBody, "nextAction") ? { nextAction: optionalTextField(patchBody, "nextAction") } : {},
+				...Object.hasOwn(patchBody, "blockedReason") ? { blockedReason: optionalTextField(patchBody, "blockedReason") } : {}
+			},
+			progressNote: optionalTextField(body, "progressNote") ?? void 0,
+			rationale: optionalTextField(body, "rationale") ?? void 0,
+			confidence
+		});
+		if (!suggestion) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			suggestion
+		}, 201);
+	});
+	authenticated.post("/api/work-item-update-suggestions/:id/apply", async (c) => {
+		const result = workItems.applyUpdateSuggestion(c.req.param("id"));
+		if (!result) return c.json({
+			ok: false,
+			error: "Suggestion not found or already resolved"
+		}, 404);
+		return c.json({
+			ok: true,
+			item: result.item,
+			suggestion: result.suggestion
+		});
+	});
+	authenticated.post("/api/work-item-update-suggestions/:id/dismiss", async (c) => {
+		const suggestion = workItems.dismissUpdateSuggestion(c.req.param("id"));
+		if (!suggestion) return c.json({
+			ok: false,
+			error: "Suggestion not found or already resolved"
+		}, 404);
+		return c.json({
+			ok: true,
+			suggestion
+		});
+	});
+	authenticated.post("/api/work-items/:id/start-chat", async (c) => {
+		const item = workItems.getWorkItem(c.req.param("id"));
+		if (!item) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		const project = service.projects.get(item.projectId);
+		if (!project) return c.json({
+			ok: false,
+			error: "Project not found"
+		}, 404);
+		const agentId = resolveProjectAgentId({
+			config: service.currentConfig,
+			projects: service.projects,
+			explicitAgentId: item.ownerAgentId,
+			projectId: project.id
+		});
+		const peerId = `work_item_${Date.now()}`;
+		const sessionKey = buildSessionKey({
+			agentId,
+			source: "webchat",
+			accountId: "default",
+			peerKind: "direct",
+			peerId
+		});
+		await service.sessionIndexInstance.saveMessages(sessionKey, [], { metadata: buildWorkItemChatSessionMetadata({
+			agentId,
+			accountId: "default",
+			peerId,
+			workItemId: item.id,
+			title: item.title,
+			updatedAt: item.updatedAt
+		}) });
+		service.projects.attachSession(sessionKey, project.id);
+		const session = await service.sessions.getSession(sessionKey);
+		workItems.addLink(item.id, {
+			kind: "chat",
+			targetId: sessionKey,
+			title: session?.name || item.title,
+			statusSnapshot: session?.status
+		}, "chat_started");
+		const updated = item.status === "todo" || item.status === "backlog" ? workItems.updateWorkItem(item.id, { status: "in_progress" }) : workItems.getWorkItem(item.id);
+		return c.json({
+			ok: true,
+			session,
+			item: updated
+		}, 201);
+	});
+	authenticated.post("/api/work-items/:id/create-goal", async (c) => {
+		const item = workItems.getWorkItem(c.req.param("id"));
+		if (!item) return c.json({
+			ok: false,
+			error: "Work item not found"
+		}, 404);
+		const project = service.projects.get(item.projectId);
+		if (!project) return c.json({
+			ok: false,
+			error: "Project not found"
+		}, 404);
+		const goal = goals.create({
+			title: item.title,
+			description: item.description || item.nextAction,
+			priority: item.priority === "urgent" ? "high" : item.priority,
+			agentId: item.ownerAgentId || project.defaultAgentId || void 0,
+			projectId: project.id,
+			source: "api",
+			config: service.currentConfig
+		});
+		goals.setContextMessage({
+			goalId: goal.id,
+			text: buildWorkItemAgentContext(item).text
+		});
+		workItems.addLink(item.id, {
+			kind: "goal",
+			targetId: goal.id,
+			title: goal.title,
+			statusSnapshot: goal.status
+		}, "goal_created");
+		const updated = item.status === "todo" || item.status === "backlog" ? workItems.updateWorkItem(item.id, { status: "in_progress" }) : workItems.getWorkItem(item.id);
+		return c.json({
+			ok: true,
+			goal,
+			item: updated
+		}, 201);
+	});
 	authenticated.post("/api/projects/:id/digest-memory", async (c) => {
 		const project = service.projects.getWithDetails(c.req.param("id"));
 		if (!project) return c.json({
@@ -406,7 +1100,7 @@ function registerProjectsRoutes(authenticated, deps) {
 			const sessions = await Promise.all(keys.map((key) => service.sessions.getSession(key)));
 			return c.json({
 				ok: true,
-				sessions: sessions.filter(Boolean)
+				sessions: sessions.filter((session) => session && !isHiddenEmptyProjectChatShell(session))
 			});
 		} catch (error) {
 			return c.json({
@@ -430,39 +1124,12 @@ function registerProjectsRoutes(authenticated, deps) {
 		}
 	});
 	authenticated.get("/api/projects/:id/files", async (c) => {
-		const project = service.projects.get(c.req.param("id"));
-		if (!project) return c.json({
-			ok: false,
-			error: "Project not found"
-		}, 404);
-		if (!project.workspaceRoot?.trim()) return c.json({
+		const resolved = await resolveProjectWorkspacePath(service, c.req.param("id"), c.req.query("path"));
+		if (resolved.ok === false) return c.json({
 			ok: false,
-			error: "Project workspace root is not set"
-		}, 400);
-		let root;
-		try {
-			root = await realpath(project.workspaceRoot);
-			if (!(await stat(root)).isDirectory()) return c.json({
-				ok: false,
-				error: "Project workspace root is not a directory"
-			}, 400);
-		} catch (err) {
-			log.warn({
-				err,
-				projectId: project.id,
-				path: project.workspaceRoot
-			}, "project workspace root unavailable");
-			return c.json({
-				ok: false,
-				error: "Project workspace root is unavailable"
-			}, 404);
-		}
-		const requestedPath = normalizeRelativePath(c.req.query("path"));
-		const candidate = path$1.resolve(root, requestedPath);
-		if (!isWithinDirectory(root, candidate)) return c.json({
-			ok: false,
-			error: "Path is outside project workspace"
-		}, 400);
+			error: resolved.error
+		}, resolved.status);
+		const { root, absolutePath: candidate } = resolved;
 		let currentPath;
 		try {
 			currentPath = await realpath(candidate);
@@ -477,7 +1144,7 @@ function registerProjectsRoutes(authenticated, deps) {
 		} catch (err) {
 			log.warn({
 				err,
-				projectId: project.id,
+				projectId: resolved.projectId,
 				path: candidate
 			}, "project file path unavailable");
 			return c.json({
@@ -487,19 +1154,23 @@ function registerProjectsRoutes(authenticated, deps) {
 		}
 		try {
 			const dirents = await readdir(currentPath, { withFileTypes: true });
-			const entries = await Promise.all(dirents.filter((entry) => !SKIP_FILE_NAMES.has(entry.name)).map(async (entry) => {
-				const absolutePath = path$1.join(currentPath, entry.name);
+			const visibleEntries = (await Promise.all(dirents.filter((entry) => !SKIP_FILE_NAMES.has(entry.name)).map(async (entry) => {
+				const displayPath = path$1.join(currentPath, entry.name);
+				const absolutePath = await realpath(displayPath).catch(() => null);
+				if (!absolutePath || !isWithinDirectory(root, absolutePath)) return null;
 				const entryStat = await stat(absolutePath).catch(() => null);
-				const relativePath = path$1.relative(root, absolutePath).split(path$1.sep).join("/");
+				if (!entryStat) return null;
+				const relativePath = path$1.relative(root, displayPath).split(path$1.sep).join("/");
 				return {
 					name: entry.name,
 					path: relativePath,
-					type: entry.isDirectory() ? "directory" : "file",
+					absolutePath,
+					type: entryStat.isDirectory() ? "directory" : "file",
 					size: entryStat?.isFile() ? entryStat.size : void 0,
 					updatedAt: entryStat?.mtime.toISOString()
 				};
-			}));
-			entries.sort((left, right) => {
+			}))).filter((entry) => entry !== null);
+			visibleEntries.sort((left, right) => {
 				if (left.type !== right.type) return left.type === "directory" ? -1 : 1;
 				return left.name.localeCompare(right.name);
 			});
@@ -510,12 +1181,12 @@ function registerProjectsRoutes(authenticated, deps) {
 				root,
 				path: relativeCurrentPath === "." ? "" : relativeCurrentPath,
 				parentPath: parentRelativePath === "." ? "" : parentRelativePath,
-				entries
+				entries: visibleEntries
 			});
 		} catch (err) {
 			log.warn({
 				err,
-				projectId: project.id,
+				projectId: resolved.projectId,
 				path: currentPath
 			}, "project file list failed");
 			if (err?.code === "EACCES") return c.json({
@@ -528,6 +1199,176 @@ function registerProjectsRoutes(authenticated, deps) {
 			}, 500);
 		}
 	});
+	authenticated.get("/api/projects/:id/files/read", async (c) => {
+		const resolved = await resolveExistingProjectWorkspacePath(service, c.req.param("id"), c.req.query("path"));
+		if (resolved.ok === false) return c.json({
+			ok: false,
+			error: { message: resolved.error }
+		}, resolved.status);
+		if (!resolved.stat.isFile()) return c.json({
+			ok: false,
+			error: { message: "Not a file" }
+		}, 400);
+		try {
+			const content = await readFile(resolved.absolutePath, "utf-8");
+			return c.json({
+				ok: true,
+				payload: {
+					content,
+					path: resolved.relativePath,
+					absolutePath: resolved.absolutePath,
+					mtimeMs: resolved.stat.mtimeMs
+				}
+			});
+		} catch {
+			return c.json({
+				ok: false,
+				error: { message: "Read failed" }
+			}, 500);
+		}
+	});
+	authenticated.get("/api/projects/:id/files/raw", async (c) => {
+		const resolved = await resolveExistingProjectWorkspacePath(service, c.req.param("id"), c.req.query("path"));
+		if (resolved.ok === false) return c.json({
+			ok: false,
+			error: { message: resolved.error }
+		}, resolved.status);
+		if (!resolved.stat.isFile()) return c.json({
+			ok: false,
+			error: { message: "Not a file" }
+		}, 400);
+		const contentType = PROJECT_FILE_MIME_BY_EXT[resolved.relativePath.split(".").pop()?.toLowerCase() ?? ""] || "application/octet-stream";
+		try {
+			const buf = await readFile(resolved.absolutePath);
+			return new Response(buf, { headers: {
+				"Content-Type": contentType,
+				"Cache-Control": "private, max-age=3600"
+			} });
+		} catch {
+			return c.json({
+				ok: false,
+				error: { message: "Read failed" }
+			}, 500);
+		}
+	});
+	authenticated.get("/api/projects/:id/files/resolve-reference", async (c) => {
+		const rawPath = typeof c.req.query("path") === "string" ? c.req.query("path").trim() : "";
+		if (!rawPath) return c.json({
+			ok: false,
+			error: {
+				code: "INVALID_PATH",
+				message: "Missing path"
+			}
+		}, 400);
+		const resolved = await resolveProjectWorkspacePath(service, c.req.param("id"), rawPath);
+		if (resolved.ok === false) return c.json({
+			ok: false,
+			error: {
+				code: "PROJECT_WORKSPACE_RESOLUTION_FAILED",
+				message: resolved.error
+			}
+		}, resolved.status);
+		let st = null;
+		let absolutePath = resolved.absolutePath;
+		try {
+			absolutePath = await realpath(resolved.absolutePath);
+			if (!isWithinDirectory(resolved.root, absolutePath)) return c.json({
+				ok: false,
+				error: {
+					code: "PROJECT_WORKSPACE_RESOLUTION_FAILED",
+					message: "Path is outside project workspace"
+				}
+			}, 400);
+			st = await stat(absolutePath);
+		} catch {
+			st = null;
+		}
+		const displayName = path$1.basename(rawPath);
+		if (!st) return c.json({
+			ok: true,
+			payload: {
+				inputPath: rawPath,
+				displayName,
+				scope: "missing",
+				exists: false,
+				absolutePath: resolved.absolutePath,
+				capabilities: ["copyPath"],
+				errorCode: "FILE_NOT_FOUND"
+			}
+		});
+		return c.json({
+			ok: true,
+			payload: {
+				inputPath: rawPath,
+				displayName,
+				scope: "workspace",
+				exists: true,
+				isDirectory: st.isDirectory(),
+				absolutePath,
+				workspaceRelativePath: resolved.relativePath,
+				capabilities: st.isDirectory() ? [
+					"openExternal",
+					"revealInFolder",
+					"copyPath"
+				] : [
+					"preview",
+					"edit",
+					"openExternal",
+					"revealInFolder",
+					"copyPath"
+				],
+				mtimeMs: st.mtimeMs
+			}
+		});
+	});
+	authenticated.put("/api/projects/:id/files/write", async (c) => {
+		let body;
+		try {
+			body = await c.req.json();
+		} catch {
+			return c.json({
+				ok: false,
+				error: { message: "Invalid JSON" }
+			}, 400);
+		}
+		const bodyRecord = typeof body === "object" && body !== null ? body : {};
+		const pathRel = typeof bodyRecord.path === "string" ? bodyRecord.path : "";
+		const content = typeof bodyRecord.content === "string" ? bodyRecord.content : "";
+		if (!pathRel.trim()) return c.json({
+			ok: false,
+			error: { message: "Missing path" }
+		}, 400);
+		const resolved = await resolveProjectWorkspaceWritePath(service, c.req.param("id"), pathRel);
+		if (resolved.ok === false) return c.json({
+			ok: false,
+			error: { message: resolved.error }
+		}, resolved.status);
+		if (resolved.existingStat && !resolved.existingStat.isFile()) return c.json({
+			ok: false,
+			error: { message: "Not a file" }
+		}, 400);
+		try {
+			await writeFile(resolved.absolutePath, content, "utf-8");
+			const mtimeMs = (await stat(resolved.absolutePath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
+			return c.json({
+				ok: true,
+				payload: {
+					path: resolved.relativePath,
+					mtimeMs
+				}
+			});
+		} catch (err) {
+			log.error({
+				err,
+				projectId: resolved.projectId,
+				path: resolved.absolutePath
+			}, "project file write failed");
+			return c.json({
+				ok: false,
+				error: { message: "Write failed" }
+			}, 500);
+		}
+	});
 	authenticated.post("/api/projects/:id/sessions/:sessionKey", async (c) => {
 		try {
 			service.projects.attachSession(c.req.param("sessionKey"), c.req.param("id"));