@xopcai/xopc 0.0.303 → 0.0.307

package/dist/src/infra/exec.d.ts

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import type { ChildProcess } from 'node:child_process';
 export type ExecResult = {
     stdout: string;
     stderr: string;
@@ -13,4 +13,4 @@ export type ExecOptions = {
 export declare function runExec(file: string, args: string[], opts?: ExecOptions): Promise<ExecResult>;
 export declare function spawnDetached(file: string, args: string[], opts: {
     stdio?: 'ignore' | 'pipe';
-}): ReturnType<typeof spawn>;
+}): ChildProcess;

package/dist/src/infra/exec.js

@@ -1,37 +1,42 @@
-import { execFile, spawn } from "node:child_process";
+import { ProcessExitError } from "../process/process-spec.js";
+import { runProcess, spawnProcess } from "../process/run-process.js";
 //#region src/infra/exec.ts
-function execFileAsync(file, args, opts) {
-	return new Promise((resolve, reject) => {
-		execFile(file, args, {
-			encoding: "utf8",
-			maxBuffer: opts.maxBuffer ?? 1024 * 1024,
-			cwd: opts.cwd,
-			env: opts.env,
-			timeout: opts.timeoutMs
-		}, (err, stdout, stderr) => {
-			if (err) {
-				const enriched = err;
-				enriched.stdout = typeof stdout === "string" ? stdout : String(stdout ?? "");
-				enriched.stderr = typeof stderr === "string" ? stderr : String(stderr ?? "");
-				reject(enriched);
-				return;
-			}
-			resolve({
-				stdout: typeof stdout === "string" ? stdout : String(stdout ?? ""),
-				stderr: typeof stderr === "string" ? stderr : String(stderr ?? "")
-			});
-		});
-	});
-}
 /** Run a subprocess and capture stdout/stderr (OpenClaw-aligned). */
 async function runExec(file, args, opts = {}) {
-	return execFileAsync(file, args, opts);
+	const result = await runProcess({
+		program: file,
+		args,
+		cwd: opts.cwd,
+		env: opts.env,
+		timeoutMs: opts.timeoutMs,
+		maxOutputBytes: opts.maxBuffer,
+		terminationPolicy: "tree"
+	});
+	if (result.exitCode !== 0) {
+		const error = new ProcessExitError({
+			program: file,
+			args
+		}, result);
+		error.stdout = result.stdout;
+		error.stderr = result.stderr;
+		throw error;
+	}
+	return {
+		stdout: result.stdout,
+		stderr: result.stderr
+	};
 }
 function spawnDetached(file, args, opts) {
-	return spawn(file, args, {
-		stdio: opts.stdio ?? "ignore",
+	const handle = spawnProcess({
+		program: file,
+		args,
 		detached: false
 	});
+	if (opts.stdio === "ignore") {
+		handle.child.stdout?.resume();
+		handle.child.stderr?.resume();
+	}
+	return handle.child;
 }
 //#endregion
 export { runExec, spawnDetached };

package/dist/src/infra/run-command.js

@@ -1,11 +1,6 @@
-import { spawn } from "node:child_process";
+import { runProcess } from "../process/run-process.js";
 //#region src/infra/run-command.ts
 const MAX_CAPTURE_BYTES = 512 * 1024;
-function appendCaptured(current, chunk) {
-	const next = current + chunk.toString();
-	if (next.length <= MAX_CAPTURE_BYTES) return next;
-	return next.slice(-MAX_CAPTURE_BYTES);
-}
 function createDefaultCommandRunner() {
 	return (argv, options) => runCommandWithTimeout(argv, options);
 }
@@ -16,50 +11,20 @@ function runCommandWithTimeout(argv, options) {
 		stdout: "",
 		stderr: "empty argv"
 	});
-	return new Promise((resolve) => {
-		const child = spawn(command, args, {
-			cwd: options.cwd,
-			env: options.env ?? process.env,
-			stdio: [
-				"ignore",
-				"pipe",
-				"pipe"
-			],
-			...process.platform === "win32" ? { shell: process.env.ComSpec && process.env.ComSpec.trim() || "cmd.exe" } : {}
-		});
-		let stdout = "";
-		let stderr = "";
-		let settled = false;
-		const finish = (result) => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeoutId);
-			resolve(result);
-		};
-		const timeoutId = setTimeout(() => {
-			child.kill("SIGTERM");
-		}, options.timeoutMs);
-		child.stdout?.on("data", (chunk) => {
-			stdout = appendCaptured(stdout, chunk);
-		});
-		child.stderr?.on("data", (chunk) => {
-			stderr = appendCaptured(stderr, chunk);
-		});
-		child.on("error", (err) => {
-			finish({
-				code: null,
-				stdout,
-				stderr: stderr || err.message
-			});
-		});
-		child.on("close", (code) => {
-			finish({
-				code,
-				stdout,
-				stderr
-			});
-		});
-	});
+	return runProcess({
+		program: command,
+		args,
+		cwd: options.cwd,
+		env: options.env,
+		timeoutMs: options.timeoutMs,
+		maxOutputBytes: MAX_CAPTURE_BYTES,
+		terminationPolicy: "tree",
+		...process.platform === "win32" ? { shell: process.env.ComSpec && process.env.ComSpec.trim() || "cmd.exe" } : {}
+	}).then((result) => ({
+		code: result.exitCode,
+		stdout: result.stdout,
+		stderr: result.stderr
+	}));
 }
 //#endregion
 export { createDefaultCommandRunner, runCommandWithTimeout };

