@xopcai/xopc 0.0.188 → 0.0.189

package/dist/src/tui/backends/{gateway-sse-backend.js → gateway-realtime-backend.js}

@@ -4,13 +4,15 @@ import { prependEnvelopeTimestamp } from "../../channels/envelope-timestamp.js";
 import { transcriptRowsToClientHistory } from "../../session/client-history.js";
 import { parseModelRef } from "../../agent/models/selection.js";
 import { gatewayCredentialAuthorization } from "../../gateway/credential.js";
-import { consumeSSEStream, parseSSEData } from "../sse-consumer.js";
+import { RealtimeClient } from "../../../packages/realtime-client/src/index.js";
 import { buildTuiTranscriptTree, transcriptTreeEntryIdToRowNumber } from "../tui-transcript-tree.js";
 import { computeTuiSessionStats } from "../tui-session-stats.js";
+import { createRequire } from "node:module";
 import crypto from "node:crypto";
-//#region src/tui/backends/gateway-sse-backend.ts
+//#region src/tui/backends/gateway-realtime-backend.ts
 init_logger();
-const log = createLogger("TUI:GatewaySSE");
+const log = createLogger("TUI:GatewayRealtime");
+const { WebSocket } = createRequire(import.meta.url)("ws");
 function normalizeGatewayModelChoice(model) {
 	const providerPrefix = `${model.provider}/`;
 	const id = model.id.startsWith(providerPrefix) ? model.id.slice(providerPrefix.length) : model.id;
@@ -19,19 +21,6 @@ function normalizeGatewayModelChoice(model) {
 		id
 	};
 }
-function isRecord(value) {
-	return !!value && typeof value === "object" && !Array.isArray(value);
-}
-function normalizeGatewaySseEvent(evt) {
-	if (evt.event !== "agent.stream" || !isRecord(evt.data)) return evt;
-	const inner = evt.data.event;
-	if (!isRecord(inner) || typeof inner.type !== "string" || !inner.type) return evt;
-	return {
-		event: inner.type,
-		data: inner,
-		source: evt.source
-	};
-}
 /** Fetch wrapper that adds auth headers. */
 async function gatewayFetch(baseUrl, path, credential, init) {
 	const authorization = gatewayCredentialAuthorization(credential);
@@ -46,16 +35,19 @@ async function gatewayFetch(baseUrl, path, credential, init) {
 	});
 }
 /**
-* TUI backend that communicates with a running xopc gateway via HTTP + SSE.
+* TUI backend that communicates with a running xopc gateway via REST + realtime WebSocket.
 *
-* - Agent input: durable session input REST plus resumable run SSE
-* - Broadcast events: `GET /api/events` via long-lived SSE
+* - Agent input: durable session input REST plus replayable run topics
+* - Broadcast events: gateway realtime topic
 * - REST calls for sessions, models, etc.
 */
