@xopcai/xopc 0.0.268 → 0.0.270

package/dist/src/proactive/follow-ups.d.ts

@@ -0,0 +1,123 @@
+import { ProactiveEventService } from './service.js';
+export declare const COMMUNICATION_SCENARIO = "communication_follow_up";
+export type MailFollowUp = {
+    id: string;
+    subscription_id: string;
+    workspace_id: string;
+    source_item_id: string;
+    instructions: string;
+    due_at: string;
+    status: 'watching' | 'paused' | 'completed';
+    revision: number;
+    last_fingerprint: string | null;
+    last_checked_at: string | null;
+    session_key: string | null;
+};
+export declare function requireMailFollowUp(workspace: string, id: string): MailFollowUp;
+export declare function authorizedMailThread(follow: MailFollowUp): {
+    origin: import("../knowledge/types.js").KnowledgeSourceItem;
+    items: import("../knowledge/types.js").KnowledgeSourceItem[];
+    threadKey: string;
+    fingerprint: string;
+};
+export declare function mailFollowUpView(follow: MailFollowUp): {
+    id: string;
+    subscriptionId: string;
+    instructions: string;
+    dueAt: string;
+    status: "completed" | "paused" | "watching";
+    revision: number;
+    lastCheckedAt: string;
+    sessionKey: string;
+    sourceAvailable: boolean;
+    enabled: boolean;
+    subject: string;
+    latestMessageAt: string;
+    latestDirection: string;
+    lastSyncedAt: string;
+    syncFailed: boolean;
+};
+export declare function listMailFollowUps(workspace: string): {
+    id: string;
+    subscriptionId: string;
+    instructions: string;
+    dueAt: string;
+    status: "completed" | "paused" | "watching";
+    revision: number;
+    lastCheckedAt: string;
+    sessionKey: string;
+    sourceAvailable: boolean;
+    enabled: boolean;
+    subject: string;
+    latestMessageAt: string;
+    latestDirection: string;
+    lastSyncedAt: string;
+    syncFailed: boolean;
+}[];
+export declare function mailFollowUpSources(workspace: string): {
+    id: string;
+    subject: string;
+    sender: string;
+    occurredAt: string;
+    accountLabel: string;
+}[];
+export declare function startMailFollowUp(workspace: string, value: unknown): {
+    id: string;
+    subscriptionId: string;
+    instructions: string;
+    dueAt: string;
+    status: "completed" | "paused" | "watching";
+    revision: number;
+    lastCheckedAt: string;
+    sessionKey: string;
+    sourceAvailable: boolean;
+    enabled: boolean;
+    subject: string;
+    latestMessageAt: string;
+    latestDirection: string;
+    lastSyncedAt: string;
+    syncFailed: boolean;
+};
+export declare function updateMailFollowUp(workspace: string, id: string, value: unknown): {
+    id: string;
+    subscriptionId: string;
+    instructions: string;
+    dueAt: string;
+    status: "completed" | "paused" | "watching";
+    revision: number;
+    lastCheckedAt: string;
+    sessionKey: string;
+    sourceAvailable: boolean;
+    enabled: boolean;
+    subject: string;
+    latestMessageAt: string;
+    latestDirection: string;
+    lastSyncedAt: string;
+    syncFailed: boolean;
+};
+/** Keep the existing chat and its exact connector confirmation flow as the write boundary. */
+export declare function continueMailFollowUp(workspace: string, id: string, sessionKey: string): {
+    followUp: {
+        id: string;
+        subscriptionId: string;
+        instructions: string;
+        dueAt: string;
+        status: "completed" | "paused" | "watching";
+        revision: number;
+        lastCheckedAt: string;
+        sessionKey: string;
+        sourceAvailable: boolean;
+        enabled: boolean;
+        subject: string;
+        latestMessageAt: string;
+        latestDirection: string;
+        lastSyncedAt: string;
+        syncFailed: boolean;
+    };
+    connectionId: unknown;
+    sourceItemId: string;
+    threadId: string;
+    instruction: string;
+};
+/** Poll only delegated threads; unchanged threads and passed deadlines produce no repeat signals. */
+export declare function scanMailFollowUps(events: ProactiveEventService, now?: Date): number;

package/dist/src/proactive/follow-ups.js

