@xopcai/xopc 0.0.307 → 0.0.309

package/dist/src/connectors/connected-source-understanding.js

@@ -95,6 +95,7 @@ async function deriveConnectedSourceUnderstanding(input) {
 			config: input.config,
 			items
 		});
+		input.assertAuthorized?.();
 		const byRef = new Map(items.map((item) => [item.evidenceRef, item]));
 		let created = 0;
 		for (const candidate of analysis.profileCandidates.filter(isPortraitCandidate)) {

package/dist/src/connectors/learning-coordinator.js

@@ -15,7 +15,7 @@ import "../knowledge/index.js";
 import { ingestComposioConnectedSource } from "./connected-source-ingestion.js";
 import { deriveConnectedSourceUnderstanding } from "./connected-source-understanding.js";
 import { listConnectedContentCandidates, readConnectedContent } from "./content-enrichment.js";
-import { createUnderstandingSourceRun, getUnderstandingSourceGrant, listUnderstandingSourceRuns, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant } from "../user-context/sources/repository.js";
+import { createUnderstandingSourceRun, getUnderstandingSourceGrant, listUnderstandingSourceGrants, listUnderstandingSourceRuns, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant } from "../user-context/sources/repository.js";
 //#region src/connectors/learning-coordinator.ts
 init_logger();
 const log = createLogger("ConnectorLearning");
@@ -33,7 +33,9 @@ function connectorSourceCategory(toolkit) {
 	return "files";
 }
 function ensureUnderstandingSourceRun(job, toolkit, displayName) {
-	const grant = upsertUnderstandingSourceGrant({
+	const existing = listUnderstandingSourceGrants({ includeRevoked: true }).find((grant) => grant.sourceKey === `connector-account:${job.accountId}`);
+	if (existing?.status === "revoked") throw new Error("Source authorization was revoked.");
+	const grant = existing ?? upsertUnderstandingSourceGrant({
 		sourceKey: `connector-account:${job.accountId}`,
 		adapterId: `connector:${job.connectorId}`,
 		category: connectorSourceCategory(toolkit),
@@ -75,6 +77,14 @@ function startConnectorLearningCoordinator(options) {
 		if (!connection) return null;
 		if (!connection.accountId) throw new Error(`Connector account is missing for connection ${connection.id}.`);
 		if (!getConnectorAccount(connection.accountId)?.enabled) return null;
+		if (listUnderstandingSourceGrants({ includeRevoked: true }).some((grant) => grant.sourceKey === `connector-account:${connection.accountId}` && grant.status === "revoked")) return null;
+		if (request.reason === "manual") {
+			const active = listConnectorLearningJobs({
+				accountId: connection.accountId,
+				limit: 100
+			}).find((job) => job.status === "running" || job.status === "queued" && (!job.nextRunAt || Date.parse(job.nextRunAt) <= Date.now()));
+			if (active) return active;
+		}
 		const syncPolicy = getConnectorSyncPolicyForConnection(connection.id);
 		if (request.reason !== "manual" && syncPolicy?.scanEnabled !== true) return null;
 		const definition = getConnectorDefinition(connection.connectorId);
@@ -213,13 +223,21 @@ function startConnectorLearningCoordinator(options) {
 			knowledgeCount: 0,
 			status: "completed"
 		};
+		const sourceGrantPolicy = getUnderstandingSourceGrant(sourceRun.grantId)?.processingPolicy;
 		try {
 			semantic = await deriveConnectedSourceUnderstanding({
 				config: options.getConfig(),
 				agentId: job.agentId,
 				sourceInstanceId: job.sourceInstanceId,
 				sourceRunId: sourceRun.id,
-				processingPolicy: getUnderstandingSourceGrant(sourceRun.grantId)?.processingPolicy ?? "local_only"
+				processingPolicy: getUnderstandingSourceGrant(sourceRun.grantId)?.processingPolicy ?? "local_only",
+				assertAuthorized: () => {
+					const grant = getUnderstandingSourceGrant(sourceRun.grantId);
+					if (grant?.status !== "active" || !getConnectorAccount(job.accountId)?.enabled || grant.processingPolicy !== sourceGrantPolicy || !learningEnabled(options.getConfig()) || listConnectorLearningJobs({
+						accountId: job.accountId,
+						limit: 100
+					}).find((item) => item.id === job.id)?.status !== "running") throw new Error("Source authorization changed during analysis.");
+				}
 			});
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error);
@@ -297,7 +315,7 @@ function startConnectorLearningCoordinator(options) {
 					await execute(job);
 				} catch (err) {
 					const errorMessage = err instanceof Error ? err.message : String(err);
-					const exhausted = job.attemptCount >= 5;
+					const exhausted = job.attemptCount >= 5 || job.idempotencyKey.startsWith("understanding-refresh:");
 					publish(updateConnectorLearningJob(job.id, {
 						status: exhausted ? "paused" : "failed",
 						error: learningFailureCode(err),
@@ -305,11 +323,15 @@ function startConnectorLearningCoordinator(options) {
 						finished: true
 					}));
 					const definition = getConnectorDefinition(job.connectorId);
-					if (definition?.runtime.type === "composio" && definition.runtime.role === "toolkit") updateUnderstandingSourceRun(ensureUnderstandingSourceRun(job, definition.runtime.toolkit, definition.displayName).id, {
-						status: "failed",
-						errorMessage: learningFailureCode(err),
-						completed: true
-					});
+					if (definition?.runtime.type === "composio" && definition.runtime.role === "toolkit") {
+						const grant = listUnderstandingSourceGrants({ includeRevoked: true }).find((item) => item.sourceKey === `connector-account:${job.accountId}`);
+						const sourceRun = grant && listUnderstandingSourceRuns(grant.id, 100).find((item) => item.metadata.connectorLearningJobId === job.id);
+						if (sourceRun) updateUnderstandingSourceRun(sourceRun.id, {
+							status: "failed",
+							errorMessage: learningFailureCode(err),
+							completed: true
+						});
+					}
 					log.warn({
 						err,
 						jobId: job.id,

package/dist/src/gateway/agent-builtin-tools.d.ts

@@ -277,4 +277,4 @@ export declare const GATEWAY_BUILTIN_TOOLS: readonly [{
         readonly zh: "使用已验证的参数执行选定的外部工具。";
     };
 }];
-export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "image" | "knowledge_search" | "knowledge_get" | "knowledge_write" | "user_context_search" | "user_context_get" | "user_context_update" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "todo" | "clarify" | "web_extract" | "image_generate" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "xopc_tool_search" | "xopc_tool_describe" | "xopc_tool_execute" | "send_message" | "send_media" | "read_media" | "create_share" | "session_status" | "memory_maintenance" | "computer_use" | "tool_manual" | "delegate_task" | "skill_install" | "text_to_speech" | "execute_code" | "create_desktop_pet")[];
+export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "image" | "knowledge_search" | "knowledge_get" | "knowledge_write" | "user_context_search" | "user_context_get" | "user_context_update" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "todo" | "clarify" | "xopc_tool_execute" | "web_extract" | "image_generate" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "xopc_tool_search" | "xopc_tool_describe" | "send_message" | "send_media" | "read_media" | "create_share" | "session_status" | "memory_maintenance" | "computer_use" | "tool_manual" | "delegate_task" | "skill_install" | "text_to_speech" | "execute_code" | "create_desktop_pet")[];

package/dist/src/gateway/heartbeat/service.js

@@ -4,11 +4,11 @@ import { init_agent_scope, resolveDefaultAgentId } from "../../agent/agent-scope
 import { createConversation, init_conversation_repository, resolveRoutedConversation } from "../../storage/sqlite/conversation-repository.js";
 import { shouldSilence, stripHeartbeatToken } from "../../heartbeat/tokens.js";
 import { proactiveChecksAllowed, proactivePreferences } from "../../proactive/policy/service.js";
+import { beginHeartbeatCheck, completeHeartbeatCheck, deliverHeartbeatChecks, recentHeartbeatChecks, recoverHeartbeatChecks } from "./check-store.js";
+import { appendCronEventLines } from "../../heartbeat/event-prompt.js";
 import { isWithinActiveHours } from "../../heartbeat/active-hours.js";
 import { isHeartbeatContentEmpty } from "../../heartbeat/content-check.js";
-import { appendCronEventLines } from "../../heartbeat/event-prompt.js";
 import { createHeartbeatWake } from "../../heartbeat/wake.js";
-import { beginHeartbeatCheck, completeHeartbeatCheck, deliverHeartbeatChecks, recentHeartbeatChecks, recoverHeartbeatChecks } from "./check-store.js";
 import { resolveHeartbeatMdPath } from "../workspace-heartbeat-path.js";
 import { readFile } from "fs/promises";
 //#region src/gateway/heartbeat/service.ts

package/dist/src/gateway/hono/lib/config-payload.d.ts

@@ -49,6 +49,7 @@ export declare function buildSafeWebConfigPayload(service: GatewayService, optio
             };
             tools: Record<string, {
                 mode: "allow" | "deny" | "ask";
+                readOnly?: boolean;
                 maxCallsPerTurn?: number;
                 timeoutMs?: number;
             }>;
@@ -99,6 +100,7 @@ export declare function buildSafeWebConfigPayload(service: GatewayService, optio
             };
             tools: Record<string, {
                 mode: "allow" | "deny" | "ask";
+                readOnly?: boolean;
                 maxCallsPerTurn?: number;
                 timeoutMs?: number;
             }>;
@@ -222,7 +224,7 @@ export declare function buildSafeWebConfigPayload(service: GatewayService, optio
         };
         userModel: {
             enabled: boolean;
-            writePolicy: "allow" | "confirm" | "deny";
+            writePolicy: "allow" | "deny";
             sensitiveWritePolicy: "allow" | "confirm" | "deny";
             processingPolicy: "local_only" | "remote_allowed";
             extraction: {
@@ -244,7 +246,7 @@ export declare function buildSafeWebConfigPayload(service: GatewayService, optio
         };
         knowledgeMemory: {
             enabled: boolean;
-            writePolicy: "allow" | "confirm" | "deny";
+            writePolicy: "allow" | "deny";
             readScopes: ("project" | "session" | "agent" | "workspace" | "global")[];
             contentSources: ("memory" | "connector" | "local_import")[];
             searchStrategy: "local-first" | "external-first" | "fanout" | "local-only" | "external-only";

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

@@ -19,6 +19,7 @@ import { createConnectorSetupSecretRequest, submitConnectorSetupSecret } from ".
 import { recordConnectorHealthUsage } from "../../../connectors/usage.js";
 import { getConnectorInstance, getInstalledConnectorDefinition, listConnectorInstances } from "../../../connectors/instances.js";
 import { installConnector, installConnectorDefinition, uninstallConnector, updateConnectorConfig } from "../../../connectors/install.js";
+import { ConfigPersistenceError, persistConfigMutation } from "../../../config/config-mutation.js";
 import { resumeApprovedConnectorAction } from "../../../connectors/approval-resume.js";
 import { getMcpOAuthManager } from "../../../agent/mcp/oauth/mcp-oauth-manager.js";
 import { startConnectorAuthorization } from "../../../connectors/auth-provider-registry.js";
@@ -26,7 +27,6 @@ import { composioLogoResponse } from "../../../connectors/composio-logo.js";
 import { inspectManagedComposioStatus } from "../../../connectors/composio-managed-client.js";
 import { appendComposioTriggerEvent, listComposioTriggerEvents } from "../../../connectors/composio-triggers.js";
 import { ingestLocalFolderSource } from "../../../connectors/connected-source-ingestion.js";
-import { ConfigPersistenceError, persistConfigMutation } from "../../../config/config-mutation.js";
 import { previewConnectorDefinition, testConnectorInstance } from "../../../connectors/health.js";
 import { listUnderstandingSourceGrants, revokeUnderstandingSourceGrant } from "../../../user-context/sources/repository.js";
 import { setConnectorEnabled } from "../../../connectors/lifecycle.js";

package/dist/src/gateway/hono/routes/context-sources.js

@@ -8,7 +8,6 @@ import "../../../user-model/index.js";
 import { listConnectedContentCandidates, readConnectedContent } from "../../../connectors/content-enrichment.js";
 import { getUnderstandingSourceGrant, listUnderstandingSourceGrants, listUnderstandingSourceRuns, revokeUnderstandingSourceGrant, updateUnderstandingSourceGrantPolicies } from "../../../user-context/sources/repository.js";
 import { listUnderstandingSourceDefinitions } from "../../../user-context/sources/catalog.js";
-import { randomUUID } from "node:crypto";
 //#region src/gateway/hono/routes/context-sources.ts
 init_agent_scope();
 init_transaction();
@@ -103,28 +102,6 @@ function registerContextSourceRoutes(authenticated, deps) {
 			return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
 		}
 	});
-	authenticated.post("/api/context-sources/grants/:grantId/refresh", limited, async (c) => {
-		const grant = getUnderstandingSourceGrant(c.req.param("grantId"));
-		if (!grant || grant.status !== "active") return c.json({ error: "Active context source not found" }, 404);
-		try {
-			if (grant.adapterId === "local-work-folders") {
-				const result = await service.refreshDirectorySourceIfChanged({
-					id: grant.id,
-					idempotencyKey: randomUUID()
-				});
-				return c.json({ result }, result.changed ? 202 : 200);
-			}
-			const accountId = typeof grant.config.accountId === "string" ? grant.config.accountId : "";
-			const connectionId = accountId ? getConnectorAccount(accountId)?.currentConnectionId : void 0;
-			const job = connectionId ? deps.service.requestConnectorLearning(connectionId, {
-				mode: "incremental",
-				reason: "manual"
-			}) : null;
-			return job ? c.json({ job }, 202) : c.json({ error: "Context source cannot be refreshed here" }, 409);
-		} catch (error) {
-			return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
-		}
-	});
 	authenticated.get("/api/context-sources/work-folders", (c) => c.json({ sources: service.listDirectorySources() }));
 	authenticated.post("/api/context-sources/work-folders", limited, async (c) => {
 		const input = await c.req.json().catch(() => null);

package/dist/src/gateway/hono/routes/lazy-bundles.js

@@ -329,6 +329,14 @@ const AUTHENTICATED_LAZY_ROUTE_BUNDLES = [
 			return { register: registerVoiceRoutes };
 		}
 	},
+	{
+		id: "user-model-refresh",
+		match: (pathname) => pathname === "/api/user-model/refresh" || pathname.startsWith("/api/user-model/refresh/"),
+		load: async () => {
+			const { registerUserModelRefreshRoutes } = await import("./user-model-refresh.js");
+			return { register: registerUserModelRefreshRoutes };
+		}
+	},
 	{
 		id: "user-model",
 		match: (path) => startsWithAny(path, [

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

@@ -405,6 +405,10 @@ function registerProjectsRoutes(authenticated, deps) {
 			originClass: "system",
 			replaceExisting: true
 		});
+		if (!record.item) return c.json({
+			ok: false,
+			error: "This memory was deleted and automatic recreation is disabled."
+		}, 409);
 		return c.json({
 			ok: true,
 			knowledge: record.item
@@ -804,6 +808,10 @@ function registerProjectsRoutes(authenticated, deps) {
 			originClass: "agent",
 			replaceExisting: true
 		});
+		if (!record.item) return c.json({
+			ok: false,
+			error: "This memory was deleted and automatic recreation is disabled."
+		}, 409);
 		return c.json({
 			ok: true,
 			knowledge: record.item

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

@@ -2,7 +2,9 @@ import { deleteBrowserTabBinding } from "../../../storage/sqlite/browser-tab-bin
 import { conversationIdSchema } from "../../../../packages/gateway-contract/src/conversation-identity.js";
 import { SessionDiscoveryQuerySchema } from "../../../../packages/gateway-contract/src/session-identity.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
+import "../../../session/types.js";
 import { deleteSessionRecord, init_session_repository } from "../../../storage/sqlite/session-repository.js";
+import { SidebarLayoutConflictError, getSidebarLayout, replaceSidebarLayout, sortBySidebarLayout } from "../../../storage/sqlite/sidebar-layout-repository.js";
 import { ConversationAlreadyExistsError, createConversation, init_conversation_repository } from "../../../storage/sqlite/conversation-repository.js";
 import { resolveProjectAgentId } from "../../../projects/project-agent.js";
 import "../../../projects/index.js";
@@ -48,6 +50,21 @@ function parseOffset(value) {
 	const parsed = value ? Number.parseInt(value, 10) : 0;
 	return Number.isFinite(parsed) ? Math.max(0, parsed) : 0;
 }
+function listAllSidebarProjects(service, options = {}) {
+	const items = [];
+	let offset = 0;
+	while (true) {
+		const page = service.projects.listWithSidebarSessions({
+			status: "active",
+			limit: 50,
+			offset,
+			...options
+		});
+		items.push(...page.items);
+		if (!page.hasMore || page.items.length === 0) return items;
+		offset += page.items.length;
+	}
+}
 function isHistoryCursor(value) {
 	if (!/^(0|[1-9]\d*)$/.test(value)) return false;
 	return Number.isSafeInteger(Number(value));
@@ -101,18 +118,25 @@ function registerSessionsRoutes(authenticated, deps) {
 		const staleDays = parsePositiveInt(c.req.query("staleDays"), DEFAULT_SIDEBAR_STALE_DAYS, 3650);
 		const updatedAfter = Date.now() - staleDays * 24 * 60 * 60 * 1e3;
 		const includeConversationId = c.req.query("includeConversationId")?.trim() || void 0;
-		const projects = service.projects.listWithSidebarSessions({
-			status: "active",
-			limit: projectLimit,
-			offset: projectOffset,
+		const allProjectItems = listAllSidebarProjects(service, {
 			updatedAfter,
 			includePinned: true,
 			includeConversationId
 		});
+		const projectLayout = getSidebarLayout("projects");
+		const orderedProjects = sortBySidebarLayout(allProjectItems, projectLayout, (project) => project.id);
+		const projects = {
+			items: orderedProjects.slice(projectOffset, projectOffset + projectLimit),
+			total: orderedProjects.length,
+			limit: projectLimit,
+			offset: projectOffset,
+			hasMore: projectOffset + projectLimit < orderedProjects.length
+		};
 		const projectItems = await Promise.all(projects.items.map(async (project) => {
-			const sessions = await service.sessions.listSessions({
+			const sessionLayout = getSidebarLayout(`project:${project.id}`);
+			const allSessions = await service.sessions.listSessions({
 				projectId: project.id,
-				limit: sessionPreviewLimit,
+				limit: 5e3,
 				offset: 0,
 				updatedAfter,
 				includePinned: true,
@@ -122,21 +146,47 @@ function registerSessionsRoutes(authenticated, deps) {
 			});
 			return {
 				project,
-				sessions: sessions.items,
-				sessionTotal: sessions.total,
-				sessionHasMore: sessions.hasMore
+				sessions: sortBySidebarLayout(allSessions.items, sessionLayout, (session) => session.key).slice(0, sessionPreviewLimit),
+				sessionTotal: allSessions.total,
+				sessionHasMore: sessionPreviewLimit < allSessions.total
 			};
 		}));
-		const inbox = await service.sessions.listSessions({
+		const inboxLayout = getSidebarLayout("inbox");
+		const allInbox = await service.sessions.listSessions({
 			unassigned: true,
-			limit: inboxLimit,
-			offset: inboxOffset,
+			limit: 5e3,
+			offset: 0,
 			updatedAfter,
 			includePinned: true,
 			includeConversationId,
 			sortBy: "updatedAt",
 			sortOrder: "desc"
 		});
+		const orderedInbox = sortBySidebarLayout(allInbox.items, inboxLayout, (session) => session.key);
+		const inbox = {
+			...allInbox,
+			items: orderedInbox.slice(inboxOffset, inboxOffset + inboxLimit),
+			limit: inboxLimit,
+			offset: inboxOffset,
+			hasMore: inboxOffset + inboxLimit < allInbox.total
+		};
+		const pinnedLayout = getSidebarLayout("pinned");
+		const pinned = sortBySidebarLayout((await service.sessions.listSessions({
+			status: "pinned",
+			limit: 5e3,
+			offset: 0,
+			sortBy: "updatedAt",
+			sortOrder: "desc"
+		})).items, pinnedLayout, (session) => session.key);
+		const layouts = Object.fromEntries([
+			projectLayout,
+			inboxLayout,
+			pinnedLayout,
+			...projects.items.map((project) => getSidebarLayout(`project:${project.id}`))
+		].map((layout) => [layout.containerId, {
+			itemIds: layout.itemIds,
+			revision: layout.revision
+		}]));
 		return c.json({
 			ok: true,
 			projects: {
@@ -146,9 +196,87 @@ function registerSessionsRoutes(authenticated, deps) {
 				offset: projects.offset,
 				hasMore: projects.hasMore
 			},
-			inbox
+			inbox,
+			pinned,
+			layouts
 		});
 	});
+	authenticated.put("/api/sidebar/layouts/:containerId", async (c) => {
+		const blocked = ensureGatewayReadyForSessions(c, service, "sessions.list");
+		if (blocked) return blocked;
+		const containerId = decodeURIComponent(c.req.param("containerId"));
+		if (containerId !== "projects" && containerId !== "pinned" && containerId !== "inbox" && !containerId.startsWith("project:")) return c.json({
+			ok: false,
+			error: "Invalid sidebar container"
+		}, 400);
+		const body = await c.req.json().catch(() => ({}));
+		if (!Array.isArray(body.itemIds) || body.itemIds.length > 5e3 || body.itemIds.some((id) => typeof id !== "string" || !id.trim())) return c.json({
+			ok: false,
+			error: "itemIds must be an array of non-empty strings"
+		}, 400);
+		if (!Number.isInteger(body.expectedRevision) || body.expectedRevision < 0) return c.json({
+			ok: false,
+			error: "expectedRevision must be a non-negative integer"
+		}, 400);
+		const itemIds = [...new Set(body.itemIds)];
+		if (itemIds.length !== body.itemIds.length) return c.json({
+			ok: false,
+			error: "itemIds must be unique"
+		}, 400);
+		let completeItemIds = itemIds;
+		if (containerId === "projects") {
+			if (itemIds.some((id) => !service.projects.get(id))) return c.json({
+				ok: false,
+				error: "Project not found"
+			}, 404);
+			const allIds = listAllSidebarProjects(service).map((project) => project.id);
+			completeItemIds = [...itemIds, ...allIds.filter((id) => !itemIds.includes(id))];
+		} else {
+			const projectId = containerId.startsWith("project:") ? containerId.slice(8) : void 0;
+			if (projectId && !service.projects.get(projectId)) return c.json({
+				ok: false,
+				error: "Project not found"
+			}, 404);
+			if ((await Promise.all(itemIds.map((id) => service.sessions.getSession(id)))).some((session) => {
+				if (!session || session.status === "archived") return true;
+				if (containerId === "pinned") return session.status !== "pinned";
+				if (session.status === "pinned") return true;
+				if (containerId === "inbox") return Boolean(session.projectId);
+				return session.projectId !== projectId;
+			})) return c.json({
+				ok: false,
+				error: "Sidebar item does not belong to the container"
+			}, 409);
+			const eligibleIds = (await service.sessions.listSessions({
+				...containerId === "pinned" ? { status: "pinned" } : containerId === "inbox" ? {
+					unassigned: true,
+					excludeArchived: true
+				} : {
+					projectId,
+					excludeArchived: true
+				},
+				limit: 5e3,
+				offset: 0,
+				sortBy: "updatedAt",
+				sortOrder: "desc"
+			})).items.filter((session) => containerId === "pinned" || session.status !== "pinned").map((session) => session.key);
+			completeItemIds = [...itemIds, ...eligibleIds.filter((id) => !itemIds.includes(id))];
+		}
+		try {
+			const layout = replaceSidebarLayout(containerId, completeItemIds, body.expectedRevision);
+			return c.json({
+				ok: true,
+				layout
+			});
+		} catch (error) {
+			if (error instanceof SidebarLayoutConflictError) return c.json({
+				ok: false,
+				error: error.message,
+				layout: error.current
+			}, 409);
+			throw error;
+		}
+	});
 	authenticated.post("/api/sessions", async (c) => {
 		const body = await c.req.json().catch(() => ({}));
 		if (body.conversationId !== void 0 && !conversationIdSchema.safeParse(body.conversationId).success) return c.json({

package/dist/src/gateway/hono/routes/user-model-refresh.d.ts

@@ -0,0 +1,5 @@
+import type { Hono } from 'hono';
+import { UnderstandingRefreshService } from '../../../user-context/sources/refresh-service.js';
+import type { AuthenticatedRouteDeps } from './deps.js';
+export declare function createUnderstandingRefreshService(deps: AuthenticatedRouteDeps): UnderstandingRefreshService;
+export declare function registerUserModelRefreshRoutes(app: Hono, deps: AuthenticatedRouteDeps, refresh?: UnderstandingRefreshService): void;

package/dist/src/gateway/hono/routes/user-model-refresh.js

@@ -0,0 +1,128 @@
+import { listConnectorLearningJobs } from "../../../storage/sqlite/connector-learning-repository.js";
+import { getConnectorAccount } from "../../../storage/sqlite/connector-account-repository.js";
+import "../../../storage/sqlite/index.js";
+import { listUnderstandingSourceRuns } from "../../../user-context/sources/repository.js";
+import { isLocalUnderstandingSourceId } from "../../../user-context/sources/local-source-contract.js";
+import { getWorkDiscoveryRun } from "../../../work-discovery/repository.js";
+import { normalizeUnderstandingSourceItems } from "../../../work-discovery/service.js";
+import { UnderstandingRefreshService } from "../../../user-context/sources/refresh-service.js";
+import { randomUUID } from "node:crypto";
+//#region src/gateway/hono/routes/user-model-refresh.ts
+function createUnderstandingRefreshService(deps) {
+	const service = deps.service;
+	return new UnderstandingRefreshService({
+		enabled: () => service.currentConfig.userContext.enabled && service.currentConfig.userContext.userModel.enabled,
+		emit: (type, payload) => service.emit(type, payload),
+		async start(grant, runId) {
+			if (grant.adapterId === "local-work-folders") return {
+				discoveryRunId: (await service.workDiscovery.rescanDirectorySource({
+					id: grant.id,
+					idempotencyKey: runId
+				})).id,
+				phase: "reading"
+			};
+			if (isLocalUnderstandingSourceId(grant.adapterId)) return { phase: "waiting_desktop" };
+			if (grant.adapterId.startsWith("connector:")) {
+				const account = typeof grant.config.accountId === "string" ? getConnectorAccount(grant.config.accountId) : void 0;
+				if (!account?.enabled || !account.currentConnectionId) throw new Error("Reconnect this source before updating.");
+				const job = service.requestConnectorLearning(account.currentConnectionId, {
+					mode: "incremental",
+					reason: "manual",
+					idempotencyKey: `understanding-refresh:${randomUUID()}`
+				});
+				if (!job) throw new Error("This source cannot currently be updated.");
+				return {
+					connectorLearningJobId: job.id,
+					accountId: account.id,
+					phase: "reading"
+				};
+			}
+			throw new Error("This source does not support understanding updates.");
+		},
+		progress(run) {
+			if (typeof run.metadata.discoveryRunId === "string") {
+				const discovery = getWorkDiscoveryRun(run.metadata.discoveryRunId);
+				if (!discovery) return {
+					status: "failed",
+					phase: "completed",
+					error: "Work folder update is no longer available."
+				};
+				return {
+					status: discovery.status === "completed" ? "completed" : discovery.status === "failed" || discovery.status === "canceled" ? "failed" : "running",
+					phase: discovery.status === "analyzing" ? "analyzing" : discovery.status === "queued" || discovery.status === "probing" ? "reading" : "completed",
+					error: discovery.errorMessage
+				};
+			}
+			if (typeof run.metadata.connectorLearningJobId === "string") {
+				const job = listConnectorLearningJobs({
+					accountId: String(run.metadata.accountId),
+					limit: 100
+				}).find((item) => item.id === run.metadata.connectorLearningJobId);
+				if (!job) return {
+					status: "failed",
+					phase: "completed",
+					error: "Connector update is no longer available."
+				};
+				const sourceRun = listUnderstandingSourceRuns(run.grantId, 100).find((item) => item.id !== run.id && item.metadata.connectorLearningJobId === job.id);
+				if (job.status === "completed") return {
+					status: sourceRun?.status === "partial" ? "partial" : "completed",
+					phase: "completed",
+					added: job.candidatesCreated,
+					itemsSeen: job.itemsDiscovered,
+					error: sourceRun?.status === "partial" ? "Some source information could not be analyzed. Retry this source." : void 0
+				};
+				if (job.status === "paused" || job.status === "failed") return {
+					status: "failed",
+					phase: "completed",
+					error: job.error ?? "Connector update failed."
+				};
+				return {
+					status: "running",
+					phase: job.phase === "deriving" ? "analyzing" : "reading",
+					itemsSeen: job.itemsDiscovered
+				};
+			}
+		},
+		async analyzeDesktop(grant, items, signal) {
+			const status = (await service.workDiscovery.importUnderstandingSources(items, grant.processingPolicy, signal, void 0, void 0, { grantId: grant.id })).sourceStatuses.find((item) => item.sourceId === grant.adapterId);
+			if (status?.status !== "completed") throw new Error(status?.error ?? "Source analysis did not complete.");
+			return {};
+		}
+	});
+}
+function registerUserModelRefreshRoutes(app, deps, refresh = createUnderstandingRefreshService(deps)) {
+	app.post("/api/user-model/refresh", deps.strictRateLimitMiddleware, async (c) => {
+		const input = await c.req.json().catch(() => null);
+		if (!input || typeof input !== "object" || Array.isArray(input) || input.sourceIds !== void 0 && (!Array.isArray(input.sourceIds) || !input.sourceIds.length || input.sourceIds.length > 100 || input.sourceIds.some((id) => typeof id !== "string" || !id))) return c.json({ error: "Provide sourceIds or an empty object to update all authorized sources." }, 400);
+		try {
+			return c.json({ batch: refresh.start(input.sourceIds) }, 202);
+		} catch (err) {
+			return c.json({ error: err instanceof Error ? err.message : String(err) }, 400);
+		}
+	});
+	app.get("/api/user-model/refresh", (c) => c.json({
+		batch: refresh.latest(),
+		sources: refresh.sources()
+	}));
+	app.get("/api/user-model/refresh/:id", (c) => {
+		const batch = refresh.get(c.req.param("id"));
+		return batch ? c.json({ batch }) : c.json({ error: "Update not found." }, 404);
+	});
+	app.post("/api/user-model/refresh/sources/:runId/collection", deps.strictRateLimitMiddleware, async (c) => {
+		const raw = await c.req.json().catch(() => null);
+		if (!raw || !Array.isArray(raw.items) || raw.items.length > 1200 || raw.error !== void 0 && typeof raw.error !== "string") return c.json({ error: "Invalid collection." }, 400);
+		const items = normalizeUnderstandingSourceItems(raw.items);
+		if (raw.items.length && !items.length) return c.json({ error: "No valid source items." }, 400);
+		try {
+			refresh.submitDesktop(c.req.param("runId"), {
+				items,
+				error: raw.error
+			});
+			return c.json({ ok: true }, 202);
+		} catch (err) {
+			return c.json({ error: err instanceof Error ? err.message : String(err) }, 409);
+		}
+	});
+}
+//#endregion
+export { createUnderstandingRefreshService, registerUserModelRefreshRoutes };

package/dist/src/gateway/hono/routes/user-model.js

@@ -1,10 +1,11 @@
 import { createCollaborationRule, getCollaborationRule, listCollaborationRules, setCollaborationRuleStatus } from "../../../storage/sqlite/collaboration-rule-repository.js";
-import { KnowledgeReviewConflictError, getKnowledgeItem, listKnowledgeItems, reviewKnowledgeItem, searchKnowledgeItems } from "../../../knowledge-memory/repository.js";
+import { KnowledgeReviewConflictError, deleteKnowledgeItem, getKnowledgeItem, listKnowledgeItems, reviewKnowledgeItem, searchKnowledgeItems } from "../../../knowledge-memory/repository.js";
 import "../../../knowledge-memory/index.js";
 import { createPriorityWindow, createUserGoal, listPriorityWindows, listUserGoals, setUserGoalStatus } from "../../../user-model/goals.js";
-import { getAssertionSlot, getUserAssertion, listUserAssertionSources, listUserAssertions, reconcileAssertion, setAssertionStatus } from "../../../user-model/repository.js";
+import { deleteUserAssertion, getAssertionSlot, getUserAssertion, listUserAssertionSources, listUserAssertions, reconcileAssertion, setAssertionStatus } from "../../../user-model/repository.js";
 import { applyUserProfilePatch, getUserProfileSnapshot } from "../../../user-model/profile.js";
 import { bootstrapUserModel } from "../../../user-model/bootstrap.js";
+import { canUseAssertion } from "../../../user-model/usage-policy.js";
 import "../../../user-model/index.js";
 import { listMemoryMaintenanceRuns } from "../../../memory-maintenance/service.js";
 import "../../../memory-maintenance/index.js";
@@ -117,7 +118,8 @@ function assertionView(assertion, sources = listUserAssertionSources([assertion.
 		predicate: slot.predicate,
 		subject: slot.subject,
 		scope: slot.scope,
-		sources
+		sources,
+		usable: canUseAssertion(assertion)
 	};
 }
 function registerUserModelRoutes(authenticated, deps) {
@@ -259,11 +261,14 @@ function registerUserModelRoutes(authenticated, deps) {
 				createdBy: "user",
 				...typeof input.correctionOfAssertionId === "string" ? { correctionOfAssertionId: input.correctionOfAssertionId } : {}
 			};
-			return c.json(reconcileAssertion(candidate), 201);
+			return c.json(reconcileAssertion(candidate, Date.now(), { restoreDeleted: true }), 201);
 		} catch (error) {
 			return c.json({ error: errorMessage(error) }, 400);
 		}
 	});
+	authenticated.delete("/api/user-model/assertions/:id", write, (c) => {
+		return deleteUserAssertion(c.req.param("id")) ? c.json({ ok: true }) : c.json({ error: "Assertion not found" }, 404);
+	});
 	authenticated.patch("/api/user-model/assertions/:id/status", write, async (c) => {
 		const input = await body(c);
 		const status = input?.status;
@@ -307,7 +312,6 @@ function registerUserModelRoutes(authenticated, deps) {
 				...current.validFrom === void 0 ? {} : { validFrom: current.validFrom },
 				...current.validTo === void 0 ? {} : { validTo: current.validTo },
 				observedAt: Date.now(),
-				...current.reviewAt === void 0 ? {} : { reviewAt: current.reviewAt },
 				createdBy: "user",
 				correctionOfAssertionId: current.id
 			}));
@@ -405,6 +409,9 @@ function registerUserModelRoutes(authenticated, deps) {
 		const item = getKnowledgeItem(c.req.param("id"));
 		return item ? c.json({ item }) : c.json({ error: "Knowledge item not found" }, 404);
 	});
+	authenticated.delete("/api/knowledge-memory/:id", write, (c) => {
+		return deleteKnowledgeItem(c.req.param("id")) ? c.json({ ok: true }) : c.json({ error: "Knowledge item not found" }, 404);
+	});
 	authenticated.post("/api/knowledge-memory/:id/review", write, async (c) => {
 		const input = await body(c);
 		const action = String(input?.action ?? "");