@xopcai/xopc 0.0.268 → 0.0.269

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

@@ -1,5 +1,7 @@
 import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { effectiveProactivePolicy } from "../policy/service.js";
 import { decideProactiveDisposition, nextQuietHoursEnd, proactiveDispositionReason } from "../../tasks/project-monitoring-service.js";
+import { insightSourcesAuthorized } from "../execution/authorization.js";
 import { randomUUID } from "node:crypto";
 //#region src/proactive/inbox/repository.ts
 const s = (row, key) => String(row[key]);
@@ -8,6 +10,12 @@ function itemFromRow(row) {
 	return {
 		id: s(row, "inbox_item_id"),
 		insightId: s(row, "insight_id"),
+		subscriptionId: s(row, "subscription_id"),
+		withdrawnAt: row.withdrawn_at ? s(row, "withdrawn_at") : void 0,
+		correlationKey: row.correlation_key ? s(row, "correlation_key") : void 0,
+		revision: Number(row.revision),
+		notificationRevision: Number(row.notification_revision),
+		...row.expires_at ? { expiresAt: s(row, "expires_at") } : {},
 		status: s(row, "status"),
 		...row.snoozed_until ? { snoozedUntil: s(row, "snoozed_until") } : {},
 		...row.resolution ? { resolution: s(row, "resolution") } : {},
@@ -42,7 +50,7 @@ const SELECT_ITEM = `SELECT i.*, x.subscription_id, x.scenario_key, x.title, x.s
   JOIN proactive_insights x ON x.insight_id = i.insight_id`;
 function projectInsightsToInbox(now = /* @__PURE__ */ new Date()) {
 	return runSqliteWriteTransaction((db) => {
-		const missing = db.prepare(`SELECT x.insight_id, x.confidence, x.value_score, x.decision_json,
+		const missing = db.prepare(`SELECT x.insight_id, x.subscription_id, x.scenario_key, x.urgency, x.confidence, x.value_score, x.decision_json,
       x.proposed_action_json, b.aggregation_key, p.project_id, p.mode, p.quiet_hours_json,
       p.allowed_actions_json, p.confidence_threshold FROM proactive_insights x
       JOIN proactive_runs r ON r.run_id = x.run_id
@@ -52,6 +60,11 @@ function projectInsightsToInbox(now = /* @__PURE__ */ new Date()) {
       WHERE x.disposition IS NULL ORDER BY x.created_at`).all();
 		let projected = 0;
 		for (const row of missing) {
+			const attention = effectiveProactivePolicy(String(row.subscription_id), now);
+			if (!attention.enabled) {
+				db.prepare("UPDATE proactive_insights SET disposition = 'record_silently', disposition_reason = 'Proactive subscription paused' WHERE insight_id = ?").run(String(row.insight_id));
+				continue;
+			}
 			const aggregationKey = String(row.aggregation_key);
 			const projectId = aggregationKey.startsWith("project:") ? aggregationKey.slice(8) : void 0;
 			const policy = projectId ? row.project_id ? {
@@ -85,19 +98,53 @@ function projectInsightsToInbox(now = /* @__PURE__ */ new Date()) {
 				...action ? { actionId: action.id } : {},
 				requiresApproval: !action && Boolean(row.decision_json)
 			};
-			const disposition = action && !projectId ? "show_in_work" : decideProactiveDisposition(policy, dispositionInput);
+			const legacyDisposition = action && !projectId ? "show_in_work" : decideProactiveDisposition(policy, dispositionInput);
+			const disposition = attention.settings.managed && legacyDisposition === "record_silently" ? action && projectId ? "request_approval" : "show_in_work" : legacyDisposition;
 			const reason = action && !projectId ? "Proposed project action cannot run outside a project scope" : proactiveDispositionReason(policy, dispositionInput, disposition);
 			const actionStatus = action ? disposition === "auto_execute" ? "pending" : disposition === "request_approval" ? "approval_required" : disposition === "show_in_work" ? "not_authorized" : null : null;
 			const nowIso = now.toISOString();
 			db.prepare(`UPDATE proactive_insights SET disposition = ?, disposition_reason = ?, action_status = ?,
         disposition_at = ?, action_updated_at = ? WHERE insight_id = ? AND disposition IS NULL`).run(disposition, reason, actionStatus, nowIso, actionStatus ? nowIso : null, String(row.insight_id));
 			if (disposition === "record_silently") continue;
-			const id = randomUUID();
-			db.prepare(`INSERT INTO proactive_inbox_items (inbox_item_id, insight_id, status, created_at, updated_at)
-        VALUES (?, ?, 'unread', ?, ?)`).run(id, String(row.insight_id), nowIso, nowIso);
-			const nextAttemptAt = nextQuietHoursEnd(policy.quietHours, now)?.toISOString() ?? nowIso;
+			const previous = attention.settings.managed ? db.prepare(`SELECT i.inbox_item_id, x.urgency, x.decision_json,
+        o.delivered_at FROM proactive_inbox_items i JOIN proactive_insights x USING(insight_id)
+        JOIN proactive_runs r USING(run_id) JOIN proactive_signal_batches b USING(batch_id)
+        LEFT JOIN proactive_delivery_outbox o USING(inbox_item_id)
+        WHERE x.subscription_id = ? AND x.scenario_key = ? AND b.aggregation_key = ?
+        AND i.withdrawn_at IS NULL AND i.status IN ('unread', 'read', 'snoozed') AND (i.expires_at IS NULL OR i.expires_at > ?)
+        AND (x.action_status IS NULL OR x.action_status IN ('not_authorized', 'rejected', 'failed'))
+        ORDER BY i.updated_at DESC LIMIT 1`).get(String(row.subscription_id), String(row.scenario_key), aggregationKey, nowIso) : void 0;
+			const id = previous?.inbox_item_id ?? randomUUID();
+			const urgencyRank = {
+				low: 0,
+				medium: 1,
+				high: 2,
+				critical: 3
+			};
+			const materialChange = previous && ((urgencyRank[String(row.urgency)] ?? 0) > (urgencyRank[previous.urgency] ?? 0) || row.decision_json !== previous.decision_json);
+			if (previous) db.prepare(`UPDATE proactive_inbox_items SET insight_id = ?, updated_at = ?,
+          notification_revision = notification_revision + ? WHERE inbox_item_id = ?`).run(String(row.insight_id), nowIso, materialChange ? 1 : 0, id);
+			else db.prepare(`INSERT INTO proactive_inbox_items (inbox_item_id, insight_id, status, created_at, updated_at)
+          VALUES (?, ?, 'unread', ?, ?)`).run(id, String(row.insight_id), nowIso, nowIso);
+			if (attention.settings.managed) {
+				const meeting = db.prepare(`SELECT e.payload_json FROM proactive_events e
+          JOIN proactive_batch_events be ON be.event_id = e.event_id
+          JOIN proactive_runs r ON r.batch_id = be.batch_id JOIN proactive_insights x ON x.run_id = r.run_id
+          WHERE x.insight_id = ? AND e.type = 'connected_source.calendar_window.v1' ORDER BY e.occurred_at DESC LIMIT 1`).get(String(row.insight_id));
+				const meetingStart = meeting ? JSON.parse(meeting.payload_json).meetingStartsAt : void 0;
+				const expiresAt = typeof meetingStart === "string" && Number.isFinite(Date.parse(meetingStart)) ? meetingStart : new Date(now.getTime() + 7 * 864e5).toISOString();
+				db.prepare("UPDATE proactive_inbox_items SET expires_at = ? WHERE inbox_item_id = ?").run(expiresAt, id);
+			}
+			const quietEnd = nextQuietHoursEnd(policy.quietHours, now)?.getTime() ?? now.getTime();
+			const cooldownEnd = previous?.delivered_at ? Date.parse(previous.delivered_at) + 4 * 36e5 : now.getTime();
+			const nextAttemptAt = new Date(Math.max(quietEnd, cooldownEnd)).toISOString();
+			if (previous && !materialChange) {
+				projected += 1;
+				continue;
+			}
 			db.prepare(`INSERT INTO proactive_delivery_outbox (delivery_id, inbox_item_id, status, attempt, next_attempt_at, created_at, updated_at)
-        VALUES (?, ?, 'pending', 0, ?, ?, ?)`).run(randomUUID(), id, nextAttemptAt, nowIso, nowIso);
+        VALUES (?, ?, 'pending', 0, ?, ?, ?)
+        ON CONFLICT(inbox_item_id) DO UPDATE SET delivery_id = excluded.delivery_id, status = 'pending', attempt = 0, next_attempt_at = excluded.next_attempt_at, lease_expires_at = NULL, updated_at = excluded.updated_at`).run(randomUUID(), id, nextAttemptAt, nowIso, nowIso);
 			projected += 1;
 		}
 		return projected;
@@ -109,22 +156,29 @@ function wakeSnoozedItems(now = /* @__PURE__ */ new Date()) {
 }
 function listInbox(input = {}) {
 	const limit = Math.min(200, Math.max(1, input.limit ?? 50));
-	return (input.status ? getSqliteDatabase().prepare(`${SELECT_ITEM} WHERE i.status = ? ORDER BY i.updated_at DESC LIMIT ?`).all(input.status, limit) : getSqliteDatabase().prepare(`${SELECT_ITEM} ORDER BY i.updated_at DESC LIMIT ?`).all(limit)).map(itemFromRow);
+	return (input.status ? getSqliteDatabase().prepare(`${SELECT_ITEM} WHERE i.status = ? ORDER BY i.updated_at DESC LIMIT ?`).all(input.status, limit) : getSqliteDatabase().prepare(`${SELECT_ITEM} ORDER BY i.updated_at DESC LIMIT ?`).all(limit)).map(itemFromRow).filter((item) => !item.withdrawnAt && insightSourcesAuthorized(item.insightId));
 }
 function getInboxItem(id) {
 	const row = getSqliteDatabase().prepare(`${SELECT_ITEM} WHERE i.inbox_item_id = ?`).get(id);
 	return row ? itemFromRow(row) : null;
 }
 function transitionInboxItem(id, input, now = /* @__PURE__ */ new Date()) {
-	if (input.status === "snoozed" && (!input.snoozedUntil || Date.parse(input.snoozedUntil) <= now.getTime())) throw new Error("snoozedUntil must be in the future");
+	if (input.status === "snoozed" && (!input.snoozedUntil || !Number.isFinite(Date.parse(input.snoozedUntil)) || Date.parse(input.snoozedUntil) <= now.getTime())) throw new Error("snoozedUntil must be in the future");
 	if (input.status === "resolved" && !input.resolution?.trim()) throw new Error("resolution is required");
 	runSqliteWriteTransaction((db) => {
+		const current = getInboxItem(id);
+		if (!current || current.withdrawnAt || !insightSourcesAuthorized(current.insightId)) throw new Error("Inbox item not found");
+		if ((current.status === "resolved" || current.expiresAt && Date.parse(current.expiresAt) <= now.getTime()) && input.status !== "resolved") throw new Error("Card is no longer actionable");
 		if (db.prepare(`UPDATE proactive_inbox_items SET status = ?, snoozed_until = ?, resolution = ?, updated_at = ? WHERE inbox_item_id = ?`).run(input.status, input.status === "snoozed" ? input.snoozedUntil : null, input.status === "resolved" ? input.resolution.trim() : null, now.toISOString(), id).changes !== 1) throw new Error("Inbox item not found");
 	});
 	return getInboxItem(id);
 }
 function recordDecision(id, choice, note = "", now = /* @__PURE__ */ new Date()) {
 	if (!choice.trim()) throw new Error("choice is required");
+	const activeItem = getInboxItem(id);
+	if (!activeItem || activeItem.withdrawnAt || !insightSourcesAuthorized(activeItem.insightId)) throw new Error("Inbox item not found");
+	if (activeItem?.expiresAt && Date.parse(activeItem.expiresAt) <= now.getTime()) throw new Error("Card expired");
+	if (choice === "approve" && activeItem?.subscriptionId && !effectiveProactivePolicy(activeItem.subscriptionId, now).enabled) throw new Error("Subscription paused");
 	runSqliteWriteTransaction((db) => {
 		const row = db.prepare(`SELECT i.status, x.decision_json, x.action_status FROM proactive_inbox_items i
       JOIN proactive_insights x ON x.insight_id = i.insight_id WHERE i.inbox_item_id = ?`).get(id);
@@ -168,12 +222,15 @@ function finishDelivery(id, error, attempt = 1, now = /* @__PURE__ */ new Date()
 	runSqliteWriteTransaction((db) => {
 		const retry = Boolean(error) && attempt < 5;
 		db.prepare(`UPDATE proactive_delivery_outbox SET status = ?, next_attempt_at = ?, lease_expires_at = NULL,
-      error_message = ?, delivered_at = ?, updated_at = ? WHERE delivery_id = ?`).run(error ? retry ? "retryable" : "failed" : "delivered", retry ? new Date(now.getTime() + attempt * 3e4).toISOString() : now.toISOString(), error ? String(error instanceof Error ? error.message : error).slice(0, 1e3) : null, error ? null : now.toISOString(), now.toISOString(), id);
+      error_message = ?, delivered_at = ?, updated_at = ? WHERE delivery_id = ? AND status = 'delivering' AND attempt = ?`).run(error ? retry ? "retryable" : "failed" : "delivered", retry ? new Date(now.getTime() + attempt * 3e4).toISOString() : now.toISOString(), error ? String(error instanceof Error ? error.message : error).slice(0, 1e3) : null, error ? null : now.toISOString(), now.toISOString(), id, attempt);
 	});
 }
 function recoverExpiredDeliveries(now = /* @__PURE__ */ new Date()) {
 	return Number(runSqliteWriteTransaction((db) => db.prepare(`UPDATE proactive_delivery_outbox SET status = 'retryable', next_attempt_at = ?, lease_expires_at = NULL, updated_at = ?
     WHERE status = 'delivering' AND lease_expires_at <= ?`).run(now.toISOString(), now.toISOString(), now.toISOString()).changes));
 }
+function deferDelivery(id, attempt, retryAt) {
+	getSqliteDatabase().prepare("UPDATE proactive_delivery_outbox SET status = 'pending', attempt = attempt - 1, next_attempt_at = ?, lease_expires_at = NULL WHERE delivery_id = ? AND status = 'delivering' AND attempt = ?").run(retryAt, id, attempt);
+}
 //#endregion
-export { claimDelivery, finishDelivery, getInboxItem, getInboxSubscriptionId, listInbox, projectInsightsToInbox, recordDecision, recordFeedback, recoverExpiredDeliveries, transitionInboxItem, wakeSnoozedItems };
+export { claimDelivery, deferDelivery, finishDelivery, getInboxItem, getInboxSubscriptionId, listInbox, projectInsightsToInbox, recordDecision, recordFeedback, recoverExpiredDeliveries, transitionInboxItem, wakeSnoozedItems };

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

@@ -2,6 +2,12 @@ export type InboxStatus = 'unread' | 'read' | 'snoozed' | 'resolved';
 export interface InboxItem {
     id: string;
     insightId: string;
+    subscriptionId?: string;
+    revision?: number;
+    notificationRevision?: number;
+    expiresAt?: string;
+    withdrawnAt?: string;
+    correlationKey?: string;
     status: InboxStatus;
     snoozedUntil?: string;
     resolution?: string;
@@ -49,5 +55,7 @@ export interface InboxDelivery {
     deliveryId: string;
 }
 export interface InboxDeliveryAdapter {
-    deliver(delivery: InboxDelivery): Promise<void>;
+    deliver(delivery: InboxDelivery): Promise<void | {
+        retryAt: string;
+    }>;
 }

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

@@ -1,8 +1,9 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { pruneProactiveHistory } from "../maintenance.js";
+import { reconcileCards } from "./lifecycle.js";
 import { executePendingProactiveActions } from "../actions/service.js";
-import { claimDelivery, finishDelivery, projectInsightsToInbox, recoverExpiredDeliveries, wakeSnoozedItems } from "./repository.js";
+import { claimDelivery, deferDelivery, finishDelivery, projectInsightsToInbox, recoverExpiredDeliveries, wakeSnoozedItems } from "./repository.js";
+import { pruneProactiveHistory } from "../maintenance.js";
 //#region src/proactive/inbox/worker.ts
 init_logger();
 const log = createLogger("ProactiveInboxWorker");
@@ -36,16 +37,21 @@ var ProactiveInboxWorker = class {
 				this.lastMaintenanceAt = now;
 			}
 			projectInsightsToInbox();
+			reconcileCards();
 			executePendingProactiveActions();
 			wakeSnoozedItems();
 			recoverExpiredDeliveries();
 			const claim = claimDelivery();
 			if (!claim) return;
 			try {
-				await this.delivery.deliver({
+				const result = await this.delivery.deliver({
 					deliveryId: claim.id,
 					inboxItem: claim.item
 				});
+				if (result && result.retryAt) {
+					deferDelivery(claim.id, claim.attempt, result.retryAt);
+					return;
+				}
 				finishDelivery(claim.id, void 0, claim.attempt);
 			} catch (error) {
 				finishDelivery(claim.id, error, claim.attempt);

package/dist/src/proactive/index.js

@@ -1,4 +1,5 @@
 import { ProactiveScenarioService } from "./scenarios/service.js";
+import { ProactiveInboxService } from "./inbox/service.js";
 import { normalizeEventEnvelope } from "./events/envelope.js";
 import { mapProductEventToProactive } from "./events/product-event-bridge.js";
 import { matchScenario, matchesCondition } from "./routing/matcher.js";
@@ -9,6 +10,5 @@ import { ReadonlyProactiveAgentExecutor } from "./execution/agent-executor.js";
 import { listInsights } from "./execution/repository.js";
 import { ProactiveWorker } from "./execution/worker.js";
 import { ProactiveTemporalWorker } from "./temporal/worker.js";
-import { ProactiveInboxService } from "./inbox/service.js";
 import { ProactiveInboxWorker } from "./inbox/worker.js";
 export { AutomationStateContextProvider, ConnectedSourceContextProvider, ContextProviderRegistry, EventBatchContextProvider, InternalObjectContextProvider, MeetingWorkspaceContextProvider, ProactiveEventService, ProactiveInboxService, ProactiveInboxWorker, ProactiveScenarioService, ProactiveTemporalWorker, ProactiveWorker, ProjectStateContextProvider, ReadonlyProactiveAgentExecutor, UserModelContextProvider, listInsights, mapProductEventToProactive, matchScenario, matchesCondition, normalizeEventEnvelope, pruneProactiveHistory };

package/dist/src/proactive/maintenance.js

@@ -11,6 +11,13 @@ function pruneProactiveHistory(now = /* @__PURE__ */ new Date()) {
         SELECT 1 FROM proactive_batch_events batch_event
         WHERE batch_event.event_id = proactive_events.event_id
       )`).run(cutoff).changes;
+		db.prepare("DELETE FROM proactive_notification_budget WHERE created_at < ?").run(cutoff);
+		db.prepare("DELETE FROM proactive_presence WHERE expires_at <= ?").run(now.getTime());
+		db.prepare("DELETE FROM proactive_delivery_decisions WHERE created_at < ?").run(cutoff);
+		db.prepare("DELETE FROM proactive_preview_runs WHERE created_at < ?").run(cutoff);
+		db.prepare("DELETE FROM proactive_push_probes WHERE created_at < ?").run(Date.parse(cutoff));
+		db.prepare("DELETE FROM proactive_digest_queue WHERE consumed_at < ?").run(cutoff);
+		db.prepare("DELETE FROM proactive_digests WHERE created_at < ?").run(cutoff);
 		return {
 			batches: Number(batches),
 			events: Number(events)

package/dist/src/proactive/metrics.d.ts

@@ -0,0 +1,10 @@
+export declare function proactiveMetrics(workspace: string, now?: number): {
+    usage: Record<string, import("node:sqlite").SQLOutputValue>;
+    since: string;
+    cards: Record<string, import("node:sqlite").SQLOutputValue>;
+    feedback: Record<string, import("node:sqlite").SQLOutputValue>[];
+    interruptions: Record<string, import("node:sqlite").SQLOutputValue>[];
+    runs: Record<string, import("node:sqlite").SQLOutputValue>[];
+    browser: Record<string, import("node:sqlite").SQLOutputValue>[];
+    telegram: Record<string, import("node:sqlite").SQLOutputValue>[];
+};

package/dist/src/proactive/metrics.js

@@ -0,0 +1,27 @@
+import { getSqliteDatabase } from "../storage/sqlite/transaction.js";
+//#region src/proactive/metrics.ts
+function proactiveMetrics(workspace, now = Date.now()) {
+	const db = getSqliteDatabase();
+	const since = (/* @__PURE__ */ new Date(now - 30 * 864e5)).toISOString();
+	const cards = db.prepare(`SELECT COUNT(*) AS total, SUM(CASE WHEN i.status = 'resolved' THEN 1 ELSE 0 END) AS resolved,
+    SUM(CASE WHEN i.withdrawn_at IS NOT NULL THEN 1 ELSE 0 END) AS withdrawn FROM proactive_inbox_items i
+    JOIN proactive_insights x USING(insight_id) JOIN proactive_scenario_subscriptions s USING(subscription_id) WHERE s.workspace_id = ? AND i.created_at >= ?`).get(workspace, since);
+	const feedback = db.prepare(`SELECT f.rating, COUNT(*) AS count FROM proactive_feedback f JOIN proactive_inbox_items i USING(inbox_item_id)
+    JOIN proactive_insights x USING(insight_id) JOIN proactive_scenario_subscriptions s USING(subscription_id) WHERE s.workspace_id = ? AND f.created_at >= ? AND NOT EXISTS (SELECT 1 FROM proactive_feedback newer WHERE newer.inbox_item_id = f.inbox_item_id AND (newer.created_at > f.created_at OR (newer.created_at = f.created_at AND newer.rowid > f.rowid))) GROUP BY f.rating`).all(workspace, since);
+	const interruptions = db.prepare("SELECT local_day AS day, COUNT(*) AS count FROM proactive_notification_budget WHERE workspace_id = ? AND created_at >= ? GROUP BY local_day ORDER BY local_day DESC").all(workspace, since);
+	const runs = db.prepare(`SELECT r.status, r.outcome_reason AS reason, COUNT(*) AS count FROM proactive_runs r JOIN proactive_scenario_subscriptions s USING(subscription_id) WHERE s.workspace_id = ? AND r.started_at >= ? GROUP BY r.status, r.outcome_reason`).all(workspace, since);
+	const browser = db.prepare(`SELECT d.status, COUNT(*) AS count FROM proactive_web_push_deliveries d JOIN proactive_web_push_subscriptions s ON s.id = d.subscription_id WHERE s.workspace_id = ? GROUP BY d.status`).all(workspace);
+	const telegram = db.prepare("SELECT status, COUNT(*) AS count FROM proactive_channel_deliveries WHERE workspace_id = ? GROUP BY status").all(workspace);
+	return {
+		usage: db.prepare(`SELECT SUM(r.input_tokens) AS inputTokens, SUM(r.output_tokens) AS outputTokens, SUM(r.estimated_cost_usd) AS estimatedCostUsd, COUNT(r.estimated_cost_usd) AS pricedRuns, COUNT(*) AS totalRuns FROM proactive_runs r JOIN proactive_scenario_subscriptions s USING(subscription_id) WHERE s.workspace_id = ? AND r.started_at >= ?`).get(workspace, since),
+		since,
+		cards,
+		feedback,
+		interruptions,
+		runs,
+		browser,
+		telegram
+	};
+}
+//#endregion
+export { proactiveMetrics };

package/dist/src/proactive/policy/presence.d.ts

@@ -0,0 +1,2 @@
+export declare function recordProactivePresence(workspaceId: string, value: unknown, now?: number): void;
+export declare function viewingProactiveCards(workspaceId: string, now?: number): boolean;

package/dist/src/proactive/policy/presence.js

@@ -0,0 +1,27 @@
+import { getSqliteDatabase } from "../../storage/sqlite/transaction.js";
+import { z } from "zod";
+//#region src/proactive/policy/presence.ts
+const PresenceSchema = z.object({
+	clientId: z.string().min(8).max(128),
+	active: z.boolean(),
+	surface: z.enum([
+		"web",
+		"electron",
+		"mobile"
+	])
+}).strict();
+function recordProactivePresence(workspaceId, value, now = Date.now()) {
+	const input = PresenceSchema.parse(value);
+	const db = getSqliteDatabase();
+	db.prepare("DELETE FROM proactive_presence WHERE expires_at <= ?").run(now);
+	if (!input.active) {
+		db.prepare("DELETE FROM proactive_presence WHERE workspace_id = ? AND client_id = ?").run(workspaceId, input.clientId);
+		return;
+	}
+	db.prepare(`INSERT INTO proactive_presence VALUES (?, ?, ?, ?) ON CONFLICT(workspace_id, client_id) DO UPDATE SET surface = excluded.surface, expires_at = excluded.expires_at`).run(workspaceId, input.clientId, input.surface, now + 75e3);
+}
+function viewingProactiveCards(workspaceId, now = Date.now()) {
+	return Boolean(getSqliteDatabase().prepare("SELECT 1 FROM proactive_presence WHERE workspace_id = ? AND expires_at > ?").get(workspaceId, now));
+}
+//#endregion
+export { recordProactivePresence, viewingProactiveCards };

package/dist/src/proactive/policy/service.d.ts

@@ -0,0 +1,53 @@
+import { type ProactivePreferences } from '@xopcai/gateway-contract';
+export declare class ProactiveConflict extends Error {
+}
+export declare function subscriptionSettings(id: string): {
+    revision: number;
+    managed: boolean;
+    level: "off" | "active" | "quiet" | "balanced";
+    delivery: "digest" | "inbox" | "important";
+    preparationWorkflowId: string;
+    scanIntervalMinutes: number;
+    userInstructions: string;
+};
+export declare function proactivePreferences(workspaceId: string): ProactivePreferences;
+export declare function updateProactivePreferences(workspaceId: string, value: unknown): ProactivePreferences;
+export declare function effectiveProactivePolicy(subscriptionId: string, now?: Date): {
+    enabled: boolean;
+    level: "off" | "active" | "quiet" | "balanced";
+    settings: {
+        revision: number;
+        managed: boolean;
+        level: "off" | "active" | "quiet" | "balanced";
+        delivery: "digest" | "inbox" | "important";
+        preparationWorkflowId: string;
+        scanIntervalMinutes: number;
+        userInstructions: string;
+    };
+    preferences: {
+        level: "off" | "active" | "quiet" | "balanced";
+        timezone: string;
+        quietStartHour: number;
+        quietEndHour: number;
+        dailyNotificationLimit: number;
+        digestEnabled: boolean;
+        digestHour: number;
+        digestMinute: number;
+        preferredChannel: "mobile" | "all" | "auto" | "browser" | "telegram";
+        suppressWhileViewing: boolean;
+        telegram: {
+            chatId: string;
+            publicUrl: string;
+            accountId?: string;
+        };
+        pausedUntil: string;
+        revision: number;
+    };
+    workspaceId: string;
+    scanIntervalMinutes: number;
+};
+export declare function localProactiveDay(now: Date, timezone: string): string;
+export declare function quietHoursEnd(preferences: ProactivePreferences, now: Date): Date | null;
+/** Called in the same transaction as notification persistence. Reservations survive retries. */
+export declare function reserveProactiveNotification(subscriptionId: string, dedupeKey: string, now?: Date): 'allowed' | 'suppressed' | Date;
+export declare function nextDigestTime(preferences: ProactivePreferences, after: Date): Date;

package/dist/src/proactive/policy/service.js

@@ -0,0 +1,122 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { ProactivePreferencesSchema, ProactivePreferencesUpdateSchema, ProactiveSubscriptionSettingsSchema } from "../../../packages/gateway-contract/src/proactive.js";
+//#region src/proactive/policy/service.ts
+var ProactiveConflict = class extends Error {};
+function subscriptionSettings(id) {
+	const row = getSqliteDatabase().prepare("SELECT settings_json, revision FROM proactive_subscription_settings WHERE subscription_id = ?").get(id);
+	return {
+		...ProactiveSubscriptionSettingsSchema.parse(row ? JSON.parse(row.settings_json) : {}),
+		revision: row?.revision ?? 0,
+		managed: Boolean(row)
+	};
+}
+function proactivePreferences(workspaceId) {
+	const row = getSqliteDatabase().prepare("SELECT preferences_json, revision FROM proactive_preferences WHERE workspace_id = ?").get(workspaceId);
+	return ProactivePreferencesSchema.parse(row ? {
+		...JSON.parse(row.preferences_json),
+		revision: row.revision
+	} : {});
+}
+function updateProactivePreferences(workspaceId, value) {
+	const { expectedRevision, ...patch } = ProactivePreferencesUpdateSchema.parse(value);
+	return runSqliteWriteTransaction((db) => {
+		const current = proactivePreferences(workspaceId);
+		if (current.revision !== expectedRevision) throw new ProactiveConflict("Preferences changed; refresh and try again");
+		const next = ProactivePreferencesSchema.parse({
+			...current,
+			...patch,
+			revision: current.revision + 1
+		});
+		if (next.preferredChannel === "telegram" && !next.telegram) throw new Error("Telegram destination is required");
+		db.prepare(`INSERT INTO proactive_preferences(workspace_id, preferences_json, revision) VALUES (?, ?, ?)
+      ON CONFLICT(workspace_id) DO UPDATE SET preferences_json = excluded.preferences_json, revision = excluded.revision`).run(workspaceId, JSON.stringify(next), next.revision);
+		if (next.timezone !== current.timezone || next.digestHour !== current.digestHour || next.digestMinute !== current.digestMinute) db.prepare("UPDATE proactive_digest_queue SET due_at = ? WHERE workspace_id = ? AND mode = 'daily' AND consumed_at IS NULL").run(nextDigestTime(next, /* @__PURE__ */ new Date()).toISOString(), workspaceId);
+		if (next.level === "off") {
+			db.prepare("DELETE FROM proactive_digest_queue WHERE workspace_id = ?").run(workspaceId);
+			db.prepare(`UPDATE proactive_delivery_outbox SET status = 'delivered', error_message = 'proactive_disabled'
+        WHERE status IN ('pending', 'retryable') AND inbox_item_id IN (
+          SELECT i.inbox_item_id FROM proactive_inbox_items i JOIN proactive_insights x USING(insight_id)
+          JOIN proactive_scenario_subscriptions s USING(subscription_id) WHERE s.workspace_id = ?
+        )`).run(workspaceId);
+		}
+		return next;
+	});
+}
+function effectiveProactivePolicy(subscriptionId, now = /* @__PURE__ */ new Date()) {
+	const sub = getSqliteDatabase().prepare("SELECT workspace_id, enabled FROM proactive_scenario_subscriptions WHERE subscription_id = ?").get(subscriptionId);
+	const settings = subscriptionSettings(subscriptionId);
+	const preferences = proactivePreferences(sub?.workspace_id ?? "default");
+	const level = preferences.level === "off" ? "off" : settings.level ?? preferences.level;
+	return {
+		enabled: Boolean(sub?.enabled) && level !== "off" && !(preferences.pausedUntil && Date.parse(preferences.pausedUntil) > now.getTime()),
+		level,
+		settings,
+		preferences,
+		workspaceId: sub?.workspace_id ?? "",
+		scanIntervalMinutes: settings.scanIntervalMinutes ?? (level === "active" ? 30 : level === "quiet" ? 1440 : 120)
+	};
+}
+function localProactiveDay(now, timezone) {
+	return new Intl.DateTimeFormat("en-CA", {
+		timeZone: timezone,
+		year: "numeric",
+		month: "2-digit",
+		day: "2-digit"
+	}).format(now);
+}
+function quietHoursEnd(preferences, now) {
+	const { quietStartHour: start, quietEndHour: end, timezone } = preferences;
+	const quiet = (at) => {
+		const hour = Number(new Intl.DateTimeFormat("en-US", {
+			timeZone: timezone,
+			hour: "2-digit",
+			hourCycle: "h23"
+		}).format(at));
+		return start !== end && (start < end ? hour >= start && hour < end : hour >= start || hour < end);
+	};
+	if (!quiet(now)) return null;
+	for (let minutes = 1; minutes <= 2880; minutes++) {
+		const at = /* @__PURE__ */ new Date(Math.floor(now.getTime() / 6e4) * 6e4 + minutes * 6e4);
+		if (!quiet(at)) return at;
+	}
+	return new Date(now.getTime() + 864e5);
+}
+/** Called in the same transaction as notification persistence. Reservations survive retries. */
+function reserveProactiveNotification(subscriptionId, dedupeKey, now = /* @__PURE__ */ new Date()) {
+	return runSqliteWriteTransaction((db) => {
+		const policy = effectiveProactivePolicy(subscriptionId, now);
+		if (!policy.enabled) return "suppressed";
+		if (!policy.settings.managed && policy.preferences.revision === 0) return "allowed";
+		if (policy.level === "quiet" || policy.settings.delivery === "inbox") return "suppressed";
+		const end = quietHoursEnd(policy.preferences, now);
+		if (end) return end;
+		if (db.prepare("SELECT 1 FROM proactive_notification_budget WHERE dedupe_key = ?").get(dedupeKey)) return "allowed";
+		const day = localProactiveDay(now, policy.preferences.timezone);
+		if (db.prepare("SELECT COUNT(*) AS count FROM proactive_notification_budget WHERE workspace_id = ? AND local_day = ?").get(policy.workspaceId, day).count >= policy.preferences.dailyNotificationLimit) return "suppressed";
+		db.prepare("INSERT INTO proactive_notification_budget(dedupe_key, workspace_id, local_day, created_at) VALUES (?, ?, ?, ?)").run(dedupeKey, policy.workspaceId, day, now.toISOString());
+		return "allowed";
+	});
+}
+function nextDigestTime(preferences, after) {
+	const formatter = new Intl.DateTimeFormat("en-GB", {
+		timeZone: preferences.timezone,
+		hour: "2-digit",
+		minute: "2-digit",
+		hourCycle: "h23"
+	});
+	const target = preferences.digestHour * 60 + preferences.digestMinute;
+	let previousMinute = -1;
+	let previousDay = "";
+	for (let offset = 0; offset <= 2880; offset++) {
+		const date = /* @__PURE__ */ new Date(Math.floor(after.getTime() / 6e4) * 6e4 + offset * 6e4);
+		const parts = formatter.formatToParts(date);
+		const minute = Number(parts.find((part) => part.type === "hour")?.value) * 60 + Number(parts.find((part) => part.type === "minute")?.value);
+		const day = localProactiveDay(date, preferences.timezone);
+		if (minute === target || offset > 0 && previousDay === day && previousMinute < target && minute > target) return date;
+		previousMinute = minute;
+		previousDay = day;
+	}
+	return new Date(after.getTime() + 864e5);
+}
+//#endregion
+export { ProactiveConflict, effectiveProactivePolicy, localProactiveDay, nextDigestTime, proactivePreferences, quietHoursEnd, reserveProactiveNotification, subscriptionSettings, updateProactivePreferences };

package/dist/src/proactive/routing/matcher.js

@@ -46,10 +46,11 @@ function aggregationKey(event, route) {
 	return `${event.subject.kind}:${event.subject.id}`;
 }
 function matchScenario(event, route) {
-	if (!route.enabled || !route.eventTypes.includes(event.type)) return null;
+	const scheduled = event.type === "proactive.scan.v1" && event.source.kind === "proactive_scheduler" && event.payload.subscriptionId === route.subscriptionId;
+	if (!route.enabled || !scheduled && !route.eventTypes.includes(event.type)) return null;
 	if (route.scope?.workspaceId && route.scope.workspaceId !== event.scope.workspaceId) return null;
 	if (route.scope?.projectId && route.scope.projectId !== event.scope.projectId) return null;
-	if (route.condition && !matchesCondition(event, route.condition)) return null;
+	if (!scheduled && route.condition && !matchesCondition(event, route.condition)) return null;
 	return aggregationKey(event, route);
 }
 //#endregion

package/dist/src/proactive/scenarios/control.d.ts

@@ -0,0 +1,90 @@
+export declare function requireSubscription(id: string, workspaceId: string): import("./types.js").ScenarioSubscription;
+export declare function templateCatalog(workspaceId?: string): {
+    parameterSchema: {
+        type: string;
+        properties: {
+            scanIntervalMinutes: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            userInstructions: {
+                type: string;
+                maxLength: number;
+            };
+        };
+    };
+    calendarSource?: {
+        status: string;
+        lastSyncedAt: string;
+    };
+    key: string;
+    version: number;
+    title: string;
+    description: string;
+    scopeKind: "project" | "workspace";
+    eventTypes: string[];
+    contextProviderIds: string[];
+    scheduled: boolean;
+    requiresCalendar: boolean;
+}[];
+export declare function controlledSubscriptions(workspaceId: string): {
+    effectiveLevel: "off" | "active" | "quiet" | "balanced";
+    schedule: Record<string, import("node:sqlite").SQLOutputValue>;
+    revision: number;
+    managed: boolean;
+    level: "off" | "active" | "quiet" | "balanced";
+    delivery: "digest" | "inbox" | "important";
+    preparationWorkflowId: string;
+    scanIntervalMinutes: number;
+    userInstructions: string;
+    id: string;
+    scenarioKey: string;
+    workspaceId: string;
+    scopeKind: "workspace" | "project";
+    scopeId: string;
+    enabled: boolean;
+    activePromptRevisionId?: string;
+    createdAt: string;
+    updatedAt: string;
+}[];
+export declare function createControlledSubscription(workspaceId: string, value: unknown): {
+    effectiveLevel: "off" | "active" | "quiet" | "balanced";
+    schedule: Record<string, import("node:sqlite").SQLOutputValue>;
+    revision: number;
+    managed: boolean;
+    level: "off" | "active" | "quiet" | "balanced";
+    delivery: "digest" | "inbox" | "important";
+    preparationWorkflowId: string;
+    scanIntervalMinutes: number;
+    userInstructions: string;
+    id: string;
+    scenarioKey: string;
+    workspaceId: string;
+    scopeKind: "workspace" | "project";
+    scopeId: string;
+    enabled: boolean;
+    activePromptRevisionId?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export declare function updateControlledSubscription(workspaceId: string, id: string, value: unknown): {
+    effectiveLevel: "off" | "active" | "quiet" | "balanced";
+    schedule: Record<string, import("node:sqlite").SQLOutputValue>;
+    revision: number;
+    managed: boolean;
+    level: "off" | "active" | "quiet" | "balanced";
+    delivery: "digest" | "inbox" | "important";
+    preparationWorkflowId: string;
+    scanIntervalMinutes: number;
+    userInstructions: string;
+    id: string;
+    scenarioKey: string;
+    workspaceId: string;
+    scopeKind: "workspace" | "project";
+    scopeId: string;
+    enabled: boolean;
+    activePromptRevisionId?: string;
+    createdAt: string;
+    updatedAt: string;
+};