@@ -0,0 +1,169 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { listKnowledgeSourceItems } from "../storage/sqlite/knowledge-repository.js";
+import { getConnectorConnection } from "../storage/sqlite/connector-repository.js";
+import { emailFields, readMailThread } from "./mail-thread.js";
+import { authorizedConnectedSource } from "./execution/authorization.js";
+import { ProactiveConflict, effectiveProactivePolicy } from "./policy/service.js";
+import { listSubscriptions } from "./scenarios/repository.js";
+import { createControlledSubscription } from "./scenarios/control.js";
+import { ProactiveScenarioService } from "./scenarios/service.js";
+import { ProactiveEventService } from "./service.js";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+//#region src/proactive/follow-ups.ts
+const COMMUNICATION_SCENARIO = "communication_follow_up";
+const CreateSchema = z.object({
+	sourceItemId: z.string().min(1),
+	instructions: z.string().trim().min(1).max(12e3),
+	dueAt: z.string().datetime()
+}).strict();
+const UpdateSchema = z.object({
+	expectedRevision: z.number().int().positive(),
+	instructions: z.string().trim().min(1).max(12e3).optional(),
+	dueAt: z.string().datetime().optional(),
+	status: z.enum([
+		"watching",
+		"paused",
+		"completed"
+	]).optional()
+}).strict();
+function requireMailFollowUp(workspace, id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM proactive_follow_ups WHERE id = ? AND workspace_id = ?").get(id, workspace);
+	if (!row) throw new Error("Follow-up not found");
+	return row;
+}
+function authorizedMailThread(follow) {
+	if (!authorizedConnectedSource(follow.source_item_id, follow.workspace_id, "communication_follow_up")) return null;
+	const thread = readMailThread(follow.source_item_id);
+	if (!thread || thread.items.some((item) => !authorizedConnectedSource(item.id, follow.workspace_id, "communication_follow_up") || item.metadata.connectionId !== thread.origin.metadata.connectionId)) return null;
+	return thread;
+}
+function mailFollowUpView(follow) {
+	const thread = authorizedMailThread(follow);
+	const latest = thread?.items.at(-1);
+	const sync = thread ? getSqliteDatabase().prepare("SELECT status, error, finished_at FROM knowledge_sync_runs WHERE source_instance_id = ? ORDER BY started_at DESC LIMIT 1").get(thread.origin.sourceInstanceId) : void 0;
+	return {
+		id: follow.id,
+		subscriptionId: follow.subscription_id,
+		instructions: follow.instructions,
+		dueAt: follow.due_at,
+		status: follow.status,
+		revision: follow.revision,
+		lastCheckedAt: follow.last_checked_at,
+		sessionKey: follow.session_key,
+		sourceAvailable: Boolean(thread),
+		enabled: effectiveProactivePolicy(follow.subscription_id).enabled,
+		subject: thread ? emailFields(thread.origin.normalizedText).subject ?? "Email follow-up" : null,
+		latestMessageAt: latest?.occurredAt ?? null,
+		latestDirection: latest ? emailFields(latest.normalizedText).labels?.includes("SENT") ? "sent" : emailFields(latest.normalizedText).labels?.includes("INBOX") ? "received" : "unknown" : null,
+		lastSyncedAt: sync?.finished_at ? new Date(sync.finished_at).toISOString() : null,
+		syncFailed: Boolean(sync?.error)
+	};
+}
+function listMailFollowUps(workspace) {
+	return getSqliteDatabase().prepare("SELECT * FROM proactive_follow_ups WHERE workspace_id = ? ORDER BY updated_at DESC").all(workspace).map(mailFollowUpView);
+}
+function mailFollowUpSources(workspace) {
+	const seen = /* @__PURE__ */ new Set();
+	return listKnowledgeSourceItems({
+		itemType: "email",
+		limit: 500
+	}).flatMap((item) => {
+		if (!authorizedConnectedSource(item.id, workspace, "communication_follow_up")) return [];
+		const thread = readMailThread(item.id);
+		if (!thread || seen.has(thread.threadKey)) return [];
+		seen.add(thread.threadKey);
+		const fields = emailFields(item.normalizedText);
+		const connection = getConnectorConnection(String(item.metadata.connectionId));
+		const account = connection?.alias ?? connection?.identity.email ?? connection?.identity.name;
+		return [{
+			id: item.id,
+			subject: fields.subject ?? "Email",
+			sender: fields.sender ?? "",
+			occurredAt: item.occurredAt,
+			accountLabel: typeof account === "string" ? account : "Connected email account"
+		}];
+	}).slice(0, 100);
+}
+function startMailFollowUp(workspace, value) {
+	const input = CreateSchema.parse(value);
+	if (Date.parse(input.dueAt) <= Date.now()) throw new Error("Choose a future follow-up time");
+	if (!authorizedConnectedSource(input.sourceItemId, workspace, "communication_follow_up")) throw new Error("Authorize this email account for proactive follow-up first");
+	const thread = readMailThread(input.sourceItemId);
+	if (!thread) throw new Error("This email has no available thread");
+	return runSqliteWriteTransaction((db) => {
+		if (db.prepare("SELECT 1 FROM proactive_follow_ups WHERE workspace_id = ? AND thread_key = ?").get(workspace, thread.threadKey)) throw new ProactiveConflict("This conversation is already delegated; update the existing follow-up");
+		const sub = listSubscriptions("communication_follow_up").find((item) => item.workspaceId === workspace) ?? createControlledSubscription(workspace, {
+			scenarioKey: "communication_follow_up",
+			scopeKind: "workspace",
+			scopeId: workspace
+		});
+		const id = randomUUID();
+		const now = (/* @__PURE__ */ new Date()).toISOString();
+		db.prepare(`INSERT INTO proactive_follow_ups(id, subscription_id, workspace_id, source_item_id, thread_key, instructions, due_at, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, sub.id, workspace, input.sourceItemId, thread.threadKey, input.instructions, input.dueAt, now, now);
+		scanMailFollowUps(new ProactiveEventService(() => new ProactiveScenarioService().routes()));
+		return mailFollowUpView(requireMailFollowUp(workspace, id));
+	});
+}
+function updateMailFollowUp(workspace, id, value) {
+	const input = UpdateSchema.parse(value);
+	return runSqliteWriteTransaction((db) => {
+		const row = requireMailFollowUp(workspace, id);
+		if (row.revision !== input.expectedRevision) throw new ProactiveConflict("Follow-up changed; refresh before editing");
+		if (input.dueAt && Date.parse(input.dueAt) <= Date.now()) throw new Error("Choose a future follow-up time");
+		db.prepare(`UPDATE proactive_follow_ups SET instructions = ?, due_at = ?, status = ?, revision = revision + 1,
+      last_fingerprint = NULL, updated_at = ? WHERE id = ?`).run(input.instructions ?? row.instructions, input.dueAt ?? row.due_at, input.status ?? row.status, (/* @__PURE__ */ new Date()).toISOString(), id);
+		scanMailFollowUps(new ProactiveEventService(() => new ProactiveScenarioService().routes()));
+		return mailFollowUpView(requireMailFollowUp(workspace, id));
+	});
+}
+/** Keep the existing chat and its exact connector confirmation flow as the write boundary. */
+function continueMailFollowUp(workspace, id, sessionKey) {
+	const follow = requireMailFollowUp(workspace, id);
+	const thread = authorizedMailThread(follow);
+	if (!thread || follow.status !== "watching" || !effectiveProactivePolicy(follow.subscription_id).enabled) throw new Error("Resume and authorize this follow-up before continuing");
+	getSqliteDatabase().prepare("UPDATE proactive_follow_ups SET session_key = ? WHERE id = ?").run(sessionKey, id);
+	return {
+		followUp: mailFollowUpView(requireMailFollowUp(workspace, id)),
+		connectionId: thread.origin.metadata.connectionId,
+		sourceItemId: thread.origin.id,
+		threadId: emailFields(thread.origin.normalizedText).threadId,
+		instruction: "Read the current card and latest thread using this exact connection. Review the recipients and complete draft with the user before sending through the connector approval flow. Never infer successful delivery from a draft or approval. Use provider results, then continue watching synchronized replies."
+	};
+}
+/** Poll only delegated threads; unchanged threads and passed deadlines produce no repeat signals. */
+function scanMailFollowUps(events, now = /* @__PURE__ */ new Date()) {
+	const db = getSqliteDatabase();
+	let published = 0;
+	for (const follow of db.prepare("SELECT * FROM proactive_follow_ups WHERE status = 'watching'").all()) {
+		if (!effectiveProactivePolicy(follow.subscription_id, now).enabled) continue;
+		const thread = authorizedMailThread(follow);
+		if (!thread) continue;
+		const fingerprint = `${follow.revision}:${thread.fingerprint}:${Date.parse(follow.due_at) <= now.getTime() ? "due" : "waiting"}`;
+		if (fingerprint !== follow.last_fingerprint) {
+			if (events.publish({
+				type: "proactive.follow_up.v1",
+				schemaVersion: 1,
+				source: {
+					kind: "connector",
+					id: String(thread.origin.metadata.connectionId)
+				},
+				subject: {
+					kind: "mail_follow_up",
+					id: follow.id
+				},
+				actor: { kind: "system" },
+				scope: { workspaceId: follow.workspace_id },
+				occurredAt: now.toISOString(),
+				dedupeKey: `mail-follow-up:${follow.id}:${fingerprint}`,
+				sensitivity: "personal",
+				payload: { followUpId: follow.id }
+			}, now).inserted) published++;
+		}
+		db.prepare("UPDATE proactive_follow_ups SET last_fingerprint = ?, last_checked_at = ? WHERE id = ?").run(fingerprint, now.toISOString(), follow.id);
+	}
+	return published;
+}
+//#endregion
+export { COMMUNICATION_SCENARIO, authorizedMailThread, continueMailFollowUp, listMailFollowUps, mailFollowUpSources, mailFollowUpView, requireMailFollowUp, scanMailFollowUps, startMailFollowUp, updateMailFollowUp };

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,266 @@
+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 { insightSourcesAuthorized, insightSourcesChanged } from "../execution/authorization.js";
+import { ProactiveConflict, effectiveProactivePolicy, subscriptionSettings } from "../policy/service.js";
+import { updateControlledSubscription } from "../scenarios/control.js";
+import { withdrawCard } from "./lifecycle.js";
+import { executePendingProactiveActions } from "../actions/service.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 (!item.withdrawnAt && item.insight.actionStatus !== "completed" && (!item.expiresAt || Date.parse(item.expiresAt) > Date.now()) && insightSourcesChanged(item.insightId)) {
+		item.expiresAt = (/* @__PURE__ */ new Date()).toISOString();
+		getSqliteDatabase().prepare("UPDATE proactive_inbox_items SET expires_at = ? WHERE inbox_item_id = ?").run(item.expiresAt, id);
+		item.revision = getInboxItem(id).revision;
+	}
+	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,
+		...insight.artifact ? { artifact: insight.artifact } : {},
+		...insight.proposedAction && insight.actionStatus === "approval_required" ? { taskDraft: insight.proposedAction.input } : {},
+		...typeof insight.actionResult?.taskId === "string" ? { followUp: getSqliteDatabase().prepare("SELECT task_id AS taskId, title, phase, resolution FROM tasks WHERE task_id = ?").get(insight.actionResult.taskId) } : {},
+		...insight.scenarioKey === "communication_follow_up" ? { communication: getSqliteDatabase().prepare(`SELECT f.id, f.session_key AS sessionKey
+      FROM proactive_runs r JOIN proactive_context_snapshots c ON c.snapshot_id = r.context_snapshot_id
+      JOIN proactive_follow_ups f ON f.id = json_extract(c.content_json, '$.follow_up.followUpId') WHERE r.run_id = (SELECT run_id FROM proactive_insights WHERE insight_id = ?)`).get(item.insightId) } : {},
+		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 && !["completed", "rejected"].includes(insight.actionStatus ?? "") ? { 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();
+	if (input.taskDraft && (input.actionId !== "decide" || input.choice !== "approve" || !card.taskDraft)) throw new Error("Task draft requires a pending approval");
+	if (input.artifact && input.actionId !== "edit_artifact") throw new Error("Artifact requires an edit action");
+	switch (input.actionId) {
+		case "edit_artifact":
+			if (!input.artifact || !card.artifact || input.artifact.kind !== card.artifact.kind) throw new Error("An existing artifact is required");
+			getSqliteDatabase().prepare(`UPDATE proactive_insights SET artifact_json = ?, artifact_edited_at = ?
+        WHERE insight_id = (SELECT insight_id FROM proactive_inbox_items WHERE inbox_item_id = ?)`).run(JSON.stringify(input.artifact), (/* @__PURE__ */ new Date()).toISOString(), card.id);
+			break;
+		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 "handled":
+			service.transition(card.id, {
+				status: "resolved",
+				resolution: "user_reported_done"
+			});
+			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");
+			if (input.taskDraft) {
+				const item = getInboxItem(card.id);
+				getSqliteDatabase().prepare("UPDATE proactive_insights SET proposed_action_json = ? WHERE insight_id = ?").run(JSON.stringify({
+					...item.insight.proposedAction,
+					input: input.taskDraft
+				}), item.insightId);
+			}
+			service.decide(card.id, input.choice);
+			break;
+		case "pause": {
+			const settings = subscriptionSettings(card.subscriptionId);
+			updateControlledSubscription(workspaceId, card.subscriptionId, {
+				expectedRevision: settings.revision,
+				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,54 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { insightSourcesAuthorized, insightSourcesChanged } from "../execution/authorization.js";
+import { effectiveProactivePolicy, localProactiveDay, nextDigestTime, quietHoursEnd, reserveProactiveNotification } from "../policy/service.js";
+import { insightCorrelation } from "./lifecycle.js";
+import { getInboxItem } from "./repository.js";
+import { viewingProactiveCards } from "../policy/presence.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.insight.actionStatus !== "completed" && insightSourcesChanged(current.insightId)) 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;
+		if (policy.level !== "active" && ["low", "medium"].includes(current.insight.urgency) && !current.insight.decision) 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[];