@xopcai/xopc 0.0.227 → 0.0.228

package/dist/src/notifications/planner.js

@@ -0,0 +1,156 @@
+import { NotificationTargetSchema } from "../../packages/gateway-contract/src/notifications.js";
+//#region src/notifications/planner.ts
+function chatPlan(payload) {
+	if (!payload || typeof payload !== "object") return null;
+	const event = payload;
+	if (event.status !== "success" && event.status !== "error") return null;
+	if (typeof event.runId !== "string" || !event.runId) return null;
+	const target = NotificationTargetSchema.safeParse(event.target);
+	if (!target.success || target.data.kind !== "chat" || target.data.sessionKey !== event.sessionKey) return null;
+	const completed = event.status === "success";
+	const type = completed ? "chat.completed" : "chat.failed";
+	const fallback = {
+		en: "Open the conversation to review the result.",
+		zh: "打开对话查看结果。"
+	};
+	const sessionTitle = typeof event.sessionTitle === "string" ? event.sessionTitle.trim().slice(0, 120) : "";
+	return {
+		dedupeKey: `${type}:${event.runId}`,
+		notification: {
+			type,
+			target: target.data,
+			priority: completed ? "normal" : "high",
+			title: completed ? {
+				en: "Response ready",
+				zh: "回答已就绪"
+			} : {
+				en: "Response needs attention",
+				zh: "回答需要处理"
+			},
+			body: sessionTitle ? {
+				en: sessionTitle,
+				zh: sessionTitle
+			} : fallback,
+			payload: { runId: event.runId }
+		}
+	};
+}
+function taskPlan(payload) {
+	if (!payload || typeof payload !== "object") return null;
+	const data = payload;
+	const taskId = typeof data.task?.id === "string" ? data.task.id : typeof data.taskId === "string" ? data.taskId : "";
+	const sourceEventId = typeof data.sourceEventId === "string" ? data.sourceEventId : "";
+	if (!taskId || !sourceEventId) return null;
+	const type = data.reason === "blocked" ? "task.blocked" : data.reason === "failed" ? "task.failed" : data.reason === "user_input" || data.reason === "approval" ? "task.needs_input" : data.to === "closed" && data.resolution === "done" ? "task.completed" : void 0;
+	if (!type) return null;
+	const taskTitle = typeof data.task?.title === "string" ? data.task.title.trim().slice(0, 120) : "";
+	const title = type === "task.needs_input" ? {
+		en: "Action needed",
+		zh: "需要你的操作"
+	} : type === "task.blocked" ? {
+		en: "Task blocked",
+		zh: "任务受阻"
+	} : type === "task.failed" ? {
+		en: "Task failed",
+		zh: "任务失败"
+	} : {
+		en: "Task completed",
+		zh: "任务已完成"
+	};
+	return {
+		dedupeKey: `${type}:${sourceEventId}`,
+		notification: {
+			type,
+			target: {
+				kind: "task",
+				taskId
+			},
+			priority: type === "task.completed" ? "normal" : "high",
+			title,
+			...taskTitle ? { body: {
+				en: taskTitle,
+				zh: taskTitle
+			} } : {},
+			payload: {
+				taskId,
+				sourceEventId
+			}
+		}
+	};
+}
+function automationPlan(payload) {
+	if (!payload || typeof payload !== "object") return null;
+	const event = payload;
+	if (event.notificationPolicy === "none") return null;
+	if (event.notificationPolicy === "attention" && event.requiresAttention !== true) return null;
+	const run = event.run;
+	if (!run || run.status !== "failed" && run.status !== "timeout" && run.status !== "succeeded") return null;
+	const completed = run.status === "succeeded";
+	const type = completed ? "automation.completed" : "automation.failed";
+	return {
+		dedupeKey: `${type}:${run.id}`,
+		notification: {
+			type,
+			target: {
+				kind: "automation_run",
+				automationId: run.automationId,
+				runId: run.id
+			},
+			priority: completed ? "normal" : "high",
+			title: completed ? {
+				en: "Automation completed",
+				zh: "自动化已完成"
+			} : {
+				en: "Automation needs attention",
+				zh: "自动化需要处理"
+			},
+			body: {
+				en: (run.error || run.summary || run.automationName).slice(0, 180),
+				zh: (run.error || run.summary || run.automationName).slice(0, 180)
+			},
+			payload: {
+				automationId: run.automationId,
+				runId: run.id
+			}
+		}
+	};
+}
+function proactivePlan(payload) {
+	if (!payload || typeof payload !== "object") return null;
+	const item = payload;
+	if (typeof item.id !== "string" || typeof item.insight?.id !== "string" || typeof item.insight.title !== "string") return null;
+	const title = item.insight.title.trim().slice(0, 120);
+	const summary = typeof item.insight.summary === "string" ? item.insight.summary.trim().slice(0, 180) : "";
+	return {
+		dedupeKey: `proactive.insight:${item.id}`,
+		notification: {
+			type: "proactive.insight",
+			target: {
+				kind: "insight",
+				inboxItemId: item.id
+			},
+			priority: item.insight.urgency === "high" || item.insight.urgency === "critical" ? "high" : "normal",
+			title: {
+				en: title,
+				zh: title
+			},
+			...summary ? { body: {
+				en: summary,
+				zh: summary
+			} } : {},
+			payload: {
+				inboxItemId: item.id,
+				insightId: item.insight.id
+			}
+		}
+	};
+}
+function notificationPlanFromGatewayEvent(type, payload) {
+	if (type === "agent.run.ended") return chatPlan(payload);
+	if (type === "task.attention_required.v2" || type === "task.phase_changed.v2") return taskPlan(payload);
+	if (type === "automation.run.completed") return automationPlan(payload);
+	if (type === "proactive.inbox.created") return proactivePlan(payload);
+	return null;
+}
+//#endregion
+export { notificationPlanFromGatewayEvent };

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

