@xopcai/xopc 0.0.267 → 0.0.269

package/dist/src/notifications/service.js

@@ -1,9 +1,15 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
 import { localizeNotification } from "../../packages/gateway-contract/src/notifications.js";
-import { disableNotificationDeviceForPushToken, listDeliverableNotificationDevices } from "./device-store.js";
+import { proactivePreferences } from "../proactive/policy/service.js";
+import { flushDueDigests } from "../proactive/inbox/digest.js";
 import { notificationPlanFromGatewayEvent } from "./planner.js";
-import { createNotificationEvent, expireUndeliverableNotificationDeliveries, listDueNotificationDeliveries, markNotificationDeliveryAccepted, markNotificationDeliveryDead, markNotificationDeliveryDelivered, pruneNotificationEvents, rescheduleNotificationDelivery } from "./store.js";
+import { proactiveNotificationWorkspace, recheckNotificationDelivery } from "./proactive-policy.js";
+import { createNotificationEvent, deferNotificationDelivery, expireUndeliverableNotificationDeliveries, listDueNotificationDeliveries, markNotificationDeliveryAccepted, markNotificationDeliveryDead, markNotificationDeliveryDelivered, pruneNotificationEvents, rescheduleNotificationDelivery } from "./store.js";
+import { drainChannelNotifications, enqueueChannelNotification } from "./proactive-channel.js";
+import { drainBrowserPush, enqueueBrowserPush } from "./web-push.js";
+import { disableNotificationDeviceForPushToken, listDeliverableNotificationDevices } from "./device-store.js";
 //#region src/notifications/service.ts
 init_logger();
 const log = createLogger("Notifications");
