@xopcai/xopc 0.0.283 → 0.0.285

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

@@ -1,6 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.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";
@@ -31,22 +33,41 @@ function heartbeatRunnerConfigFromConfig(cfg) {
 var HeartbeatService = class {
 	intervalId = null;
 	wake;
-	lastHeartbeatText = "";
-	lastHeartbeatAt = 0;
+	nextCheckAt = null;
+	deliveryTimer = null;
+	delivering = false;
+	recovered = false;
 	runnerConfig = null;
 	constructor(deps) {
 		this.deps = deps;
-		this.wake = createHeartbeatWake((reasons) => this.runHeartbeatOnce(reasons));
+		this.wake = createHeartbeatWake(async (reasons) => {
+			try {
+				await this.runHeartbeatOnce(reasons);
+			} catch (err) {
+				log.error({ err }, "Heartbeat check failed unexpectedly");
+			}
+		});
 	}
 	start(config) {
+		if (this.runnerConfig) this.stop();
 		if (!config.enabled) {
 			log.info("Heartbeat disabled");
 			this.runnerConfig = null;
 			return;
 		}
 		this.runnerConfig = config;
+		if (!this.recovered) {
+			recoverHeartbeatChecks(this.deps.getWorkspace());
+			this.recovered = true;
+		}
+		this.deliveryTimer = setInterval(() => {
+			this.drainDeliveries().catch((err) => log.warn({ err }, "Heartbeat delivery check failed"));
+		}, 1e4);
+		this.deliveryTimer.unref?.();
+		this.nextCheckAt = new Date(Date.now() + config.intervalMs).toISOString();
 		log.info({ intervalMs: config.intervalMs }, "Heartbeat timer started (interval wake)");
 		this.intervalId = setInterval(() => {
+			this.nextCheckAt = new Date(Date.now() + config.intervalMs).toISOString();
 			this.wake.request({ reason: "interval" });
 		}, config.intervalMs);
 		this.intervalId.unref?.();
@@ -56,6 +77,9 @@ var HeartbeatService = class {
 		this.wake.request({ reason: opts?.reason ?? "manual" });
 	}
 	stop() {
+		if (this.deliveryTimer) clearInterval(this.deliveryTimer);
+		this.deliveryTimer = null;
+		this.nextCheckAt = null;
 		if (this.intervalId) {
 			clearInterval(this.intervalId);
 			this.intervalId = null;
@@ -73,6 +97,24 @@ var HeartbeatService = class {
 	isRunning() {
 		return this.intervalId !== null;
 	}
+	status() {
+		const preferences = proactivePreferences(this.deps.getWorkspace());
+		return {
+			enabled: Boolean(this.runnerConfig?.enabled),
+			checksAllowed: proactiveChecksAllowed(preferences),
+			nextCheckAt: proactiveChecksAllowed(preferences) ? this.nextCheckAt : null,
+			recent: recentHeartbeatChecks(this.deps.getWorkspace())
+		};
+	}
+	async drainDeliveries() {
+		if (this.delivering || !this.runnerConfig?.enabled) return;
+		this.delivering = true;
+		try {
+			await deliverHeartbeatChecks(this.deps.getWorkspace(), this.deps.messageBus, this.runnerConfig.target?.trim(), this.runnerConfig.targetChatId?.trim());
+		} finally {
+			this.delivering = false;
+		}
+	}
 	async runHeartbeatOnce(reasons) {
 		const reasonSummary = [...new Set(reasons)].join(", ") || "unknown";
 		const cfg = this.runnerConfig;
@@ -80,36 +122,34 @@ var HeartbeatService = class {
 			log.debug({ reasons: reasonSummary }, "Heartbeat: skip (disabled)");
 			return;
 		}
+		if (!proactiveChecksAllowed(proactivePreferences(this.deps.getWorkspace()))) return;
 		if (cfg.activeHours && !isWithinActiveHours(cfg.activeHours)) {
 			log.debug({ reasons: reasonSummary }, "Heartbeat: skip (outside active hours)");
 			return;
 		}
+		const checkId = beginHeartbeatCheck(this.deps.getWorkspace());
 		const heartbeatPath = resolveHeartbeatMdPath(this.deps.getConfig());
 		if (!heartbeatPath) {
-			log.debug({ reasons: reasonSummary }, "Heartbeat: skip (no HEARTBEAT path)");
+			completeHeartbeatCheck(checkId, "blocked", "No workspace checklist path");
 			return;
 		}
 		let heartbeatContent;
 		try {
 			const raw = await readFile(heartbeatPath, "utf-8");
 			if (isHeartbeatContentEmpty(raw)) {
-				log.debug({
-					path: heartbeatPath,
-					reasons: reasonSummary
-				}, "Heartbeat: skip (HEARTBEAT.md empty)");
+				completeHeartbeatCheck(checkId, "empty_checklist");
 				return;
 			}
 			heartbeatContent = raw.trim();
 		} catch {
-			log.debug({
-				path: heartbeatPath,
-				reasons: reasonSummary
-			}, "Heartbeat: HEARTBEAT.md missing; continuing");
+			completeHeartbeatCheck(checkId, "blocked", "Checklist could not be read");
+			return;
 		}
 		const sessionKey = cfg.isolatedSession ? `heartbeat:isolated:${Date.now()}` : "heartbeat:main";
 		let basePrompt = (cfg.prompt?.trim() || DEFAULT_PROMPT).trim();
 		if (heartbeatContent) basePrompt = `${basePrompt}\n\n---\nHEARTBEAT.md:\n${heartbeatContent}\n---`;
 		basePrompt = appendCronEventLines(basePrompt, reasons);
+		basePrompt += "\nReturn notifications in your final response. Do not send messages, media or voice directly; delivery follows the user notification policy.";
 		const prompt = `${basePrompt}\n\nCurrent time: ${(/* @__PURE__ */ new Date()).toISOString()}`;
 		const ackMax = cfg.ackMaxChars ?? 300;
 		log.debug({
@@ -143,14 +183,21 @@ var HeartbeatService = class {
 				source: "heartbeat"
 			});
 		} catch (error) {
+			completeHeartbeatCheck(checkId, "failed", "Agent check failed; see gateway logs");
 			log.error({ err: error }, "Heartbeat: agent call failed");
 			return;
 		}
+		if (cfg !== this.runnerConfig || !proactiveChecksAllowed(proactivePreferences(this.deps.getWorkspace()))) {
+			completeHeartbeatCheck(checkId, "cancelled", "Checks paused or configuration changed");
+			return;
+		}
 		if (!reply?.trim()) {
+			completeHeartbeatCheck(checkId, "no_change");
 			log.debug({ reasons: reasonSummary }, "Heartbeat: skip (empty model reply)");
 			return;
 		}
 		if (shouldSilence(reply, ackMax)) {
+			completeHeartbeatCheck(checkId, "no_change");
 			log.info({
 				ackMax,
 				replyChars: reply.length,
@@ -159,38 +206,8 @@ var HeartbeatService = class {
 			return;
 		}
 		const { stripped } = stripHeartbeatToken(reply);
-		const finalText = stripped || reply.trim();
-		if (this.isDuplicate(finalText)) {
-			log.info({
-				finalTextChars: finalText.length,
-				reasons: reasonSummary
-			}, "Heartbeat: not sent — duplicate within 24h");
-			return;
-		}
-		const target = cfg.target?.trim();
-		const targetChatId = cfg.targetChatId?.trim();
-		if (Boolean(target && targetChatId)) {
-			await this.deps.messageBus.publishOutbound({
-				channel: target,
-				chat_id: targetChatId,
-				content: finalText,
-				type: "message"
-			});
-			log.info({
-				reasons: reasonSummary,
-				channel: target,
-				chatId: targetChatId,
-				contentChars: finalText.length
-			}, "Heartbeat: sent — outbound queued");
-		} else log.info({
-			reasons: reasonSummary,
-			finalTextChars: finalText.length
-		}, "Heartbeat: not sent — no delivery target (set gateway.heartbeat.target + targetChatId)");
-		this.lastHeartbeatText = finalText;
-		this.lastHeartbeatAt = Date.now();
-	}
-	isDuplicate(text) {
-		return text.trim() === this.lastHeartbeatText.trim() && Date.now() - this.lastHeartbeatAt < 1440 * 60 * 1e3;
+		completeHeartbeatCheck(checkId, "prepared", void 0, stripped || reply.trim(), cfg.target?.trim(), cfg.targetChatId?.trim());
+		await this.drainDeliveries();
 	}
 };
 //#endregion

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

@@ -1,11 +1,11 @@
 import { DISCUSSION_STATUSES } from "../../../../packages/gateway-contract/src/discussions.js";
 import { hasGatewayScope } from "../../security/gateway-scopes.js";
 import { DiscussionServiceError } from "../../../discussions/errors.js";
-import { convertMeetingAction, meetingActionTasks } from "../../../discussions/action-tasks.js";
 import { MeetingEditSchema } from "../../../discussions/edits.js";
-import { exportDiscussion } from "../../../discussions/export.js";
 import "../../../discussions/index.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
+import { convertMeetingAction, meetingActionTasks } from "../../../discussions/action-tasks.js";
+import { exportDiscussion } from "../../../discussions/export.js";
 import { createReadStream } from "node:fs";
 import { stat } from "node:fs/promises";
 import { Readable } from "node:stream";

package/dist/src/gateway/hono/routes/imports.d.ts

@@ -0,0 +1,3 @@
+import type { Hono } from 'hono';
+import type { AuthenticatedRouteDeps } from './deps.js';
+export declare function registerImportRoutes(app: Hono, deps: AuthenticatedRouteDeps): void;

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

@@ -0,0 +1,56 @@
+import { getGatewayPrincipal } from "../../security/gateway-principal.js";
+import { ImportError } from "../../../imports/types.js";
+import { isImportSource } from "../../../imports/sources.js";
+import { ImportSelectionRepository } from "../../../storage/sqlite/import-selection-repository.js";
+import { getLiveInventory, previewInventoryItem, publicInventory, scanProduct } from "../../../imports/inventory.js";
+import { importSelection, listImportSources } from "../../../imports/productImport.js";
+import { createRuntimeImportService } from "../../../imports/runtime.js";
+import { z } from "zod";
+//#region src/gateway/hono/routes/imports.ts
+const selectionSchema = z.object({
+	inventoryId: z.string().uuid(),
+	candidateIds: z.array(z.string().uuid()).min(1).max(5e3),
+	requestId: z.string().uuid(),
+	retryOf: z.string().uuid().optional()
+}).strict();
+function registerImportRoutes(app, deps) {
+	const service = () => createRuntimeImportService("gateway-owner", () => deps.service.agentService.refreshSkillsAfterDiskChange(), (root) => deps.service.agentService.getWorkspaceTrust(root).trusted);
+	const respond = async (c, run) => {
+		try {
+			if (getGatewayPrincipal(c).kind !== "owner") throw new ImportError("owner_required", "Only the Gateway owner can import local capabilities", 403);
+			return c.json({
+				ok: true,
+				data: await run()
+			});
+		} catch (error) {
+			if (error instanceof z.ZodError) return c.json({
+				ok: false,
+				code: "invalid_input",
+				error: "Invalid import request"
+			}, 400);
+			if (error instanceof ImportError) return c.json({
+				ok: false,
+				code: error.code,
+				error: error.message
+			}, error.status);
+			return c.json({
+				ok: false,
+				code: "import_failed",
+				error: "Import could not finish. Existing content is preserved."
+			}, 400);
+		}
+	};
+	app.get("/api/imports/sources", (c) => respond(c, () => ({ sources: listImportSources("gateway-owner") })));
+	app.post("/api/imports/sources/:source/scan", deps.strictRateLimitMiddleware, (c) => respond(c, async () => {
+		const source = c.req.param("source");
+		if (!isImportSource(source)) throw new ImportError("unsupported_source", "Unsupported source");
+		z.object({}).strict().parse(await c.req.json());
+		return scanProduct(service(), source);
+	}));
+	app.get("/api/imports/inventories/:id", (c) => respond(c, () => publicInventory(getLiveInventory("gateway-owner", c.req.param("id")))));
+	app.get("/api/imports/inventories/:id/items/:itemId/preview", (c) => respond(c, () => previewInventoryItem(service(), "gateway-owner", c.req.param("id"), c.req.param("itemId"))));
+	app.post("/api/imports/runs", deps.strictRateLimitMiddleware, (c) => respond(c, async () => importSelection(service(), selectionSchema.parse(await c.req.json()))));
+	app.get("/api/imports/runs/:id", (c) => respond(c, () => new ImportSelectionRepository("gateway-owner").get("run", c.req.param("id"))));
+}
+//#endregion
+export { registerImportRoutes };

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

@@ -3,6 +3,14 @@ function startsWithAny(path, prefixes) {
 	return prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
 }
 const AUTHENTICATED_LAZY_ROUTE_BUNDLES = [
+	{
+		id: "imports",
+		match: (path) => startsWithAny(path, ["/api/imports"]),
+		load: async () => {
+			const { registerImportRoutes } = await import("./imports.js");
+			return { register: registerImportRoutes };
+		}
+	},
 	{
 		id: "project-understanding",
 		match: (path) => /^\/api\/projects\/[^/]+\/understanding$/.test(path),

package/dist/src/gateway/hono/routes/proactive-control.js

@@ -33,7 +33,8 @@ function registerProactiveControlRoutes(app, deps) {
 	}));
 	app.get("/api/proactive/overview", (c) => c.json({
 		ok: true,
-		...delegationOverview(workspace())
+		...delegationOverview(workspace()),
+		heartbeat: deps.service.heartbeatStatus()
 	}));
 	app.post("/api/proactive/delegations", deps.strictRateLimitMiddleware, async (c) => c.json({
 		ok: true,

package/dist/src/gateway/service.d.ts

@@ -124,6 +124,7 @@ export declare class GatewayService {
     private ensureHeartbeatService;
     private createTaskRunDispatcher;
     private createNotificationService;
+    private readonly taskRunDispatch;
     dispatchTaskRuns(): void;
     ensureTaskConversation(taskId: string, options?: {
         runId?: string;
@@ -255,6 +256,12 @@ export declare class GatewayService {
         manageable: boolean;
         order: number;
     }>;
+    heartbeatStatus(): {
+        enabled: boolean;
+        checksAllowed: boolean;
+        nextCheckAt: string;
+        recent: import("./heartbeat/check-store.js").HeartbeatCheck[];
+    };
     /**
      * Request an immediate heartbeat run (coalesced like interval/cron wakes).
      */

package/dist/src/gateway/service.js

@@ -63,23 +63,24 @@ import { ConnectionRecoveryService } from "../connectors/connection-recovery-ser
 import { startConnectorLearningCoordinator } from "../connectors/learning-coordinator.js";
 import { ConnectedSourceChangePublisher } from "../connectors/source-change-publisher.js";
 import { startConnectorSupervisor } from "../connectors/supervisor.js";
-import { DiscussionService } from "../discussions/service.js";
-import { DiscussionOrganizer } from "../discussions/organizer.js";
-import { DiscussionLiveWorker } from "../discussions/live-worker.js";
-import { DiscussionOrganizerWorker } from "../discussions/organizer-worker.js";
-import { DiscussionSealer } from "../discussions/sealer.js";
-import "../discussions/index.js";
 import { EndpointToolRuntime } from "../endpoint-tools/runtime.js";
 import "../endpoint-tools/index.js";
 import { assertGatewayAuthConfigured, extractToken, resolveGatewayAuth, validateToken } from "./auth.js";
 import { prepareAutomationAgentSession } from "./automation-agent-session.js";
 import { stopTailscaleExposure } from "./tailscale-lifecycle.js";
+import { createBackgroundTask } from "../infra/background-task.js";
 import { buildTaskAgentContext } from "../agent/source-context/task-context.js";
 import { deliverProactiveCard } from "../proactive/inbox/delivery.js";
 import { WorkDiscoveryService } from "../work-discovery/service.js";
 import { buildVoiceMemoryContext } from "../voice/realtime/memory-context.js";
 import { buildVoicePersonaContext } from "../voice/realtime/persona-context.js";
 import { voiceMemoryBudget, voicePersonaBudget } from "../voice/realtime/conversation-context.js";
+import { DiscussionService } from "../discussions/service.js";
+import { DiscussionOrganizer } from "../discussions/organizer.js";
+import { DiscussionLiveWorker } from "../discussions/live-worker.js";
+import { DiscussionOrganizerWorker } from "../discussions/organizer-worker.js";
+import { DiscussionSealer } from "../discussions/sealer.js";
+import "../discussions/index.js";
 import { NotesStore } from "../notes/store.js";
 import { buildNoteAgentContext } from "../notes/agent-context.js";
 import { NotesService } from "../notes/service.js";
@@ -665,7 +666,8 @@ var GatewayService = class {
 			agentService: this.ensureAgentService(),
 			messageBus: this.bus,
 			sessionStore: this.sessionIndex.getStore(),
-			getConfig: () => this.config
+			getConfig: () => this.config,
+			getWorkspace: () => this.workspacePath
 		});
 		return this.heartbeatService;
 	}
@@ -721,11 +723,21 @@ var GatewayService = class {
 		});
 		return this.notificationService;
 	}
-	dispatchTaskRuns() {
+	taskRunDispatch = createBackgroundTask(async () => {
 		new TaskSignalService().tick();
 		this.dispatchTaskEvents();
 		this.createTaskRunDispatcher().dispatch();
-		this.createWorkflowRunService().dispatchTaskRuns();
+		await this.createWorkflowRunService().dispatchTaskRuns();
+	}, (err) => {
+		const errorMessage = err instanceof Error ? err.message : String(err);
+		log.error({
+			err,
+			errorMessage,
+			phase: "task_run_dispatch"
+		}, `Task dispatch failed: ${errorMessage}`);
+	});
+	dispatchTaskRuns() {
+		this.taskRunDispatch();
 	}
 	async ensureTaskConversation(taskId, options = {}) {
 		const task = new TaskRepository().require(taskId);
@@ -955,6 +967,8 @@ var GatewayService = class {
 		});
 		log.debug("Starting gateway service...");
 		openXopcDatabase();
+		const { recoverCapabilityImports } = await import("../imports/runtime.js");
+		await recoverCapabilityImports();
 		this.createNotificationService().start();
 		this.startTime = Date.now();
 		this.running = true;
@@ -1429,6 +1443,9 @@ var GatewayService = class {
 			return a.id.localeCompare(b.id);
 		});
 	}
+	heartbeatStatus() {
+		return this.heartbeatService?.status() ?? null;
+	}
 	/**
 	* Request an immediate heartbeat run (coalesced like interval/cron wakes).
 	*/

package/dist/src/imports/compatibility.d.ts

@@ -0,0 +1,7 @@
+import type { ImportCandidate, ImportFile } from './types.js';
+export declare function parseSkill(raw: string): {
+    metadata: Record<string, unknown>;
+    body: string;
+};
+export declare function inspectSkill(base: Pick<ImportCandidate, 'id' | 'source' | 'scope' | 'location' | 'shared'>, files: ImportFile[]): ImportCandidate;
+export declare function inspectMcp(base: Pick<ImportCandidate, 'id' | 'source' | 'scope' | 'location' | 'shared'>, name: string, raw: unknown): ImportCandidate;

package/dist/src/imports/compatibility.js

@@ -0,0 +1,174 @@
+import { McpServerSchema, init_schema } from "../config/schema.js";
+import { isValidSkillId } from "../agent/skills/managed-store.js";
+import { containsSecret, isCredentialPath } from "./secrets.js";
+import { digest, fileHash } from "./files.js";
+import yaml from "js-yaml";
+//#region src/imports/compatibility.ts
+init_schema();
+function parseSkill(raw) {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(raw);
+	if (!match || match[1].length > 64 * 1024) throw new Error("A valid YAML header is required");
+	if (/(?:^|\s)[&*][\w-]+/.test(match[1])) throw new Error("YAML aliases are not supported");
+	let metadata;
+	try {
+		metadata = yaml.load(match[1], { schema: yaml.JSON_SCHEMA });
+	} catch {
+		throw new Error("Invalid YAML header");
+	}
+	if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) throw new Error("Invalid skill metadata");
+	return {
+		metadata,
+		body: match[2]
+	};
+}
+function inspectSkill(base, files) {
+	const item = {
+		...base,
+		kind: "skill",
+		name: base.id,
+		description: "",
+		files,
+		hash: fileHash(files),
+		compatibility: "compatible",
+		findings: [],
+		requiredEnv: []
+	};
+	try {
+		if (files.reduce((n, f) => n + Buffer.byteLength(f.data, "base64"), 0) > 15 * 1024 * 1024) throw new Error("Skill exceeds 15 MiB");
+		if (files.some((f) => f.path.endsWith("/SKILL.md"))) throw new Error("Nested skill scopes need separate imports");
+		const primary = files.find((f) => f.path === "SKILL.md");
+		if (!primary || Buffer.byteLength(primary.data, "base64") > 1024 * 1024) throw new Error("SKILL.md is missing or exceeds 1 MiB");
+		const { metadata, body } = parseSkill(Buffer.from(primary.data, "base64").toString("utf8"));
+		if (typeof metadata.name !== "string" || !isValidSkillId(metadata.name)) throw new Error("Skill name must be a portable identifier");
+		item.name = metadata.name;
+		if (typeof metadata.description !== "string" || !metadata.description.trim() || metadata.description.length > 1024) throw new Error("Skill description must contain 1–1024 characters");
+		item.description = metadata.description;
+		const supported = new Set([
+			"name",
+			"description",
+			"license",
+			"compatibility",
+			"metadata",
+			"disable-model-invocation",
+			"allowed-tools"
+		]);
+		for (const key of Object.keys(metadata)) if (!supported.has(key)) item.findings.push(`Unsupported skill field: ${key}`);
+		if (metadata["disable-model-invocation"] !== void 0 && typeof metadata["disable-model-invocation"] !== "boolean") item.findings.push("disable-model-invocation must be boolean");
+		if (/\$ARGUMENTS|\$\{?(?:CLAUDE_|CODEX_)|!`/.test(body)) item.findings.push("Product-specific variables or command expansion require adaptation");
+		const meta = metadata.metadata;
+		if (meta && (typeof meta !== "object" || Array.isArray(meta))) item.findings.push("Invalid metadata");
+		if (meta && Object.keys(meta).some((k) => ![
+			"author",
+			"version",
+			"short-description",
+			"short_description",
+			"category",
+			"tags",
+			"license",
+			"homepage"
+		].includes(k))) item.findings.push("Extended metadata needs manual compatibility review");
+		for (const match of body.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)) {
+			const ref = match[1].split("#")[0];
+			if (ref && !/^(?:[a-z]+:|#)/i.test(ref) && !files.some((f) => f.path === ref.replace(/^\.\//, ""))) item.findings.push("A referenced local file is missing or outside the skill");
+		}
+		if (item.findings.length) item.compatibility = "blocked";
+		if (metadata["allowed-tools"]) item.findings.push("Source tool pre-approvals are not transferred; xopc permissions apply");
+		for (const file of files) if (isCredentialPath(file.path) || containsSecret(Buffer.from(file.data, "base64").toString("utf8"))) {
+			item.compatibility = "blocked";
+			item.findings.push("Possible credentials found; remove them from the source and scan again");
+			item.files = [];
+			item.description = "";
+			break;
+		}
+	} catch (error) {
+		item.compatibility = "blocked";
+		item.findings.push(error instanceof Error ? error.message : "Invalid skill");
+	}
+	if (files.some((f) => containsSecret(Buffer.from(f.data, "base64").toString("utf8")))) {
+		item.files = [];
+		item.description = "";
+		item.compatibility = "blocked";
+		item.findings = ["Possible credentials found; remove them and scan again"];
+	}
+	return item;
+}
+function inspectMcp(base, name, raw) {
+	const item = {
+		...base,
+		kind: "mcp",
+		name,
+		description: "MCP connection draft",
+		files: [],
+		hash: "",
+		compatibility: "needs_setup",
+		findings: [],
+		requiredEnv: []
+	};
+	const value = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+	const draft = {};
+	const supported = new Set([
+		"command",
+		"args",
+		"cwd",
+		"url",
+		"type",
+		"env",
+		"headers",
+		"http_headers",
+		"startup_timeout_sec",
+		"tool_timeout_sec"
+	]);
+	for (const [key, v] of Object.entries(value)) {
+		if (!supported.has(key)) {
+			item.compatibility = "blocked";
+			item.findings.push(`Unsupported MCP field: ${key}`);
+			continue;
+		}
+		if ([
+			"env",
+			"headers",
+			"http_headers"
+		].includes(key)) {
+			if (v && typeof v === "object") item.requiredEnv.push(...Object.keys(v));
+			item.findings.push(`${key} values omitted; configure them in xopc`);
+		} else if (key === "type") {
+			if (v === "http") draft.transport = "streamable-http";
+			else if (v === "sse") draft.transport = "sse";
+			else if (v !== "stdio") {
+				item.compatibility = "blocked";
+				item.findings.push("Unsupported MCP transport");
+			}
+		} else if (key === "startup_timeout_sec" || key === "tool_timeout_sec") if (typeof v === "number") draft[key === "startup_timeout_sec" ? "connectionTimeoutMs" : "requestTimeoutMs"] = v * 1e3;
+		else {
+			item.compatibility = "blocked";
+			item.findings.push("Invalid MCP timeout");
+		}
+		else draft[key] = v;
+	}
+	if (typeof draft.url === "string") try {
+		const url = new URL(draft.url);
+		if (url.username || url.password || url.search || url.hash) {
+			delete draft.url;
+			item.findings.push("URL credentials or query parameters omitted; enter a clean endpoint");
+		}
+	} catch {
+		delete draft.url;
+	}
+	if (containsSecret(JSON.stringify(draft)) || /--?[a-z-]*(?:token|password|secret|api-key|authorization)(?:[=\s\"]|$)/i.test(JSON.stringify(draft))) {
+		Object.keys(draft).forEach((k) => delete draft[k]);
+		item.findings.push("Possible credentials omitted from connection fields");
+	}
+	if (!McpServerSchema.safeParse(draft).success || !draft.command && !draft.url) {
+		item.compatibility = "blocked";
+		item.findings.push("A valid command or URL is required");
+	}
+	if (base.scope === "project") {
+		item.compatibility = "blocked";
+		item.findings.push("Project-scoped MCP activation is not supported");
+	}
+	item.mcp = draft;
+	item.hash = digest(draft);
+	return item;
+}
+//#endregion
+export { inspectMcp, inspectSkill, parseSkill };

package/dist/src/imports/contextImport.d.ts

@@ -0,0 +1,3 @@
+import type { ImportCandidate } from './types.js';
+/** Small source records fit the existing retrieval budget without injecting entire documents. */
+export declare function importContextDocument(item: ImportCandidate, projectId?: string): 'created' | 'unchanged' | 'kept';

package/dist/src/imports/contextImport.js

@@ -0,0 +1,56 @@
+import { runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { listKnowledgeItems, writeKnowledgeItem } from "../knowledge-memory/repository.js";
+import "../knowledge-memory/index.js";
+import { digest } from "./files.js";
+//#region src/imports/contextImport.ts
+/** Small source records fit the existing retrieval budget without injecting entire documents. */
+function importContextDocument(item, projectId) {
+	const content = item.content?.trim();
+	if (!content) throw new Error("Missing context");
+	const scope = projectId ? {
+		type: "project",
+		id: projectId
+	} : { type: "global" };
+	const canonicalKey = `product-import:${item.source}:${digest(item.location)}`;
+	return runSqliteWriteTransaction(() => {
+		const existing = listKnowledgeItems({
+			canonicalKey,
+			scope,
+			statuses: [
+				"active",
+				"candidate",
+				"needs_review",
+				"stale",
+				"archived",
+				"rejected"
+			]
+		})[0];
+		if (existing) return existing.source.hash === item.hash ? "unchanged" : "kept";
+		for (let offset = 0, part = 0; offset < content.length; offset += 2e3, part++) {
+			const chunk = content.slice(offset, offset + 2e3).trim();
+			if (!chunk) continue;
+			writeKnowledgeItem({
+				kind: "note",
+				scope,
+				content: chunk,
+				canonicalKey: part === 0 ? canonicalKey : `${canonicalKey}:part:${part}`,
+				recordClass: "source_index",
+				status: "active",
+				confidence: .7,
+				importance: .7,
+				originClass: "system",
+				source: {
+					kind: "product_import",
+					product: item.source,
+					path: item.location,
+					hash: item.hash,
+					part,
+					importedAt: Date.now()
+				}
+			});
+		}
+		return "created";
+	});
+}
+//#endregion
+export { importContextDocument };

package/dist/src/imports/files.d.ts

@@ -0,0 +1,13 @@
+import { type ImportFile } from './types.js';
+export declare const IMPORT_LIMITS: {
+    file: number;
+    total: number;
+    count: number;
+    depth: number;
+};
+export declare function digest(value: unknown): string;
+export declare function fileHash(files: ImportFile[]): string;
+export declare function inside(root: string, path: string): boolean;
+export declare function safePath(path: string): boolean;
+export declare function readRegularFile(path: string, limit?: number): Buffer;
+export declare function readTree(rootPath: string): ImportFile[];