package/dist/src/infra/update-restart.js

@@ -2,8 +2,8 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { init_paths, resolveConfigPath } from "../config/paths.js";
 import { init_loader, loadConfig } from "../config/loader.js";
-import { isRestartEnabled } from "../config/commands.flags.js";
 import { resolveGatewayService } from "../daemon/service.js";
+import { isRestartEnabled } from "../config/commands.flags.js";
 import { authorizeGatewaySigusr1Restart, writeGatewayRestartIntentSync } from "./restart.js";
 import { findVerifiedGatewayListenerPidsOnPortSync, signalVerifiedGatewayPidSync } from "./gateway-processes.js";
 import { refreshGatewayServiceAfterUpdate } from "./update-service-refresh.js";

package/dist/src/knowledge/connected-knowledge-pipeline.js

@@ -2,7 +2,7 @@ import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { claimKnowledgeSourceItems, completeKnowledgeSourceItemSynthesis, listKnowledgeSourceItems, pruneBoundedKnowledgeSourceItems } from "../storage/sqlite/knowledge-repository.js";
 import "../storage/sqlite/index.js";
-import { listKnowledgeItems, setKnowledgeStatus, writeKnowledgeItem } from "../knowledge-memory/repository.js";
+import { listKnowledgeItems, transitionKnowledgeStatus, writeKnowledgeItem } from "../knowledge-memory/repository.js";
 import "../knowledge-memory/index.js";
 import { randomUUID } from "node:crypto";
 //#region src/knowledge/connected-knowledge-pipeline.ts