@@ -0,0 +1,18 @@
+export declare class NotificationService {
+    private readonly options;
+    private timer;
+    private draining;
+    private lastMaintenanceAt;
+    constructor(options: {
+        publish: (type: string, payload: unknown) => void;
+        fetch?: typeof fetch;
+    });
+    start(): void;
+    stop(): void;
+    handleGatewayEvent(type: string, payload: unknown): void;
+    drain(): Promise<void>;
+    private deliverPending;
+    private send;
+    private checkReceipts;
+    private retryOrFail;
+}

package/dist/src/notifications/service.js

@@ -0,0 +1,184 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+import { localizeNotification } from "../../packages/gateway-contract/src/notifications.js";
+import { disableNotificationDeviceForPushToken, listDeliverableNotificationDevices } from "./device-store.js";
+import { notificationPlanFromGatewayEvent } from "./planner.js";
+import { createNotificationEvent, expireUndeliverableNotificationDeliveries, listDueNotificationDeliveries, markNotificationDeliveryAccepted, markNotificationDeliveryDead, markNotificationDeliveryDelivered, pruneNotificationEvents, rescheduleNotificationDelivery } from "./store.js";
+//#region src/notifications/service.ts
+init_logger();
+const log = createLogger("Notifications");
+const EXPO_PUSH_URL = "https://exp.host/--/api/v2/push/send";
+const EXPO_RECEIPTS_URL = "https://exp.host/--/api/v2/push/getReceipts";
+const MAX_DELIVERY_ATTEMPTS = 5;
+const RETRY_DELAYS_MS = [
+	3e4,
+	12e4,
+	6e5,
+	36e5,
+	216e5
+];
+const RECEIPT_DELAY_MS = 15 * 6e4;
+function preferenceAllows(type, preferences) {
+	switch (type) {
+		case "chat.completed": return preferences.chatCompleted;
+		case "chat.failed": return preferences.chatFailed;
+		case "task.needs_input": return preferences.taskNeedsInput;
+		case "task.blocked": return preferences.taskBlocked;
+		case "task.failed": return preferences.taskFailed;
+		case "task.completed": return preferences.taskCompleted;
+		case "automation.completed": return preferences.automationCompleted;
+		case "automation.failed": return preferences.automationFailed;
+		case "proactive.insight": return preferences.proactiveInsight;
+	}
+}
+function retryAt(attempts, now) {
+	return now + RETRY_DELAYS_MS[Math.min(attempts, RETRY_DELAYS_MS.length - 1)];
+}
+function expoError(result) {
+	return result.details?.error || result.message || "Expo rejected the notification";
+}
+var NotificationService = class {
+	timer = null;
+	draining = false;
+	lastMaintenanceAt = 0;
+	constructor(options) {
+		this.options = options;
+	}
+	start() {
+		if (this.timer) return;
+		this.drain();
+		this.timer = setInterval(() => void this.drain(), 3e4);
+		this.timer.unref?.();
+	}
+	stop() {
+		if (this.timer) clearInterval(this.timer);
+		this.timer = null;
+	}
+	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);
+			this.drain();
+		} catch (err) {
+			log.error({
+				err,
+				eventType: type
+			}, "Notification event persistence failed");
+		}
+	}
+	async drain() {
+		if (this.draining) return;
+		this.draining = true;
+		try {
+			const now = Date.now();
+			if (now - this.lastMaintenanceAt >= 3600 * 1e3) {
+				expireUndeliverableNotificationDeliveries(now);
+				pruneNotificationEvents(now - 720 * 60 * 60 * 1e3);
+				this.lastMaintenanceAt = now;
+			}
+			await this.deliverPending();
+			await this.checkReceipts();
+		} catch (err) {
+			log.warn({ err }, "Notification delivery pass failed");
+		} finally {
+			this.draining = false;
+		}
+	}
+	async deliverPending() {
+		const deliveries = listDueNotificationDeliveries("pending");
+		await Promise.all(deliveries.map((delivery) => this.send(delivery)));
+	}
+	async send(delivery) {
+		const fetchImpl = this.options.fetch ?? fetch;
+		const localized = localizeNotification(delivery.event, delivery.locale);
+		try {
+			const response = await fetchImpl(EXPO_PUSH_URL, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					accept: "application/json"
+				},
+				signal: AbortSignal.timeout(1e4),
+				body: JSON.stringify({
+					to: delivery.pushToken,
+					title: localized.localizedTitle,
+					body: localized.localizedBody,
+					sound: delivery.event.priority === "high" ? "default" : void 0,
+					priority: delivery.event.priority,
+					data: {
+						eventId: delivery.event.id,
+						target: delivery.event.target,
+						...delivery.event.payload
+					}
+				})
+			});
+			if (!response.ok) throw new Error(`Expo push request failed (${response.status})`);
+			const body = await response.json();
+			const result = Array.isArray(body.data) ? body.data[0] : body.data;
+			if (result?.status !== "ok" || !result.id) {
+				const error = expoError(result ?? {});
+				if (result?.details?.error === "DeviceNotRegistered") {
+					disableNotificationDeviceForPushToken(delivery.pushToken);
+					markNotificationDeliveryDead(delivery.event.id, delivery.deviceId, error);
+					return;
+				}
+				throw new Error(error);
+			}
+			markNotificationDeliveryAccepted(delivery.event.id, delivery.deviceId, result.id, Date.now() + RECEIPT_DELAY_MS);
+		} catch (err) {
+			this.retryOrFail(delivery, err);
+		}
+	}
+	async checkReceipts() {
+		const withTickets = listDueNotificationDeliveries("accepted").filter((delivery) => delivery.providerTicketId);
+		if (withTickets.length === 0) return;
+		const fetchImpl = this.options.fetch ?? fetch;
+		try {
+			const response = await fetchImpl(EXPO_RECEIPTS_URL, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					accept: "application/json"
+				},
+				signal: AbortSignal.timeout(1e4),
+				body: JSON.stringify({ ids: withTickets.map((delivery) => delivery.providerTicketId) })
+			});
+			if (!response.ok) throw new Error(`Expo receipt request failed (${response.status})`);
+			const body = await response.json();
+			for (const delivery of withTickets) {
+				const result = body.data?.[delivery.providerTicketId];
+				if (!result) this.retryOrFail(delivery, /* @__PURE__ */ new Error("Expo receipt is not ready"), "accepted");
+				else if (result.status === "ok") markNotificationDeliveryDelivered(delivery.event.id, delivery.deviceId);
+				else {
+					const error = expoError(result);
+					if (result.details?.error === "DeviceNotRegistered") disableNotificationDeviceForPushToken(delivery.pushToken);
+					markNotificationDeliveryDead(delivery.event.id, delivery.deviceId, error);
+				}
+			}
+		} catch (err) {
+			for (const delivery of withTickets) this.retryOrFail(delivery, err, "accepted");
+		}
+	}
+	retryOrFail(delivery, error, status = "pending") {
+		const message = error instanceof Error ? error.message : String(error);
+		if (delivery.attempts + 1 >= MAX_DELIVERY_ATTEMPTS) {
+			markNotificationDeliveryDead(delivery.event.id, delivery.deviceId, message);
+			log.warn({
+				eventId: delivery.event.id,
+				deviceId: delivery.deviceId,
+				errorMessage: message
+			}, `Notification delivery exhausted retries: ${message}`);
+			return;
+		}
+		rescheduleNotificationDelivery(delivery.event.id, delivery.deviceId, status, retryAt(delivery.attempts, Date.now()), message);
+	}
+};
+//#endregion
+export { NotificationService };

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

