@nextclaw/ncp-toolkit 0.5.13 → 0.5.15

package/dist/index.d.ts

@@ -72,7 +72,7 @@ declare class EventPublisher {
   close(): void;
 }
 //#endregion
-//#region src/agent/agent-backend/agent-backend-types.d.ts
+//#region src/agent/agent-backend/agent-backend.types.d.ts
 type RuntimeFactoryParams = {
   sessionId: string;
   agentId?: string;
@@ -87,6 +87,14 @@ type AgentSessionRecord = {
   sessionId: string;
   agentId?: string;
   messages: NcpMessage[];
+  createdAt?: string;
+  updatedAt: string;
+  metadata?: Record<string, unknown>;
+};
+type AgentSessionEventRecord = {
+  sessionId: string;
+  agentId?: string;
+  createdAt?: string;
   updatedAt: string;
   metadata?: Record<string, unknown>;
 };
@@ -99,6 +107,7 @@ type LiveSessionExecution = {
 type LiveSessionState = {
   sessionId: string;
   agentId?: string;
+  createdAt: string;
   runtime: NcpAgentRuntime;
   stateManager: NcpAgentConversationStateManager;
   metadata: Record<string, unknown>;
@@ -108,19 +117,27 @@ type LiveSessionState = {
 interface AgentSessionStore {
   getSession(sessionId: string): Promise<AgentSessionRecord | null>;
   listSessions(): Promise<AgentSessionRecord[]>;
+  getSessionSummary?(sessionId: string): Promise<NcpSessionSummary | null>;
+  listSessionSummaries?(): Promise<NcpSessionSummary[]>;
+  listSessionMessages?(sessionId: string): Promise<NcpMessage[]>;
+  appendSessionEvent?(params: {
+    session: AgentSessionEventRecord;
+    event: NcpEndpointEvent;
+    updatedAt: string;
+  }): Promise<void>;
   saveSession(session: AgentSessionRecord): Promise<void>;
   replaceSession(session: AgentSessionRecord): Promise<void>;
   deleteSession(sessionId: string): Promise<AgentSessionRecord | null>;
 }
 //#endregion
-//#region src/agent/agent-backend/agent-backend-session-utils.d.ts
+//#region src/agent/agent-backend/agent-backend-session.utils.d.ts
 type SessionContextWindowResolver = (params: {
   messages: readonly NcpMessage[];
   metadata: Record<string, unknown>;
   sessionId: string;
 }) => Record<string, unknown> | null;
 //#endregion
-//#region src/agent/agent-backend/agent-backend.d.ts
+//#region src/agent/agent-backend/agent-backend.service.d.ts
 type DefaultNcpAgentBackendConfig = {
   createRuntime: CreateRuntimeFn;
   sessionStore: AgentSessionStore;
@@ -159,6 +176,7 @@ declare class DefaultNcpAgentBackend implements NcpAgentServerEndpoint, NcpSessi
     signal: AbortSignal;
   }, opts?: NcpAgentRunStreamOptions) => AsyncIterable<NcpEndpointEvent>;
   listSessions: () => Promise<NcpSessionSummary[]>;
+  isLiveSessionRunning: (sessionId: string) => boolean;
   listSessionMessages: (sessionId: string) => Promise<NcpMessage[]>;
   getSession: (sessionId: string) => Promise<NcpSessionSummary | null>;
   appendMessage: (sessionId: string, message: NcpMessage) => Promise<NcpSessionSummary | null>;
@@ -169,16 +187,15 @@ declare class DefaultNcpAgentBackend implements NcpAgentServerEndpoint, NcpSessi
   private startSessionExecution;
   private finishSessionExecution;
   private handleAbort;
-  private persistSession;
 }
 //#endregion
-//#region src/agent/agent-backend/agent-run-executor.d.ts
+//#region src/agent/agent-backend/agent-run-executor.service.d.ts
 declare class AgentRunExecutor {
-  executeRun(session: LiveSessionState, envelope: NcpRequestEnvelope, controller: AbortController): AsyncGenerator<NcpEndpointEvent>;
+  executeRun: (session: LiveSessionState, envelope: NcpRequestEnvelope, controller: AbortController) => AsyncGenerator<NcpEndpointEvent>;
   private publishFailure;
 }
 //#endregion
-//#region src/agent/agent-backend/in-memory-agent-session-store.d.ts
+//#region src/agent/agent-backend/in-memory-agent-session.store.d.ts
 declare class InMemoryAgentSessionStore implements AgentSessionStore {
   private readonly sessions;
   getSession: (sessionId: string) => Promise<AgentSessionRecord | null>;
@@ -224,4 +241,4 @@ declare class NcpReplyConsumer {
   consume: (input: NcpReplyInput) => Promise<void>;
 }
 //#endregion
-export { AgentRunExecutor, type AgentSessionRecord, type AgentSessionStore, Chat, ChatTarget, type CreateRuntimeFn, DefaultNcpAgentBackend, type DefaultNcpAgentBackendConfig, DefaultNcpAgentConversationStateManager, EventPublisher, InMemoryAgentSessionStore, type LiveSessionExecution, type LiveSessionState, NcpErrorException, NcpEventStream, NcpReplyConsumer, NcpReplyInput, type RuntimeFactoryParams, createAgentClientFromServer };
+export { AgentRunExecutor, type AgentSessionEventRecord, type AgentSessionRecord, type AgentSessionStore, Chat, ChatTarget, type CreateRuntimeFn, DefaultNcpAgentBackend, type DefaultNcpAgentBackendConfig, DefaultNcpAgentConversationStateManager, EventPublisher, InMemoryAgentSessionStore, type LiveSessionExecution, type LiveSessionState, NcpErrorException, NcpEventStream, NcpReplyConsumer, NcpReplyInput, type RuntimeFactoryParams, createAgentClientFromServer };

package/dist/index.js

@@ -574,6 +574,9 @@ var DefaultNcpAgentConversationStateManager = class {
 };
 //#endregion
 //#region src/agent/agent-client-from-server.ts
+function assertMaterializedEnvelope(envelope) {
+	if (!envelope.sessionId?.trim() || !envelope.message.sessionId?.trim()) throw new Error("NCP request envelope must be materialized before server dispatch.");
+}
 /**
 * Creates an NcpAgentClientEndpoint that forwards to an in-process NcpAgentServerEndpoint.
 * Use when the agent runs in-process and you need to pass a client endpoint to the HTTP server.
@@ -592,6 +595,7 @@ function createAgentClientFromServer(server) {
 		async emit(event) {
 			switch (event.type) {
 				case NcpEventType.MessageRequest:
+					assertMaterializedEnvelope(event.payload);
 					await consume(server.send(event.payload));
 					return;
 				case NcpEventType.MessageStreamRequest:
@@ -607,6 +611,7 @@ function createAgentClientFromServer(server) {
 			return server.subscribe(listener);
 		},
 		async send(envelope) {
+			assertMaterializedEnvelope(envelope);
 			await consume(server.send(envelope));
 		},
 		async stream(payload) {
@@ -656,7 +661,7 @@ var EventPublisher = class {
 	}
 };
 //#endregion
-//#region src/agent/agent-backend/agent-live-session-registry.ts
+//#region src/agent/agent-backend/agent-live-session-registry.service.ts
 function readOptionalAgentId$2(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim().toLowerCase();
@@ -695,6 +700,7 @@ var AgentLiveSessionRegistry = class {
 		const session = {
 			sessionId,
 			...sessionAgentId ? { agentId: sessionAgentId } : {},
+			createdAt: storedSession?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
 			stateManager,
 			metadata: sessionMetadata,
 			runtime: null,
@@ -747,7 +753,7 @@ var NcpErrorException = class extends Error {
 	}
 };
 //#endregion
-//#region src/agent/agent-backend/agent-backend-execution-utils.ts
+//#region src/agent/agent-backend/agent-backend-execution.utils.ts
 function startAgentBackendSessionExecution(params) {
 	const { session, envelope, signal, onStatusChanged } = params;
 	if (session.activeExecution && !session.activeExecution.closed) throw new NcpErrorException("runtime-error", `Session ${session.sessionId} already has an active execution.`, { sessionId: session.sessionId });
@@ -775,22 +781,18 @@ function finishAgentBackendSessionExecution(params) {
 			status: "idle"
 		});
 	}
-	closeAgentBackendSessionExecution(execution);
-}
-function closeAgentBackendSessionExecution(execution) {
-	if (execution.closed) return;
-	execution.closed = true;
 }
 //#endregion
-//#region src/agent/agent-backend/agent-run-executor.ts
+//#region src/agent/agent-backend/agent-run-executor.service.ts
 var AgentRunExecutor = class {
-	async *executeRun(session, envelope, controller) {
+	executeRun = (session, envelope, controller) => (async function* (self) {
 		if (!isHiddenNcpMessage(envelope.message)) {
 			const messageSent = {
 				type: NcpEventType.MessageSent,
 				payload: {
 					sessionId: envelope.sessionId,
 					message: structuredClone(envelope.message),
+					...envelope.correlationId ? { correlationId: envelope.correlationId } : {},
 					metadata: envelope.metadata
 				}
 			};
@@ -803,27 +805,39 @@ var AgentRunExecutor = class {
 				messages: [envelope.message],
 				correlationId: envelope.correlationId,
 				metadata: envelope.metadata
-			}, { signal: controller.signal })) yield structuredClone(event);
+			}, { signal: controller.signal })) yield normalizeRunEvent(event, envelope);
 		} catch (error) {
 			if (!controller.signal.aborted) {
-				const runErrorEvent = await this.publishFailure(error, envelope, session);
+				const runErrorEvent = await self.publishFailure(error, envelope, session);
 				yield structuredClone(runErrorEvent);
 			}
 		}
-	}
-	async publishFailure(error, envelope, session) {
+	})(this);
+	publishFailure = async (error, envelope, session) => {
 		const message = error instanceof Error ? error.message : String(error);
 		const runErrorEvent = {
 			type: NcpEventType.RunError,
 			payload: {
 				sessionId: envelope.sessionId,
+				...envelope.correlationId ? { correlationId: envelope.correlationId } : {},
 				error: message
 			}
 		};
 		await session.stateManager.dispatch(runErrorEvent);
 		return runErrorEvent;
-	}
+	};
 };
+function normalizeRunEvent(event, envelope) {
+	if (!("payload" in event) || !event.payload || typeof event.payload !== "object") return structuredClone(event);
+	return structuredClone({
+		...event,
+		payload: {
+			...event.payload,
+			sessionId: "sessionId" in event.payload && typeof event.payload.sessionId === "string" ? event.payload.sessionId : envelope.sessionId,
+			...envelope.correlationId && (!("correlationId" in event.payload) || typeof event.payload.correlationId !== "string") ? { correlationId: envelope.correlationId } : {}
+		}
+	});
+}
 //#endregion
 //#region src/agent/agent-backend/async-queue.ts
 function createAsyncQueue() {
@@ -874,7 +888,7 @@ function createAsyncQueue() {
 	};
 }
 //#endregion
-//#region src/agent/agent-backend/agent-backend-session-realtime.ts
+//#region src/agent/agent-backend/agent-backend-session-realtime.service.ts
 function readEventSessionId(event) {
 	const payload = "payload" in event ? event.payload : null;
 	if (!payload || typeof payload !== "object") return null;
@@ -888,7 +902,7 @@ var AgentBackendSessionRealtime = class {
 		if (options.dispatchToStateManager) await session.stateManager.dispatch(event);
 		this.params.publishEndpointEvent(event);
 		session.publisher.publish(event);
-		if (options.persistSession !== false) await this.params.persistSession(session.sessionId);
+		if (options.persistSession !== false) await this.params.persistSessionEvent(session, event);
 	};
 	streamSessionEvents = (payloadOrParams, opts) => {
 		return (async function* (self) {
@@ -958,7 +972,7 @@ var AgentBackendSessionRealtime = class {
 	};
 };
 //#endregion
-//#region src/agent/agent-backend/agent-backend-session-utils.ts
+//#region src/agent/agent-backend/agent-backend-session.utils.ts
 const AUTO_SESSION_LABEL_MAX_LENGTH = 64;
 function readOptionalAgentId$1(value) {
 	if (typeof value !== "string") return;
@@ -970,6 +984,9 @@ function readMessages(snapshot) {
 	if (snapshot.streamingMessage) messages.push(structuredClone(snapshot.streamingMessage));
 	return messages;
 }
+function readSessionActivityAt(summary) {
+	return summary.lastMessageAt ?? summary.createdAt ?? summary.updatedAt;
+}
 function toSessionSummary(session, liveSession) {
 	const metadata = withAutoSessionLabel({
 		metadata: session.metadata ? structuredClone({
@@ -982,6 +999,7 @@ function toSessionSummary(session, liveSession) {
 		sessionId: session.sessionId,
 		...readOptionalAgentId$1(session.agentId) ? { agentId: readOptionalAgentId$1(session.agentId) } : {},
 		messageCount: session.messages.length,
+		...session.createdAt ? { createdAt: session.createdAt } : {},
 		updatedAt: session.updatedAt,
 		...session.messages.length > 0 ? { lastMessageAt: session.messages[session.messages.length - 1]?.timestamp ?? session.updatedAt } : {},
 		status: liveSession?.activeExecution ? "running" : "idle",
@@ -999,6 +1017,7 @@ function toLiveSessionSummary(session) {
 		sessionId: session.sessionId,
 		...readOptionalAgentId$1(session.agentId) ? { agentId: readOptionalAgentId$1(session.agentId) } : {},
 		messageCount: messages.length,
+		createdAt: session.createdAt,
 		updatedAt,
 		...messages.length > 0 ? { lastMessageAt: messages[messages.length - 1]?.timestamp ?? updatedAt } : {},
 		status: session.activeExecution ? "running" : "idle",
@@ -1020,6 +1039,36 @@ function toLiveSessionSummaryWithContextWindow(session, resolver) {
 	const messages = readMessages(session.stateManager.getSnapshot());
 	return withSessionContextWindow(toLiveSessionSummary(session), messages, resolver);
 }
+async function listBackendSessionSummaries(params) {
+	const { liveSessions, sessionStore } = params;
+	const summaries = sessionStore.listSessionSummaries ? await sessionStore.listSessionSummaries() : (await sessionStore.listSessions()).map((session) => toSessionSummary(session, liveSessions.find((liveSession) => liveSession.sessionId === session.sessionId) ?? null));
+	for (const liveSession of liveSessions) {
+		const existingIndex = summaries.findIndex((session) => session.sessionId === liveSession.sessionId);
+		if (existingIndex >= 0) {
+			summaries[existingIndex] = {
+				...summaries[existingIndex],
+				status: liveSession.activeExecution ? "running" : "idle"
+			};
+			continue;
+		}
+		summaries.push(toLiveSessionSummary(liveSession));
+	}
+	return summaries.sort((left, right) => readSessionActivityAt(right).localeCompare(readSessionActivityAt(left)));
+}
+async function listBackendSessionMessages(params) {
+	const { liveSession, sessionId, sessionStore } = params;
+	if (liveSession) return readMessages(liveSession.stateManager.getSnapshot());
+	if (sessionStore.listSessionMessages) return sessionStore.listSessionMessages(sessionId);
+	const session = await sessionStore.getSession(sessionId);
+	return session ? session.messages.map((message) => structuredClone(message)) : [];
+}
+async function getBackendSessionSummary(params) {
+	const { liveSession, resolveSessionContextWindow, sessionId, sessionStore } = params;
+	if (!liveSession && sessionStore.getSessionSummary) return sessionStore.getSessionSummary(sessionId);
+	const storedSession = await sessionStore.getSession(sessionId);
+	const liveMessages = liveSession ? readMessages(liveSession.stateManager.getSnapshot()) : null;
+	return storedSession ? withSessionContextWindow(toSessionSummary(storedSession, liveSession), liveMessages ?? storedSession.messages, resolveSessionContextWindow) : liveSession ? toLiveSessionSummaryWithContextWindow(liveSession, resolveSessionContextWindow) : null;
+}
 function now() {
 	return (/* @__PURE__ */ new Date()).toISOString();
 }
@@ -1101,7 +1150,7 @@ function normalizeSendRunEvent(params) {
 	};
 }
 //#endregion
