@xopcai/xopc 0.0.227 → 0.0.229

package/dist/src/history/ctx/format.js

@@ -0,0 +1,282 @@
+import { createHash } from "node:crypto";
+//#region src/history/ctx/format.ts
+const CTX_HISTORY_SCHEMA_VERSION = "ctx-history-jsonl-v2";
+const CTX_PROVIDER_KEY = "xopc";
+const CTX_SOURCE_ID = "default";
+const CTX_SOURCE_FORMAT = "xopc-session-history-v1";
+const EVENT_INDEX_STRIDE = 65536;
+const MAX_TEXT_CHUNK_BYTES = 1024 * 1024;
+const MAX_JSONL_LINE_BYTES = 16 * 1024 * 1024;
+function asRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+	return typeof value === "string" ? value : void 0;
+}
+function timestamp(value, label) {
+	const date = new Date(value);
+	if (!Number.isFinite(value) || Number.isNaN(date.getTime())) throw new Error(`Invalid ${label}: ${String(value)}`);
+	return date.toISOString();
+}
+function stringifyValue(value) {
+	if (typeof value === "string") return value;
+	if (value === void 0) return "";
+	return JSON.stringify(value) ?? "";
+}
+function textParts(content) {
+	if (typeof content === "string") return content.length > 0 ? [content] : [];
+	if (!Array.isArray(content)) return [];
+	return content.flatMap((block) => {
+		const record = asRecord(block);
+		return record?.type === "text" && typeof record.text === "string" && record.text.length > 0 ? [record.text] : [];
+	});
+}
+function outputText(output) {
+	if (typeof output === "string") return output;
+	return textParts(output).join("");
+}
+function toolCallDetails(block) {
+	const toolName = stringValue(block.name);
+	if (!toolName) return null;
+	const toolCallId = stringValue(block.id);
+	const argumentsText = stringifyValue(block.arguments);
+	return {
+		eventType: "tool_call",
+		role: "assistant",
+		text: argumentsText ? `${toolName} ${argumentsText}` : toolName,
+		details: {
+			tool_name: toolName,
+			...toolCallId ? { tool_call_id: toolCallId } : {}
+		}
+	};
+}
+function normalizeAssistant(row) {
+	if (typeof row.content === "string") return row.content.length > 0 ? [{
+		eventType: "message",
+		role: "assistant",
+		text: row.content
+	}] : [];
+	if (!Array.isArray(row.content)) return [];
+	const events = [];
+	for (const block of row.content) {
+		const record = asRecord(block);
+		if (!record) continue;
+		if (record.type === "text" && typeof record.text === "string" && record.text.length > 0) {
+			events.push({
+				eventType: "message",
+				role: "assistant",
+				text: record.text
+			});
+			continue;
+		}
+		if (record.type === "toolCall") {
+			const event = toolCallDetails(record);
+			if (event) events.push(event);
+		}
+	}
+	return events;
+}
+function normalizeToolResult(row) {
+	const text = textParts(row.content).join("");
+	if (!text) return [];
+	const toolName = stringValue(row.toolName);
+	const toolCallId = stringValue(row.toolCallId);
+	return [{
+		eventType: "tool_output",
+		role: "tool",
+		text,
+		details: {
+			...toolName ? { tool_name: toolName } : {},
+			...toolCallId ? { tool_call_id: toolCallId } : {},
+			...typeof row.isError === "boolean" ? { is_error: row.isError } : {}
+		}
+	}];
+}
+function normalizeBashExecution(row) {
+	const command = stringValue(row.command);
+	if (!command) return [];
+	const events = [{
+		eventType: "command_started",
+		role: "user",
+		text: command
+	}];
+	const output = outputText(row.output);
+	if (output) events.push({
+		eventType: "command_output",
+		role: "tool",
+		text: output
+	});
+	events.push({
+		eventType: "command_finished",
+		role: "tool",
+		text: row.exitCode == null ? "Command finished" : `Command exited with code ${String(row.exitCode)}`,
+		details: {
+			...typeof row.exitCode === "number" ? { exit_code: row.exitCode } : {},
+			...typeof row.signal === "string" ? { signal: row.signal } : {},
+			...typeof row.truncated === "boolean" ? { truncated: row.truncated } : {}
+		}
+	});
+	return events;
+}
+function normalizeStoredRow(row) {
+	if (row.kind === "context" || row.role === "system") return [];
+	if (row.type === "compaction" && typeof row.summary === "string" && row.summary.length > 0) return [{
+		eventType: "summary",
+		role: "assistant",
+		text: row.summary
+	}];
+	if ((row.role === "branchSummary" || row.role === "compactionSummary") && typeof row.summary === "string" && row.summary.length > 0) return [{
+		eventType: "summary",
+		role: "assistant",
+		text: row.summary
+	}];
+	if (row.role === "bashExecution") return normalizeBashExecution(row);
+	if (row.role === "custom" || row.type === "custom_message") {
+		if (row.display === false) return [];
+		return textParts(row.content).map((text) => ({
+			eventType: "message",
+			role: "user",
+			text
+		}));
+	}
+	if (row.role === "user") return textParts(row.content).map((text) => ({
+		eventType: "message",
+		role: "user",
+		text
+	}));
+	if (row.role === "assistant") return normalizeAssistant(row);
+	if (row.role === "toolResult" || row.role === "tool") return normalizeToolResult(row);
+	return [];
+}
+function splitTextByUtf8Bytes(text) {
+	if (Buffer.byteLength(text, "utf8") <= MAX_TEXT_CHUNK_BYTES) return [text];
+	const chunks = [];
+	let start = 0;
+	while (start < text.length) {
+		let low = start + 1;
+		let high = text.length;
+		let end = low;
+		while (low <= high) {
+			const middle = Math.floor((low + high) / 2);
+			if (Buffer.byteLength(text.slice(start, middle), "utf8") <= MAX_TEXT_CHUNK_BYTES) {
+				end = middle;
+				low = middle + 1;
+			} else high = middle - 1;
+		}
+		const previous = text.charCodeAt(end - 1);
+		const next = text.charCodeAt(end);
+		if (previous >= 55296 && previous <= 56319 && next >= 56320 && next <= 57343) end -= 1;
+		chunks.push(text.slice(start, end));
+		start = end;
+	}
+	return chunks;
+}
+function stableEventId(sessionId, entryId, eventOffset) {
+	return `xopc:${createHash("sha256").update(sessionId).update("\0").update(entryId).update("\0").update(String(eventOffset)).digest("hex")}`;
+}
+function serializeRecord(record) {
+	const line = JSON.stringify(record);
+	const size = Buffer.byteLength(line, "utf8");
+	if (size > MAX_JSONL_LINE_BYTES) throw new Error(`ctx history record exceeds 16 MiB (${size} bytes)`);
+	return line;
+}
+function sessionRecord(session) {
+	const active = session.status === "active";
+	return {
+		record_type: "session",
+		source_id: CTX_SOURCE_ID,
+		provider_session_id: session.sessionId,
+		started_at: timestamp(session.createdAt, `session timestamp for ${session.sessionId}`),
+		external_agent_id: session.agentId,
+		cwd: session.cwd,
+		...session.archivedAt === null ? {} : { ended_at: timestamp(session.archivedAt, `session end timestamp for ${session.sessionId}`) },
+		status: active ? "active" : "completed",
+		agent_scope: session.sessionType === "workflow-subagent" ? "subagent" : "primary"
+	};
+}
+function entryRecords(session, entry) {
+	let parsed;
+	try {
+		parsed = JSON.parse(entry.payloadJson);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Invalid transcript payload for entry ${entry.entryId}: ${message}`);
+	}
+	const row = asRecord(parsed);
+	if (!row) throw new Error(`Transcript payload for entry ${entry.entryId} is not an object`);
+	const occurredAt = timestamp(entry.createdAt, `entry timestamp for ${entry.entryId}`);
+	const records = [];
+	let offset = 0;
+	for (const event of normalizeStoredRow(row)) {
+		const chunks = splitTextByUtf8Bytes(event.text);
+		for (let chunkIndex = 0; chunkIndex < chunks.length; chunkIndex += 1) {
+			if (offset >= EVENT_INDEX_STRIDE) throw new Error(`Transcript entry ${entry.entryId} expands to too many ctx events`);
+			const eventIndex = entry.seq * EVENT_INDEX_STRIDE + offset;
+			if (!Number.isSafeInteger(eventIndex) || eventIndex < 0) throw new Error(`Transcript sequence is outside the supported range: ${entry.seq}`);
+			records.push({
+				record_type: "event",
+				source_id: CTX_SOURCE_ID,
+				provider_session_id: session.sessionId,
+				event_index: eventIndex,
+				event_id: stableEventId(session.sessionId, entry.entryId, offset),
+				occurred_at: occurredAt,
+				event_type: event.eventType,
+				...event.role ? { role: event.role } : {},
+				payload: {
+					text: chunks[chunkIndex],
+					...event.details,
+					...chunks.length > 1 ? {
+						chunk_index: chunkIndex,
+						chunk_count: chunks.length
+					} : {}
+				}
+			});
+			offset += 1;
+		}
+	}
+	return records;
+}
+function buildCtxHistoryJsonl(sessions) {
+	const lines = [serializeRecord({
+		record_type: "manifest",
+		schema_version: CTX_HISTORY_SCHEMA_VERSION,
+		producer: "xopc"
+	}), serializeRecord({
+		record_type: "source",
+		source_id: CTX_SOURCE_ID,
+		provider_key: CTX_PROVIDER_KEY,
+		source_format: CTX_SOURCE_FORMAT
+	})];
+	let eventCount = 0;
+	for (const session of sessions) {
+		lines.push(serializeRecord(sessionRecord(session)));
+		for (const entry of session.entries) {
+			const records = entryRecords(session, entry);
+			eventCount += records.length;
+			lines.push(...records.map(serializeRecord));
+		}
+	}
+	return {
+		contents: `${lines.join("\n")}\n`,
+		eventCount
+	};
+}
+function buildCtxPluginManifest() {
+	return `${JSON.stringify({
+		schema_version: 1,
+		name: "xopc",
+		display_name: "XOPC history",
+		version: "1.0.0",
+		history_sources: [{
+			id: CTX_SOURCE_ID,
+			provider_key: CTX_PROVIDER_KEY,
+			source_id: CTX_SOURCE_ID,
+			source_format: CTX_SOURCE_FORMAT,
+			path: "history.jsonl",
+			enabled: true,
+			refresh: "manual"
+		}]
+	}, null, 2)}\n`;
+}
+//#endregion
+export { CTX_HISTORY_SCHEMA_VERSION, CTX_PROVIDER_KEY, CTX_SOURCE_FORMAT, CTX_SOURCE_ID, buildCtxHistoryJsonl, buildCtxPluginManifest };

package/dist/src/knowledge/index.d.ts

@@ -1,6 +1,5 @@
 export * from './types.js';
 export * from './ingestion-service.js';
 export * from './connected-knowledge-pipeline.js';
-export * from './connected-understanding-pipeline.js';
 export * from './coordinator.js';
 export * from './local-folder-adapter.js';

package/dist/src/knowledge/index.js

@@ -1,6 +1,5 @@
 import { KnowledgeIngestionService, SqliteKnowledgeSourceStateStore } from "./ingestion-service.js";
 import { ConnectedKnowledgePipeline } from "./connected-knowledge-pipeline.js";
-import { ConnectedUnderstandingPipeline, deriveConnectedClaimObservations, renderConnectedObservation } from "./connected-understanding-pipeline.js";
 import { startConnectedKnowledgeCoordinator } from "./coordinator.js";
 import { LocalFolderKnowledgeSourceAdapter } from "./local-folder-adapter.js";
-export { ConnectedKnowledgePipeline, ConnectedUnderstandingPipeline, KnowledgeIngestionService, LocalFolderKnowledgeSourceAdapter, SqliteKnowledgeSourceStateStore, deriveConnectedClaimObservations, renderConnectedObservation, startConnectedKnowledgeCoordinator };
+export { ConnectedKnowledgePipeline, KnowledgeIngestionService, LocalFolderKnowledgeSourceAdapter, SqliteKnowledgeSourceStateStore, startConnectedKnowledgeCoordinator };

package/dist/src/media/session-references.d.ts

@@ -1,6 +1,12 @@
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
+export declare function collectMediaUrisFromValues(values: readonly unknown[]): Set<string>;
 export declare function collectMediaUrisFromMessages(messages: readonly AgentMessage[]): Set<string>;
 export declare function messagesReferenceMediaUri(messages: readonly AgentMessage[], uri: string): boolean;
+/**
+ * A media object remains live while any non-deleted session references it,
+ * including archived transcripts retained by a reset of that session key.
+ */
+export declare function isMediaUriReferencedByLiveSession(uri: string): boolean;
 export declare function deleteMediaUris(uris: Iterable<string>): Promise<void>;
 export declare function deleteMediaUrisNoLongerReferenced(params: {
     removed: readonly AgentMessage[];

package/dist/src/media/session-references.js

@@ -1,3 +1,5 @@
+import { getSqliteDatabase } from "../storage/sqlite/transaction.js";
+import "../storage/sqlite/index.js";
 import { tryParseMediaUri } from "./uri.js";
 import { deleteMediaBuffer } from "./store.js";
 //#region src/media/session-references.ts
@@ -19,19 +21,38 @@ function collectFromValue(value, out, seen) {
 	const record = value;
 	for (const nested of Object.values(record)) collectFromValue(nested, out, seen);
 }
-function collectMediaUrisFromMessages(messages) {
+function collectMediaUrisFromValues(values) {
 	const out = /* @__PURE__ */ new Set();
 	const seen = /* @__PURE__ */ new WeakSet();
-	for (const message of messages) collectFromValue(message, out, seen);
+	for (const value of values) collectFromValue(value, out, seen);
 	return out;
 }
+function collectMediaUrisFromMessages(messages) {
+	return collectMediaUrisFromValues(messages);
+}
 function messagesReferenceMediaUri(messages, uri) {
 	return collectMediaUrisFromMessages(messages).has(uri.trim());
 }
+/**
+* A media object remains live while any non-deleted session references it,
+* including archived transcripts retained by a reset of that session key.
+*/
+function isMediaUriReferencedByLiveSession(uri) {
+	const normalized = uri.trim();
+	if (!normalized) return false;
+	const escaped = JSON.stringify(normalized).replaceAll("\\", "\\\\").replaceAll("%", "\\%").replaceAll("_", "\\_");
+	return getSqliteDatabase().prepare(`SELECT 1 AS referenced
+       FROM transcript_entries e
+       JOIN transcripts t ON t.session_id = e.session_id
+       JOIN sessions s ON s.session_key = t.session_key
+       WHERE e.payload_json LIKE ? ESCAPE '\\'
+       LIMIT 1`).get(`%${escaped}%`)?.referenced === 1;
+}
 async function deleteMediaUris(uris) {
 	for (const uri of new Set(uris)) {
 		const parsed = tryParseMediaUri(uri);
 		if (!parsed) continue;
+		if (isMediaUriReferencedByLiveSession(uri)) continue;
 		await deleteMediaBuffer(parsed.id, parsed.bucket).catch(() => {});
 	}
 }
@@ -43,4 +64,4 @@ async function deleteMediaUrisNoLongerReferenced(params) {
 	await deleteMediaUris(removedUris);
 }
 //#endregion
-export { collectMediaUrisFromMessages, deleteMediaUris, deleteMediaUrisNoLongerReferenced, messagesReferenceMediaUri };
+export { collectMediaUrisFromMessages, collectMediaUrisFromValues, deleteMediaUris, deleteMediaUrisNoLongerReferenced, isMediaUriReferencedByLiveSession, messagesReferenceMediaUri };

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

@@ -0,0 +1,16 @@
+import { type NotificationDevice, type NotificationDevicePlatform, type NotificationLanguage, type NotificationPermission, type NotificationPreferences } from './types.js';
+export type RegisterNotificationDeviceInput = {
+    id: string;
+    platform: NotificationDevicePlatform;
+    pushToken: string;
+    permissions: NotificationPermission;
+    preferences?: Partial<NotificationPreferences>;
+    locale: NotificationLanguage;
+    appVersion?: string;
+};
+export declare function registerNotificationDevice(input: RegisterNotificationDeviceInput): NotificationDevice;
+export declare function getNotificationDevice(deviceId: string): NotificationDevice | null;
+export declare function listDeliverableNotificationDevices(now?: number): NotificationDevice[];
+export declare function updateNotificationDevicePreferences(deviceId: string, patch: Partial<NotificationPreferences>): NotificationDevice | null;
+export declare function removeNotificationDevice(deviceId: string): boolean;
+export declare function disableNotificationDeviceForPushToken(pushToken: string): void;

package/dist/src/notifications/device-store.js

@@ -0,0 +1,96 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { DEFAULT_NOTIFICATION_PREFERENCES } from "./types.js";
+//#region src/notifications/device-store.ts
+const DEVICE_LEASE_MS = 10080 * 60 * 1e3;
+function parsePreferences(raw) {
+	try {
+		const value = JSON.parse(raw);
+		return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+	} catch {
+		return {};
+	}
+}
+function normalizePreferences(input) {
+	return {
+		chatCompleted: input?.chatCompleted ?? DEFAULT_NOTIFICATION_PREFERENCES.chatCompleted,
+		chatFailed: input?.chatFailed ?? DEFAULT_NOTIFICATION_PREFERENCES.chatFailed,
+		taskNeedsInput: input?.taskNeedsInput ?? DEFAULT_NOTIFICATION_PREFERENCES.taskNeedsInput,
+		taskBlocked: input?.taskBlocked ?? DEFAULT_NOTIFICATION_PREFERENCES.taskBlocked,
+		taskFailed: input?.taskFailed ?? DEFAULT_NOTIFICATION_PREFERENCES.taskFailed,
+		taskCompleted: input?.taskCompleted ?? DEFAULT_NOTIFICATION_PREFERENCES.taskCompleted,
+		automationCompleted: input?.automationCompleted ?? DEFAULT_NOTIFICATION_PREFERENCES.automationCompleted,
+		automationFailed: input?.automationFailed ?? DEFAULT_NOTIFICATION_PREFERENCES.automationFailed,
+		proactiveInsight: input?.proactiveInsight ?? DEFAULT_NOTIFICATION_PREFERENCES.proactiveInsight
+	};
+}
+function deviceFromRow(row) {
+	return {
+		id: row.device_id,
+		platform: row.platform === "android" ? "android" : "ios",
+		pushToken: row.push_token,
+		enabled: row.enabled !== 0,
+		permissions: row.permissions === "granted" || row.permissions === "denied" ? row.permissions : "unknown",
+		preferences: normalizePreferences(parsePreferences(row.preferences_json)),
+		locale: row.locale === "zh" ? "zh" : "en",
+		appVersion: row.app_version ?? void 0,
+		leaseExpiresAt: row.lease_expires_at,
+		lastSeenAt: row.last_seen_at,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	};
+}
+function registerNotificationDevice(input) {
+	const now = Date.now();
+	const preferences = input.preferences ? normalizePreferences(input.preferences) : getNotificationDevice(input.id)?.preferences ?? normalizePreferences();
+	runSqliteWriteTransaction((db) => {
+		db.prepare(`DELETE FROM notification_devices
+       WHERE push_provider = 'expo' AND push_token = ? AND device_id <> ?`).run(input.pushToken, input.id);
+		db.prepare(`INSERT INTO notification_devices (
+        device_id, platform, push_token, enabled, permissions, preferences_json,
+        locale, app_version, lease_expires_at, last_seen_at, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(device_id) DO UPDATE SET
+        platform = excluded.platform,
+        push_token = excluded.push_token,
+        enabled = excluded.enabled,
+        permissions = excluded.permissions,
+        preferences_json = excluded.preferences_json,
+        locale = excluded.locale,
+        app_version = excluded.app_version,
+        lease_expires_at = excluded.lease_expires_at,
+        last_seen_at = excluded.last_seen_at,
+        updated_at = excluded.updated_at`).run(input.id, input.platform, input.pushToken, input.permissions === "granted" ? 1 : 0, input.permissions, JSON.stringify(preferences), input.locale, input.appVersion?.trim() || null, now + DEVICE_LEASE_MS, now, now, now);
+	});
+	return getNotificationDevice(input.id);
+}
+function getNotificationDevice(deviceId) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM notification_devices WHERE device_id = ?").get(deviceId);
+	return row ? deviceFromRow(row) : null;
+}
+function listDeliverableNotificationDevices(now = Date.now()) {
+	return getSqliteDatabase().prepare(`SELECT * FROM notification_devices
+     WHERE enabled = 1 AND permissions = 'granted' AND lease_expires_at > ?
+     ORDER BY updated_at DESC`).all(now).map(deviceFromRow);
+}
+function updateNotificationDevicePreferences(deviceId, patch) {
+	const current = getNotificationDevice(deviceId);
+	if (!current) return null;
+	const preferences = normalizePreferences({
+		...current.preferences,
+		...patch
+	});
+	runSqliteWriteTransaction((db) => {
+		db.prepare("UPDATE notification_devices SET preferences_json = ?, updated_at = ? WHERE device_id = ?").run(JSON.stringify(preferences), Date.now(), deviceId);
+	});
+	return getNotificationDevice(deviceId);
+}
+function removeNotificationDevice(deviceId) {
+	return runSqliteWriteTransaction((db) => db.prepare("DELETE FROM notification_devices WHERE device_id = ?").run(deviceId).changes > 0);
+}
+function disableNotificationDeviceForPushToken(pushToken) {
+	runSqliteWriteTransaction((db) => {
+		db.prepare("UPDATE notification_devices SET enabled = 0, updated_at = ? WHERE push_token = ?").run(Date.now(), pushToken);
+	});
+}
+//#endregion
+export { disableNotificationDeviceForPushToken, getNotificationDevice, listDeliverableNotificationDevices, registerNotificationDevice, removeNotificationDevice, updateNotificationDevicePreferences };

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

@@ -0,0 +1,6 @@
+import { type ProductNotification } from '@xopcai/gateway-contract';
+export type NotificationPlan = {
+    dedupeKey: string;
+    notification: Omit<ProductNotification, 'schemaVersion' | 'id' | 'createdAt'>;
+};
+export declare function notificationPlanFromGatewayEvent(type: string, payload: unknown): NotificationPlan | null;

package/dist/src/notifications/planner.js

@@ -0,0 +1,160 @@
+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) : "";
+	const responsePreview = completed && typeof event.responsePreview === "string" ? Array.from(event.responsePreview.trim()).slice(0, 180).join("") : "";
+	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: responsePreview ? {
+				en: responsePreview,
+				zh: responsePreview
+			} : 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;
+}