@@ -0,0 +1,53 @@
+import { type ProductNotification } from '@xopcai/gateway-contract';
+export type NotificationDelivery = {
+    event: ProductNotification;
+    deviceId: string;
+    pushToken: string;
+    locale: 'en' | 'zh';
+    attempts: number;
+    providerTicketId?: string;
+};
+export declare function createNotificationEvent(input: {
+    dedupeKey: string;
+    notification: Omit<ProductNotification, 'id' | 'createdAt' | 'schemaVersion'>;
+    deviceIds: string[];
+    createdAt?: number;
+}): {
+    notification: ProductNotification;
+    created: boolean;
+};
+export declare function listNotificationEvents(options?: {
+    afterId?: string;
+    since?: number;
+    limit?: number;
+}): {
+    items: ProductNotification[];
+    nextCursor: string | null;
+};
+export declare function acknowledgeNotification(eventId: string, consumerId: string, surface: 'web' | 'electron' | 'mobile'): boolean;
+export declare function listDueNotificationDeliveries(status: 'pending' | 'accepted', now?: number, limit?: number): NotificationDelivery[];
+export declare function markNotificationDeliveryAccepted(eventId: string, deviceId: string, ticketId: string, receiptAt: number): void;
+export declare function markNotificationDeliveryDelivered(eventId: string, deviceId: string): void;
+export declare function markNotificationDeliveryDead(eventId: string, deviceId: string, error: string): void;
+export declare function rescheduleNotificationDelivery(eventId: string, deviceId: string, status: 'pending' | 'accepted', nextAttemptAt: number, error: string): void;
+export declare function notificationDeliveryMetrics(): {
+    pending: number;
+    accepted: number;
+    delivered: number;
+    dead: number;
+    due: number;
+    devices: {
+        deliverable: number;
+        expired: number;
+        disabled: number;
+    };
+    oldestPendingAt: number | null;
+    latestError: {
+        eventId: string;
+        deviceId: string;
+        message: string;
+        updatedAt: number;
+    } | null;
+};
+export declare function expireUndeliverableNotificationDeliveries(now?: number): number;
+export declare function pruneNotificationEvents(before: number): number;