@@ -54,7 +54,12 @@ var ConnectedKnowledgePipeline = class {
 				limit: 2e3
 			}).find((entry) => entry.canonicalKey === `source-item:${item.sourceInstanceId}:${item.externalId}`);
 			if (item.deletedAt) {
-				if (existing) setKnowledgeStatus(existing.id, "archived");
+				if (existing) transitionKnowledgeStatus({
+					id: existing.id,
+					status: "archived",
+					actor: "runtime",
+					reason: "Connected source item was deleted."
+				});
 				completeKnowledgeSourceItemSynthesis({
 					itemId: item.id,
 					workerId: this.workerId,
@@ -139,7 +144,12 @@ var ConnectedKnowledgePipeline = class {
 			recordClass: "source_index",
 			limit: 2e3
 		})) if (typeof item.source.sourceItemId === "string" && expiredIds.has(item.source.sourceItemId)) {
-			if (setKnowledgeStatus(item.id, "archived")) derivedDeleted += 1;
+			if (transitionKnowledgeStatus({
+				id: item.id,
+				status: "archived",
+				actor: "maintenance",
+				reason: "Connected source retention window expired."
+			})) derivedDeleted += 1;
 		}
 		return {
 			rawDeleted: pruneBoundedKnowledgeSourceItems(sourceInstanceId, olderThanMs),

package/dist/src/knowledge-memory/domain.d.ts

@@ -1,9 +1,16 @@
 import type { UserModelScope } from '../user-model/domain.js';
 export type KnowledgeKind = 'project_fact' | 'workspace_fact' | 'decision' | 'task_lesson' | 'commitment' | 'open_question' | 'episode' | 'note';
 export type KnowledgeStatus = 'candidate' | 'active' | 'needs_review' | 'stale' | 'archived' | 'rejected';
+export type KnowledgeReviewAction = 'approve' | 'edit_and_approve' | 'reject' | 'archive';
+export type KnowledgeStatusActor = 'user' | 'agent' | 'runtime' | 'maintenance' | 'migration';
 export type KnowledgeOriginClass = 'owner' | 'agent' | 'system' | 'untrusted';
 export type KnowledgeRecordClass = 'memory' | 'source_index';
-export type KnowledgeSource = 'session' | 'workspace' | 'project' | 'connector';
+export type KnowledgeVisibilityScope = UserModelScope['type'];
+export type KnowledgeContentSource = 'memory' | 'local_import' | 'connector';
+export interface KnowledgeReadPolicy {
+    scopes: readonly KnowledgeVisibilityScope[];
+    contentSources: readonly KnowledgeContentSource[];
+}
 export interface KnowledgeItem {
     id: string;
     principalId: string;
@@ -34,3 +41,12 @@ export interface KnowledgeVisibilityContext {
     projectId?: string;
     conversationId: string;
 }
+export interface KnowledgeStatusEvent {
+    id: string;
+    knowledgeId: string;
+    fromStatus?: KnowledgeStatus;
+    toStatus: KnowledgeStatus;
+    actor: KnowledgeStatusActor;
+    reason: string;
+    createdAt: number;
+}

package/dist/src/knowledge-memory/index.js

@@ -1,2 +1,2 @@
-import { getKnowledgeItem, knowledgeSourceAllowed, listKnowledgeItems, searchKnowledgeItems, setKnowledgeStatus, writeKnowledgeItem } from "./repository.js";
-export { getKnowledgeItem, knowledgeSourceAllowed, listKnowledgeItems, searchKnowledgeItems, setKnowledgeStatus, writeKnowledgeItem };
+import { KnowledgeReviewConflictError, classifyKnowledgeContentSource, getKnowledgeItem, knowledgeItemAllowed, listKnowledgeItems, listKnowledgeStatusEvents, reviewKnowledgeItem, searchKnowledgeItems, transitionKnowledgeStatus, writeKnowledgeItem } from "./repository.js";
+export { KnowledgeReviewConflictError, classifyKnowledgeContentSource, getKnowledgeItem, knowledgeItemAllowed, listKnowledgeItems, listKnowledgeStatusEvents, reviewKnowledgeItem, searchKnowledgeItems, transitionKnowledgeStatus, writeKnowledgeItem };

package/dist/src/knowledge-memory/repository.d.ts

@@ -1,5 +1,5 @@
 import { type UserModelScope } from '../user-model/domain.js';
-import type { KnowledgeItem, KnowledgeKind, KnowledgeOriginClass, KnowledgeRecordClass, KnowledgeSource, KnowledgeStatus, KnowledgeVisibilityContext } from './domain.js';
+import type { KnowledgeItem, KnowledgeKind, KnowledgeOriginClass, KnowledgeRecordClass, KnowledgeContentSource, KnowledgeReadPolicy, KnowledgeStatus, KnowledgeReviewAction, KnowledgeStatusActor, KnowledgeStatusEvent, KnowledgeVisibilityContext } from './domain.js';
 export interface WriteKnowledgeInput {
     principalId?: string;
     kind: KnowledgeKind;
@@ -23,6 +23,9 @@ export interface WriteKnowledgeInput {
     replaceExisting?: boolean;
     now?: number;
 }
+export declare class KnowledgeReviewConflictError extends Error {
+    constructor(message: string);
+}
 export declare function writeKnowledgeItem(input: WriteKnowledgeInput): {
     item: KnowledgeItem;
     created: boolean;
@@ -36,7 +39,25 @@ export declare function listKnowledgeItems(input?: {
     recordClass?: KnowledgeRecordClass;
     limit?: number;
 }): KnowledgeItem[];
-export declare function setKnowledgeStatus(id: string, status: KnowledgeStatus, now?: number): KnowledgeItem | undefined;
+export declare function transitionKnowledgeStatus(input: {
+    id: string;
+    status: KnowledgeStatus;
+    actor: KnowledgeStatusActor;
+    reason: string;
+    expectedStatus?: KnowledgeStatus;
+    content?: string;
+    now?: number;
+}): KnowledgeItem | undefined;
+export declare function reviewKnowledgeItem(input: {
+    id: string;
+    action: KnowledgeReviewAction;
+    actor: KnowledgeStatusActor;
+    reason: string;
+    expectedStatus?: KnowledgeStatus;
+    content?: string;
+    now?: number;
+}): KnowledgeItem | undefined;
+export declare function listKnowledgeStatusEvents(knowledgeId: string): KnowledgeStatusEvent[];
 export declare function searchKnowledgeItems(input: {
     query: string;
     context: KnowledgeVisibilityContext;
@@ -44,7 +65,8 @@ export declare function searchKnowledgeItems(input: {
     asOf?: number;
     recordClass?: KnowledgeRecordClass;
     trustedOnly?: boolean;
-    sources?: readonly KnowledgeSource[];
+    policy?: KnowledgeReadPolicy;
     limit?: number;
 }): KnowledgeItem[];
-export declare function knowledgeSourceAllowed(item: KnowledgeItem, sources: readonly KnowledgeSource[]): boolean;
+export declare function classifyKnowledgeContentSource(item: KnowledgeItem): KnowledgeContentSource;
+export declare function knowledgeItemAllowed(item: KnowledgeItem, policy: KnowledgeReadPolicy): boolean;

package/dist/src/knowledge-memory/repository.js

@@ -5,6 +5,12 @@ import { randomUUID } from "node:crypto";
 //#region src/knowledge-memory/repository.ts
 init_fts();
 init_transaction();
+var KnowledgeReviewConflictError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "KnowledgeReviewConflictError";
+	}
+};
 function fromRow(row) {
 	return {
 		id: row.knowledge_id,
@@ -37,6 +43,14 @@ function fromRow(row) {
 function bounded(value, field) {
 	if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`${field} must be between 0 and 1.`);
 }
+function statusActorForOrigin(origin) {
+	return origin === "owner" ? "user" : origin === "agent" ? "agent" : "runtime";
+}
+function insertStatusEvent(db, input) {
+	db.prepare(`INSERT INTO knowledge_item_status_events (
+    event_id, knowledge_id, from_status, to_status, actor_type, reason, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(randomUUID(), input.knowledgeId, input.fromStatus, input.toStatus, input.actor, input.reason, input.now);
+}
 function writeKnowledgeItem(input) {
 	validateScope(input.scope);
 	bounded(input.confidence, "confidence");
@@ -67,25 +81,43 @@ function writeKnowledgeItem(input) {
 			created: false
 		};
 		if (existing) {
+			const nextStatus = input.status ?? (input.originClass === "owner" ? "active" : "candidate");
 			db.prepare(`UPDATE knowledge_items SET kind = ?, content = ?, record_class = ?, status = ?, confidence = ?,
         importance = ?, valid_from = ?, valid_to = ?, expires_at = ?, review_at = ?,
         origin_class = ?, source_agent_id = ?, source_conversation_id = ?, source_turn_id = ?,
-        derived_from_recalled_context = ?, source_json = ?, updated_at = ? WHERE knowledge_id = ?`).run(input.kind, input.content.trim(), input.recordClass ?? "memory", input.status ?? (input.originClass === "owner" ? "active" : "candidate"), input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, existing.knowledge_id);
+        derived_from_recalled_context = ?, source_json = ?, updated_at = ? WHERE knowledge_id = ?`).run(input.kind, input.content.trim(), input.recordClass ?? "memory", nextStatus, input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, existing.knowledge_id);
 			db.prepare("DELETE FROM knowledge_items_fts WHERE knowledge_id = ?").run(existing.knowledge_id);
 			db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(input.content.trim(), existing.knowledge_id);
+			if (existing.status !== nextStatus) insertStatusEvent(db, {
+				knowledgeId: existing.knowledge_id,
+				fromStatus: existing.status,
+				toStatus: nextStatus,
+				actor: statusActorForOrigin(input.originClass),
+				reason: "Knowledge replaced from its source.",
+				now
+			});
 			return {
 				item: fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(existing.knowledge_id)),
 				created: false
 			};
 		}
 		const id = randomUUID();
+		const status = input.status ?? (input.originClass === "owner" ? "active" : "candidate");
 		db.prepare(`INSERT INTO knowledge_items (
       knowledge_id, principal_id, kind, scope_type, scope_id, content, canonical_key, record_class,
       status, confidence, importance, valid_from, valid_to, expires_at, review_at,
       origin_class, source_agent_id, source_conversation_id, source_turn_id,
       derived_from_recalled_context, source_json, created_at, updated_at
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, principalId, input.kind, input.scope.type, input.scope.id ?? null, input.content.trim(), input.canonicalKey.trim(), input.recordClass ?? "memory", input.status ?? (input.originClass === "owner" ? "active" : "candidate"), input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, now);
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, principalId, input.kind, input.scope.type, input.scope.id ?? null, input.content.trim(), input.canonicalKey.trim(), input.recordClass ?? "memory", status, input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceConversationId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, now);
 		db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(input.content.trim(), id);
+		insertStatusEvent(db, {
+			knowledgeId: id,
+			fromStatus: null,
+			toStatus: status,
+			actor: statusActorForOrigin(input.originClass),
+			reason: "Knowledge admitted.",
+			now
+		});
 		return {
 			item: fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(id)),
 			created: true
@@ -112,46 +144,146 @@ function listKnowledgeItems(input = {}) {
       ${input.canonicalKey ? "AND canonical_key = ?" : ""}
     ORDER BY importance DESC, updated_at DESC LIMIT ?`).all(input.principalId ?? "local-owner", ...statuses, ...input.recordClass ? [input.recordClass] : [], ...input.scope ? [input.scope.type, input.scope.id ?? null] : [], ...input.canonicalKey ? [input.canonicalKey] : [], Math.max(1, Math.min(2e3, input.limit ?? 200))).map(fromRow);
 }
-function setKnowledgeStatus(id, status, now = Date.now()) {
-	return getSqliteDatabase().prepare(`UPDATE knowledge_items SET status = ?, updated_at = ?
-    WHERE knowledge_id = ?`).run(status, now, id).changes ? getKnowledgeItem(id) : void 0;
+function transitionKnowledgeStatus(input) {
+	const reason = input.reason.trim();
+	if (!reason) throw new Error("A knowledge status change reason is required.");
+	const content = input.content?.trim();
+	if (input.content !== void 0 && !content) throw new Error("Knowledge content is required.");
+	const now = input.now ?? Date.now();
+	return runSqliteWriteTransaction((db) => {
+		const current = db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(input.id);
+		if (!current) return void 0;
+		if (input.expectedStatus && current.status !== input.expectedStatus) throw new KnowledgeReviewConflictError(`Knowledge status changed from ${input.expectedStatus} to ${current.status}.`);
+		db.prepare(`UPDATE knowledge_items SET status = ?, content = COALESCE(?, content), updated_at = ?
+      WHERE knowledge_id = ?`).run(input.status, content ?? null, now, input.id);
+		if (content !== void 0) {
+			db.prepare("DELETE FROM knowledge_items_fts WHERE knowledge_id = ?").run(input.id);
+			db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(content, input.id);
+		}
+		insertStatusEvent(db, {
+			knowledgeId: input.id,
+			fromStatus: current.status,
+			toStatus: input.status,
+			actor: input.actor,
+			reason,
+			now
+		});
+		return fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(input.id));
+	});
 }
-function visibilityClause(context) {
-	const parts = [
-		"k.scope_type = 'global'",
-		"(k.scope_type = 'agent' AND k.scope_id = ?)",
-		"(k.scope_type = 'workspace' AND k.scope_id = ?)",
-		"(k.scope_type = 'session' AND k.scope_id = ?)"
-	];
-	const values = [
-		context.agentId ?? "",
-		context.workspaceId ?? "",
-		context.conversationId ?? ""
-	];
-	if (context.projectId) {
+const REVIEW_TRANSITIONS = {
+	approve: {
+		from: [
+			"candidate",
+			"needs_review",
+			"stale"
+		],
+		to: "active"
+	},
+	edit_and_approve: {
+		from: [
+			"candidate",
+			"needs_review",
+			"stale"
+		],
+		to: "active",
+		requiresContent: true
+	},
+	reject: {
+		from: [
+			"candidate",
+			"needs_review",
+			"stale"
+		],
+		to: "rejected"
+	},
+	archive: {
+		from: [
+			"candidate",
+			"needs_review",
+			"stale",
+			"active"
+		],
+		to: "archived"
+	}
+};
+function reviewKnowledgeItem(input) {
+	const current = getKnowledgeItem(input.id);
+	if (!current) return void 0;
+	const transition = REVIEW_TRANSITIONS[input.action];
+	if (!transition.from.includes(current.status)) throw new KnowledgeReviewConflictError(`Cannot ${input.action} knowledge with status ${current.status}.`);
+	if (transition.requiresContent && !input.content?.trim()) throw new Error("Edited knowledge content is required.");
+	return transitionKnowledgeStatus({
+		id: input.id,
+		status: transition.to,
+		actor: input.actor,
+		reason: input.reason,
+		expectedStatus: input.expectedStatus ?? current.status,
+		...input.content === void 0 ? {} : { content: input.content },
+		...input.now === void 0 ? {} : { now: input.now }
+	});
+}
+function listKnowledgeStatusEvents(knowledgeId) {
+	return getSqliteDatabase().prepare(`SELECT event_id, knowledge_id, from_status, to_status,
+    actor_type, reason, created_at FROM knowledge_item_status_events
+    WHERE knowledge_id = ? ORDER BY created_at ASC, event_id ASC`).all(knowledgeId).map((row) => ({
+		id: row.event_id,
+		knowledgeId: row.knowledge_id,
+		...row.from_status === null ? {} : { fromStatus: row.from_status },
+		toStatus: row.to_status,
+		actor: row.actor_type,
+		reason: row.reason,
+		createdAt: row.created_at
+	}));
+}
+function visibilityClause(context, policy) {
+	const allowed = new Set(policy?.scopes ?? [
+		"global",
+		"agent",
+		"workspace",
+		"project",
+		"session"
+	]);
+	const parts = [];
+	const values = [];
+	if (allowed.has("global")) parts.push("k.scope_type = 'global'");
+	if (allowed.has("agent")) {
+		parts.push("(k.scope_type = 'agent' AND k.scope_id = ?)");
+		values.push(context.agentId ?? "");
+	}
+	if (allowed.has("workspace")) {
+		parts.push("(k.scope_type = 'workspace' AND k.scope_id = ?)");
+		values.push(context.workspaceId ?? "");
+	}
+	if (allowed.has("session")) {
+		parts.push("(k.scope_type = 'session' AND k.scope_id = ?)");
+		values.push(context.conversationId ?? "");
+	}
+	if (allowed.has("project") && context.projectId) {
 		parts.push("(k.scope_type = 'project' AND k.scope_id = ?)");
 		values.push(context.projectId);
 	}
 	return {
-		sql: `(${parts.join(" OR ")})`,
+		sql: `(${parts.length ? parts.join(" OR ") : "0"})`,
 		values
 	};
 }
+function contentSourceClause(policy) {
+	if (!policy) return "1";
+	const allowed = new Set(policy.contentSources);
+	const importedSource = "COALESCE(json_extract(k.source_json, '$.kind'), '') = 'product_import'";
+	const parts = [];
+	if (allowed.has("memory")) parts.push("k.record_class = 'memory'");
+	if (allowed.has("local_import")) parts.push(`(k.record_class = 'source_index' AND ${importedSource})`);
+	if (allowed.has("connector")) parts.push(`(k.record_class = 'source_index' AND NOT (${importedSource}))`);
+	return `(${parts.length ? parts.join(" OR ") : "0"})`;
+}
 function searchKnowledgeItems(input) {
 	const principalId = input.principalId ?? "local-owner";
 	const asOf = input.asOf ?? Date.now();
 	const limit = Math.max(1, Math.min(100, input.limit ?? 12));
-	const visible = visibilityClause(input.context);
-	const sourceParts = [];
-	const sourceValues = [];
-	const importedSource = "COALESCE(json_extract(k.source_json, '$.kind'), '') = 'product_import'";
-	if (input.sources?.includes("connector")) sourceParts.push(`(k.record_class = 'source_index' AND NOT (${importedSource}))`);
-	if (input.sources?.includes("workspace")) sourceParts.push(`(k.record_class = 'source_index' AND ${importedSource})`);
-	const memoryScopes = input.sources?.filter((source) => source !== "connector") ?? [];
-	if (memoryScopes.length) {
-		sourceParts.push(`(k.record_class = 'memory' AND k.scope_type IN (${memoryScopes.map(() => "?").join(", ")}))`);
-		sourceValues.push(...memoryScopes);
-	}
+	const visible = visibilityClause(input.context, input.policy);
+	const contentSource = contentSourceClause(input.policy);
 	const fts = buildFts5SearchQuery(input.query);
 	if (!fts) return [];
 	return getSqliteDatabase().prepare(`SELECT k.*, bm25(knowledge_items_fts) AS rank
@@ -162,13 +294,16 @@ function searchKnowledgeItems(input) {
       AND (k.expires_at IS NULL OR k.expires_at >= ?)
       ${input.recordClass ? "AND k.record_class = ?" : ""}
       ${input.trustedOnly ? "AND k.origin_class != 'untrusted'" : ""}
-      ${input.sources ? `AND (${sourceParts.length ? sourceParts.join(" OR ") : "0"})` : ""}
+      AND ${contentSource}
       AND ${visible.sql}
-    ORDER BY rank ASC, k.importance DESC, k.updated_at DESC LIMIT ?`).all(fts, principalId, asOf, asOf, asOf, ...input.recordClass ? [input.recordClass] : [], ...sourceValues, ...visible.values, limit).map(fromRow);
+    ORDER BY rank ASC, k.importance DESC, k.updated_at DESC LIMIT ?`).all(fts, principalId, asOf, asOf, asOf, ...input.recordClass ? [input.recordClass] : [], ...visible.values, limit).map(fromRow);
+}
+function classifyKnowledgeContentSource(item) {
+	if (item.recordClass === "memory") return "memory";
+	return item.source.kind === "product_import" ? "local_import" : "connector";
 }
-function knowledgeSourceAllowed(item, sources) {
-	if (item.recordClass === "source_index") return sources.includes(item.source.kind === "product_import" ? "workspace" : "connector");
-	return item.scope.type === "session" ? sources.includes("session") : item.scope.type === "workspace" ? sources.includes("workspace") : item.scope.type === "project" ? sources.includes("project") : false;
+function knowledgeItemAllowed(item, policy) {
+	return policy.scopes.includes(item.scope.type) && policy.contentSources.includes(classifyKnowledgeContentSource(item));
 }
 //#endregion
-export { getKnowledgeItem, knowledgeSourceAllowed, listKnowledgeItems, searchKnowledgeItems, setKnowledgeStatus, writeKnowledgeItem };
+export { KnowledgeReviewConflictError, classifyKnowledgeContentSource, getKnowledgeItem, knowledgeItemAllowed, listKnowledgeItems, listKnowledgeStatusEvents, reviewKnowledgeItem, searchKnowledgeItems, transitionKnowledgeStatus, writeKnowledgeItem };

package/dist/src/mcp/channel-bridge.js

@@ -62,10 +62,14 @@ var XopcChannelBridge = class {
 			issueTicket: async () => {
 				const response = await this.client.postJson("/api/realtime/tickets", {
 					clientId: this.realtimeClientId,
-					clientKind: "mcp"
+					clientKind: "mcp",
+					protocolVersion: 2
 				});
-				if (!response.payload?.ticket) throw new Error(response.error?.message ?? "Realtime ticket response is invalid");
-				return response.payload.ticket;
+				if (!response.payload?.ticket || !response.payload.realtime) throw new Error(response.error?.message ?? "Realtime ticket response is invalid");
+				return {
+					ticket: response.payload.ticket,
+					realtime: response.payload.realtime
+				};
 			},
 			createWebSocket: (url) => new WebSocket(url),
 			onEvent: (event) => this.handleRealtimeEvent(event),

package/dist/src/media-understanding/registry.js

@@ -14,6 +14,7 @@ function indexProvider(provider) {
 }
 function registerMediaUnderstandingProvider(provider) {
 	const keys = indexProvider(provider);
+	const previous = new Map(keys.map((key) => [key, registry.get(key)]));
 	const conflicts = keys.filter((key) => registry.has(key));
 	if (conflicts.length > 0) log.warn({
 		providerId: provider.id,
@@ -21,7 +22,11 @@ function registerMediaUnderstandingProvider(provider) {
 	}, `Media-understanding provider "${provider.id}" overrides existing registration(s): ${conflicts.join(", ")}`);
 	for (const key of keys) registry.set(key, provider);
 	return () => {
-		for (const key of keys) if (registry.get(key) === provider) registry.delete(key);
+		for (const key of keys) if (registry.get(key) === provider) {
+			const prior = previous.get(key);
+			if (prior) registry.set(key, prior);
+			else registry.delete(key);
+		}
 	};
 }
 function getMediaUnderstandingProvider(id) {

package/dist/src/migrations/knowledge-memory-read-policy-config.d.ts

@@ -0,0 +1,2 @@
+import type { Migration } from './types.js';
+export declare const knowledgeMemoryReadPolicyConfigMigration: Migration;