-//#region src/agent/agent-backend/agent-backend-session-persistence.ts
+//#region src/agent/agent-backend/agent-backend-session-persistence.utils.ts
 function readOptionalAgentId(value) {
 	if (typeof value !== "string") return;
 	const trimmed = value.trim().toLowerCase();
@@ -1111,44 +1160,94 @@ function readAgentIdFromMetadata(metadata) {
 	return readOptionalAgentId(metadata?.agent_id) ?? readOptionalAgentId(metadata?.agentId);
 }
 function resolvePersistedAgentId(params) {
-	return readOptionalAgentId(params.liveSession?.agentId) ?? readOptionalAgentId(params.storedSession?.agentId) ?? readAgentIdFromMetadata(params.liveSession?.metadata) ?? readAgentIdFromMetadata(params.storedSession?.metadata);
+	const { liveSession, storedSession } = params;
+	return readOptionalAgentId(liveSession?.agentId) ?? readOptionalAgentId(storedSession?.agentId) ?? readAgentIdFromMetadata(liveSession?.metadata) ?? readAgentIdFromMetadata(storedSession?.metadata);
 }
 function buildUpdatedSessionRecord(params) {
-	const nextMetadata = params.patch.metadata === null ? {} : params.patch.metadata ? structuredClone(params.patch.metadata) : structuredClone(params.liveSession?.metadata ?? params.storedSession?.metadata ?? {});
-	if (params.liveSession) params.liveSession.metadata = structuredClone(nextMetadata);
+	const { liveSession, patch, sessionId, storedSession, updatedAt } = params;
+	const nextMetadata = patch.metadata === null ? {} : patch.metadata ? structuredClone(patch.metadata) : structuredClone(liveSession?.metadata ?? storedSession?.metadata ?? {});
+	if (liveSession) liveSession.metadata = structuredClone(nextMetadata);
+	const agentId = resolvePersistedAgentId({
+		liveSession,
+		storedSession
+	});
 	return {
-		sessionId: params.sessionId,
-		...resolvePersistedAgentId({
-			liveSession: params.liveSession,
-			storedSession: params.storedSession
-		}) ? { agentId: resolvePersistedAgentId({
-			liveSession: params.liveSession,
-			storedSession: params.storedSession
-		}) } : {},
-		messages: params.liveSession ? readMessages(params.liveSession.stateManager.getSnapshot()) : params.storedSession?.messages.map((message) => structuredClone(message)) ?? [],
-		updatedAt: params.updatedAt,
+		sessionId,
+		...agentId ? { agentId } : {},
+		messages: liveSession ? readMessages(liveSession.stateManager.getSnapshot()) : storedSession?.messages.map((message) => structuredClone(message)) ?? [],
+		createdAt: storedSession?.createdAt ?? liveSession?.createdAt ?? updatedAt,
+		updatedAt,
 		metadata: nextMetadata
 	};
 }
 function buildPersistedLiveSessionRecord(params) {
-	const messages = readMessages(params.session.stateManager.getSnapshot());
+	const { session, sessionId, updatedAt } = params;
+	const messages = readMessages(session.stateManager.getSnapshot());
 	const metadata = withAutoSessionLabel({
 		metadata: {
-			...params.session.metadata ? structuredClone(params.session.metadata) : {},
-			...params.session.activeExecution?.requestEnvelope.metadata ? structuredClone(params.session.activeExecution.requestEnvelope.metadata) : {}
+			...session.metadata ? structuredClone(session.metadata) : {},
+			...session.activeExecution?.requestEnvelope.metadata ? structuredClone(session.activeExecution.requestEnvelope.metadata) : {}
 		},
 		messages
 	});
+	const agentId = readOptionalAgentId(session.agentId) ?? readAgentIdFromMetadata(session.metadata) ?? readAgentIdFromMetadata(session.activeExecution?.requestEnvelope.metadata);
 	return {
-		sessionId: params.sessionId,
-		...readOptionalAgentId(params.session.agentId) ?? readAgentIdFromMetadata(params.session.metadata) ?? readAgentIdFromMetadata(params.session.activeExecution?.requestEnvelope.metadata) ? { agentId: readOptionalAgentId(params.session.agentId) ?? readAgentIdFromMetadata(params.session.metadata) ?? readAgentIdFromMetadata(params.session.activeExecution?.requestEnvelope.metadata) } : {},
+		sessionId,
+		...agentId ? { agentId } : {},
 		messages,
-		updatedAt: params.updatedAt,
+		createdAt: session.createdAt,
+		updatedAt,
+		metadata
+	};
+}
+function buildLiveSessionEventRecord(params) {
+	const { session, updatedAt } = params;
+	const metadata = {
+		...session.metadata ? structuredClone(session.metadata) : {},
+		...session.activeExecution?.requestEnvelope.metadata ? structuredClone(session.activeExecution.requestEnvelope.metadata) : {}
+	};
+	const agentId = readOptionalAgentId(session.agentId) ?? readAgentIdFromMetadata(session.metadata) ?? readAgentIdFromMetadata(session.activeExecution?.requestEnvelope.metadata);
+	return {
+		sessionId: session.sessionId,
+		...agentId ? { agentId } : {},
+		createdAt: session.createdAt,
+		updatedAt,
 		metadata
 	};
 }
+function shouldPersistRunEndSnapshot(sessionStore) {
+	return !sessionStore.appendSessionEvent;
+}
+async function persistLiveSession(params) {
+	const { session, sessionId, sessionStore, updatedAt } = params;
+	if (!session) return;
+	await sessionStore.saveSession(buildPersistedLiveSessionRecord({
+		sessionId,
+		session,
+		updatedAt
+	}));
+}
+async function persistLiveSessionEvent(params) {
+	const { event, session, sessionStore, updatedAt } = params;
+	if (sessionStore.appendSessionEvent) {
+		await sessionStore.appendSessionEvent({
+			session: buildLiveSessionEventRecord({
+				session,
+				updatedAt
+			}),
+			event,
+			updatedAt
+		});
+		return;
+	}
+	await sessionStore.saveSession(buildPersistedLiveSessionRecord({
+		sessionId: session.sessionId,
+		session,
+		updatedAt
+	}));
+}
 //#endregion
-//#region src/agent/agent-backend/agent-backend.ts
+//#region src/agent/agent-backend/agent-backend.service.ts
 const DEFAULT_SUPPORTED_PART_TYPES = [
 	"text",
 	"file",
@@ -1161,6 +1260,9 @@ const DEFAULT_SUPPORTED_PART_TYPES = [
 	"action",
 	"extension"
 ];
+const disposeRuntime = async (runtime) => {
+	await runtime.dispose?.();
+};
 var DefaultNcpAgentBackend = class {
 	manifest;
 	sessionStore;
@@ -1183,7 +1285,18 @@ var DefaultNcpAgentBackend = class {
 			sessionStore: this.sessionStore,
 			publishEndpointEvent: (event) => this.publisher.publish(event),
 			subscribeEndpointEvent: (listener) => this.publisher.subscribe(listener),
-			persistSession: (sessionId) => this.persistSession(sessionId),
+			persistSession: (sessionId) => persistLiveSession({
+				sessionStore: this.sessionStore,
+				session: this.sessionRegistry.getSession(sessionId),
+				sessionId,
+				updatedAt: now()
+			}),
+			persistSessionEvent: (session, event) => persistLiveSessionEvent({
+				sessionStore: this.sessionStore,
+				session,
+				event,
+				updatedAt: now()
+			}),
 			getSessionSummary: (sessionId) => this.getSession(sessionId)
 		});
 		this.manifest = {
@@ -1211,12 +1324,14 @@ var DefaultNcpAgentBackend = class {
 			const execution = session.activeExecution;
 			if (!execution) {
 				session.publisher.close();
+				await disposeRuntime(session.runtime);
 				continue;
 			}
 			execution.abortHandled = true;
 			execution.controller.abort();
 			this.finishSessionExecution(session, execution);
 			session.publisher.close();
+			await disposeRuntime(session.runtime);
 		}
 		this.sessionRegistry.clear();
 	};
@@ -1224,7 +1339,15 @@ var DefaultNcpAgentBackend = class {
 		await this.ensureStarted();
 		switch (event.type) {
 			case NcpEventType.MessageRequest:
-				for await (const emittedEvent of this.send(event.payload));
+				if (!event.payload.sessionId) throw new Error("MessageRequest requires a sessionId before it reaches the agent backend.");
+				for await (const emittedEvent of this.send({
+					...event.payload,
+					sessionId: event.payload.sessionId,
+					message: {
+						...event.payload.message,
+						sessionId: event.payload.sessionId
+					}
+				}));
 				return;
 			case NcpEventType.MessageStreamRequest:
 				await this.ensureStarted();
@@ -1266,31 +1389,38 @@ var DefaultNcpAgentBackend = class {
 				}
 			} finally {
 				self.finishSessionExecution(session, execution);
-				await self.persistSession(session.sessionId);
+				if (shouldPersistRunEndSnapshot(self.sessionStore)) await persistLiveSession({
+					sessionStore: self.sessionStore,
+					session,
+					sessionId: session.sessionId,
+					updatedAt: now()
+				});
 			}
 		})(this);
 	};
 	abort = async (payload) => this.handleAbort(payload);
 	stream = (payloadOrParams, opts) => this.sessionRealtime.streamSessionEvents(payloadOrParams, opts);
 	listSessions = async () => {
-		const summaries = (await this.sessionStore.listSessions()).map((session) => toSessionSummary(session, this.sessionRegistry.getSession(session.sessionId)));
-		for (const liveSession of this.sessionRegistry.listSessions()) {
-			if (summaries.some((session) => session.sessionId === liveSession.sessionId)) continue;
-			summaries.push(toLiveSessionSummary(liveSession));
-		}
-		return summaries.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+		return listBackendSessionSummaries({
+			sessionStore: this.sessionStore,
+			liveSessions: this.sessionRegistry.listSessions()
+		});
 	};