package/dist/src/notifications/store.js

@@ -0,0 +1,184 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { ProductNotificationSchema } from "../../packages/gateway-contract/src/notifications.js";
+import { randomUUID } from "node:crypto";
+//#region src/notifications/store.ts
+function parseJson(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+function eventFromRow(row) {
+	return ProductNotificationSchema.parse({
+		schemaVersion: 1,
+		id: row.event_id,
+		type: row.event_type,
+		target: parseJson(row.target_json),
+		priority: row.priority,
+		title: {
+			en: row.title_en,
+			zh: row.title_zh
+		},
+		...row.body_en && row.body_zh ? { body: {
+			en: row.body_en,
+			zh: row.body_zh
+		} } : {},
+		payload: parseJson(row.payload_json),
+		createdAt: row.created_at
+	});
+}
+function deliveryFromRow(row) {
+	return {
+		event: eventFromRow(row),
+		deviceId: row.device_id,
+		pushToken: row.push_token,
+		locale: row.locale === "zh" ? "zh" : "en",
+		attempts: row.attempts,
+		...row.provider_ticket_id ? { providerTicketId: row.provider_ticket_id } : {}
+	};
+}
+function createNotificationEvent(input) {
+	const id = randomUUID();
+	const createdAt = input.createdAt ?? Date.now();
+	const created = runSqliteWriteTransaction((db) => {
+		const inserted = db.prepare(`INSERT OR IGNORE INTO notification_events (
+        event_id, dedupe_key, event_type, target_json, priority,
+        title_en, title_zh, body_en, body_zh, payload_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.dedupeKey, input.notification.type, JSON.stringify(input.notification.target), input.notification.priority, input.notification.title.en, input.notification.title.zh, input.notification.body?.en ?? null, input.notification.body?.zh ?? null, JSON.stringify(input.notification.payload), createdAt).changes > 0;
+		if (inserted) {
+			const enqueue = db.prepare(`INSERT INTO notification_deliveries (
+          event_id, device_id, status, next_attempt_at, updated_at
+        ) VALUES (?, ?, 'pending', ?, ?)`);
+			for (const deviceId of input.deviceIds) enqueue.run(id, deviceId, createdAt, createdAt);
+		}
+		return inserted;
+	});
+	return {
+		notification: eventFromRow(getSqliteDatabase().prepare("SELECT * FROM notification_events WHERE dedupe_key = ?").get(input.dedupeKey)),
+		created
+	};
+}
+function listNotificationEvents(options = {}) {
+	const limit = Math.max(1, Math.min(100, options.limit ?? 50));
+	const after = options.afterId ? getSqliteDatabase().prepare("SELECT created_at, event_id FROM notification_events WHERE event_id = ?").get(options.afterId) : void 0;
+	const items = (after ? getSqliteDatabase().prepare(`SELECT * FROM notification_events
+       WHERE created_at > ? OR (created_at = ? AND event_id > ?)
+       ORDER BY created_at, event_id LIMIT ?`).all(after.created_at, after.created_at, after.event_id, limit) : getSqliteDatabase().prepare(`SELECT * FROM notification_events WHERE created_at >= ?
+       ORDER BY created_at, event_id LIMIT ?`).all(options.since ?? Date.now(), limit)).map(eventFromRow);
+	return {
+		items,
+		nextCursor: items.at(-1)?.id ?? null
+	};
+}
+function acknowledgeNotification(eventId, consumerId, surface) {
+	if (!getSqliteDatabase().prepare("SELECT 1 FROM notification_events WHERE event_id = ?").get(eventId)) return false;
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`INSERT INTO notification_acknowledgements (
+        event_id, consumer_id, surface, acknowledged_at
+      ) VALUES (?, ?, ?, ?)
+      ON CONFLICT(event_id, consumer_id) DO UPDATE SET
+        surface = excluded.surface,
+        acknowledged_at = excluded.acknowledged_at`).run(eventId, consumerId, surface, Date.now());
+	});
+	return true;
+}
+const DELIVERY_JOIN = `
+  SELECT e.*, d.device_id, d.attempts, d.provider_ticket_id,
+         n.push_token, n.locale
+  FROM notification_deliveries d
+  JOIN notification_events e ON e.event_id = d.event_id
+  JOIN notification_devices n ON n.device_id = d.device_id
+`;
+function listDueNotificationDeliveries(status, now = Date.now(), limit = 100) {
+	return getSqliteDatabase().prepare(`${DELIVERY_JOIN}
+     WHERE d.status = ? AND d.next_attempt_at <= ?
+       AND n.enabled = 1 AND n.permissions = 'granted' AND n.lease_expires_at > ?
+     ORDER BY d.next_attempt_at LIMIT ?`).all(status, now, now, Math.max(1, Math.min(1e3, limit))).map(deliveryFromRow);
+}
+function markNotificationDeliveryAccepted(eventId, deviceId, ticketId, receiptAt) {
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE notification_deliveries
+       SET status = 'accepted', attempts = attempts + 1, provider_ticket_id = ?,
+           next_attempt_at = ?, last_error = NULL, updated_at = ?
+       WHERE event_id = ? AND device_id = ?`).run(ticketId, receiptAt, Date.now(), eventId, deviceId);
+	});
+}
+function markNotificationDeliveryDelivered(eventId, deviceId) {
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE notification_deliveries
+       SET status = 'delivered', last_error = NULL, updated_at = ?
+       WHERE event_id = ? AND device_id = ?`).run(Date.now(), eventId, deviceId);
+	});
+}
+function markNotificationDeliveryDead(eventId, deviceId, error) {
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE notification_deliveries
+       SET status = 'dead', attempts = attempts + 1, last_error = ?, updated_at = ?
+       WHERE event_id = ? AND device_id = ?`).run(error.slice(0, 500), Date.now(), eventId, deviceId);
+	});
+}
+function rescheduleNotificationDelivery(eventId, deviceId, status, nextAttemptAt, error) {
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`UPDATE notification_deliveries
+       SET status = ?, attempts = attempts + 1, next_attempt_at = ?, last_error = ?, updated_at = ?
+       WHERE event_id = ? AND device_id = ?`).run(status, nextAttemptAt, error.slice(0, 500), Date.now(), eventId, deviceId);
+	});
+}
+function notificationDeliveryMetrics() {
+	const rows = getSqliteDatabase().prepare("SELECT status, COUNT(*) AS count FROM notification_deliveries GROUP BY status").all();
+	const counts = Object.fromEntries(rows.map((row) => [row.status, row.count]));
+	const now = Date.now();
+	const due = getSqliteDatabase().prepare(`SELECT COUNT(*) AS count FROM notification_deliveries
+     WHERE status IN ('pending', 'accepted') AND next_attempt_at <= ?`).get(now);
+	const devices = getSqliteDatabase().prepare(`SELECT
+       SUM(CASE WHEN enabled = 1 AND permissions = 'granted' AND lease_expires_at > ? THEN 1 ELSE 0 END) AS deliverable,
+       SUM(CASE WHEN enabled = 1 AND lease_expires_at <= ? THEN 1 ELSE 0 END) AS expired,
+       SUM(CASE WHEN enabled = 0 OR permissions <> 'granted' THEN 1 ELSE 0 END) AS disabled
+     FROM notification_devices`).get(now, now);
+	const oldest = getSqliteDatabase().prepare(`SELECT MIN(next_attempt_at) AS value FROM notification_deliveries
+     WHERE status IN ('pending', 'accepted')`).get();
+	const latestError = getSqliteDatabase().prepare(`SELECT event_id, device_id, last_error, updated_at
+     FROM notification_deliveries WHERE last_error IS NOT NULL
+     ORDER BY updated_at DESC LIMIT 1`).get();
+	return {
+		pending: counts.pending ?? 0,
+		accepted: counts.accepted ?? 0,
+		delivered: counts.delivered ?? 0,
+		dead: counts.dead ?? 0,
+		due: due.count,
+		devices: {
+			deliverable: devices.deliverable ?? 0,
+			expired: devices.expired ?? 0,
+			disabled: devices.disabled ?? 0
+		},
+		oldestPendingAt: oldest.value,
+		latestError: latestError ? {
+			eventId: latestError.event_id,
+			deviceId: latestError.device_id,
+			message: latestError.last_error,
+			updatedAt: latestError.updated_at
+		} : null
+	};
+}
+function expireUndeliverableNotificationDeliveries(now = Date.now()) {
+	return Number(runSqliteWriteTransaction((db) => db.prepare(`UPDATE notification_deliveries
+     SET status = 'dead', last_error = 'Device registration is disabled or expired', updated_at = ?
+     WHERE status IN ('pending', 'accepted')
+       AND EXISTS (
+         SELECT 1 FROM notification_devices n
+         WHERE n.device_id = notification_deliveries.device_id
+           AND (n.enabled = 0 OR n.permissions <> 'granted' OR n.lease_expires_at <= ?)
+       )`).run(now, now).changes));
+}
+function pruneNotificationEvents(before) {
+	return Number(runSqliteWriteTransaction((db) => db.prepare(`DELETE FROM notification_events
+     WHERE created_at < ?
+       AND NOT EXISTS (
+         SELECT 1 FROM notification_deliveries d
+         WHERE d.event_id = notification_events.event_id
+           AND d.status IN ('pending', 'accepted')
+       )`).run(before).changes));
+}
+//#endregion
+export { acknowledgeNotification, createNotificationEvent, expireUndeliverableNotificationDeliveries, listDueNotificationDeliveries, listNotificationEvents, markNotificationDeliveryAccepted, markNotificationDeliveryDead, markNotificationDeliveryDelivered, notificationDeliveryMetrics, pruneNotificationEvents, rescheduleNotificationDelivery };

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