-var GatewaySseBackend = class {
+var GatewayRealtimeBackend = class {
 	baseUrl;
 	credential;
-	eventAbort = null;
+	clientId = `tui-${crypto.randomUUID()}`;
+	realtime = null;
+	activeRunId = null;
+	observedSessionKey = null;
 	chatAbort = null;
 	onEvent;
 	onConnected;
@@ -69,11 +61,13 @@ var GatewaySseBackend = class {
 		return this.baseUrl;
 	}
 	start() {
-		this.startEventStream();
+		this.startRealtime();
 	}
 	stop() {
-		this.eventAbort?.abort();
-		this.eventAbort = null;
+		this.realtime?.disconnect();
+		this.realtime = null;
+		this.activeRunId = null;
+		this.observedSessionKey = null;
 		this.chatAbort?.abort();
 		this.chatAbort = null;
 	}
@@ -95,6 +89,7 @@ var GatewaySseBackend = class {
 		return (await res.json()).item;
 	}
 	async sendChat(opts) {
+		this.observedSessionKey = opts.sessionKey;
 		this.chatAbort?.abort();
 		this.chatAbort = new AbortController();
 		const signal = this.chatAbort.signal;
@@ -185,85 +180,18 @@ var GatewaySseBackend = class {
 		};
 	}
 	async resumeChat(opts) {
+		this.observedSessionKey = opts.sessionKey;
 		this.chatAbort?.abort();
 		this.chatAbort = new AbortController();
-		const signal = this.chatAbort.signal;
-		this.onEvent?.({
-			event: "run_start",
-			data: {
-				type: "run_start",
-				runId: opts.runId,
-				sessionKey: opts.sessionKey,
-				timestamp: Date.now(),
-				payload: { channel: "webchat" }
-			},
-			source: "agent-resume"
-		});
-		let res;
-		try {
-			res = await gatewayFetch(this.baseUrl, "/api/agent/resume", this.credential, {
-				method: "POST",
-				headers: { Accept: "text/event-stream" },
-				body: JSON.stringify({
-					runId: opts.runId,
-					sessionKey: opts.sessionKey
-				}),
-				signal
-			});
-		} catch (error) {
-			if (signal.aborted) return {
-				ok: false,
-				reason: "resume aborted"
-			};
-			return {
-				ok: false,
-				reason: error instanceof Error ? error.message : String(error)
-			};
-		}
-		if (!res.ok) return {
-			ok: false,
-			reason: (await res.json().catch(() => ({}))).error?.message ?? `Resume failed: ${res.status}`
-		};
-		if (!(res.headers.get("Content-Type") ?? "").includes("text/event-stream") || !res.body) return {
-			ok: false,
-			reason: "Resume endpoint did not return an SSE stream"
-		};
-		(async () => {
-			try {
-				await consumeSSEStream(res.body, (sseEvent) => {
-					if (signal.aborted) return;
-					const data = parseSSEData(sseEvent.data);
-					if (!data) return;
-					this.onEvent?.({
-						event: sseEvent.event,
-						data,
-						source: "agent-resume"
-					});
-				}, signal);
-			} catch (error) {
-				if (signal.aborted) return;
-				const errorMessage = error instanceof Error ? error.message : String(error);
-				this.onEvent?.({
-					event: "error",
-					data: {
-						type: "error",
-						runId: opts.runId,
-						sessionKey: opts.sessionKey,
-						timestamp: Date.now(),
-						payload: {
-							code: "NETWORK_ERROR",
-							message: errorMessage
-						}
-					},
-					source: "agent-resume"
-				});
-			}
-		})();
+		this.unsubscribeActiveRun();
+		this.activeRunId = opts.runId;
+		this.realtime?.subscribe(`run:${opts.runId}`, 0);
 		return { ok: true };
 	}
 	async abortChat(opts) {
 		this.chatAbort?.abort();
 		this.chatAbort = null;
+		this.unsubscribeActiveRun();
 		try {
 			return { ok: (await (await gatewayFetch(this.baseUrl, "/api/agent/abort", this.credential, {
 				method: "POST",
@@ -274,6 +202,7 @@ var GatewaySseBackend = class {
 		}
 	}
 	async submitChatInput(opts) {
+		this.observedSessionKey = opts.sessionKey;
 		try {
 			const res = await gatewayFetch(this.baseUrl, `/api/sessions/${encodeURIComponent(opts.sessionKey)}/inputs`, this.credential, {
 				method: "POST",
@@ -752,65 +681,99 @@ var GatewaySseBackend = class {
 			return { ok: false };
 		}
 	}
-	startEventStream() {
-		this.eventAbort?.abort();
-		this.eventAbort = new AbortController();
-		const url = new URL(`${this.baseUrl}/api/events`);
-		const connect = async () => {
-			try {
-				const res = await fetch(url.toString(), {
-					signal: this.eventAbort.signal,
-					headers: {
-						Accept: "text/event-stream",
-						...gatewayCredentialAuthorization(this.credential) ? { Authorization: gatewayCredentialAuthorization(this.credential) } : {}
-					}
+	startRealtime() {
+		this.realtime?.disconnect();
+		this.realtime = new RealtimeClient({
+			clientId: this.clientId,
+			clientKind: "tui",
+			getWebSocketUrl: () => {
+				const url = new URL(this.baseUrl);
+				url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+				url.pathname = "/api/realtime/v1/ws";
+				url.search = "";
+				url.hash = "";
+				return url.toString();
+			},
+			issueTicket: async () => {
+				const response = await gatewayFetch(this.baseUrl, "/api/realtime/tickets", this.credential, {
+					method: "POST",
+					body: JSON.stringify({
+						clientId: this.clientId,
+						clientKind: "tui"
+					})
 				});
-				if (!res.ok || !res.body) {
-					this.onDisconnected?.(`event stream error: ${res.status}`);
-					this.scheduleReconnect();
-					return;
-				}
-				this.onConnected?.();
-				await consumeSSEStream(res.body, (sseEvent) => {
-					if (sseEvent.event === "connected") return;
-					if (sseEvent.event === "gap") {
-						const gapData = parseSSEData(sseEvent.data);
-						if (gapData && typeof gapData.expected === "number" && typeof gapData.received === "number") this.onGap?.({
-							expected: gapData.expected,
-							received: gapData.received
-						});
-						return;
-					}
-					const data = parseSSEData(sseEvent.data);
-					if (data !== null) this.onEvent?.(normalizeGatewaySseEvent({
-						event: sseEvent.event,
-						data,
-						source: "broadcast"
-					}));
-				}, this.eventAbort.signal);
-				if (!this.eventAbort?.signal.aborted) {
-					this.onDisconnected?.("stream closed");
-					this.scheduleReconnect();
+				const body = await response.json().catch(() => null);
+				if (!response.ok || !body?.payload?.ticket) throw new Error(body?.error?.message ?? `Realtime ticket failed (${response.status})`);
+				return body.payload.ticket;
+			},
+			createWebSocket: (url) => new WebSocket(url),
+			onStateChange: (state, error) => {
+				if (state === "connected") this.onConnected?.();
+				else if (state === "error") this.onDisconnected?.(error ?? "Realtime connection failed");
+			},
+			onEvent: (event) => this.handleRealtimeEvent(event),
+			onGap: (gap) => {
+				this.onGap?.({
+					expected: gap.requestedSeq + 1,
+					received: gap.earliestSeq
+				});
+				if (gap.topic === `run:${this.activeRunId}`) {
+					const runId = this.activeRunId;
+					this.unsubscribeActiveRun();
+					this.onEvent?.({
+						event: "error",
+						data: {
+							type: "error",
+							runId,
+							timestamp: Date.now(),
+							payload: {
+								code: "REALTIME_GAP",
+								message: "Run replay is no longer available"
+							}
+						},
+						source: "realtime-run"
+					});
 				}
-			} catch (error) {
-				if (this.eventAbort?.signal.aborted) return;
-				const errorMessage = error instanceof Error ? error.message : String(error);
-				log.warn({
-					err: error,
-					errorMessage
-				}, `Event stream failed: ${errorMessage}`);
-				this.onDisconnected?.(errorMessage);
-				this.scheduleReconnect();
 			}
-		};
-		connect();
+		});
+		this.realtime.subscribe("gateway");
+		this.realtime.subscribe("sessions");
+		this.realtime.connect();
+	}
+	handleRealtimeEvent(event) {
+		if (event.topic === `run:${this.activeRunId}`) {
+			const data = event.data && typeof event.data === "object" ? {
+				...event.data,
+				seq: event.seq
+			} : event.data;
+			this.onEvent?.({
+				event: event.event,
+				data,
+				source: "realtime-run"
+			});
+			if (event.event === "run_end" || event.event === "error") this.unsubscribeActiveRun();
+			return;
+		}
+		if (event.topic === "gateway") {
+			this.onEvent?.({
+				event: event.event,
+				data: event.data,
+				source: "realtime"
+			});
+			return;
+		}
+		if (event.topic === "sessions" && event.event === "run.started") {
+			const data = event.data;
+			if (typeof data?.sessionKey === "string" && data.sessionKey === this.observedSessionKey && typeof data.runId === "string" && data.runId && data.runId !== this.activeRunId) this.resumeChat({
+				sessionKey: data.sessionKey,
+				runId: data.runId
+			});
+		}
 	}
-	scheduleReconnect() {
-		if (this.eventAbort?.signal.aborted) return;
-		setTimeout(() => {
-			if (!this.eventAbort?.signal.aborted) this.startEventStream();
-		}, 3e3);
+	unsubscribeActiveRun() {
+		if (this.activeRunId) this.realtime?.unsubscribe(`run:${this.activeRunId}`);
+		this.activeRunId = null;
 	}
 };
 //#endregion
-export { GatewaySseBackend, normalizeGatewaySseEvent };
+export { GatewayRealtimeBackend };

package/dist/src/tui/tui-agent-events.d.ts

@@ -4,7 +4,6 @@ import type { ChatLog } from './components/chat-log.js';
 import type { TuiEventSource, TuiState } from './tui-types.js';
 export declare function clearSeenStreamEvents(): void;
 export declare function clearSeenStreamEventsForRun(runId: string): void;
-export declare function shouldSkipDuplicateBroadcastEvent(event: string, data: Record<string, unknown>, state: TuiState, source: TuiEventSource): boolean;
 export declare function dispatchAgentEvent(event: string, data: Record<string, unknown>, state: TuiState, chatLog: ChatLog, tui: TUI, setActivityStatus: (status: string) => void, touchStreamingActivity?: () => void, onRunEnded?: () => void, onAssistantFinalized?: (message: AgentMessage, options?: {
     errorMessage?: string;
 }) => void, source?: TuiEventSource): void;

package/dist/src/tui/tui-agent-events.js

@@ -29,22 +29,10 @@ const STREAM_TOUCH_EVENTS = new Set([
 	"assistant_message_end",
 	"progress"
 ]);
-const DIRECT_RESPONSE_OWNED_EVENTS = new Set([
-	...STREAM_TOUCH_EVENTS,
-	"run_end",
-	"error"
-]);
 function resolveEventRunId(data, state) {
 	if (typeof data.runId === "string" && data.runId) return data.runId;
 	return state.activeRunId ?? state.runStatus.runId ?? state.runStatus.lastCompletedRunId;
 }
-function shouldSkipDuplicateBroadcastEvent(event, data, state, source) {
-	if (source !== "broadcast") return false;
-	if (!DIRECT_RESPONSE_OWNED_EVENTS.has(event)) return false;
-	const directRunId = state.runStatus.directStreamRunId;
-	if (!directRunId) return false;
-	return resolveEventRunId(data, state) === directRunId;
-}
 function streamEventKey(data, state) {
 	const runId = resolveEventRunId(data, state);
 	const seq = data.seq;
@@ -52,7 +40,7 @@ function streamEventKey(data, state) {
 	return `${runId}:${seq}`;
 }
 function shouldSkipSeenStreamEvent(data, state, source) {
-	if (source !== "agent-response" && source !== "agent-resume" && source !== "broadcast") return false;
+	if (source !== "realtime-run") return false;
 	const key = streamEventKey(data, state);
 	if (!key) return false;
 	if (seenStreamEventKeys.has(key)) return true;
@@ -176,7 +164,6 @@ function errorAssistantMessage(errorContent) {
 }
 function dispatchAgentEvent(event, data, state, chatLog, tui, setActivityStatus, touchStreamingActivity, onRunEnded, onAssistantFinalized, source = "unknown") {
 	if (shouldSkipSeenStreamEvent(data, state, source)) return;
-	if (shouldSkipDuplicateBroadcastEvent(event, data, state, source)) return;
 	if (STREAM_TOUCH_EVENTS.has(event)) touchStreamingActivity?.();
 	const runId = resolveEventRunId(data, state) ?? state.activeRunId ?? "default";
 	const p = payload(data);
@@ -356,4 +343,4 @@ function dispatchAgentEvent(event, data, state, chatLog, tui, setActivityStatus,
 }
 const DEFAULT_STREAMING_WATCHDOG_MS = 3e4;
 //#endregion
-export { DEFAULT_STREAMING_WATCHDOG_MS, clearSeenStreamEvents, clearSeenStreamEventsForRun, dispatchAgentEvent, shouldSkipDuplicateBroadcastEvent };
+export { DEFAULT_STREAMING_WATCHDOG_MS, clearSeenStreamEvents, clearSeenStreamEventsForRun, dispatchAgentEvent };

package/dist/src/tui/tui-backend.d.ts

@@ -19,7 +19,7 @@ export interface TuiInboundAttachment {
     size?: number;
     uri?: string;
 }
-/** SSE event from the agent stream or broadcast channel. */
+/** Event from an agent run or gateway topic. */
 export interface TuiEvent {
     event: string;
     data: unknown;
@@ -171,7 +171,7 @@ export interface TuiTranscriptTreeEntry {
     isCurrentLeaf?: boolean;
 }
 /**
- * Abstraction over the gateway (SSE) or embedded agent backend.
+ * Abstraction over the realtime gateway or embedded agent backend.
  *
  * Both implementations expose the same surface so the TUI core stays
  * transport-agnostic.
@@ -183,12 +183,12 @@ export interface TuiBackend {
     onEvent?: (evt: TuiEvent) => void;
     onConnected?: () => void;
     onDisconnected?: (reason: string) => void;
-    /** Broadcast SSE sequence gap (if the gateway emits `gap` events). */
+    /** Realtime sequence gap. */
     onGap?: (info: {
         expected: number;
         received: number;
     }) => void;
-    /** Start the backend (open SSE streams / start agent service). */
+    /** Start the backend connection or embedded agent service. */
     start(): void;
     /** Stop the backend. */
     stop(): void;

package/dist/src/tui/tui-run-state.js

@@ -6,14 +6,12 @@ const STALE_WATCH_ACTIVITY = new Set([
 	"running"
 ]);
 function markRunEvent(state, phase, runId, event, source, nowMs = Date.now()) {
-	const directStreamRunId = (source === "agent-response" || source === "agent-resume") && runId ? runId : state.runStatus.directStreamRunId;
 	const isStartingNewRun = phase !== "idle" && state.runStatus.phase === "idle" && (runId === null || state.runStatus.runId === null || state.runStatus.runId !== runId);
 	const startedAt = phase === "idle" ? null : isStartingNewRun || state.runStatus.startedAt == null ? nowMs : state.runStatus.startedAt;
 	state.runStatus = {
 		...state.runStatus,
 		phase,
 		runId,
-		directStreamRunId,
 		source,
 		lastEvent: event,
 		startedAt,
@@ -26,7 +24,6 @@ function markRunSending(state, nowMs = Date.now()) {
 		...state.runStatus,
 		phase: "sending",
 		runId: null,
-		directStreamRunId: null,
 		lastCompletedRunId: null,
 		source: "unknown",
 		lastEvent: "send",
@@ -65,7 +62,6 @@ function resetRunStatus(state) {
 		...state.runStatus,
 		phase: "idle",
 		runId: null,
-		directStreamRunId: null,
 		lastCompletedRunId: null,
 		lastEvent: null,
 		startedAt: null,

package/dist/src/tui/tui-types.d.ts

@@ -28,20 +28,13 @@ export type TuiExitReason = 'exit' | 'signal';
 export interface TuiResult {
     exitReason: TuiExitReason;
 }
-/** Parsed SSE event from the stream. */
-export interface ParsedSSEEvent {
-    event: string;
-    data: string;
-    id?: string;
-}
 /** Activity status for the TUI status bar. */
 export type ActivityStatus = 'idle' | 'sending' | 'waiting' | 'streaming' | 'running' | 'compacting' | 'stalled' | 'recovering' | 'aborting';
-export type TuiEventSource = 'agent-response' | 'agent-resume' | 'broadcast' | 'embedded' | 'unknown';
+export type TuiEventSource = 'realtime-run' | 'realtime' | 'embedded' | 'unknown';
 export type TuiRunPhase = 'idle' | 'sending' | 'waiting' | 'streaming' | 'tool' | 'progress' | 'stalled' | 'recovering' | 'aborting';
 export interface TuiRunStatus {
     phase: TuiRunPhase;
     runId: string | null;
-    directStreamRunId: string | null;
     lastCompletedRunId: string | null;
     source: TuiEventSource;
     lastEvent: string | null;
@@ -86,7 +79,7 @@ export interface TuiState {
     scopedModelRefs: string[] | null;
     /** Last Escape timestamp for double-press actions. */
     lastEscapeAt: number;
-    /** Human-readable progress from SSE `progress` events. */
+    /** Human-readable progress from run `progress` events. */
     progressMessage: string | null;
     /** Session compaction in flight (local /compact handler). */
     isCompacting: boolean;

package/dist/src/tui/tui-types.js

@@ -8,7 +8,6 @@ function createInitialState(sessionKey) {
 		runStatus: {
 			phase: "idle",
 			runId: null,
-			directStreamRunId: null,
 			lastCompletedRunId: null,
 			source: "unknown",
 			lastEvent: null,

package/dist/src/tui/tui.js

@@ -46,7 +46,7 @@ import { createEditorSubmitHandler, createSubmitBurstCoalescer, shouldEnableWind
 import { withTuiSuspended } from "./tui-suspend.js";
 import { createInitialState } from "./tui-types.js";
 import { EmbeddedBackend } from "./backends/embedded-backend.js";
-import { GatewaySseBackend } from "./backends/gateway-sse-backend.js";
+import { GatewayRealtimeBackend } from "./backends/gateway-realtime-backend.js";
 import { ChatLog } from "./components/chat-log.js";
 import { CustomEditor } from "./components/custom-editor.js";
 import { TuiBottomBar } from "./components/tui-bottom-bar.js";
@@ -236,7 +236,7 @@ async function runTui(opts) {
 		extensionRegistry,
 		implicitTrustedWorkspace,
 		isWorkspaceTrusted: () => projectTrustSessionDecision
-	}) : new GatewaySseBackend({
+	}) : new GatewayRealtimeBackend({
 		url: opts.url ?? "http://localhost:3120",
 		credential: opts.credential
 	});
@@ -2172,7 +2172,7 @@ async function runTui(opts) {
 				updateFooter();
 				tui.requestRender();
 			});
-			if (state.activeRunId) recoverActiveRunFromHistory("broadcast reconnect");
+			if (state.activeRunId) recoverActiveRunFromHistory("realtime reconnect");
 			updateHeader();
 			updateFooter();
 			tui.requestRender();
@@ -2188,7 +2188,7 @@ async function runTui(opts) {
 		touchStreamingActivity();
 		if (isLocalMode) setConnectionStatus(`local stopped: ${reason}`);
 		else {
-			setConnectionStatus(`disconnected${wasConnected || state.historyLoaded ? ` (${reason}). Reconnecting broadcast stream…` : `. Ensure gateway is running (xopc gateway) or use --local.`}`);
+			setConnectionStatus(`disconnected${wasConnected || state.historyLoaded ? ` (${reason}). Reconnecting realtime stream…` : `. Ensure gateway is running (xopc gateway) or use --local.`}`);
 			if (!wasConnected && !state.historyLoaded) {
 				const gatewayUrl = opts.url ?? "http://localhost:3120";
 				chatLog.addSystem(`Cannot reach gateway at ${gatewayUrl}.\nStart the gateway (\`xopc gateway\`) or run \`xopc tui --local\` for embedded mode.`);
@@ -2199,7 +2199,7 @@ async function runTui(opts) {
 	client.onGap = (info) => {
 		chatLog.addSystem(`⚠️ Event gap: expected ${info.expected}, received ${info.received}. Some updates may be missing.`);
 		setConnectionStatus(`event gap: expected ${info.expected}, got ${info.received}`);
-		if (state.activeRunId) recoverActiveRunFromHistory("broadcast event gap");
+		if (state.activeRunId) recoverActiveRunFromHistory("realtime event gap");
 		else loadSessionHistory({ merge: true });
 		refreshComposerHistory();
 		tui.requestRender();

package/dist/src/tunnel/gateway-lifecycle.d.ts

@@ -2,7 +2,7 @@ import type { Config } from '../config/schema.js';
 type TunnelEventSink = {
     emit(type: string, payload: unknown): void;
 };
-/** Publish `tunnel.status` on gateway SSE when tunnel lifecycle changes. */
+/** Publish `tunnel.status` on the gateway realtime topic when tunnel lifecycle changes. */
 export declare function wireTunnelEventsToGateway(service: TunnelEventSink): void;
 export type ConfigureTunnelFromGatewayConfigOptions = {
     force?: boolean;

package/dist/src/tunnel/gateway-lifecycle.js

@@ -10,7 +10,7 @@ import { fetchTunnelWellKnown } from "./well-known.js";
 init_logger();
 const log = createLogger("Tunnel");
 let tunnelSseWired = false;
-/** Publish `tunnel.status` on gateway SSE when tunnel lifecycle changes. */
+/** Publish `tunnel.status` on the gateway realtime topic when tunnel lifecycle changes. */
 function wireTunnelEventsToGateway(service) {
 	if (tunnelSseWired) return;
 	tunnelSseWired = true;

package/dist/src/user-context/actionableInsights.d.ts

@@ -0,0 +1,14 @@
+import type { MemoryRecord } from '../agent/memory/types.js';
+export declare const USER_CONFIRMED_MEMORY_TAG = "user-confirmed";
+export declare const INSIGHT_ACCEPTED_TAG = "insight-action:accepted";
+export declare const INSIGHT_DISMISSED_TAG = "insight-action:dismissed";
+export type ActionableInsightSuggestion = {
+    id: string;
+    insight: string;
+    kind: MemoryRecord['kind'];
+    action: 'make_repeatable' | 'start_progress' | 'add_playbook';
+    evidenceCount: number;
+    confidence?: number;
+    sourceName: string;
+};
+export declare function buildActionableInsightSuggestions(records: MemoryRecord[], existingTaskTexts: readonly string[]): ActionableInsightSuggestion[];

package/dist/src/user-context/actionableInsights.js

@@ -0,0 +1,34 @@
+import { isActionableUnderstandingContent, isNearDuplicateUnderstanding } from "./understandingQuality.js";
+//#region src/user-context/actionableInsights.ts
+const USER_CONFIRMED_MEMORY_TAG = "user-confirmed";
+const INSIGHT_ACCEPTED_TAG = "insight-action:accepted";
+const INSIGHT_DISMISSED_TAG = "insight-action:dismissed";
+function actionFor(record) {
+	if (record.kind === "routine") return "make_repeatable";
+	if (record.kind === "long_term_goal") return "start_progress";
+	if (record.kind === "task_lesson" || record.kind === "derived_insight") return "add_playbook";
+	return null;
+}
+function buildActionableInsightSuggestions(records, existingTaskTexts) {
+	const selected = [];
+	const sorted = records.filter((record) => record.status === "active").filter((record) => record.tags?.includes(USER_CONFIRMED_MEMORY_TAG)).filter((record) => !record.tags?.includes("insight-action:accepted") && !record.tags?.includes("insight-action:dismissed")).filter((record) => isActionableUnderstandingContent(record.content)).filter((record) => record.kind !== "long_term_goal" || record.durability !== "ephemeral").sort((left, right) => right.importance - left.importance || Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
+	for (const record of sorted) {
+		const action = actionFor(record);
+		if (!action) continue;
+		if (selected.some((item) => item.action === action && isNearDuplicateUnderstanding(item.insight, record.content))) continue;
+		if (action === "start_progress" && existingTaskTexts.some((text) => isNearDuplicateUnderstanding(text, record.content))) continue;
+		selected.push({
+			id: record.id,
+			insight: record.content,
+			kind: record.kind,
+			action,
+			evidenceCount: record.evidence?.length ?? 0,
+			confidence: record.confidence,
+			sourceName: record.source.provider ?? "local"
+		});
+		if (selected.length === 5) break;
+	}
+	return selected;
+}
+//#endregion
+export { INSIGHT_ACCEPTED_TAG, INSIGHT_DISMISSED_TAG, USER_CONFIRMED_MEMORY_TAG, buildActionableInsightSuggestions };

package/dist/src/user-context/manual-understanding.js

@@ -2,6 +2,7 @@ import { listMemoryRecords, upsertMemoryRecord } from "../storage/sqlite/memory-
 import "../storage/sqlite/index.js";
 import { nextMemoryReviewAt } from "../agent/memory/lifecycle.js";
 import { isUserContextRecord } from "./projection.js";
+import { USER_CONFIRMED_MEMORY_TAG } from "./actionableInsights.js";
 //#region src/user-context/manual-understanding.ts
 const STATUSES = [
 	"candidate",
@@ -50,7 +51,11 @@ function createManualUnderstanding(input) {
 				path: "you://manual"
 			},
 			confidence: 1,
-			tags: ["user-understanding", "explicit-user-memory"],
+			tags: [
+				"user-understanding",
+				"explicit-user-memory",
+				USER_CONFIRMED_MEMORY_TAG
+			],
 			status: "active",
 			sensitivity: input.sensitivity,
 			explicitness: "explicit",

package/dist/src/user-context/projection.d.ts

@@ -68,7 +68,7 @@ export declare function projectPersonalContextSources(definitions: ConnectorDefi
     }>;
 }): {
     category: import("../connectors/types.js").ConnectorCategory;
-    capabilities: ("context" | "tools" | "events" | "memory_source")[];
+    capabilities: ("tools" | "context" | "events" | "memory_source")[];
     access: {
         context: boolean;
         memory: boolean;

package/dist/src/user-context/understandingQuality.d.ts

@@ -0,0 +1,5 @@
+import type { MemoryKind } from '../agent/memory/types.js';
+export declare function isStandaloneUnderstandingContent(content: string): boolean;
+export declare function isActionableUnderstandingContent(content: string): boolean;
+export declare function isDurableUnderstandingCandidate(kind: MemoryKind, content: string): boolean;
+export declare function isNearDuplicateUnderstanding(left: string, right: string): boolean;