@xopcai/xopc 0.0.227 → 0.0.229

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",

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

@@ -1,7 +1,7 @@
 export { SessionIndex, type SessionIndexConfig } from './manager.js';
 export { onSessionTranscriptUpdate, emitSessionTranscriptUpdate, type SessionTranscriptUpdate, } from './transcript-events.js';
 export { SessionStore } from './store.js';
-export type { SessionStoreOptions } from './store.js';
+export type { SessionStoreOptions, ForkSessionAtTurnOptions, ForkSessionResult, } from './store.js';
 export { SessionConfigStore, resolveThinkingLevel, resolveReasoningLevel, resolveVerboseLevel } from './config-store.js';
 export { DEFAULT_ACTIVITY_DETAIL_LEVEL, resolveConfiguredActivityDetailDefault, resolveEffectiveThinkingLevel, resolveEffectiveReasoningLevel, } from './thinking-resolve.js';
 export type { SessionAgentConfig } from './config-types.js';

package/dist/src/session/manager.d.ts

@@ -89,6 +89,7 @@ export declare class SessionIndex extends EventEmitter {
         sessionKey: string;
         rowCount: number;
     }>;
+    forkSessionAtTurn(sourceKey: string, options: import('./store.js').ForkSessionAtTurnOptions): Promise<import('./store.js').ForkSessionResult>;
     getStats(): Promise<GlobalSessionStats>;
     archiveOldSessions(olderThanDays: number): Promise<number>;
     onSessionCreated(callback: (metadata: SessionMetadata) => void): void;

package/dist/src/session/manager.js

@@ -171,6 +171,12 @@ var SessionIndex = class extends EventEmitter$1 {
 		if (metadata) this.emit("sessionCreated", metadata);
 		return result;
 	}
+	async forkSessionAtTurn(sourceKey, options) {
+		const result = await this.store.forkSessionAtTurn(sourceKey, options);
+		const metadata = await this.store.getMetadata(result.sessionKey);
+		if (metadata) this.emit("sessionCreated", metadata);
+		return result;
+	}
 	async getStats() {
 		return this.store.getStats();
 	}

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

@@ -27,6 +27,16 @@ export interface SessionCompactionHooks {
     }) => Promise<void> | void;
 }
 export type ModelFallbackPreparation = 'prompt' | 'resume' | 'unsafe';
+export interface ForkSessionAtTurnOptions {
+    targetKey: string;
+    lastTurnId: string;
+    targetMetadata: SessionMetadataSeed;
+}
+export interface ForkSessionResult {
+    sessionKey: string;
+    rowCount: number;
+    lastTurnId?: string;
+}
 export declare class SessionStore {
     private options;
     private window;
@@ -182,6 +192,11 @@ export declare class SessionStore {
         sessionKey: string;
         rowCount: number;
     }>;
+    /**
+     * Atomically copy a completed turn prefix into a new session, including the
+     * source session's per-session agent configuration.
+     */
+    forkSessionAtTurn(sourceKey: string, options: ForkSessionAtTurnOptions): Promise<ForkSessionResult>;
     getStats(): Promise<GlobalSessionStats>;
     archiveOld(olderThanDays: number): Promise<number>;
     estimateTokens(messages: AgentMessage[]): number;

package/dist/src/session/store.js

@@ -2,12 +2,14 @@ import { init_paths_state, resolveStateDir } from "../config/paths-state.js";
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { requireXopcDatabase } from "../storage/sqlite/connection.js";
+import { runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
 import { buildSessionContextForLlm, buildSessionDisplayMessages, isRuntimeOnlyTranscriptMessage, isTranscriptCompactionEntry, mergeLlmMessagesPreservingContextRows, transcriptRowsFromJsonArray } from "./session-context-for-llm.js";
 import "./types.js";
 import { init_agent_session_key, resolveAgentIdFromSessionKey } from "../routing/agent-session-key.js";
 import { estimateTokensFromMessages } from "../storage/sqlite/row-mappers.js";
 import { deleteSessionRecord, ensureSessionRecord, findSessionKeyBySessionId, getGlobalSessionStats, getSessionMetadata, listSessionMetadata, listSessionsByAgent, patchSessionMetadata, resetSessionRecord } from "../storage/sqlite/session-repository.js";
 import { appendCompactionBoundaryIfUnchanged, appendTranscriptEntry, listCompactionBoundaries, loadCompactionSourceSnapshot, loadLlmMessagesForSession, loadTranscriptHistoryRowsForSession, loadTranscriptRowsForSession, paginateTranscriptMessages, replaceTranscriptRows, restoreBeforeCompactionBoundary, searchSessionTranscript } from "../storage/sqlite/transcript-repository.js";
+import { getSessionConfig, setSessionConfig } from "../storage/sqlite/config-repository.js";
 import "../storage/sqlite/index.js";
 import { resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { readPostCompactionContext } from "../agent/reply/post-compaction-context.js";
@@ -657,6 +659,62 @@ var SessionStore = class {
 			};
 		});
 	}