@@ -0,0 +1,29 @@
+export type NotificationDevicePlatform = 'ios' | 'android';
+export type NotificationPermission = 'granted' | 'denied' | 'unknown';
+export type NotificationLanguage = 'en' | 'zh';
+export type NotificationPreferences = {
+    chatCompleted: boolean;
+    chatFailed: boolean;
+    taskNeedsInput: boolean;
+    taskBlocked: boolean;
+    taskFailed: boolean;
+    taskCompleted: boolean;
+    automationCompleted: boolean;
+    automationFailed: boolean;
+    proactiveInsight: boolean;
+};
+export type NotificationDevice = {
+    id: string;
+    platform: NotificationDevicePlatform;
+    pushToken: string;
+    enabled: boolean;
+    permissions: NotificationPermission;
+    preferences: NotificationPreferences;
+    locale: NotificationLanguage;
+    appVersion?: string;
+    leaseExpiresAt: number;
+    lastSeenAt: number;
+    createdAt: number;
+    updatedAt: number;
+};
+export declare const DEFAULT_NOTIFICATION_PREFERENCES: NotificationPreferences;

package/dist/src/notifications/types.js

@@ -0,0 +1,14 @@
+//#region src/notifications/types.ts
+const DEFAULT_NOTIFICATION_PREFERENCES = {
+	chatCompleted: true,
+	chatFailed: true,
+	taskNeedsInput: true,
+	taskBlocked: true,
+	taskFailed: true,
+	taskCompleted: false,
+	automationCompleted: false,
+	automationFailed: true,
+	proactiveInsight: true
+};
+//#endregion
+export { DEFAULT_NOTIFICATION_PREFERENCES };