@@ -58,15 +64,9 @@ var NotificationService = class {
 	}
 	handleGatewayEvent(type, payload) {
 		try {
-			const plan = notificationPlanFromGatewayEvent(type, payload);
-			if (!plan) return;
-			const devices = listDeliverableNotificationDevices().filter((device) => preferenceAllows(plan.notification.type, device.preferences));
-			const result = createNotificationEvent({
-				...plan,
-				deviceIds: devices.map((device) => device.id)
-			});
-			if (!result.created) return;
-			this.options.publish("notification.created", result.notification);
+			const notification = this.persistGatewayEvent(type, payload);
+			if (!notification) return;
+			this.options.publish("notification.created", notification);
 			this.drain();
 		} catch (err) {
 			log.error({
@@ -75,6 +75,50 @@ var NotificationService = class {
 			}, "Notification event persistence failed");
 		}
 	}
+	/** Throws on persistence failure so durable producers can retry the handoff. */
+	persistGatewayEvent(type, payload) {
+		const plan = notificationPlanFromGatewayEvent(type, payload);
+		if (!plan) return null;
+		return this.persistPlan(plan);
+	}
+	persistPlan(plan) {
+		let devices = listDeliverableNotificationDevices().filter((device) => preferenceAllows(plan.notification.type, device.preferences));
+		const workspace = proactiveNotificationWorkspace(plan.notification);
+		let browserIds;
+		let selectedChannel = "all";
+		if (workspace) {
+			const preferences = proactivePreferences(workspace);
+			const browsers = getSqliteDatabase().prepare("SELECT id FROM proactive_web_push_subscriptions WHERE workspace_id = ? ORDER BY created_at DESC, id").all(workspace);
+			selectedChannel = preferences.preferredChannel === "auto" ? browsers.length ? "browser" : devices.length ? "mobile" : "browser" : preferences.preferredChannel;
+			if (!["all", "mobile"].includes(selectedChannel)) devices = [];
+			else if (preferences.preferredChannel === "auto") devices = devices.slice(0, 1);
+			browserIds = ["all", "browser"].includes(selectedChannel) ? browsers.map((row) => row.id) : [];
+			if (preferences.preferredChannel === "auto") browserIds = browserIds.slice(0, 1);
+			plan = {
+				...plan,
+				notification: {
+					...plan.notification,
+					payload: {
+						...plan.notification.payload,
+						deliveryChannel: selectedChannel,
+						deliveryMode: preferences.preferredChannel
+					}
+				}
+			};
+		}
+		const result = runSqliteWriteTransaction(() => {
+			const created = createNotificationEvent({
+				...plan,
+				deviceIds: devices.map((device) => device.id)
+			});
+			if (created.created) {
+				enqueueBrowserPush(created.notification, browserIds);
+				if (workspace && selectedChannel === "telegram") enqueueChannelNotification(created.notification, workspace);
+			}
+			return created;
+		});
+		return result.created ? result.notification : null;
+	}
 	async drain() {
 		if (this.draining) return;
 		this.draining = true;
@@ -85,8 +129,11 @@ var NotificationService = class {
 				pruneNotificationEvents(now - 720 * 60 * 60 * 1e3);
 				this.lastMaintenanceAt = now;
 			}
+			for (const notification of flushDueDigests((plan) => this.persistPlan(plan))) this.options.publish("notification.created", notification);
 			await this.deliverPending();
 			await this.checkReceipts();
+			await drainBrowserPush();
+			if (this.options.sendChannel) await drainChannelNotifications(this.options.sendChannel);
 		} catch (err) {
 			log.warn({ err }, "Notification delivery pass failed");
 		} finally {
@@ -98,6 +145,17 @@ var NotificationService = class {
 		await Promise.all(deliveries.map((delivery) => this.send(delivery)));
 	}
 	async send(delivery) {
+		if (delivery.event.type === "proactive.insight") {
+			const policy = recheckNotificationDelivery(delivery.event, "mobile");
+			if (policy === "cancel") {
+				markNotificationDeliveryDead(delivery.event.id, delivery.deviceId, "Proactive policy changed");
+				return;
+			}
+			if (policy instanceof Date) {
+				deferNotificationDelivery(delivery.event.id, delivery.deviceId, policy.getTime());
+				return;
+			}
+		}
 		const fetchImpl = this.options.fetch ?? fetch;
 		const localized = localizeNotification(delivery.event, delivery.locale);
 		try {
@@ -110,8 +168,8 @@ var NotificationService = class {
 				signal: AbortSignal.timeout(1e4),
 				body: JSON.stringify({
 					to: delivery.pushToken,
-					title: localized.localizedTitle,
-					body: localized.localizedBody,
+					title: delivery.event.type === "proactive.insight" ? delivery.locale.startsWith("zh") ? "有一项工作需要查看" : "A work update is ready" : localized.localizedTitle,
+					body: delivery.event.type === "proactive.insight" ? delivery.locale.startsWith("zh") ? "打开 xopc 查看详情。" : "Open xopc to review it." : localized.localizedBody,
 					sound: delivery.event.priority === "high" ? "default" : void 0,
 					priority: delivery.event.priority,
 					data: {

package/dist/src/notifications/store.d.ts

@@ -51,3 +51,5 @@ export declare function notificationDeliveryMetrics(): {
 };
 export declare function expireUndeliverableNotificationDeliveries(now?: number): number;
 export declare function pruneNotificationEvents(before: number): number;
+export declare function deferNotificationDelivery(eventId: string, deviceId: string, nextAttemptAt: number): void;
+export declare function getNotificationEvent(id: string): ProductNotification | null;

package/dist/src/notifications/store.js

@@ -180,5 +180,12 @@ function pruneNotificationEvents(before) {
            AND d.status IN ('pending', 'accepted')
        )`).run(before).changes));
 }
+function deferNotificationDelivery(eventId, deviceId, nextAttemptAt) {
+	getSqliteDatabase().prepare("UPDATE notification_deliveries SET next_attempt_at = ?, last_error = 'Proactive quiet hours' WHERE event_id = ? AND device_id = ? AND status = 'pending'").run(nextAttemptAt, eventId, deviceId);
+}
+function getNotificationEvent(id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM notification_events WHERE event_id = ?").get(id);
+	return row ? eventFromRow(row) : null;
+}
 //#endregion
-export { acknowledgeNotification, createNotificationEvent, expireUndeliverableNotificationDeliveries, listDueNotificationDeliveries, listNotificationEvents, markNotificationDeliveryAccepted, markNotificationDeliveryDead, markNotificationDeliveryDelivered, notificationDeliveryMetrics, pruneNotificationEvents, rescheduleNotificationDelivery };
+export { acknowledgeNotification, createNotificationEvent, deferNotificationDelivery, expireUndeliverableNotificationDeliveries, getNotificationEvent, listDueNotificationDeliveries, listNotificationEvents, markNotificationDeliveryAccepted, markNotificationDeliveryDead, markNotificationDeliveryDelivered, notificationDeliveryMetrics, pruneNotificationEvents, rescheduleNotificationDelivery };

package/dist/src/notifications/web-push.d.ts

@@ -0,0 +1,19 @@
+import { type ProductNotification } from '@xopcai/gateway-contract';
+import webPush from 'web-push';
+export declare function allowedPushEndpoint(value: string): boolean;
+export declare function prepareBrowserPush(): {
+    publicKey: string;
+};
+export declare function registerBrowserPush(workspaceId: string, value: unknown): {
+    id: string;
+};
+export declare function unregisterBrowserPush(workspaceId: string, id: string): void;
+export declare function enqueueBrowserPush(notification: ProductNotification, selectedIds?: string[]): void;
+export declare function drainBrowserPush(send?: typeof webPush.sendNotification): Promise<void>;
+/** A user-triggered probe to this browser only; provider acceptance is not user delivery. */
+export declare function testBrowserPush(workspaceId: string, subscriptionId: string, send?: typeof webPush.sendNotification): Promise<{
+    id: `${string}-${string}-${string}-${string}-${string}`;
+    status: string;
+}>;
+export declare function acknowledgeBrowserProbe(workspaceId: string, id: string): void;
+export declare function listBrowserProbes(workspaceId: string): Record<string, import("node:sqlite").SQLOutputValue>[];

package/dist/src/notifications/web-push.js

@@ -0,0 +1,182 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { ProductNotificationSchema, notificationTargetRoute } from "../../packages/gateway-contract/src/notifications.js";
+import { proactiveNotificationWorkspace, recheckNotificationDelivery } from "./proactive-policy.js";
+import { createHash, randomUUID } from "node:crypto";
+import { z } from "zod";
+import webPush from "web-push";
+//#region src/notifications/web-push.ts
+function allowedPushEndpoint(value) {
+	try {
+		const url = new URL(value);
+		const host = url.hostname;
+		return url.protocol === "https:" && !url.username && !url.password && (!url.port || url.port === "443") && (host === "fcm.googleapis.com" || host === "updates.push.services.mozilla.com" || host.endsWith(".push.services.mozilla.com") || host === "web.push.apple.com" || host.endsWith(".notify.windows.com"));
+	} catch {
+		return false;
+	}
+}
+const BrowserPushSchema = z.object({
+	subscription: z.object({
+		endpoint: z.string().max(4096).refine(allowedPushEndpoint, "Unsupported push service"),
+		expirationTime: z.number().nullable().optional(),
+		keys: z.object({
+			auth: z.string().regex(/^[A-Za-z0-9_-]{22}$/),
+			p256dh: z.string().regex(/^[A-Za-z0-9_-]{87}$/)
+		}).strict()
+	}).strict(),
+	language: z.enum(["en", "zh"]).default("en")
+}).strict();
+function prepareBrowserPush() {
+	return runSqliteWriteTransaction((db) => {
+		let keys = db.prepare("SELECT public_key, private_key FROM proactive_web_push_keys WHERE id = 1").get();
+		if (!keys) {
+			const generated = webPush.generateVAPIDKeys();
+			db.prepare("INSERT INTO proactive_web_push_keys(id, public_key, private_key) VALUES (1, ?, ?)").run(generated.publicKey, generated.privateKey);
+			keys = {
+				public_key: generated.publicKey,
+				private_key: generated.privateKey
+			};
+		}
+		return { publicKey: keys.public_key };
+	});
+}
+function registerBrowserPush(workspaceId, value) {
+	const input = BrowserPushSchema.parse(value);
+	return runSqliteWriteTransaction((db) => {
+		const existing = db.prepare("SELECT id, workspace_id FROM proactive_web_push_subscriptions WHERE endpoint = ?").get(input.subscription.endpoint);
+		if (existing && existing.workspace_id !== workspaceId) throw new Error("Push subscription belongs to another workspace");
+		const id = existing?.id ?? randomUUID();
+		db.prepare(`INSERT INTO proactive_web_push_subscriptions(id, workspace_id, endpoint, subscription_json, language, created_at) VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(endpoint) DO UPDATE SET subscription_json = excluded.subscription_json, language = excluded.language`).run(id, workspaceId, input.subscription.endpoint, JSON.stringify(input.subscription), input.language, (/* @__PURE__ */ new Date()).toISOString());
+		return { id };
+	});
+}
+function unregisterBrowserPush(workspaceId, id) {
+	getSqliteDatabase().prepare("DELETE FROM proactive_web_push_subscriptions WHERE workspace_id = ? AND id = ?").run(workspaceId, id);
+}
+function enqueueBrowserPush(notification, selectedIds) {
+	const workspace = proactiveNotificationWorkspace(notification);
+	if (!workspace) return;
+	const targetId = notification.target.kind === "insight" ? notification.target.inboxItemId : "";
+	const subscriptions = getSqliteDatabase().prepare("SELECT id FROM proactive_web_push_subscriptions WHERE workspace_id = ?").all(workspace);
+	for (const subscription of subscriptions) {
+		if (selectedIds && !selectedIds.includes(subscription.id)) continue;
+		getSqliteDatabase().prepare(`INSERT OR IGNORE INTO proactive_web_push_deliveries(notification_id, subscription_id, inbox_item_id, notification_revision, next_attempt_at) VALUES (?, ?, ?, ?, ?)`).run(notification.id, subscription.id, targetId, typeof notification.payload.notificationRevision === "number" ? notification.payload.notificationRevision : 1, Date.now());
+	}
+}
+async function drainBrowserPush(send = webPush.sendNotification) {
+	const db = getSqliteDatabase();
+	const keys = db.prepare("SELECT public_key, private_key FROM proactive_web_push_keys WHERE id = 1").get();
+	if (!keys) return;
+	const claim = runSqliteWriteTransaction((tx) => {
+		tx.prepare("UPDATE proactive_web_push_deliveries SET status = 'failed', last_error = 'Delivery lease exhausted' WHERE status = 'sending' AND lease_until <= ? AND attempt >= 5").run(Date.now());
+		const row = tx.prepare(`SELECT d.*, s.subscription_json, s.language FROM proactive_web_push_deliveries d
+      JOIN proactive_web_push_subscriptions s ON s.id = d.subscription_id
+      WHERE (d.status = 'pending' AND d.next_attempt_at <= ?) OR (d.status = 'sending' AND d.lease_until <= ?)
+      ORDER BY d.next_attempt_at LIMIT 1`).get(Date.now(), Date.now());
+		if (!row) return null;
+		tx.prepare("UPDATE proactive_web_push_deliveries SET status = 'sending', attempt = attempt + 1, lease_until = ? WHERE notification_id = ? AND subscription_id = ?").run(Date.now() + 6e4, row.notification_id, row.subscription_id);
+		return {
+			...row,
+			attempt: row.attempt + 1
+		};
+	});
+	if (!claim) return;
+	const finish = (status, nextAt, error = null) => db.prepare(`UPDATE proactive_web_push_deliveries SET status = ?, next_attempt_at = ?, last_error = ?, lease_until = NULL
+    WHERE notification_id = ? AND subscription_id = ? AND attempt = ? AND status = 'sending'`).run(status, nextAt, error, claim.notification_id, claim.subscription_id, claim.attempt);
+	try {
+		const row = db.prepare("SELECT * FROM notification_events WHERE event_id = ?").get(claim.notification_id);
+		const notification = ProductNotificationSchema.parse({
+			schemaVersion: 1,
+			id: row.event_id,
+			type: row.event_type,
+			target: JSON.parse(String(row.target_json)),
+			priority: row.priority,
+			title: {
+				en: row.title_en,
+				zh: row.title_zh
+			},
+			payload: JSON.parse(String(row.payload_json)),
+			createdAt: row.created_at
+		});
+		const policy = recheckNotificationDelivery(notification, "browser");
+		if (policy === "cancel") {
+			finish("failed", Date.now(), "Policy changed or card expired");
+			return;
+		}
+		if (policy instanceof Date) {
+			finish("pending", policy.getTime());
+			db.prepare("UPDATE proactive_web_push_deliveries SET attempt = attempt - 1 WHERE notification_id = ? AND subscription_id = ? AND attempt = ?").run(claim.notification_id, claim.subscription_id, claim.attempt);
+			return;
+		}
+		const subscription = JSON.parse(claim.subscription_json);
+		if (!allowedPushEndpoint(subscription.endpoint)) throw new Error("Unsupported push service");
+		await send(subscription, JSON.stringify({
+			id: claim.notification_id,
+			title: claim.language === "zh" ? "有一项工作需要查看" : "A work update is ready",
+			body: claim.language === "zh" ? "打开 xopc 查看详情。" : "Open xopc to review it.",
+			route: notificationTargetRoute(notification.target, "web")
+		}), {
+			vapidDetails: {
+				subject: "https://xopc.ai",
+				publicKey: keys.public_key,
+				privateKey: keys.private_key
+			},
+			TTL: 3600,
+			timeout: 1e4,
+			topic: createHash("sha256").update(claim.inbox_item_id || claim.notification_id).digest("base64url").slice(0, 32)
+		});
+		finish("sent", Date.now());
+	} catch (error) {
+		const status = error.statusCode;
+		if (status === 404 || status === 410) {
+			db.prepare("DELETE FROM proactive_web_push_subscriptions WHERE id = ?").run(claim.subscription_id);
+			return;
+		}
+		finish(claim.attempt >= 5 ? "failed" : "pending", Date.now() + Math.min(36e5, 3e4 * 2 ** claim.attempt), status ? `Push service HTTP ${status}` : "Push delivery failed");
+	}
+}
+/** A user-triggered probe to this browser only; provider acceptance is not user delivery. */
+async function testBrowserPush(workspaceId, subscriptionId, send = webPush.sendNotification) {
+	const id = randomUUID();
+	const claimed = runSqliteWriteTransaction((db) => {
+		const row = db.prepare("SELECT subscription_json FROM proactive_web_push_subscriptions WHERE id = ? AND workspace_id = ?").get(subscriptionId, workspaceId);
+		if (!row) throw new Error("Browser subscription not found");
+		if (db.prepare("SELECT 1 FROM proactive_push_probes WHERE workspace_id = ? AND created_at > ?").get(workspaceId, Date.now() - 6e4)) throw new Error("Wait one minute before another push test");
+		db.prepare("INSERT INTO proactive_push_probes(id, workspace_id, subscription_id, status, created_at) VALUES (?, ?, ?, ?, ?)").run(id, workspaceId, subscriptionId, "sending", Date.now());
+		return JSON.parse(row.subscription_json);
+	});
+	const keys = getSqliteDatabase().prepare("SELECT public_key, private_key FROM proactive_web_push_keys WHERE id = 1").get();
+	try {
+		if (!allowedPushEndpoint(claimed.endpoint)) throw new Error("Unsupported push service");
+		await send(claimed, JSON.stringify({
+			id,
+			title: "xopc 推送测试 / Push test",
+			body: "点击此通知确认打开 / Tap to confirm opening",
+			route: `/proactive?probe=${encodeURIComponent(id)}`
+		}), {
+			vapidDetails: {
+				subject: "https://xopc.ai",
+				publicKey: keys.public_key,
+				privateKey: keys.private_key
+			},
+			TTL: 300,
+			timeout: 1e4
+		});
+		getSqliteDatabase().prepare("UPDATE proactive_push_probes SET status = CASE WHEN opened_at IS NULL THEN 'accepted' ELSE 'opened' END WHERE id = ?").run(id);
+		return {
+			id,
+			status: "accepted"
+		};
+	} catch {
+		getSqliteDatabase().prepare("UPDATE proactive_push_probes SET status = 'failed', error = 'Push service did not accept the test' WHERE id = ?").run(id);
+		throw new Error("Push test failed; verify browser subscription and network connectivity");
+	}
+}
+function acknowledgeBrowserProbe(workspaceId, id) {
+	getSqliteDatabase().prepare("UPDATE proactive_push_probes SET status = 'opened', opened_at = ? WHERE id = ? AND workspace_id = ?").run(Date.now(), id, workspaceId);
+}
+function listBrowserProbes(workspaceId) {
+	return getSqliteDatabase().prepare("SELECT id, status, created_at AS createdAt, opened_at AS openedAt, error FROM proactive_push_probes WHERE workspace_id = ? ORDER BY created_at DESC LIMIT 10").all(workspaceId);
+}
+//#endregion
+export { acknowledgeBrowserProbe, allowedPushEndpoint, drainBrowserPush, enqueueBrowserPush, listBrowserProbes, prepareBrowserPush, registerBrowserPush, testBrowserPush, unregisterBrowserPush };

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

@@ -1,5 +1,8 @@
 import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
 import { TaskApplicationService } from "../../tasks/task-application-service.js";
+import { effectiveProactivePolicy } from "../policy/service.js";
+import { insightSourcesAuthorized } from "../execution/authorization.js";
+import { insightCorrelation } from "../inbox/lifecycle.js";
 //#region src/proactive/actions/service.ts
 function projectIdFromAggregationKey(value) {
 	if (!value.startsWith("project:") || value.length === 8) throw new Error("Proactive action has no project scope");
@@ -8,9 +11,14 @@ function projectIdFromAggregationKey(value) {
 function executeClaimedAction(row, now = /* @__PURE__ */ new Date()) {
 	const action = JSON.parse(row.proposed_action_json);
 	try {
+		if (getSqliteDatabase().prepare("SELECT 1 FROM proactive_inbox_items WHERE insight_id = ? AND withdrawn_at IS NOT NULL").get(row.insight_id)) throw new Error("Card was withdrawn");
+		if (!insightSourcesAuthorized(row.insight_id)) throw new Error("Source permission is no longer available");
+		if (!effectiveProactivePolicy(row.subscription_id).enabled) throw new Error("Proactive subscription paused");
+		const permission = getSqliteDatabase().prepare(`SELECT mode, allowed_actions_json FROM project_monitoring_policies WHERE project_id = ?`).get(projectIdFromAggregationKey(row.aggregation_key));
+		if (!getSqliteDatabase().prepare(`SELECT 1 FROM proactive_decisions d JOIN proactive_inbox_items i USING(inbox_item_id) WHERE i.insight_id = ? AND d.choice = 'approve'`).get(row.insight_id) && !(permission?.mode === "auto_low_risk" && JSON.parse(permission.allowed_actions_json).includes(action.id))) throw new Error("Action permission is no longer available");
 		if (action.id !== "create_project_task") throw new Error(`Unsupported proactive action: ${action.id}`);
 		const result = new TaskApplicationService().create({
-			idempotencyKey: `proactive:${row.insight_id}:${action.id}`,
+			idempotencyKey: `proactive:${insightCorrelation(row.insight_id)}:${action.id}`,
 			title: action.input.title,
 			projectId: projectIdFromAggregationKey(row.aggregation_key),
 			priority: "normal",
@@ -53,7 +61,7 @@ function executePendingProactiveActions(now = /* @__PURE__ */ new Date()) {
 	let executed = 0;
 	while (true) {
 		const row = runSqliteWriteTransaction((db) => {
-			const candidate = db.prepare(`SELECT x.insight_id, b.aggregation_key, x.proposed_action_json
+			const candidate = db.prepare(`SELECT x.insight_id, x.subscription_id, b.aggregation_key, x.proposed_action_json
         FROM proactive_insights x
         JOIN proactive_runs r ON r.run_id = x.run_id
         JOIN proactive_signal_batches b ON b.batch_id = r.batch_id

package/dist/src/proactive/actions/workflow.d.ts

@@ -0,0 +1,15 @@
+import type { WorkflowRunService } from '../../workflows/service/workflow-run-service.js';
+export declare function prepareCardWorkflow(workspace: string, cardId: string, value: unknown, agentId: string, workflows: WorkflowRunService): Promise<{
+    runId: string | null;
+    agentId: string;
+    sessionKey: string | null;
+    status: string;
+    error: string | null;
+}>;
+export declare function workflowForCard(cardId: string, workspace: string, workflows: WorkflowRunService): Promise<{
+    runId: string | null;
+    agentId: string;
+    sessionKey: string | null;
+    status: string;
+    error: string | null;
+}>;

package/dist/src/proactive/actions/workflow.js

@@ -0,0 +1,88 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { ProactiveConflict, effectiveProactivePolicy } from "../policy/service.js";
+import { requireSubscription } from "../scenarios/control.js";
+import { getCard } from "../inbox/cards.js";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+//#region src/proactive/actions/workflow.ts
+const StartSchema = z.object({
+	expectedRevision: z.number().int().positive(),
+	retry: z.boolean().default(false)
+}).strict();
+async function prepareCardWorkflow(workspace, cardId, value, agentId, workflows) {
+	const input = StartSchema.parse(value);
+	const card = getCard(cardId, workspace);
+	const policy = effectiveProactivePolicy(card.subscriptionId);
+	const sub = requireSubscription(card.subscriptionId, workspace);
+	if (!policy.enabled || card.status === "withdrawn" || card.status === "expired") throw new Error("Card is no longer actionable");
+	if (card.revision !== input.expectedRevision) throw new ProactiveConflict("Card changed; refresh before acting");
+	const definitionId = policy.settings.preparationWorkflowId;
+	if (!definitionId) throw new Error("Choose a preparation workflow in the subscription settings first");
+	const claim = runSqliteWriteTransaction((db) => {
+		const previous = db.prepare("SELECT * FROM proactive_workflow_links WHERE inbox_item_id = ?").get(cardId);
+		if (previous?.lease_until && previous.lease_until > Date.now()) throw new ProactiveConflict("Workflow request is already running");
+		if (previous?.run_id && !input.retry) return {
+			existing: true,
+			...previous
+		};
+		if (previous && previous.definition_id !== definitionId) throw new Error("Workflow selection changed; open the existing run to recover it");
+		const attemptKey = previous?.status === "starting" || previous?.status === "failed" && !previous.run_id ? previous.attempt_key : `proactive-prepare:${cardId}:${randomUUID()}`;
+		db.prepare(`INSERT INTO proactive_workflow_links(inbox_item_id, definition_id, agent_id, attempt_key, status, lease_until)
+      VALUES (?, ?, ?, ?, 'starting', ?) ON CONFLICT(inbox_item_id) DO UPDATE SET status = 'starting', attempt_key = excluded.attempt_key, lease_until = excluded.lease_until, error = NULL`).run(cardId, definitionId, agentId, attemptKey, Date.now() + 12e4);
+		return {
+			existing: false,
+			run_id: previous?.run_id ?? null,
+			agent_id: previous?.agent_id ?? agentId,
+			attempt_key: attemptKey
+		};
+	});
+	if (claim.existing) return workflowForCard(cardId, workspace, workflows);
+	try {
+		if (input.retry && claim.run_id) {
+			const previous = await workflows.createRunStore(claim.agent_id).readRunView(claim.run_id);
+			if (previous && ![
+				"failed",
+				"cancelled",
+				"interrupted"
+			].includes(previous.run.status)) throw new Error("Only failed or interrupted workflows can be retried");
+		}
+		if (["withdrawn", "expired"].includes(getCard(cardId, workspace).status) || !effectiveProactivePolicy(card.subscriptionId).enabled) throw new Error("Card permissions changed");
+		const result = await workflows.startWorkflowRun({
+			agentId: claim.agent_id,
+			definitionId,
+			preparationOnly: true,
+			writebackPolicy: { targets: [] },
+			...sub.scopeKind === "project" ? { projectId: sub.scopeId } : {},
+			goal: `Prepare a reviewable checklist for this user-selected card. Do not send messages or publish results.\n${card.title}\n${card.summary}\n${card.recommendation}`,
+			input: {
+				cardId,
+				evidence: card.evidence,
+				purpose: "preparation_checklist"
+			},
+			source: { kind: "webui" },
+			concurrency: 1,
+			tokenBudget: 5e3,
+			idempotencyKey: claim.attempt_key,
+			...input.retry && claim.run_id ? { retryOfRunId: claim.run_id } : {}
+		});
+		if (result.ok === false) throw new Error(result.message);
+		getSqliteDatabase().prepare("UPDATE proactive_workflow_links SET status = 'started', run_id = ?, session_key = ?, lease_until = NULL WHERE inbox_item_id = ? AND attempt_key = ?").run(result.runId, result.sessionKey, cardId, claim.attempt_key);
+		return workflowForCard(cardId, workspace, workflows);
+	} catch (error) {
+		getSqliteDatabase().prepare("UPDATE proactive_workflow_links SET status = 'failed', lease_until = NULL, error = ? WHERE inbox_item_id = ? AND attempt_key = ?").run(error instanceof Error ? error.message.slice(0, 500) : "Workflow failed", cardId, claim.attempt_key);
+		throw error;
+	}
+}
+async function workflowForCard(cardId, workspace, workflows) {
+	if (getCard(cardId, workspace).status === "withdrawn") return null;
+	const row = getSqliteDatabase().prepare("SELECT run_id AS runId, agent_id AS agentId, session_key AS sessionKey, status, error FROM proactive_workflow_links WHERE inbox_item_id = ?").get(cardId);
+	if (!row) return null;
+	if (!row.runId) return row;
+	const view = await workflows.createRunStore(row.agentId).readRunView(row.runId);
+	return {
+		...row,
+		status: view?.run.status ?? row.status
+	};
+}
+//#endregion
+export { prepareCardWorkflow, workflowForCard };

package/dist/src/proactive/execution/agent-executor.d.ts

@@ -12,5 +12,10 @@ export declare class ReadonlyProactiveAgentExecutor implements ProactiveAgentExe
     }): Promise<{
         text: string;
         modelRef: string;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+            estimatedCostUsd?: number;
+        };
     }>;
 }

package/dist/src/proactive/execution/agent-executor.js

@@ -56,6 +56,7 @@ var ReadonlyProactiveAgentExecutor = class {
 		this.config = config;
 	}
 	async execute(input) {
+		input.signal?.throwIfAborted();
 		const model = resolveModel(getDefaultModelSync(this.config()));
 		let toolCalls = 0;
 		const agent = new Agent({
@@ -91,8 +92,28 @@ var ReadonlyProactiveAgentExecutor = class {
 			const text = assistantText(agent.state.messages);
 			if (!text) throw new Error("Proactive agent returned empty output");
 			if (toolCalls === 0) throw new Error("Proactive agent did not inspect authorized evidence");
+			const usage = {
+				inputTokens: 0,
+				outputTokens: 0,
+				estimatedCostUsd: 0
+			};
+			for (const message of agent.state.messages) {
+				if (message.role !== "assistant") continue;
+				const reported = message.usage;
+				if (reported) {
+					usage.inputTokens += reported.input ?? 0;
+					usage.outputTokens += reported.output ?? 0;
+					usage.estimatedCostUsd += reported.cost?.total ?? 0;
+				}
+			}
+			const priced = Object.values(model.cost).some((value) => value > 0);
 			return {
 				text,
+				usage: {
+					inputTokens: usage.inputTokens,
+					outputTokens: usage.outputTokens,
+					...priced ? { estimatedCostUsd: usage.estimatedCostUsd } : {}
+				},
 				modelRef: `${model.provider}/${model.id}`
 			};
 		} finally {

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

@@ -0,0 +1,3 @@
+/** Recheck connector consent for stored cards and actions, not just model input. */
+export declare function insightSourcesAuthorized(insightId: string): boolean;
+export declare function authorizedConnectedSource(itemId: string, workspaceId: string, scenarioKey: string, agentId?: string | null): import("../../knowledge/types.js").KnowledgeSourceItem;

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

@@ -0,0 +1,23 @@
+import { getSqliteDatabase } from "../../storage/sqlite/transaction.js";
+import { getKnowledgeSourceItem } from "../../storage/sqlite/knowledge-repository.js";
+import { getConnectorSyncPolicyForConnection } from "../../storage/sqlite/connector-sync-policy-repository.js";
+//#region src/proactive/execution/authorization.ts
+/** Recheck connector consent for stored cards and actions, not just model input. */
+function insightSourcesAuthorized(insightId) {
+	return getSqliteDatabase().prepare(`SELECT e.subject_id, e.workspace_id, x.scenario_key
+    FROM proactive_insights x JOIN proactive_runs r USING(run_id)
+    JOIN proactive_batch_events be ON be.batch_id = r.batch_id JOIN proactive_events e USING(event_id)
+    WHERE x.insight_id = ? AND e.type LIKE 'connected_source.%'`).all(insightId).every((row) => Boolean(authorizedConnectedSource(row.subject_id, row.workspace_id, row.scenario_key)));
+}
+function authorizedConnectedSource(itemId, workspaceId, scenarioKey, agentId) {
+	const item = getKnowledgeSourceItem(itemId);
+	if (!item || item.deletedAt || item.metadata.workspaceId !== workspaceId || item.sensitivity === "secret" || item.sensitivity === "regulated") return null;
+	if (agentId && item.metadata.agentId && item.metadata.agentId !== agentId) return null;
+	const connectionId = item.metadata.connectionId;
+	if (typeof connectionId !== "string") return null;
+	if (!getSqliteDatabase().prepare("SELECT 1 FROM connector_connections WHERE id = ? AND status = 'active'").get(connectionId)) return null;
+	const policy = getConnectorSyncPolicyForConnection(connectionId);
+	return policy?.scanEnabled && policy.proactiveEnabled && (!policy.allowedScenarioKeys.length || policy.allowedScenarioKeys.includes(scenarioKey)) ? item : null;
+}
+//#endregion
+export { authorizedConnectedSource, insightSourcesAuthorized };

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

@@ -1,9 +1,8 @@
 import { getSqliteDatabase } from "../../storage/sqlite/transaction.js";
-import { getKnowledgeSourceItem } from "../../storage/sqlite/knowledge-repository.js";
-import { getConnectorSyncPolicyForConnection } from "../../storage/sqlite/connector-sync-policy-repository.js";
 import { getAssertionSlot, listUserAssertions } from "../../user-model/repository.js";
 import "../../user-model/index.js";
 import { getDiscussionCapture, getLatestDiscussionOrganization } from "../../discussions/repository.js";
+import { authorizedConnectedSource } from "./authorization.js";
 import { wrapExternalContent } from "../../gateway/security/external-content.js";
 //#region src/proactive/execution/context.ts
 const MAX_EVENT_COUNT = 50;
@@ -28,15 +27,7 @@ function emptyContext() {
 	};
 }
 function authorizedConnectedSourceItem(event, scenarioKey) {
-	const item = getKnowledgeSourceItem(event.subject_id);
-	const connectionId = typeof item?.metadata.connectionId === "string" ? item.metadata.connectionId : void 0;
-	if (!item || item.deletedAt || !connectionId) return null;
-	if (item.sensitivity === "secret" || item.sensitivity === "regulated") return null;
-	if (item.metadata.workspaceId !== event.workspace_id) return null;
-	if (event.agent_id && item.metadata.agentId && item.metadata.agentId !== event.agent_id) return null;
-	const policy = getConnectorSyncPolicyForConnection(connectionId);
-	const scenarioAllowed = !policy?.allowedScenarioKeys.length || policy.allowedScenarioKeys.includes(scenarioKey);
-	return policy?.scanEnabled && policy.proactiveEnabled && scenarioAllowed ? item : null;
+	return authorizedConnectedSource(event.subject_id, event.workspace_id, scenarioKey, event.agent_id);
 }
 var EventBatchContextProvider = class {
 	id = "event_batch";

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

@@ -5,3 +5,10 @@ export declare function isValuableInsight(candidate: InsightCandidate, policy?:
     minConfidence: number;
     minScore: number;
 }): boolean;
+export declare function parseAnalysisResult(raw: string, allowedEvidenceIds: Set<string>): {
+    result: 'no_insight';
+    reason: string;
+} | {
+    result: 'insight';
+    candidate: InsightCandidate;
+};