@xopcai/xopc 0.0.267 → 0.0.269

package/dist/src/proactive/execution/insight.js

@@ -57,7 +57,7 @@ function parseInsightCandidate(raw, allowedEvidenceIds) {
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Insight must be a JSON object");
 	const row = value;
 	if (!URGENCY.has(String(row.urgency))) throw new Error("Insight urgency is invalid");
-	if (typeof row.confidence !== "number" || row.confidence < 0 || row.confidence > 1) throw new Error("Insight confidence is invalid");
+	if (typeof row.confidence !== "number" || !Number.isFinite(row.confidence) || row.confidence < 0 || row.confidence > 1) throw new Error("Insight confidence is invalid");
 	if (!Array.isArray(row.evidenceIds) || row.evidenceIds.length === 0 || row.evidenceIds.length > 20) throw new Error("Insight evidenceIds are invalid");
 	const evidenceIds = [...new Set(row.evidenceIds.map(String))];
 	if (evidenceIds.some((id) => !allowedEvidenceIds.has(id))) throw new Error("Insight cites unknown evidence");
@@ -93,5 +93,36 @@ function isValuableInsight(candidate, policy = {
 }) {
 	return candidate.confidence >= policy.minConfidence && candidate.urgency !== "low" && scoreInsight(candidate) >= policy.minScore;
 }
+function parseAnalysisResult(raw, allowedEvidenceIds) {
+	let value;
+	try {
+		value = JSON.parse(stripCodeFences(raw));
+	} catch {
+		throw new Error("Model output is not valid JSON");
+	}
+	if (value && typeof value === "object" && !Array.isArray(value)) {
+		const row = value;
+		if (row.result === "no_insight") {
+			if (![
+				"unchanged",
+				"routine",
+				"insufficient_evidence",
+				"duplicate"
+			].includes(String(row.reason)) || Object.keys(row).some((key) => key !== "result" && key !== "reason")) throw new Error("Invalid no_insight result");
+			return {
+				result: "no_insight",
+				reason: String(row.reason)
+			};
+		}
+		if (row.result === "insight") return {
+			result: "insight",
+			candidate: parseInsightCandidate(JSON.stringify(row.candidate), allowedEvidenceIds)
+		};
+	}
+	return {
+		result: "insight",
+		candidate: parseInsightCandidate(raw, allowedEvidenceIds)
+	};
+}
 //#endregion
-export { isValuableInsight, parseInsightCandidate, scoreInsight };
+export { isValuableInsight, parseAnalysisResult, parseInsightCandidate, scoreInsight };

package/dist/src/proactive/execution/repository.d.ts

@@ -7,6 +7,7 @@ export interface ClaimedRun {
     scenarioVersion: number;
     promptRevisionId?: string;
     attempt: number;
+    subscriptionRevision?: number;
 }
 export declare function claimNextRun(owner: string, now?: Date, leaseSeconds?: number): ClaimedRun | null;
 export declare function eventIdsForBatch(batchId: string): string[];
@@ -18,6 +19,7 @@ export declare function finishRun(input: {
     valueScore?: number;
     cooldownSeconds?: number;
     rawOutput: string;
+    outcomeReason?: string;
     modelRef?: string;
 }, now?: Date): ProactiveInsight | null;
 export declare function failRun(run: ClaimedRun, error: unknown, retryable: boolean, now?: Date): void;

package/dist/src/proactive/execution/repository.js

@@ -1,10 +1,16 @@
 import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { effectiveProactivePolicy } from "../policy/service.js";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/proactive/execution/repository.ts
 const str = (row, key) => String(row[key]);
 function claimNextRun(owner, now = /* @__PURE__ */ new Date(), leaseSeconds = 120) {
 	return runSqliteWriteTransaction((db) => {
 		const nowIso = now.toISOString();
+		for (const row of db.prepare("SELECT run_id, batch_id, subscription_id FROM proactive_runs WHERE status IN ('retryable', 'running')").all()) if (!effectiveProactivePolicy(str(row, "subscription_id"), now).enabled) {
+			db.prepare("UPDATE proactive_runs SET status = 'discarded', outcome_reason = 'disabled', updated_at = ? WHERE run_id = ?").run(nowIso, str(row, "run_id"));
+			db.prepare("UPDATE proactive_signal_batches SET status = 'ignored', updated_at = ? WHERE batch_id = ?").run(nowIso, str(row, "batch_id"));
+		}
+		for (const row of db.prepare("SELECT batch_id, subscription_id FROM proactive_signal_batches WHERE status = 'ready'").all()) if (!effectiveProactivePolicy(str(row, "subscription_id"), now).enabled) db.prepare("UPDATE proactive_signal_batches SET status = 'ignored' WHERE batch_id = ?").run(str(row, "batch_id"));
 		const dayStart = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate())).toISOString();
 		db.prepare(`UPDATE proactive_signal_batches SET status = 'ignored', updated_at = ? WHERE status = 'ready'
       AND subscription_id IN (SELECT subscription_id FROM proactive_scenario_subscriptions WHERE enabled = 0)`).run(nowIso);
@@ -38,9 +44,14 @@ function claimNextRun(owner, now = /* @__PURE__ */ new Date(), leaseSeconds = 12
       WHERE b.status = 'ready' ORDER BY b.ready_at LIMIT 1`).get();
 		if (!batch) return null;
 		const id = randomUUID();
+		const policy = effectiveProactivePolicy(str(batch, "subscription_id"), now);
 		db.prepare(`INSERT INTO proactive_runs (run_id, batch_id, subscription_id, scenario_key, scenario_version,
-      prompt_revision_id, status, attempt, lease_owner, lease_expires_at, started_at, updated_at)
-      VALUES (?, ?, ?, ?, ?, ?, 'running', 1, ?, ?, ?, ?)`).run(id, str(batch, "batch_id"), str(batch, "subscription_id"), str(batch, "scenario_key"), Number(batch.scenario_version), batch.active_prompt_revision_id ? String(batch.active_prompt_revision_id) : null, owner, new Date(now.getTime() + leaseSeconds * 1e3).toISOString(), nowIso, nowIso);
+      prompt_revision_id, status, attempt, lease_owner, lease_expires_at, started_at, updated_at, policy_revision, subscription_revision, policy_snapshot_json)
+      VALUES (?, ?, ?, ?, ?, ?, 'running', 1, ?, ?, ?, ?, ?, ?, ?)`).run(id, str(batch, "batch_id"), str(batch, "subscription_id"), str(batch, "scenario_key"), Number(batch.scenario_version), batch.active_prompt_revision_id ? String(batch.active_prompt_revision_id) : null, owner, new Date(now.getTime() + leaseSeconds * 1e3).toISOString(), nowIso, nowIso, policy.preferences.revision, policy.settings.revision, JSON.stringify({
+			level: policy.level,
+			delivery: policy.settings.delivery,
+			scanIntervalMinutes: policy.scanIntervalMinutes
+		}));
 		db.prepare("UPDATE proactive_signal_batches SET status = 'processing', updated_at = ? WHERE batch_id = ?").run(nowIso, str(batch, "batch_id"));
 		return runFromRow(db.prepare("SELECT * FROM proactive_runs WHERE run_id = ?").get(id));
 	});