package/dist/src/session/client-history.d.ts

@@ -1,3 +1,4 @@
+import { type TurnOutcome } from '@xopcai/gateway-contract';
 import type { Message } from './types.js';
 import type { TranscriptStoredRow } from './session-context-for-llm.js';
 /** Transcript row for TUI and HTTP clients (flattened from persisted session messages). */
@@ -13,7 +14,7 @@ export interface ClientHistoryMessage {
     timestamp?: number;
     /** Whitelisted display metadata; never includes source snapshot text. */
     metadata?: {
-        sourceContexts: Array<{
+        sourceContexts?: Array<{
             kind: 'note';
             sourceId: string;
             version: string;
@@ -21,6 +22,7 @@ export interface ClientHistoryMessage {
             tokenEstimate?: number;
             truncated?: boolean;
         }>;
+        turnOutcome?: TurnOutcome;
     };
     kind?: 'message' | 'compaction' | 'context' | 'bash' | 'custom' | 'branch';
     tokensBefore?: number;

package/dist/src/session/client-history.js

@@ -1,3 +1,4 @@
+import { parseTurnOutcome } from "../../packages/gateway-contract/src/turn-outcome.js";
 import { stripRuntimeContextFromUserMessage } from "./user-message-display.js";
 import { buildTranscriptOutline } from "./transcript-outline.js";
 //#region src/session/client-history.ts
@@ -286,6 +287,18 @@ function customStateRowToClientHistory(row) {
 	if (r.type !== "custom") return null;
 	const customType = optionalString(r.customType)?.trim();
 	if (!customType) return null;
+	if (customType === "turn_outcome") {
+		const outcome = parseTurnOutcome(r.data);
+		if (!outcome) return null;
+		return {
+			role: "assistant",
+			kind: "message",
+			turnId: outcome.turnId,
+			content: "",
+			timestamp: parseTimestampValue(typeof r.timestamp === "string" || typeof r.timestamp === "number" ? r.timestamp : void 0),
+			metadata: { turnOutcome: outcome }
+		};
+	}
 	return {
 		role: "system",
 		kind: "custom",