+	/**
+	* Atomically copy a completed turn prefix into a new session, including the
+	* source session's per-session agent configuration.
+	*/
+	async forkSessionAtTurn(sourceKey, options) {
+		requireXopcDatabase();
+		const targetKey = options.targetKey.trim();
+		const lastTurnId = options.lastTurnId.trim();
+		if (!targetKey) throw new Error("Target session key is required");
+		if (!lastTurnId) throw new Error("lastTurnId is required");
+		return runSqliteWriteTransaction(() => {
+			const sourceMetadata = getSessionMetadata(sourceKey);
+			if (!sourceMetadata) throw new Error(`Session not found: ${sourceKey}`);
+			if (getSessionMetadata(targetKey)) throw new Error(`Target session already exists: ${targetKey}`);
+			const rows = loadTranscriptHistoryRowsForSession(sourceKey);
+			let lastTurnRow = -1;
+			let hasAssistantOutput = false;
+			for (let index = 0; index < rows.length; index += 1) {
+				const row = rows[index];
+				if (row.turnId !== lastTurnId) continue;
+				lastTurnRow = index;
+				if (row.role === "assistant") hasAssistantOutput = true;
+			}
+			if (lastTurnRow < 0 || !hasAssistantOutput) throw new Error(`Completed turn not found: ${lastTurnId}`);
+			const selectedRows = rows.slice(0, lastTurnRow + 1);
+			const sourceLabel = sourceMetadata.name?.trim() || sourceKey;
+			const forkedAt = (/* @__PURE__ */ new Date()).toISOString();
+			const cwd = sourceMetadata.cwd?.trim() || this.resolveWorkspaceCwd(targetKey);
+			ensureSessionRecord(targetKey, cwd, {
+				...options.targetMetadata,
+				name: `Fork of ${sourceLabel}`,
+				tags: [...new Set([...sourceMetadata.tags ?? [], "fork"])],
+				projectId: sourceMetadata.projectId,
+				parentSessionKey: sourceKey,
+				hiddenFromSessionList: false,
+				customData: {
+					...sourceMetadata.customData ?? {},
+					...options.targetMetadata.customData ?? {},
+					genericNewChatShell: false,
+					forkedFromSessionKey: sourceKey,
+					forkedFromSessionId: sourceMetadata.sessionId,
+					forkedFromSessionName: sourceMetadata.name,
+					forkedFromTurnId: lastTurnId,
+					forkedAt
+				}
+			});
+			replaceTranscriptRows(targetKey, selectedRows);
+			const sourceConfig = getSessionConfig(sourceKey);
+			if (sourceConfig) setSessionConfig(targetKey, sourceConfig, cwd);
+			return {
+				sessionKey: targetKey,
+				rowCount: selectedRows.length,
+				lastTurnId
+			};
+		});
+	}
 	async getStats() {
 		requireXopcDatabase();
 		return getGlobalSessionStats();

package/dist/src/storage/sqlite/index.d.ts

@@ -9,9 +9,9 @@ export { claimContextExtractionRun, finishContextExtractionRun, getContextExtrac
 export { closeTemporalAssertions, createTemporalAssertion, linkContextObjects, listContextObjectRelations, listTemporalAssertions, type ContextObjectRelation, type ContextTemporalAssertion, } from './context-relation-repository.js';
 export { finishContextConsolidationRun, getContextConsolidationRun, listContextConsolidationDecisions, listContextConsolidationRuns, recordContextConsolidationDecision, startContextConsolidationRun, type ContextConsolidationDecision, type ContextConsolidationRun, } from './context-consolidation-repository.js';
 export { summarizeUnderstandingFeedback, summarizeUserUnderstandingQuality, type UnderstandingFeedbackSummary, type UserUnderstandingQualityMetrics, } from './user-context-quality-repository.js';
-export { createCollaborationRule, createContextEvidence, createUnderstanding, closeUnderstandingValidity, consumeContextConsent, deleteCollaborationRule, deleteUnderstanding, decideContextConsent, ensureContextConsent, getCollaborationRule, getTurnPersonalization, getUnderstanding, getUserProfile, hasContextConsent, isUnderstandingSuppressed, listCollaborationRules, listUnderstandingEvidence, listUnderstandings, linkUnderstandingEvidence, recordContextFeedback, recordContextRun, rejectUnderstanding, reviseCollaborationRule, reviseUnderstanding, searchActiveUnderstandings, setCollaborationRuleStatus, setUnderstandingStatus, updateUserProfile, type CreateUnderstandingInput, } from './user-context-repository.js';
+export { createCollaborationRule, createContextEvidence, createUnderstanding, closeUnderstandingValidity, consumeContextConsent, deleteCollaborationRule, deleteUnderstanding, decideContextConsent, ensureContextConsent, getCollaborationRule, getTurnPersonalization, getUnderstanding, getUserProfile, hasContextConsent, isUnderstandingSuppressed, listCollaborationRules, listUnderstandingEvidence, listUnderstandingStatusEvents, listUnderstandings, linkUnderstandingEvidence, recordContextFeedback, recordContextRun, rejectUnderstanding, reviseCollaborationRule, reviseUnderstanding, searchActiveUnderstandings, setCollaborationRuleStatus, setUnderstandingStatus, updateUserProfile, type CreateUnderstandingInput, type UnderstandingStatusEvent, } from './user-context-repository.js';
 export { getUserPerson, getUserPeopleIndexState, listUserPeople, mergeUserPeople, replaceUserPeopleIndex, summarizeUserPeople, updateUserPerson, } from './user-people-repository.js';
-export { cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputState, getSessionInputById, insertSessionInput, mutateQueuedSessionInput, recoverSessionInputState, setSessionInputStatus, type SessionInput, type SessionInputDelivery, type SessionInputState, type SessionInputStatus, } from './session-input-repository.js';
+export { cancelQueuedSessionInput, claimNextSessionInput, findSessionInput, finishSessionInputRun, getSessionInputState, getSessionInputById, insertSessionInput, listActiveSessionInputRuns, mutateQueuedSessionInput, recoverSessionInputState, setSessionInputStatus, type SessionInput, type SessionInputDelivery, type SessionInputState, type SessionInputStatus, } from './session-input-repository.js';
 export { replaceLatestSessionTurnAndQueueInput, validateLatestSessionTurnTarget, type ReplaceLatestSessionTurnInput, type ReplaceLatestSessionTurnResult, } from './session-turn-replace-repository.js';
 export { acknowledgeHomeAttention, isHomeAttentionAcknowledged, type HomeAttentionSubjectKind, } from './home-attention-repository.js';
 export { claimNextConnectorLearningJob, enqueueConnectorLearningJob, listConnectorLearningJobs, recoverStaleConnectorLearningJobs, setConnectorLearningPaused, updateConnectorLearningJob, type ConnectorLearningJob, type ConnectorLearningMode, type ConnectorLearningPhase, type ConnectorLearningStatus, } from './connector-learning-repository.js';