+	isLiveSessionRunning = (sessionId) => Boolean(this.sessionRegistry.getSession(sessionId)?.activeExecution);
 	listSessionMessages = async (sessionId) => {
-		const liveSession = this.sessionRegistry.getSession(sessionId);
-		if (liveSession) return readMessages(liveSession.stateManager.getSnapshot());
-		const session = await this.sessionStore.getSession(sessionId);
-		return session ? session.messages.map((message) => structuredClone(message)) : [];
+		return listBackendSessionMessages({
+			sessionStore: this.sessionStore,
+			liveSession: this.sessionRegistry.getSession(sessionId),
+			sessionId
+		});
 	};
 	getSession = async (sessionId) => {
-		const liveSession = this.sessionRegistry.getSession(sessionId);
-		const storedSession = await this.sessionStore.getSession(sessionId);
-		const liveMessages = liveSession ? readMessages(liveSession.stateManager.getSnapshot()) : null;
-		return storedSession ? withSessionContextWindow(toSessionSummary(storedSession, liveSession), liveMessages ?? storedSession.messages, this.resolveSessionContextWindow) : liveSession ? toLiveSessionSummaryWithContextWindow(liveSession, this.resolveSessionContextWindow) : null;
+		return getBackendSessionSummary({
+			sessionStore: this.sessionStore,
+			liveSession: this.sessionRegistry.getSession(sessionId),
+			sessionId,
+			resolveSessionContextWindow: this.resolveSessionContextWindow
+		});
 	};
 	appendMessage = async (sessionId, message) => {
 		await this.ensureStarted();
@@ -1319,9 +1449,10 @@ var DefaultNcpAgentBackend = class {
 		if (execution) {
 			execution.abortHandled = true;
 			execution.controller.abort();
-			closeAgentBackendSessionExecution(execution);
+			execution.closed = true;
 		}
 		liveSession?.publisher.close();
+		if (liveSession) await disposeRuntime(liveSession.runtime);
 		await this.sessionStore.deleteSession(sessionId);
 	};
 	ensureStarted = async () => {
@@ -1354,18 +1485,9 @@ var DefaultNcpAgentBackend = class {
 		await this.sessionRealtime.publishSessionEvent(session, abortEvent, { dispatchToStateManager: true });
 		this.finishSessionExecution(session, execution);
 	};
-	persistSession = async (sessionId) => {
-		const session = this.sessionRegistry.getSession(sessionId);
-		if (!session) return;
-		await this.sessionStore.saveSession(buildPersistedLiveSessionRecord({
-			sessionId,
-			session,
-			updatedAt: now()
-		}));
-	};
 };
 //#endregion
-//#region src/agent/agent-backend/in-memory-agent-session-store.ts
+//#region src/agent/agent-backend/in-memory-agent-session.store.ts
 var InMemoryAgentSessionStore = class {
 	sessions = /* @__PURE__ */ new Map();
 	getSession = async (sessionId) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-toolkit",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "private": false,
   "description": "Toolkit implementations built on top of the NextClaw Communication Protocol.",
   "type": "module",
@@ -15,14 +15,14 @@
     "dist"
   ],
   "dependencies": {
-    "@nextclaw/ncp": "0.5.8"
+    "@nextclaw/ncp": "0.5.10"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",
     "prettier": "^3.3.3",
     "typescript": "^5.6.3",
     "vitest": "^4.1.2",
-    "@nextclaw/ncp-agent-runtime": "0.3.18"
+    "@nextclaw/ncp-agent-runtime": "0.3.20"
   },
   "scripts": {
     "build": "tsdown src/index.ts --dts --clean --target es2022 --no-fixedExtension",