@xopcai/xopc 0.0.110 → 0.0.112

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

@@ -1,224 +1,721 @@
-import { PERSISTENT_GOAL_CUSTOM_KEY, defaultMaxTurns, mergeCustomDataPatch, readPersistentGoal, serializePersistentGoal } from "../../../agent/goals/state.js";
-import { applyPersistentGoalUserAction } from "../../../agent/goals/patch-from-user-action.js";
-import { applyChecklistUserMutation } from "../../../agent/goals/checklist-user.js";
-import { mergePersistentGoalUiLocale, normalizeGoalUiLocale } from "../../../agent/goals/goal-locale.js";
-import { listGoalRuns } from "../../../agent/goals/goal-run-store.js";
+import { buildSessionKey, init_session_key, sanitizeSegment } from "../../../routing/session-key.js";
+import { getDefaultAgentId, init_resolve_route } from "../../../routing/resolve-route.js";
+import { createWorkflowCatalog } from "../../../agent/workflow/catalog.js";
+import { GoalService, normalizeGoalUiLocale } from "../../../goals/goal-service.js";
+import "../../../goals/index.js";
 //#region src/gateway/hono/routes/goals.ts
-function isGoalAction(x) {
-	return x === "pause" || x === "resume" || x === "clear" || x === "restart";
+init_session_key();
+init_resolve_route();
+function parseLimit(raw, fallback = 50) {
+	if (!raw) return fallback;
+	const n = Number.parseInt(raw, 10);
+	return Number.isFinite(n) ? Math.min(500, Math.max(1, n)) : fallback;
 }
-/** Webchat persistent `/goal` REST API. */
+function parseStatuses(raw) {
+	if (!raw?.trim()) return void 0;
+	const statuses = raw.split(",").map((s) => s.trim()).filter((s) => s === "active" || s === "paused" || s === "blocked" || s === "needs_input" || s === "done" || s === "archived");
+	return statuses.length ? statuses : void 0;
+}
+function parseBodyGoalStatus(raw) {
+	return raw === "active" || raw === "paused" || raw === "blocked" || raw === "needs_input" || raw === "done" || raw === "archived" ? raw : null;
+}
+function parsePriority(raw) {
+	return raw === "low" || raw === "normal" || raw === "high" ? raw : void 0;
+}
+const STOP_WORDS = new Set([
+	"a",
+	"an",
+	"and",
+	"are",
+	"as",
+	"for",
+	"in",
+	"is",
+	"of",
+	"on",
+	"or",
+	"the",
+	"to",
+	"with",
+	"一个",
+	"这个",
+	"需要",
+	"进行",
+	"推进"
+]);
+function tokenizeForWorkflowMatch(text) {
+	return (text.toLowerCase().match(/[\p{L}\p{N}_-]+/gu) ?? []).map((token) => token.trim()).filter((token) => token.length >= 2 && !STOP_WORDS.has(token));
+}
+function goalSearchText(goal) {
+	return [
+		goal.title,
+		goal.description,
+		goal.nextAction,
+		goal.blockedReason,
+		...goal.checklist.map((item) => `${item.text} ${item.evidenceSummary ?? ""}`)
+	].filter(Boolean).join("\n");
+}
+function buildGoalWorkflowSuggestions(params) {
+	const goalTokens = new Set(tokenizeForWorkflowMatch(goalSearchText(params.goal)));
+	const runsByDefinition = /* @__PURE__ */ new Map();
+	for (const run of params.workflowRuns) {
+		const list = runsByDefinition.get(run.definitionId) ?? [];
+		list.push(run);
+		runsByDefinition.set(run.definitionId, list);
+	}
+	const suggestions = [];
+	for (const entry of createWorkflowCatalog().list()) {
+		const candidateText = [
+			entry.name,
+			entry.title,
+			entry.description,
+			entry.whenToUse,
+			...entry.tags ?? []
+		].filter(Boolean).join("\n");
+		const candidateTokens = new Set(tokenizeForWorkflowMatch(candidateText));
+		const matched = [...goalTokens].filter((token) => candidateTokens.has(token));
+		const relatedRuns = runsByDefinition.get(entry.name) ?? [];
+		const terminalRuns = relatedRuns.filter((run) => run.status !== "queued" && run.status !== "running");
+		const succeededRuns = terminalRuns.filter((run) => run.status === "succeeded");
+		const successRate = terminalRuns.length ? succeededRuns.length / terminalRuns.length : void 0;
+		const lastRun = relatedRuns.toSorted((left, right) => right.createdAtMs - left.createdAtMs)[0];
+		let score = matched.length * 8;
+		if (entry.tags?.some((tag) => goalTokens.has(tag.toLowerCase()))) score += 8;
+		if (entry.whenToUse && matched.length > 0) score += 4;
+		if (successRate != null) score += Math.round(successRate * 10);
+		if (lastRun?.status === "succeeded") score += 4;
+		if (lastRun?.status === "failed" || lastRun?.status === "timeout") score -= 3;
+		if (score <= 0) score = entry.source === "builtin" ? 1 : 0;
+		const reasons = [];
+		if (matched.length) reasons.push(`matches ${matched.slice(0, 4).join(", ")}`);
+		if (successRate != null) reasons.push(`${Math.round(successRate * 100)}% success rate`);
+		if (lastRun) reasons.push(`last run ${lastRun.status}`);
+		if (!reasons.length && entry.whenToUse) reasons.push("general workflow fit");
+		if (score > 0) suggestions.push({
+			definitionId: entry.name,
+			name: entry.name,
+			title: entry.title || entry.name,
+			description: entry.description,
+			score,
+			reasons,
+			tags: entry.tags ?? [],
+			successRate,
+			lastRunStatus: lastRun?.status
+		});
+	}
+	return suggestions.sort((left, right) => right.score - left.score || left.name.localeCompare(right.name)).slice(0, 5);
+}
+function buildGoalActivities(input) {
+	const activities = [];
+	for (const item of input.queue.filter((queueItem) => queueItem.goalId === input.goalId)) activities.push({
+		id: `queue:${item.id}`,
+		kind: "queue",
+		status: item.status,
+		title: "Goal queued",
+		summary: item.lastError || item.message || void 0,
+		createdAt: item.finishedAt ?? item.startedAt ?? item.nextRunAt ?? item.enqueuedAt,
+		link: item.sessionKey ? {
+			type: "chat",
+			value: item.sessionKey
+		} : void 0,
+		data: item
+	});
+	for (const run of input.runs) activities.push({
+		id: `goal_run:${run.id}`,
+		kind: "goal_run",
+		status: run.verdict ?? run.status,
+		title: "Goal run judged",
+		summary: run.reason || run.assistantPreview || run.nextAction,
+		createdAt: run.finishedAt ?? run.startedAt,
+		data: run
+	});
+	for (const run of input.workflowRuns) activities.push({
+		id: `workflow_run:${run.id}`,
+		kind: "workflow_run",
+		status: run.status,
+		title: run.title || run.definitionId,
+		summary: run.definitionId,
+		createdAt: run.completedAtMs ?? run.startedAtMs ?? run.createdAtMs,
+		link: {
+			type: "workflow_run",
+			value: run.id
+		},
+		data: run
+	});
+	for (const event of input.events) activities.push({
+		id: `event:${event.id}`,
+		kind: "event",
+		status: event.kind,
+		title: event.kind,
+		summary: event.message,
+		createdAt: event.createdAt,
+		data: event
+	});
+	for (const item of input.evidence) activities.push({
+		id: `evidence:${item.id}`,
+		kind: "evidence",
+		status: item.kind,
+		title: item.title,
+		summary: item.summary || item.uri,
+		createdAt: item.createdAt,
+		data: item
+	});
+	return activities.sort((left, right) => right.createdAt - left.createdAt).slice(0, input.limit);
+}
+function abortActiveWebchatRunForGoal(deps, goal) {
+	const sessionKey = goal.activeSessionKey?.trim();
+	if (!sessionKey) return {};
+	const runId = deps.service.getActiveWebchatRunId(sessionKey);
+	if (!runId) return {};
+	return {
+		abortedRunId: runId,
+		aborted: deps.service.abortAgentRun(runId)
+	};
+}
+/** First-class Goal API. Sessions are execution context; goals are durable product objects. */
 function registerGoalsRoutes(authenticated, deps) {
-	const sm = deps.service.sessionIndexInstance;
+	const goals = new GoalService();
 	const cfg = () => deps.service.currentConfig;
-	authenticated.get("/api/goals/webchat", async (c) => {
+	const workflowRunService = deps.service.createWorkflowRunService();
+	authenticated.get("/api/goals/current", async (c) => {
 		const sessionKey = c.req.query("sessionKey")?.trim();
 		if (!sessionKey) return c.json({
 			ok: false,
 			error: "Missing sessionKey"
 		}, 400);
-		const uiLocale = normalizeGoalUiLocale(c.req.query("uiLocale"));
-		let m = await sm.getSessionMetadata(sessionKey);
-		if (uiLocale && m) {
-			const merged = mergePersistentGoalUiLocale(m.customData, uiLocale);
-			if (merged !== m.customData) {
-				await sm.updateSessionMetadata(sessionKey, { customData: merged });
-				m = await sm.getSessionMetadata(sessionKey);
-			}
-		}
-		const goal = readPersistentGoal(m?.customData);
 		return c.json({
 			ok: true,
-			sessionKey,
-			persistentGoal: goal
+			goal: goals.getActiveForSession(sessionKey)
 		});
 	});
-	authenticated.get("/api/goals/webchat/runs", async (c) => {
-		const sessionKey = c.req.query("sessionKey")?.trim();
-		if (!sessionKey) return c.json({
+	authenticated.get("/api/goals", async (c) => {
+		const status = parseStatuses(c.req.query("status"));
+		const agentId = c.req.query("agentId")?.trim() || void 0;
+		const sessionKey = c.req.query("sessionKey")?.trim() || void 0;
+		const limit = parseLimit(c.req.query("limit"));
+		const offsetRaw = c.req.query("offset")?.trim();
+		const offset = offsetRaw ? Math.max(0, Number.parseInt(offsetRaw, 10) || 0) : 0;
+		return c.json({
+			ok: true,
+			goals: goals.list({
+				status,
+				agentId,
+				sessionKey,
+				limit,
+				offset
+			})
+		});
+	});
+	authenticated.get("/api/goals/queue", async (c) => {
+		return c.json({
+			ok: true,
+			queue: deps.service.getGoalQueueSnapshot()
+		});
+	});
+	authenticated.post("/api/goals", async (c) => {
+		const body = await c.req.json().catch(() => ({}));
+		const title = typeof body.title === "string" ? body.title.trim() : "";
+		if (!title) return c.json({
 			ok: false,
-			error: "Missing sessionKey"
+			error: "Missing title"
 		}, 400);
-		const limitRaw = c.req.query("limit")?.trim();
-		let limit = 50;
-		if (limitRaw) {
-			const n = Number.parseInt(limitRaw, 10);
-			if (Number.isFinite(n)) limit = Math.min(500, Math.max(1, n));
-		}
-		const runs = await listGoalRuns(cfg(), sessionKey, { limit });
+		const sessionKey = typeof body.sessionKey === "string" && body.sessionKey.trim() ? body.sessionKey.trim() : void 0;
+		const agentId = typeof body.agentId === "string" && body.agentId.trim() ? body.agentId.trim() : sessionKey ? void 0 : getDefaultAgentId(cfg());
+		const maxTurns = typeof body.maxTurns === "number" && Number.isFinite(body.maxTurns) ? Math.max(1, Math.min(500, Math.floor(body.maxTurns))) : void 0;
+		const goal = goals.create({
+			title,
+			description: typeof body.description === "string" ? body.description : void 0,
+			sessionKey,
+			agentId,
+			priority: body.priority === "low" || body.priority === "high" ? body.priority : "normal",
+			deadlineAt: typeof body.deadlineAt === "number" && Number.isFinite(body.deadlineAt) ? body.deadlineAt : void 0,
+			judgeModelRef: typeof body.judgeModelRef === "string" ? body.judgeModelRef : void 0,
+			maxTurns,
+			uiLocale: normalizeGoalUiLocale(body.uiLocale),
+			source: body.source === "cli" || body.source === "cron" || body.source === "workflow" || body.source === "channel" || body.source === "api" ? body.source : "chat",
+			config: cfg()
+		});
+		if (sessionKey) deps.service.enqueueWebchatPersistentGoalKickoff(sessionKey, title);
+		return c.json({
+			ok: true,
+			goal: goals.get(goal.id)
+		});
+	});
+	authenticated.get("/api/goals/:goalId/workflow-runs", async (c) => {
+		const goalId = c.req.param("goalId");
+		const goal = goals.get(goalId);
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const runs = await workflowRunService.createRunStore(goal.agentId || getDefaultAgentId(cfg())).listRunSummariesForGoal(goalId, parseLimit(c.req.query("limit")));
 		return c.json({
 			ok: true,
-			sessionKey,
 			runs
 		});
 	});
-	authenticated.post("/api/goals/webchat", async (c) => {
+	authenticated.post("/api/goals/:goalId/workflows/run", async (c) => {
+		const goalId = c.req.param("goalId");
+		const goal = goals.get(goalId);
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		if (goal.status === "done" || goal.status === "archived") return c.json({
+			ok: false,
+			error: `Goal is ${goal.status}`
+		}, 409);
 		const body = await c.req.json().catch(() => ({}));
-		const sessionKey = typeof body.sessionKey === "string" ? body.sessionKey.trim() : "";
-		if (!sessionKey) return c.json({
+		const definitionId = typeof body.definitionId === "string" ? body.definitionId.trim() : "";
+		if (!definitionId) return c.json({
 			ok: false,
-			error: "Missing sessionKey"
+			error: "Missing definitionId"
 		}, 400);
-		const goalsSlice = cfg().goals;
-		const actionRaw = body.action ?? (body.clear === true ? "clear" : void 0);
-		if (isGoalAction(actionRaw)) {
-			const meta = await sm.getSessionMetadata(sessionKey);
-			if (!meta) return c.json({
-				ok: false,
-				error: "Session not found"
-			}, 404);
-			const applied = applyPersistentGoalUserAction(meta.customData, actionRaw, goalsSlice);
-			if (applied.kind === "error") return c.json({
-				ok: false,
-				error: applied.error
-			}, 400);
-			if (applied.kind === "noop") {
-				const persistentGoal = readPersistentGoal(meta.customData);
-				return c.json({
-					ok: true,
-					sessionKey,
-					noop: true,
-					message: applied.message,
-					persistentGoal
-				});
-			}
-			const uiLocale = normalizeGoalUiLocale(body.uiLocale);
-			const customData = uiLocale != null ? mergePersistentGoalUiLocale(applied.customData, uiLocale) ?? applied.customData : applied.customData;
-			await sm.updateSessionMetadata(sessionKey, { customData });
-			const persistentGoal = readPersistentGoal((await sm.getSessionMetadata(sessionKey))?.customData);
-			if (applied.kickoff) deps.service.enqueueWebchatPersistentGoalKickoff(sessionKey, applied.kickoff);
+		try {
+			createWorkflowCatalog().load(definitionId);
+		} catch {
 			return c.json({
-				ok: true,
-				sessionKey,
-				action: actionRaw,
-				persistentGoal
-			});
-		}
-		if (body.clear === true) {
-			const meta = await sm.getSessionMetadata(sessionKey);
-			if (!meta) return c.json({
 				ok: false,
-				error: "Session not found"
+				error: "Workflow definition not found"
 			}, 404);
-			const base = { ...meta.customData };
-			delete base[PERSISTENT_GOAL_CUSTOM_KEY];
-			await sm.updateSessionMetadata(sessionKey, { customData: base });
+		}
+		const result = await workflowRunService.startWorkflowRun({
+			agentId: goal.agentId || getDefaultAgentId(cfg()),
+			definitionId,
+			goalId,
+			goal: typeof body.goal === "string" && body.goal.trim() ? body.goal.trim() : goal.nextAction || goal.title,
+			input: body.input ?? {
+				goal: goal.title,
+				description: goal.description,
+				nextAction: goal.nextAction,
+				checklist: goal.checklist.map((item) => ({
+					text: item.text,
+					status: item.status,
+					evidenceSummary: item.evidenceSummary
+				}))
+			},
+			parentSessionKey: goal.activeSessionKey,
+			source: { kind: "webui" },
+			concurrency: typeof body.concurrency === "number" ? body.concurrency : void 0,
+			maxSubagents: typeof body.maxSubagents === "number" ? body.maxSubagents : void 0
+		});
+		if (result.ok === false) return c.json({
+			ok: false,
+			error: result.message,
+			code: result.code
+		}, result.httpStatus);
+		return c.json({
+			ok: true,
+			runId: result.runId,
+			sessionKey: result.sessionKey
+		}, 202);
+	});
+	authenticated.get("/api/goals/:goalId/activity", async (c) => {
+		const goalId = c.req.param("goalId");
+		const goal = goals.get(goalId);
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const limit = parseLimit(c.req.query("limit"), 100);
+		const workflowRuns = await workflowRunService.createRunStore(goal.agentId || getDefaultAgentId(cfg())).listRunSummariesForGoal(goalId, limit);
+		const activities = buildGoalActivities({
+			goalId,
+			queue: deps.service.getGoalQueueSnapshot(),
+			runs: goals.listRuns(goalId, limit),
+			workflowRuns,
+			events: goals.listEvents(goalId, limit),
+			evidence: goals.listEvidence(goalId, limit),
+			limit
+		});
+		return c.json({
+			ok: true,
+			activities
+		});
+	});
+	authenticated.get("/api/goals/:goalId/workflow-suggestions", async (c) => {
+		const goalId = c.req.param("goalId");
+		const goal = goals.get(goalId);
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const workflowRuns = await workflowRunService.createRunStore(goal.agentId || getDefaultAgentId(cfg())).listRunSummaries(500);
+		return c.json({
+			ok: true,
+			suggestions: buildGoalWorkflowSuggestions({
+				goal,
+				workflowRuns
+			})
+		});
+	});
+	authenticated.get("/api/goals/:goalId", async (c) => {
+		const goal = goals.get(c.req.param("goalId"));
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.patch("/api/goals/:goalId", async (c) => {
+		const goalId = c.req.param("goalId");
+		const body = await c.req.json().catch(() => ({}));
+		const status = parseBodyGoalStatus(body.status);
+		let goal = goals.get(goalId);
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const patch = {};
+		if (typeof body.title === "string") patch.title = body.title;
+		if ("description" in body) patch.description = typeof body.description === "string" ? body.description : void 0;
+		const priority = parsePriority(body.priority);
+		if (priority) patch.priority = priority;
+		if ("deadlineAt" in body) patch.deadlineAt = typeof body.deadlineAt === "number" && Number.isFinite(body.deadlineAt) ? body.deadlineAt : void 0;
+		if (typeof body.maxTurns === "number" && Number.isFinite(body.maxTurns)) patch.maxTurns = body.maxTurns;
+		if ("judgeModelRef" in body) patch.judgeModelRef = typeof body.judgeModelRef === "string" ? body.judgeModelRef : void 0;
+		if ("nextAction" in body) patch.nextAction = typeof body.nextAction === "string" ? body.nextAction : void 0;
+		if ("blockedReason" in body) patch.blockedReason = typeof body.blockedReason === "string" ? body.blockedReason : void 0;
+		const locale = normalizeGoalUiLocale(body.uiLocale);
+		if (locale) patch.uiLocale = locale;
+		if (Object.keys(patch).length > 0) goal = goals.update(goalId, patch);
+		if (status) {
+			const previousStatus = goal?.status;
+			goal = goals.setStatus(goalId, status, { reason: typeof body.reason === "string" ? body.reason : void 0 });
+			const abortResult = goal && status === "archived" ? abortActiveWebchatRunForGoal(deps, goal) : {};
+			if (goal && previousStatus !== goal.status) deps.service.emit("goal.status.updated", {
+				goalId,
+				previousStatus,
+				status: goal.status,
+				goal
+			});
 			return c.json({
 				ok: true,
-				sessionKey,
-				cleared: true
+				goal,
+				...abortResult
 			});
 		}
-		const goalText = typeof body.goalText === "string" ? body.goalText.trim() : "";
-		if (!goalText) return c.json({
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.post("/api/goals/:goalId/continue", async (c) => {
+		const goalId = c.req.param("goalId");
+		const body = await c.req.json().catch(() => ({}));
+		const goal = goals.get(goalId);
+		if (!goal) return c.json({
 			ok: false,
-			error: "Missing goalText (or set clear:true)"
-		}, 400);
-		const meta = await sm.getSessionMetadata(sessionKey);
-		if (!meta) return c.json({
-			ok: false,
-			error: "Session not found"
-		}, 404);
-		const maxTurns = typeof body.maxTurns === "number" && Number.isFinite(body.maxTurns) ? Math.max(1, Math.min(500, Math.floor(body.maxTurns))) : defaultMaxTurns(cfg().goals);
-		const judgeModelRef = typeof body.judgeModelRef === "string" && body.judgeModelRef.trim() ? body.judgeModelRef.trim() : typeof cfg().goals?.judgeModelRef === "string" ? cfg().goals.judgeModelRef.trim() : void 0;
-		const uiLocale = normalizeGoalUiLocale(body.uiLocale);
-		const next = {
-			goal: goalText,
-			status: "active",
-			turnsUsed: 0,
-			maxTurns,
-			createdAt: Date.now(),
-			lastTurnAt: 0,
-			decomposed: false,
-			consecutiveParseFailures: 0,
-			...judgeModelRef ? { judgeModelRef } : {},
-			...uiLocale ? { uiLocale } : {}
-		};
-		const customData = mergeCustomDataPatch({ ...meta.customData }, { [PERSISTENT_GOAL_CUSTOM_KEY]: serializePersistentGoal(next) });
-		await sm.updateSessionMetadata(sessionKey, { customData });
-		const persistentGoal = readPersistentGoal((await sm.getSessionMetadata(sessionKey))?.customData);
-		deps.service.enqueueWebchatPersistentGoalKickoff(sessionKey, goalText);
+			error: "Goal not found"
+		}, 404);
+		let sessionKey = typeof body.sessionKey === "string" && body.sessionKey.trim() ? body.sessionKey.trim() : goal.activeSessionKey;
+		if (!sessionKey) {
+			sessionKey = buildSessionKey({
+				agentId: goal.agentId || getDefaultAgentId(cfg()),
+				source: "webchat",
+				accountId: "default",
+				peerKind: "direct",
+				peerId: `goal-${sanitizeSegment(goal.id) || Date.now()}`
+			});
+			await deps.service.sessionIndexInstance.saveMessages(sessionKey, []);
+			goals.attachSession(goalId, sessionKey);
+		}
+		const queued = deps.service.enqueueGoalRun(goalId, {
+			message: typeof body.message === "string" ? body.message : void 0,
+			maxRetries: typeof body.maxRetries === "number" && Number.isFinite(body.maxRetries) ? body.maxRetries : void 0,
+			source: "api"
+		});
+		const nextGoal = goals.get(goalId);
 		return c.json({
 			ok: true,
+			goal: nextGoal,
 			sessionKey,
-			persistentGoal
+			queued
+		});
+	});
+	authenticated.post("/api/goals/:goalId/enqueue", async (c) => {
+		const goalId = c.req.param("goalId");
+		const body = await c.req.json().catch(() => ({}));
+		if (!goals.get(goalId)) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const item = deps.service.enqueueGoalRun(goalId, {
+			message: typeof body.message === "string" ? body.message : void 0,
+			maxRetries: typeof body.maxRetries === "number" && Number.isFinite(body.maxRetries) ? body.maxRetries : void 0,
+			source: "api"
+		});
+		return c.json({
+			ok: true,
+			item
+		});
+	});
+	authenticated.post("/api/goals/:goalId/pause", async (c) => {
+		const body = await c.req.json().catch(() => ({}));
+		const before = goals.get(c.req.param("goalId"));
+		const goal = goals.pause(c.req.param("goalId"), typeof body.reason === "string" && body.reason.trim() ? body.reason.trim() : "user-paused");
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		if (before?.status !== goal.status) deps.service.emit("goal.status.updated", {
+			goalId: goal.id,
+			previousStatus: before?.status,
+			status: goal.status,
+			goal
+		});
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.post("/api/goals/:goalId/resume", async (c) => {
+		const before = goals.get(c.req.param("goalId"));
+		const goal = goals.resume(c.req.param("goalId"));
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		if (before?.status !== goal.status) deps.service.emit("goal.status.updated", {
+			goalId: goal.id,
+			previousStatus: before?.status,
+			status: goal.status,
+			goal
+		});
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.post("/api/goals/:goalId/reopen", async (c) => {
+		const before = goals.get(c.req.param("goalId"));
+		const goal = goals.reopen(c.req.param("goalId"));
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		if (before?.status !== goal.status) deps.service.emit("goal.status.updated", {
+			goalId: goal.id,
+			previousStatus: before?.status,
+			status: goal.status,
+			goal
+		});
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.post("/api/goals/:goalId/complete", async (c) => {
+		const before = goals.get(c.req.param("goalId"));
+		const goal = goals.complete(c.req.param("goalId"));
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		if (before?.status !== goal.status) deps.service.emit("goal.status.updated", {
+			goalId: goal.id,
+			previousStatus: before?.status,
+			status: goal.status,
+			goal
+		});
+		return c.json({
+			ok: true,
+			goal
 		});
 	});
-	/** Checklist CRUD for standing goals (`/subgoal` parity for webchat). */
-	authenticated.post("/api/goals/webchat/checklist", async (c) => {
+	authenticated.post("/api/goals/:goalId/archive", async (c) => {
+		const before = goals.get(c.req.param("goalId"));
+		const goal = goals.archive(c.req.param("goalId"));
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const abortResult = abortActiveWebchatRunForGoal(deps, goal);
+		if (before?.status !== goal.status) deps.service.emit("goal.status.updated", {
+			goalId: goal.id,
+			previousStatus: before?.status,
+			status: goal.status,
+			goal
+		});
+		return c.json({
+			ok: true,
+			goal,
+			...abortResult
+		});
+	});
+	authenticated.post("/api/goals/:goalId/unarchive", async (c) => {
+		const before = goals.get(c.req.param("goalId"));
+		const goal = goals.unarchive(c.req.param("goalId"));
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		if (before?.status !== goal.status) deps.service.emit("goal.status.updated", {
+			goalId: goal.id,
+			previousStatus: before?.status,
+			status: goal.status,
+			goal
+		});
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.post("/api/goals/:goalId/attach", async (c) => {
+		const goalId = c.req.param("goalId");
 		const body = await c.req.json().catch(() => ({}));
 		const sessionKey = typeof body.sessionKey === "string" ? body.sessionKey.trim() : "";
 		if (!sessionKey) return c.json({
 			ok: false,
 			error: "Missing sessionKey"
 		}, 400);
-		const op = typeof body.op === "string" ? body.op.trim().toLowerCase() : "";
-		const meta = await sm.getSessionMetadata(sessionKey);
-		if (!meta) return c.json({
-			ok: false,
-			error: "Session not found"
-		}, 404);
-		let mutation = null;
-		if (op === "reset") mutation = applyChecklistUserMutation(meta.customData, { type: "reset" });
-		else if (op === "add") {
-			const text = typeof body.text === "string" ? body.text : "";
-			mutation = applyChecklistUserMutation(meta.customData, {
-				type: "add",
-				text
-			});
-		} else if (op === "remove") {
-			const index = typeof body.index === "number" && Number.isFinite(body.index) ? Math.floor(body.index) : void 0;
-			if (index === void 0 || index < 1) return c.json({
-				ok: false,
-				error: "Missing or invalid index (1-based)"
-			}, 400);
-			mutation = applyChecklistUserMutation(meta.customData, {
-				type: "remove",
-				index1Based: index
-			});
-		} else if (op === "mark") {
-			const index = typeof body.index === "number" && Number.isFinite(body.index) ? Math.floor(body.index) : void 0;
-			const status = typeof body.status === "string" ? body.status.trim().toLowerCase() : "";
-			if (index === void 0 || index < 1) return c.json({
-				ok: false,
-				error: "Missing or invalid index (1-based)"
-			}, 400);
-			if (status !== "pending" && status !== "completed" && status !== "impossible") return c.json({
-				ok: false,
-				error: "status must be pending, completed, or impossible"
-			}, 400);
-			mutation = applyChecklistUserMutation(meta.customData, {
-				type: "mark",
-				index1Based: index,
-				status
-			});
-		} else return c.json({
+		const goal = goals.attachSession(goalId, sessionKey);
+		if (!goal) return c.json({
 			ok: false,
-			error: "Invalid op (add|remove|mark|reset)"
+			error: "Goal not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.post("/api/goals/:goalId/detach", async (c) => {
+		const goal = goals.update(c.req.param("goalId"), { activeSessionKey: void 0 });
+		if (!goal) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.get("/api/goals/:goalId/runs", async (c) => {
+		const goalId = c.req.param("goalId");
+		if (!goals.get(goalId)) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			runs: goals.listRuns(goalId, parseLimit(c.req.query("limit")))
+		});
+	});
+	authenticated.get("/api/goals/:goalId/events", async (c) => {
+		const goalId = c.req.param("goalId");
+		if (!goals.get(goalId)) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			events: goals.listEvents(goalId, parseLimit(c.req.query("limit"), 100))
+		});
+	});
+	authenticated.get("/api/goals/:goalId/evidence", async (c) => {
+		const goalId = c.req.param("goalId");
+		if (!goals.get(goalId)) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		return c.json({
+			ok: true,
+			evidence: goals.listEvidence(goalId, parseLimit(c.req.query("limit"), 100))
+		});
+	});
+	authenticated.post("/api/goals/:goalId/evidence", async (c) => {
+		const goalId = c.req.param("goalId");
+		if (!goals.get(goalId)) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const body = await c.req.json().catch(() => ({}));
+		const title = typeof body.title === "string" ? body.title.trim() : "";
+		const kind = body.kind;
+		if (!title) return c.json({
+			ok: false,
+			error: "Missing title"
 		}, 400);
-		if (mutation.kind === "error") return c.json({
+		if (kind !== "file" && kind !== "diff" && kind !== "command" && kind !== "test" && kind !== "link" && kind !== "message" && kind !== "artifact") return c.json({
 			ok: false,
-			error: mutation.error
+			error: "Invalid evidence kind"
 		}, 400);
-		if (mutation.kind === "noop") {
-			const persistentGoal = readPersistentGoal(meta.customData);
-			return c.json({
-				ok: true,
-				sessionKey,
-				noop: true,
-				message: mutation.message,
-				persistentGoal
-			});
-		}
-		const uiLocale = normalizeGoalUiLocale(body.uiLocale);
-		const customData = uiLocale != null ? mergePersistentGoalUiLocale(mutation.customData, uiLocale) ?? mutation.customData : mutation.customData;
-		await sm.updateSessionMetadata(sessionKey, { customData });
-		const persistentGoal = readPersistentGoal((await sm.getSessionMetadata(sessionKey))?.customData);
+		const evidence = goals.addEvidence({
+			goalId,
+			runId: typeof body.runId === "string" ? body.runId : void 0,
+			kind,
+			title,
+			summary: typeof body.summary === "string" ? body.summary : void 0,
+			uri: typeof body.uri === "string" ? body.uri : void 0,
+			data: body.data
+		});
 		return c.json({
 			ok: true,
-			sessionKey,
-			op,
-			persistentGoal
+			evidence
+		});
+	});
+	authenticated.post("/api/goals/:goalId/checklist", async (c) => {
+		const goalId = c.req.param("goalId");
+		if (!goals.get(goalId)) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const body = await c.req.json().catch(() => ({}));
+		const text = typeof body.text === "string" ? body.text.trim() : "";
+		if (!text) return c.json({
+			ok: false,
+			error: "Missing text"
+		}, 400);
+		const goal = goals.updateChecklist(goalId, {
+			type: "add",
+			text,
+			addedBy: "user"
+		});
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.patch("/api/goals/:goalId/checklist/:itemId", async (c) => {
+		const goalId = c.req.param("goalId");
+		const itemId = c.req.param("itemId");
+		if (!goals.get(goalId)) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const body = await c.req.json().catch(() => ({}));
+		const status = body.status;
+		if (status !== "pending" && status !== "completed" && status !== "impossible") return c.json({
+			ok: false,
+			error: "Invalid checklist status"
+		}, 400);
+		const goal = goals.updateChecklist(goalId, {
+			type: "mark",
+			itemId,
+			status,
+			evidenceSummary: typeof body.evidenceSummary === "string" ? body.evidenceSummary : void 0
+		});
+		return c.json({
+			ok: true,
+			goal
+		});
+	});
+	authenticated.delete("/api/goals/:goalId/checklist/:itemId", async (c) => {
+		const goalId = c.req.param("goalId");
+		if (!goals.get(goalId)) return c.json({
+			ok: false,
+			error: "Goal not found"
+		}, 404);
+		const goal = goals.updateChecklist(goalId, {
+			type: "remove",
+			itemId: c.req.param("itemId")
+		});
+		return c.json({
+			ok: true,
+			goal
 		});
 	});
 }