@@ -53,6 +64,7 @@ function runFromRow(row) {
 		scenarioKey: str(row, "scenario_key"),
 		scenarioVersion: Number(row.scenario_version),
 		attempt: Number(row.attempt),
+		subscriptionRevision: Number(row.subscription_revision),
 		...row.prompt_revision_id ? { promptRevisionId: str(row, "prompt_revision_id") } : {}
 	};
 }
@@ -77,6 +89,19 @@ function attachSnapshot(runId, snapshotId) {
 function finishRun(input, now = /* @__PURE__ */ new Date()) {
 	return runSqliteWriteTransaction((db) => {
 		const nowIso = now.toISOString();
+		const current = db.prepare("SELECT status, attempt FROM proactive_runs WHERE run_id = ?").get(input.run.id);
+		if (!current || current.status !== "running" || current.attempt !== input.run.attempt) return null;
+		const currentPolicy = effectiveProactivePolicy(input.run.subscriptionId, now);
+		if (!currentPolicy.enabled) input = {
+			...input,
+			candidate: void 0,
+			outcomeReason: "disabled"
+		};
+		else if (input.run.subscriptionRevision !== void 0 && input.run.subscriptionRevision !== currentPolicy.settings.revision) input = {
+			...input,
+			candidate: void 0,
+			outcomeReason: "policy_changed"
+		};
 		const subjectScope = db.prepare(`SELECT DISTINCT e.subject_kind, e.subject_id
       FROM proactive_batch_events be
       JOIN proactive_events e ON e.event_id = be.event_id
@@ -90,8 +115,17 @@ function finishRun(input, now = /* @__PURE__ */ new Date()) {
 		const duplicate = fingerprint ? db.prepare(`SELECT 1 FROM proactive_insights
       WHERE subscription_id = ? AND scenario_key = ? AND content_fingerprint = ? AND created_at >= ? LIMIT 1`).get(input.run.subscriptionId, input.run.scenarioKey, fingerprint, (/* @__PURE__ */ new Date(now.getTime() - (input.cooldownSeconds ?? 10080 * 60) * 1e3)).toISOString()) : void 0;
 		const valuable = Boolean(input.candidate) && !duplicate;
+		const reason = duplicate ? "duplicate" : input.outcomeReason;
+		const completed = valuable || [
+			"unchanged",
+			"routine",
+			"insufficient_evidence",
+			"duplicate",
+			"below_threshold"
+		].includes(reason ?? "");
+		db.prepare("UPDATE proactive_runs SET outcome_reason = ? WHERE run_id = ?").run(reason ?? null, input.run.id);
 		db.prepare(`UPDATE proactive_runs SET status = ?, raw_output = ?, model_ref = ?, lease_owner = NULL,
-      lease_expires_at = NULL, completed_at = ?, updated_at = ? WHERE run_id = ?`).run(valuable ? "completed" : "discarded", input.rawOutput.slice(0, 2e4), input.modelRef ?? null, nowIso, nowIso, input.run.id);
+      lease_expires_at = NULL, completed_at = ?, updated_at = ? WHERE run_id = ?`).run(completed ? "completed" : "discarded", input.rawOutput.slice(0, 2e4), input.modelRef ?? null, nowIso, nowIso, input.run.id);
 		db.prepare(`UPDATE proactive_signal_batches SET status = ?, updated_at = ? WHERE batch_id = ?`).run(valuable ? "processed" : "ignored", nowIso, input.run.batchId);
 		if (!input.candidate || duplicate) return null;
 		const insight = {
@@ -115,7 +149,7 @@ function failRun(run, error, retryable, now = /* @__PURE__ */ new Date()) {
 		const finalRetryable = retryable && run.attempt < 3;
 		const nowIso = now.toISOString();
 		const nextAttemptAt = finalRetryable ? new Date(now.getTime() + 15e3 * run.attempt).toISOString() : null;
-		db.prepare(`UPDATE proactive_runs SET status = ?, error_message = ?, lease_owner = NULL, lease_expires_at = NULL, next_attempt_at = ?, updated_at = ? WHERE run_id = ?`).run(finalRetryable ? "retryable" : "failed", String(error instanceof Error ? error.message : error).slice(0, 2e3), nextAttemptAt, nowIso, run.id);
+		if (!db.prepare(`UPDATE proactive_runs SET status = ?, error_message = ?, lease_owner = NULL, lease_expires_at = NULL, next_attempt_at = ?, updated_at = ? WHERE run_id = ? AND status = 'running' AND attempt = ?`).run(finalRetryable ? "retryable" : "failed", String(error instanceof Error ? error.message : error).slice(0, 2e3), nextAttemptAt, nowIso, run.id, run.attempt).changes) return;
 		db.prepare(`UPDATE proactive_signal_batches SET status = ?, updated_at = ? WHERE batch_id = ?`).run(finalRetryable ? "failed_retryable" : "failed_permanent", nowIso, run.batchId);
 	});
 }

package/dist/src/proactive/execution/types.d.ts

@@ -55,6 +55,11 @@ export interface ProactiveAgentExecutor {
     }): Promise<{
         text: string;
         modelRef?: string;
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+            estimatedCostUsd?: number;
+        };
     }>;
 }
 export interface ContextProvider {

package/dist/src/proactive/execution/worker.js

@@ -1,11 +1,13 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { getSqliteDatabase } from "../../storage/sqlite/transaction.js";
+import { effectiveProactivePolicy } from "../policy/service.js";
 import { getPromptRevision, getScenario } from "../scenarios/repository.js";
 import { composeScenarioPrompt } from "../scenarios/prompt-composer.js";
 import { markReadyBatches } from "../routing/batch-repository.js";
 import { ContextProviderRegistry } from "./context.js";
 import { attachSnapshot, claimNextRun, eventIdsForBatch, failRun, finishRun, saveSnapshot } from "./repository.js";
-import { isValuableInsight, parseInsightCandidate, scoreInsight } from "./insight.js";
+import { isValuableInsight, parseAnalysisResult, scoreInsight } from "./insight.js";
 import { randomUUID } from "node:crypto";
 //#region src/proactive/execution/worker.ts
 init_logger();
@@ -42,6 +44,14 @@ var ProactiveWorker = class {
 			try {
 				const scenario = getScenario(run.scenarioKey, run.scenarioVersion);
 				if (!scenario) throw new Error("Pinned scenario version is unavailable");
+				if (!effectiveProactivePolicy(run.subscriptionId).enabled) {
+					finishRun({
+						run,
+						rawOutput: "",
+						outcomeReason: "disabled"
+					});
+					return;
+				}
 				const revision = run.promptRevisionId ? getPromptRevision(run.promptRevisionId) ?? void 0 : void 0;
 				const eventIds = eventIdsForBatch(run.batchId);
 				const context = await this.contexts.collect(scenario, {
@@ -49,6 +59,14 @@ var ProactiveWorker = class {
 					eventIds,
 					subscriptionId: run.subscriptionId
 				});
+				if (context.evidenceIds.length === 0) {
+					finishRun({
+						run,
+						rawOutput: "",
+						outcomeReason: "source_unavailable"
+					});
+					return;
+				}
 				const snapshot = saveSnapshot(run.batchId, context.snapshotContent ?? context.content, context.evidenceIds);
 				attachSnapshot(run.id, snapshot.id);
 				const prompt = composeScenarioPrompt({
@@ -61,9 +79,21 @@ var ProactiveWorker = class {
 					userPrompt: prompt.text,
 					authorizedContext: context.content
 				});
-				const candidate = parseInsightCandidate(output.text, new Set(context.evidenceIds));
-				const valueScore = scoreInsight(candidate);
-				const valuable = isValuableInsight(candidate, scenario.valuePolicy);
+				if (output.usage) getSqliteDatabase().prepare("UPDATE proactive_runs SET input_tokens = ?, output_tokens = ?, estimated_cost_usd = ? WHERE run_id = ? AND attempt = ?").run(output.usage.inputTokens, output.usage.outputTokens, output.usage.estimatedCostUsd ?? null, run.id, run.attempt);
+				const latestContext = await this.contexts.collect(scenario, {
+					batchId: run.batchId,
+					eventIds,
+					subscriptionId: run.subscriptionId
+				});
+				const revoked = context.evidenceIds.some((id) => !latestContext.evidenceIds.includes(id));
+				const result = revoked ? {
+					result: "no_insight",
+					reason: "source_unavailable"
+				} : parseAnalysisResult(output.text, new Set(latestContext.evidenceIds));
+				const candidate = result.result === "insight" ? result.candidate : void 0;
+				const valueScore = candidate ? scoreInsight(candidate) : 0;
+				const enabled = effectiveProactivePolicy(run.subscriptionId).enabled;
+				const valuable = enabled && candidate && isValuableInsight(candidate, scenario.valuePolicy);
 				const insight = finishRun({
 					run,
 					...valuable ? {
@@ -71,16 +101,17 @@ var ProactiveWorker = class {
 						valueScore
 					} : {},
 					cooldownSeconds: scenario.valuePolicy.cooldownSeconds,
-					rawOutput: output.text,
+					outcomeReason: !enabled ? "disabled" : result.result === "no_insight" ? result.reason : valuable ? "insight" : "below_threshold",
+					rawOutput: revoked ? "" : output.text,
 					modelRef: output.modelRef
 				});
-				const disposition = insight ? "created" : valuable ? "duplicate_suppressed" : "value_gate_discarded";
+				const disposition = insight ? "created" : valuable ? "duplicate_suppressed" : result.result === "no_insight" ? result.reason : "value_gate_discarded";
 				log.info({
 					runId: run.id,
 					scenarioKey: run.scenarioKey,
 					disposition,
 					insightId: insight?.id
-				}, insight ? "Proactive insight created" : "Proactive output discarded");
+				}, insight ? "Proactive insight created" : "Proactive check completed without a card");
 			} catch (error) {
 				failRun(run, error, !(error instanceof Error && /Pinned scenario/.test(error.message)));
 				log.warn({

package/dist/src/proactive/inbox/cards.d.ts

@@ -0,0 +1,21 @@
+import { type ProactiveCard } from '@xopcai/gateway-contract';
+export declare function requireCardScope(id: string, workspaceId: string): void;
+export declare function getCard(id: string, workspaceId: string): ProactiveCard;
+export declare function listCards(workspaceId: string, input?: {
+    status?: string;
+    before?: string;
+    limit?: number;
+}): {
+    cards: ProactiveCard[];
+    nextCursor: string;
+};
+export declare function cardChanges(workspaceId: string, cursor?: number): {
+    items: {
+        id: string;
+        deleted: boolean;
+        card?: ProactiveCard;
+    }[];
+    nextCursor: number;
+    hasMore: boolean;
+};
+export declare function performCardAction(id: string, workspaceId: string, value: unknown): ProactiveCard;

package/dist/src/proactive/inbox/cards.js

@@ -0,0 +1,237 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { ProactiveCardActionSchema } from "../../../packages/gateway-contract/src/proactive.js";
+import { getKnowledgeSourceItem } from "../../storage/sqlite/knowledge-repository.js";
+import { ProactiveConflict, effectiveProactivePolicy, subscriptionSettings } from "../policy/service.js";
+import { insightSourcesAuthorized } from "../execution/authorization.js";
+import { withdrawCard } from "./lifecycle.js";
+import { executePendingProactiveActions } from "../actions/service.js";
+import { updateControlledSubscription } from "../scenarios/control.js";
+import { getInboxItem } from "./repository.js";
+import { ProactiveInboxService } from "./service.js";
+//#region src/proactive/inbox/cards.ts
+function requireCardScope(id, workspaceId) {
+	if (!getSqliteDatabase().prepare(`SELECT 1 FROM proactive_inbox_items i JOIN proactive_insights x USING(insight_id)
+    JOIN proactive_scenario_subscriptions s USING(subscription_id) WHERE i.inbox_item_id = ? AND s.workspace_id = ?`).get(id, workspaceId)) throw new Error("Card not found");
+}
+function getCard(id, workspaceId) {
+	requireCardScope(id, workspaceId);
+	const item = getInboxItem(id);
+	if (!insightSourcesAuthorized(item.insightId)) {
+		withdrawCard(id);
+		item.withdrawnAt = (/* @__PURE__ */ new Date()).toISOString();
+	}
+	if (item.withdrawnAt) return {
+		schemaVersion: 1,
+		id,
+		revision: getInboxItem(id).revision,
+		notificationRevision: item.notificationRevision,
+		subscriptionId: item.subscriptionId,
+		scenarioKey: item.insight.scenarioKey,
+		kind: "briefing",
+		status: "withdrawn",
+		title: "Source unavailable / 来源已撤回",
+		summary: "",
+		whyNow: "",
+		recommendation: "",
+		workDone: "",
+		evidence: [],
+		createdAt: item.createdAt,
+		updatedAt: item.withdrawnAt,
+		fallbackText: "Source unavailable / 来源已撤回"
+	};
+	const insight = item.insight;
+	const expired = item.expiresAt && Date.parse(item.expiresAt) <= Date.now();
+	return {
+		schemaVersion: 1,
+		id,
+		revision: item.revision,
+		notificationRevision: item.notificationRevision,
+		subscriptionId: item.subscriptionId,
+		preparationAvailable: Boolean(subscriptionSettings(item.subscriptionId).preparationWorkflowId),
+		relatedCardIds: item.correlationKey ? getSqliteDatabase().prepare("SELECT inbox_item_id AS id FROM proactive_inbox_items WHERE correlation_key = ? AND inbox_item_id <> ? AND withdrawn_at IS NULL").all(item.correlationKey, id).map((row) => row.id) : [],
+		scenarioKey: insight.scenarioKey,
+		kind: insight.attentionKind === "receipt" ? "receipt" : insight.decision ? "decision" : insight.scenarioKey === "meeting_preparation" ? "briefing" : insight.scenarioKey.includes("risk") || insight.scenarioKey.includes("failure") ? "risk" : insight.scenarioKey === "blocked_work" ? "reminder" : "recommendation",
+		status: expired ? "expired" : item.status,
+		title: insight.title,
+		summary: insight.summary,
+		whyNow: insight.whyNow,
+		recommendation: insight.recommendation,
+		workDone: insight.workDone,
+		evidence: insight.evidenceIds.map((evidenceId) => cardEvidence(evidenceId, workspaceId)),
+		...insight.decision ? { decision: insight.decision } : {},
+		actionStatus: insight.actionStatus,
+		actionResult: insight.actionResult,
+		actionError: insight.actionError,
+		createdAt: item.createdAt,
+		updatedAt: item.updatedAt,
+		expiresAt: item.expiresAt,
+		fallbackText: `${insight.title}\n${insight.summary}\n${insight.whyNow}`
+	};
+}
+function listCards(workspaceId, input = {}) {
+	const limit = Math.min(100, Math.max(1, input.limit ?? 30));
+	const rows = getSqliteDatabase().prepare(`SELECT i.inbox_item_id, i.created_at FROM proactive_inbox_items i
+    JOIN proactive_insights x USING(insight_id) JOIN proactive_scenario_subscriptions s USING(subscription_id)
+    WHERE i.withdrawn_at IS NULL AND s.workspace_id = ? AND (? IS NULL OR i.status = ?) AND (? IS NULL OR i.created_at || ':' || i.inbox_item_id < ?)
+    ORDER BY i.created_at DESC, i.inbox_item_id DESC LIMIT ?`).all(workspaceId, input.status || null, input.status || null, input.before || null, input.before || null, limit + 1);
+	const page = rows.slice(0, limit);
+	const last = page.at(-1);
+	return {
+		cards: page.flatMap((row) => {
+			try {
+				const card = getCard(row.inbox_item_id, workspaceId);
+				return card.status === "withdrawn" ? [] : [card];
+			} catch {
+				return [];
+			}
+		}),
+		nextCursor: rows.length > limit && last ? `${last.created_at}:${last.inbox_item_id}` : null
+	};
+}
+function cardChanges(workspaceId, cursor = 0) {
+	const rows = getSqliteDatabase().prepare("SELECT sequence, inbox_item_id, deleted FROM proactive_card_changes WHERE sequence > ? AND workspace_id = ? ORDER BY sequence LIMIT 200").all(cursor, workspaceId);
+	const items = [];
+	for (const row of rows) {
+		if (row.deleted) {
+			items.push({
+				id: row.inbox_item_id,
+				deleted: true
+			});
+			continue;
+		}
+		try {
+			const card = getCard(row.inbox_item_id, workspaceId);
+			items.push(card.status === "withdrawn" ? {
+				id: row.inbox_item_id,
+				deleted: true
+			} : {
+				id: row.inbox_item_id,
+				deleted: false,
+				card
+			});
+		} catch {
+			items.push({
+				id: row.inbox_item_id,
+				deleted: true
+			});
+		}
+	}
+	return {
+		items,
+		nextCursor: rows.at(-1)?.sequence ?? cursor,
+		hasMore: rows.length === 200
+	};
+}
+function performCardAction(id, workspaceId, value) {
+	const input = ProactiveCardActionSchema.parse(value);
+	return runSqliteWriteTransaction((db) => {
+		requireCardScope(id, workspaceId);
+		const request = JSON.stringify({
+			id,
+			...input
+		});
+		const prior = db.prepare("SELECT request_json, response_json FROM proactive_card_actions WHERE idempotency_key = ?").get(input.idempotencyKey);
+		if (prior) {
+			if (prior.request_json !== request) throw new ProactiveConflict("Idempotency key was already used for a different action");
+			return getCard(id, workspaceId);
+		}
+		const card = getCard(id, workspaceId);
+		if (card.revision !== input.expectedRevision) throw new ProactiveConflict("Card changed; refresh before acting");
+		if (card.status === "withdrawn" || card.status === "expired" || card.status === "resolved" && ![
+			"useful",
+			"not_useful",
+			"retry"
+		].includes(input.actionId)) throw new ProactiveConflict("Card is no longer actionable");
+		applyCardAction(card, workspaceId, input);
+		const result = getCard(id, workspaceId);
+		db.prepare("INSERT INTO proactive_card_actions(idempotency_key, inbox_item_id, request_json, response_json) VALUES (?, ?, ?, ?)").run(input.idempotencyKey, id, request, JSON.stringify(result));
+		return result;
+	});
+}
+function applyCardAction(card, workspaceId, input) {
+	const service = new ProactiveInboxService();
+	switch (input.actionId) {
+		case "retry":
+			if (!effectiveProactivePolicy(card.subscriptionId).enabled) throw new Error("Subscription paused");
+			if (!getSqliteDatabase().prepare("UPDATE proactive_insights SET action_status = 'pending', action_error = NULL, action_updated_at = ? WHERE insight_id = (SELECT insight_id FROM proactive_inbox_items WHERE inbox_item_id = ?) AND action_status = 'failed'").run((/* @__PURE__ */ new Date()).toISOString(), card.id).changes) throw new Error("Only failed actions can be retried");
+			executePendingProactiveActions();
+			break;
+		case "useful":
+		case "not_useful":
+			service.feedback(card.id, input.actionId);
+			break;
+		case "read":
+			service.transition(card.id, { status: "read" });
+			break;
+		case "resolve":
+			service.transition(card.id, {
+				status: "resolved",
+				resolution: "dismissed"
+			});
+			break;
+		case "snooze":
+			service.transition(card.id, {
+				status: "snoozed",
+				snoozedUntil: input.snoozedUntil ?? new Date(Date.now() + 36e5).toISOString()
+			});
+			break;
+		case "decide":
+			if (!input.choice) throw new Error("Decision choice required");
+			if (!effectiveProactivePolicy(card.subscriptionId).enabled) throw new Error("Subscription paused");
+			service.decide(card.id, input.choice);
+			break;
+		case "less":
+		case "pause": {
+			const settings = subscriptionSettings(card.subscriptionId);
+			updateControlledSubscription(workspaceId, card.subscriptionId, {
+				expectedRevision: settings.revision,
+				...input.actionId === "less" ? { delivery: "inbox" } : { enabled: false }
+			});
+			service.transition(card.id, {
+				status: "resolved",
+				resolution: input.actionId
+			});
+			break;
+		}
+	}
+}
+function cardEvidence(id, workspaceId) {
+	const db = getSqliteDatabase();
+	const split = id.indexOf(":");
+	const kind = id.slice(0, split);
+	const objectId = id.slice(split + 1);
+	if (kind === "task") {
+		const task = db.prepare("SELECT title FROM tasks WHERE task_id = ?").get(objectId);
+		if (task) return {
+			id,
+			label: task.title,
+			route: `/tasks/${encodeURIComponent(objectId)}`
+		};
+	}
+	if (kind === "project") {
+		const project = db.prepare("SELECT name FROM projects WHERE project_id = ?").get(objectId);
+		if (project) return {
+			id,
+			label: project.name,
+			route: `/projects/${encodeURIComponent(objectId)}`
+		};
+	}
+	if (kind === "source-item") {
+		const source = getKnowledgeSourceItem(objectId);
+		if (source && !source.deletedAt && source.metadata.workspaceId === workspaceId) {
+			const excerpt = source.normalizedText?.slice(0, 600) ?? "";
+			return {
+				id,
+				label: typeof source.metadata.title === "string" ? source.metadata.title.slice(0, 120) : excerpt.split("\n")[0]?.slice(0, 120) || source.itemType,
+				excerpt
+			};
+		}
+	}
+	const event = db.prepare("SELECT type, occurred_at FROM proactive_events WHERE event_id = ? AND workspace_id = ?").get(id, workspaceId);
+	return {
+		id,
+		label: event ? `${event.type} · ${event.occurred_at}` : kind || "Evidence"
+	};
+}
+//#endregion
+export { cardChanges, getCard, listCards, performCardAction, requireCardScope };

package/dist/src/proactive/inbox/delivery.d.ts

@@ -0,0 +1,6 @@
+import type { NotificationService } from '../../notifications/service.js';
+import type { InboxItem } from './types.js';
+/** The outbox is acknowledged only after a notification or suppression is persisted. */
+export declare function deliverProactiveCard(item: InboxItem, notifications: NotificationService, publish: (type: string, payload: unknown) => void): void | {
+    retryAt: string;
+};

package/dist/src/proactive/inbox/delivery.js

@@ -0,0 +1,52 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { effectiveProactivePolicy, localProactiveDay, nextDigestTime, quietHoursEnd, reserveProactiveNotification } from "../policy/service.js";
+import { viewingProactiveCards } from "../policy/presence.js";
+import { insightSourcesAuthorized } from "../execution/authorization.js";
+import { insightCorrelation } from "./lifecycle.js";
+import { getInboxItem } from "./repository.js";
+import { queueDigest } from "./digest.js";
+import { notificationPlanFromGatewayEvent } from "../../notifications/planner.js";
+import { createHash } from "node:crypto";
+//#region src/proactive/inbox/delivery.ts
+/** The outbox is acknowledged only after a notification or suppression is persisted. */
+function deliverProactiveCard(item, notifications, publish) {
+	const result = runSqliteWriteTransaction(() => {
+		const current = getInboxItem(item.id);
+		if (!current || current.withdrawnAt || !insightSourcesAuthorized(current.insightId) || current.status === "resolved" || current.expiresAt && Date.parse(current.expiresAt) <= Date.now()) return null;
+		if (current.status === "snoozed") return { retryAt: current.snoozedUntil };
+		const policy = effectiveProactivePolicy(current.subscriptionId);
+		if (!policy.enabled || policy.settings.delivery === "inbox") return null;
+		if ((policy.preferences.digestEnabled || policy.settings.delivery === "digest") && current.insight.attentionKind !== "receipt") {
+			queueDigest(current, "daily", nextDigestTime(policy.preferences, /* @__PURE__ */ new Date()));
+			return null;
+		}
+		if (!notificationPlanFromGatewayEvent("proactive.inbox.created", current)) return null;
+		if (policy.level === "quiet") return null;
+		const quietUntil = quietHoursEnd(policy.preferences, /* @__PURE__ */ new Date());
+		if (quietUntil) {
+			queueDigest(current, "quiet", quietUntil);
+			return null;
+		}
+		const db = getSqliteDatabase();
+		const key = `proactive:${insightCorrelation(current.insightId)}:${createHash("sha256").update(JSON.stringify([current.insight.urgency, current.insight.decision ?? null])).digest("hex")}:${localProactiveDay(/* @__PURE__ */ new Date(), policy.preferences.timezone)}`;
+		if (db.prepare("SELECT 1 FROM proactive_delivery_decisions WHERE notification_key = ?").get(key)) return null;
+		if (policy.preferences.suppressWhileViewing && viewingProactiveCards(policy.workspaceId)) {
+			db.prepare("INSERT INTO proactive_delivery_decisions VALUES (?, ?, ?, ?)").run(key, policy.workspaceId, "visible_in_app", (/* @__PURE__ */ new Date()).toISOString());
+			return null;
+		}
+		const decision = reserveProactiveNotification(current.subscriptionId, key);
+		if (decision instanceof Date) return { retryAt: decision.toISOString() };
+		if (decision === "suppressed") return null;
+		const result = notifications.persistGatewayEvent("proactive.inbox.created", current);
+		db.prepare("INSERT INTO proactive_delivery_decisions VALUES (?, ?, ?, ?)").run(key, policy.workspaceId, "immediate", (/* @__PURE__ */ new Date()).toISOString());
+		return result;
+	});
+	publish("proactive.card.changed", {
+		cardId: item.id,
+		revision: item.revision
+	});
+	if (result && "retryAt" in result) return result;
+	if (result) publish("notification.created", result);
+}
+//#endregion
+export { deliverProactiveCard };

package/dist/src/proactive/inbox/digest.d.ts

@@ -0,0 +1,8 @@
+import type { ProductNotification } from '@xopcai/gateway-contract';
+import type { NotificationPlan } from '../../notifications/planner.js';
+import type { InboxItem } from './types.js';
+export { nextDigestTime } from '../policy/service.js';
+export declare function queueDigest(item: InboxItem, mode: 'daily' | 'quiet', dueAt: Date): void;
+export declare function digestCards(id: string, workspaceId: string): import("@xopcai/gateway-contract").ProactiveCard[];
+export declare function reserveWorkspaceAttention(workspaceId: string, key: string, now?: Date): boolean;
+export declare function flushDueDigests(persist: (plan: NotificationPlan) => ProductNotification | null, now?: Date): ProductNotification[];