@nextclaw/ncp-toolkit 0.5.17 → 0.5.18

package/README.md

@@ -12,7 +12,6 @@ pnpm -C packages/ncp-packages/nextclaw-ncp-toolkit build
 
 - Reference conversation-state manager implementations
 - Protocol-level helper logic that depends on `@nextclaw/ncp` contracts
-- Composable agent backend building block: `DefaultNcpAgentBackend`
 - Default in-memory adapter: `InMemoryAgentSessionStore`
 - In-process adapter helper: `createAgentClientFromServer`
 - Runtime throwable helper: `NcpErrorException`

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NcpAgentClientEndpoint, NcpAgentConversationHydrationParams, NcpAgentConversationSnapshot, NcpAgentConversationStateManager, NcpAgentRunApi, NcpAgentRunInput, NcpAgentRunSendOptions, NcpAgentRunStreamOptions, NcpAgentRuntime, NcpAgentServerEndpoint, NcpAgentStreamProvider, NcpContextWindowUpdatedPayload, NcpEndpointEvent, NcpEndpointManifest, NcpEndpointSubscriber, NcpError, NcpErrorCode, NcpMessage, NcpMessageAbortPayload, NcpMessagePart, NcpMessageSentPayload, NcpReasoningDeltaPayload, NcpReasoningEndPayload, NcpReasoningStartPayload, NcpRequestEnvelope, NcpRunErrorPayload, NcpRunFinishedPayload, NcpRunMetadataPayload, NcpRunStartedPayload, NcpSessionApi, NcpSessionPatch, NcpSessionSummary, NcpStreamRequestPayload, NcpTextDeltaPayload, NcpTextEndPayload, NcpTextStartPayload, NcpToolCallArgsDeltaPayload, NcpToolCallArgsPayload, NcpToolCallEndPayload, NcpToolCallResultPayload, NcpToolCallStartPayload, OpenAITool } from "@nextclaw/ncp";
+import { NcpAgentClientEndpoint, NcpAgentConversationHydrationParams, NcpAgentConversationSnapshot, NcpAgentConversationStateManager, NcpAgentRunInput, NcpAgentRuntime, NcpAgentServerEndpoint, NcpContextWindowUpdatedPayload, NcpEndpointEvent, NcpEndpointSubscriber, NcpError, NcpErrorCode, NcpMessage, NcpMessageAbortPayload, NcpMessagePart, NcpMessageSentPayload, NcpReasoningDeltaPayload, NcpReasoningEndPayload, NcpReasoningStartPayload, NcpRequestEnvelope, NcpRunErrorPayload, NcpRunFinishedPayload, NcpRunMetadataPayload, NcpRunStartedPayload, NcpSessionSummary, NcpTextDeltaPayload, NcpTextEndPayload, NcpTextStartPayload, NcpToolCallArgsDeltaPayload, NcpToolCallArgsPayload, NcpToolCallEndPayload, NcpToolCallResultPayload, NcpToolCallStartPayload, OpenAITool } from "@nextclaw/ncp";
 
 //#region src/agent/agent-conversation-state-manager.d.ts
 declare class DefaultNcpAgentConversationStateManager implements NcpAgentConversationStateManager {
@@ -134,71 +134,6 @@ interface AgentSessionStore {
   deleteSession(sessionId: string): Promise<AgentSessionRecord | null>;
 }
 //#endregion
-//#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.service.d.ts
-type DefaultNcpAgentBackendConfig = {
-  createRuntime: CreateRuntimeFn;
-  sessionStore: AgentSessionStore;
-  resolveSessionContextWindow?: SessionContextWindowResolver;
-  onSessionRunStatusChanged?: (payload: {
-    sessionKey: string;
-    status: "running" | "idle";
-  }) => void;
-  endpointId?: string;
-  version?: string;
-  metadata?: Record<string, unknown>;
-  supportedPartTypes?: NcpEndpointManifest["supportedPartTypes"];
-  expectedLatency?: NcpEndpointManifest["expectedLatency"];
-};
-declare class DefaultNcpAgentBackend implements NcpAgentServerEndpoint, NcpSessionApi, NcpAgentStreamProvider, NcpAgentRunApi {
-  readonly manifest: NcpEndpointManifest & {
-    endpointKind: "agent";
-  };
-  private readonly sessionStore;
-  private readonly onSessionRunStatusChanged;
-  private readonly sessionRegistry;
-  private readonly executor;
-  private readonly publisher;
-  private readonly sessionRealtime;
-  private readonly resolveSessionContextWindow;
-  private started;
-  constructor(config: DefaultNcpAgentBackendConfig);
-  start: () => Promise<void>;
-  stop: () => Promise<void>;
-  emit: (event: NcpEndpointEvent) => Promise<void>;
-  subscribe: (listener: (event: NcpEndpointEvent) => void) => (() => void);
-  send: (envelope: NcpRequestEnvelope, options?: NcpAgentRunSendOptions) => AsyncIterable<NcpEndpointEvent>;
-  abort: (payload: NcpMessageAbortPayload) => Promise<void>;
-  stream: (payloadOrParams: NcpStreamRequestPayload | {
-    payload: NcpStreamRequestPayload;
-    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>;
-  updateToolCallResult: (sessionId: string, toolCallId: string, content: unknown) => Promise<NcpSessionSummary | null>;
-  updateSession: (sessionId: string, patch: NcpSessionPatch) => Promise<NcpSessionSummary | null>;
-  deleteSession: (sessionId: string) => Promise<void>;
-  private ensureStarted;
-  private startSessionExecution;
-  private finishSessionExecution;
-  private handleAbort;
-}
-//#endregion
-//#region src/agent/agent-backend/agent-run-executor.service.d.ts
-declare class AgentRunExecutor {
-  executeRun: (session: LiveSessionState, envelope: NcpRequestEnvelope, controller: AbortController) => AsyncGenerator<NcpEndpointEvent>;
-  private publishFailure;
-}
-//#endregion
 //#region src/agent/agent-backend/in-memory-agent-session.store.d.ts
 declare class InMemoryAgentSessionStore implements AgentSessionStore {
   private readonly sessions;
@@ -249,4 +184,4 @@ declare class NcpReplyConsumer {
   consume: (input: NcpReplyInput) => Promise<void>;
 }
 //#endregion
-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 };
+export { type AgentSessionEventRecord, type AgentSessionRecord, type AgentSessionStore, Chat, ChatTarget, type CreateRuntimeFn, DefaultNcpAgentConversationStateManager, EventPublisher, InMemoryAgentSessionStore, type LiveSessionExecution, type LiveSessionState, NcpErrorException, NcpEventStream, NcpReplyConsumer, NcpReplyInput, type RuntimeFactoryParams, createAgentClientFromServer };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { NcpEventType, consumeNcpRunHandle, createNcpRunHandle, isHiddenNcpMessage, sanitizeAssistantReplyTags } from "@nextclaw/ncp";
+import { NcpEventType, consumeNcpRunHandle, createNcpRunHandle, sanitizeAssistantReplyTags } from "@nextclaw/ncp";
 //#region src/agent/agent-conversation-message-normalizer.ts
 function cloneConversationMessage(message) {
 	return {
@@ -662,822 +662,6 @@ var EventPublisher = class {
 	}
 };
 //#endregion
-//#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();
-	return trimmed.length > 0 ? trimmed : void 0;
-}
-function readAgentIdFromMetadata$1(metadata) {
-	return readOptionalAgentId$2(metadata?.agent_id) ?? readOptionalAgentId$2(metadata?.agentId);
-}
-var AgentLiveSessionRegistry = class {
-	sessions = /* @__PURE__ */ new Map();
-	constructor(sessionStore, createRuntime) {
-		this.sessionStore = sessionStore;
-		this.createRuntime = createRuntime;
-	}
-	ensureSession = async (sessionId, initialMetadata) => {
-		const existing = this.sessions.get(sessionId);
-		if (existing) {
-			if (!existing.agentId) existing.agentId = readAgentIdFromMetadata$1(initialMetadata) ?? existing.agentId;
-			if (initialMetadata && Object.keys(initialMetadata).length > 0) existing.metadata = {
-				...existing.metadata,
-				...structuredClone(initialMetadata)
-			};
-			return existing;
-		}
-		const storedSession = await this.sessionStore.getSession(sessionId);
-		const stateManager = new DefaultNcpAgentConversationStateManager();
-		stateManager.hydrate({
-			sessionId,
-			messages: cloneMessages(storedSession?.messages ?? [])
-		});
-		const sessionMetadata = {
-			...storedSession?.metadata ? structuredClone(storedSession.metadata) : {},
-			...initialMetadata ? structuredClone(initialMetadata) : {}
-		};
-		const sessionAgentId = readOptionalAgentId$2(storedSession?.agentId) ?? readAgentIdFromMetadata$1(initialMetadata);
-		const session = {
-			sessionId,
-			...sessionAgentId ? { agentId: sessionAgentId } : {},
-			createdAt: storedSession?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-			stateManager,
-			metadata: sessionMetadata,
-			runtime: null,
-			publisher: new EventPublisher(),
-			activeExecution: null
-		};
-		session.runtime = this.createRuntime({
-			sessionId,
-			...sessionAgentId ? { agentId: sessionAgentId } : {},
-			stateManager,
-			sessionMetadata,
-			setSessionMetadata: (nextMetadata) => {
-				session.metadata = { ...structuredClone(nextMetadata) };
-			}
-		});
-		this.sessions.set(sessionId, session);
-		return session;
-	};
-	getSession = (sessionId) => {
-		return this.sessions.get(sessionId) ?? null;
-	};
-	deleteSession = (sessionId) => {
-		const session = this.sessions.get(sessionId) ?? null;
-		if (session) this.sessions.delete(sessionId);
-		return session;
-	};
-	clear = () => {
-		this.sessions.clear();
-	};
-	listSessions = () => {
-		return [...this.sessions.values()];
-	};
-};
-function cloneMessages(messages) {
-	return messages.map((message) => structuredClone(message));
-}
-//#endregion
-//#region src/errors/ncp-error-exception.ts
-/**
-* Throwable form of protocol error for exception-based control flows.
-*/
-var NcpErrorException = class extends Error {
-	code;
-	details;
-	constructor(code, message, details) {
-		super(message);
-		this.name = "NcpErrorException";
-		this.code = code;
-		this.details = details;
-	}
-};
-//#endregion
-//#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 });
-	const controller = new AbortController();
-	if (signal) signal.addEventListener("abort", () => controller.abort(), { once: true });
-	const execution = {
-		controller,
-		requestEnvelope: structuredClone(envelope),
-		abortHandled: false,
-		closed: false
-	};
-	session.activeExecution = execution;
-	onStatusChanged?.({
-		sessionKey: session.sessionId,
-		status: "running"
-	});
-	return execution;
-}
-function finishAgentBackendSessionExecution(params) {
-	const { session, execution, onStatusChanged } = params;
-	if (session.activeExecution === execution) {
-		session.activeExecution = null;
-		onStatusChanged?.({
-			sessionKey: session.sessionId,
-			status: "idle"
-		});
-	}
-}
-//#endregion
-//#region src/agent/agent-backend/agent-run-executor.service.ts
-var AgentRunExecutor = class {
-	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
-				}
-			};
-			await session.stateManager.dispatch(messageSent);
-			yield structuredClone(messageSent);
-		}
-		try {
-			for await (const event of session.runtime.run({
-				sessionId: envelope.sessionId,
-				messages: [envelope.message],
-				correlationId: envelope.correlationId,
-				metadata: envelope.metadata
-			}, { signal: controller.signal })) yield normalizeRunEvent(event, envelope);
-		} catch (error) {
-			if (!controller.signal.aborted) {
-				const runErrorEvent = await self.publishFailure(error, envelope, session);
-				yield structuredClone(runErrorEvent);
-			}
-		}
-	})(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() {
-	const items = [];
-	let closed = false;
-	let pendingResolve = null;
-	return {
-		push(item) {
-			if (closed) return;
-			if (pendingResolve) {
-				const resolve = pendingResolve;
-				pendingResolve = null;
-				resolve({
-					value: item,
-					done: false
-				});
-				return;
-			}
-			items.push(item);
-		},
-		close() {
-			if (closed) return;
-			closed = true;
-			if (pendingResolve) {
-				const resolve = pendingResolve;
-				pendingResolve = null;
-				resolve({
-					value: void 0,
-					done: true
-				});
-			}
-		},
-		iterable: { [Symbol.asyncIterator]() {
-			return { next: () => {
-				if (items.length > 0) return Promise.resolve({
-					value: items.shift(),
-					done: false
-				});
-				if (closed) return Promise.resolve({
-					value: void 0,
-					done: true
-				});
-				return new Promise((resolve) => {
-					pendingResolve = resolve;
-				});
-			} };
-		} }
-	};
-}
-//#endregion
-//#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;
-	return "sessionId" in payload && typeof payload.sessionId === "string" ? payload.sessionId : null;
-}
-var AgentBackendSessionRealtime = class {
-	constructor(params) {
-		this.params = params;
-	}
-	publishSessionEvent = async (session, event, options = {}) => {
-		if (options.dispatchToStateManager) await session.stateManager.dispatch(event);
-		if (options.persistSession !== false) await this.params.persistSessionEvent(session, event);
-		this.params.publishEndpointEvent(event);
-		session.publisher.publish(event);
-	};
-	streamSessionEvents = (payloadOrParams, opts) => {
-		return (async function* (self) {
-			const payload = "payload" in payloadOrParams && "signal" in payloadOrParams ? payloadOrParams.payload : payloadOrParams;
-			const signal = "payload" in payloadOrParams && "signal" in payloadOrParams ? payloadOrParams.signal : opts?.signal ?? new AbortController().signal;
-			const queue = createAsyncQueue();
-			const unsubscribe = self.params.subscribeEndpointEvent((event) => {
-				if (readEventSessionId(event) !== payload.sessionId) return;
-				queue.push(event);
-			});
-			const stop = () => {
-				unsubscribe();
-				queue.close();
-				signal.removeEventListener("abort", stop);
-			};
-			const liveSession = self.params.sessionRegistry.getSession(payload.sessionId);
-			const unsubscribeClose = liveSession ? liveSession.publisher.onClose(() => {
-				queue.close();
-			}) : () => void 0;
-			signal.addEventListener("abort", stop, { once: true });
-			try {
-				for await (const event of queue.iterable) {
-					if (signal.aborted) break;
-					yield event;
-				}
-			} finally {
-				unsubscribeClose();
-				stop();
-			}
-		})(this);
-	};
-	appendMessage = async (sessionId, message) => {
-		const normalizedSessionId = sessionId.trim();
-		if (!normalizedSessionId) return null;
-		let liveSession = this.params.sessionRegistry.getSession(normalizedSessionId);
-		if (!liveSession) {
-			if (!await this.params.sessionStore.getSession(normalizedSessionId)) return null;
-			liveSession = await this.params.sessionRegistry.ensureSession(normalizedSessionId);
-		}
-		const nextMessage = {
-			...structuredClone(message),
-			sessionId: normalizedSessionId
-		};
-		await this.publishSessionEvent(liveSession, {
-			type: NcpEventType.MessageSent,
-			payload: {
-				sessionId: normalizedSessionId,
-				message: nextMessage
-			}
-		}, { dispatchToStateManager: true });
-		return this.params.getSessionSummary(normalizedSessionId);
-	};
-	updateToolCallResult = async (sessionId, toolCallId, content) => {
-		const normalizedSessionId = sessionId.trim();
-		const normalizedToolCallId = toolCallId.trim();
-		if (!normalizedSessionId || !normalizedToolCallId) return null;
-		const liveSession = await this.params.sessionRegistry.ensureSession(normalizedSessionId);
-		await this.publishSessionEvent(liveSession, {
-			type: NcpEventType.MessageToolCallResult,
-			payload: {
-				sessionId: normalizedSessionId,
-				toolCallId: normalizedToolCallId,
-				content
-			}
-		}, { dispatchToStateManager: true });
-		return this.params.getSessionSummary(normalizedSessionId);
-	};
-};
-//#endregion
-//#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;
-	const trimmed = value.trim().toLowerCase();
-	return trimmed.length > 0 ? trimmed : void 0;
-}
-function readMessages(snapshot) {
-	const messages = snapshot.messages.map((message) => structuredClone(message));
-	if (snapshot.streamingMessage && !messages.some((message) => message.id === snapshot.streamingMessage?.id)) 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({
-			...session.metadata,
-			...liveSession?.metadata ? liveSession.metadata : {}
-		}) : liveSession?.metadata ? structuredClone(liveSession.metadata) : {},
-		messages: session.messages
-	});
-	return {
-		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",
-		...Object.keys(metadata).length > 0 ? { metadata } : {}
-	};
-}
-function toLiveSessionSummary(session) {
-	const messages = readMessages(session.stateManager.getSnapshot());
-	const updatedAt = now();
-	const metadata = withAutoSessionLabel({
-		metadata: Object.keys(session.metadata).length > 0 ? structuredClone(session.metadata) : session.activeExecution?.requestEnvelope.metadata ? structuredClone(session.activeExecution.requestEnvelope.metadata) : {},
-		messages
-	});
-	return {
-		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",
-		...Object.keys(metadata).length > 0 ? { metadata } : {}
-	};
-}
-function withSessionContextWindow(summary, messages, resolver) {
-	const contextWindow = resolver?.({
-		messages,
-		metadata: summary.metadata ?? {},
-		sessionId: summary.sessionId
-	});
-	return contextWindow ? {
-		...summary,
-		contextWindow
-	} : summary;
-}
-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();
-}
-function readOptionalString$1(value) {
-	if (typeof value !== "string") return null;
-	const trimmed = value.trim();
-	return trimmed.length > 0 ? trimmed : null;
-}
-function truncateLabel(value) {
-	const characters = Array.from(value);
-	if (characters.length <= AUTO_SESSION_LABEL_MAX_LENGTH) return value;
-	return `${characters.slice(0, AUTO_SESSION_LABEL_MAX_LENGTH).join("")}…`;
-}
-function resolveAutoSessionLabelFromMessages(messages) {
-	for (const message of messages) {
-		if (message.role !== "user") continue;
-		for (const part of message.parts) if (part.type === "text" || part.type === "rich-text") {
-			const text = readOptionalString$1(part.text);
-			if (text) return truncateLabel(text);
-		}
-	}
-	return null;
-}
-function withAutoSessionLabel(params) {
-	const { metadata, messages } = params;
-	if (readOptionalString$1(metadata.label)) return metadata;
-	const nextLabel = resolveAutoSessionLabelFromMessages(messages);
-	if (!nextLabel) return metadata;
-	return {
-		...metadata,
-		label: nextLabel
-	};
-}
-function findFinalAssistantMessageById(session, messageId) {
-	const normalizedMessageId = messageId.trim();
-	if (!normalizedMessageId) return null;
-	const snapshot = session.stateManager.getSnapshot();
-	for (let index = snapshot.messages.length - 1; index >= 0; index -= 1) {
-		const message = snapshot.messages[index];
-		if (message?.id === normalizedMessageId && message.role === "assistant" && message.status === "final") return message;
-	}
-	return null;
-}
-function buildCompletedEventForFinishedRun(session, event) {
-	const messageId = event.payload.messageId?.trim();
-	if (!messageId) throw new Error(`Run finished without messageId for session "${session.sessionId}".`);
-	const completedMessage = findFinalAssistantMessageById(session, messageId);
-	if (!completedMessage) throw new Error(`Run finished without a final assistant message for session "${session.sessionId}" and message "${messageId}".`);
-	return {
-		type: NcpEventType.MessageCompleted,
-		payload: {
-			sessionId: session.sessionId,
-			message: structuredClone(completedMessage)
-		}
-	};
-}
-function normalizeSendRunEvent(params) {
-	const { session, event } = params;
-	if (event.type === NcpEventType.MessageCompleted) {
-		if (params.completedMessageSeen) throw new Error(`Multiple final assistant messages were emitted for session "${session.sessionId}".`);
-		return {
-			eventsToPublish: [event],
-			completedMessageSeen: true
-		};
-	}
-	if (event.type === NcpEventType.RunFinished) {
-		if (params.completedMessageSeen) return {
-			eventsToPublish: [event],
-			completedMessageSeen: true
-		};
-		return {
-			eventsToPublish: [buildCompletedEventForFinishedRun(session, event), event],
-			completedMessageSeen: true
-		};
-	}
-	return {
-		eventsToPublish: [event],
-		completedMessageSeen: params.completedMessageSeen
-	};
-}
-//#endregion
-//#region src/agent/agent-backend/agent-backend-session-persistence.utils.ts
-function readOptionalAgentId(value) {
-	if (typeof value !== "string") return;
-	const trimmed = value.trim().toLowerCase();
-	return trimmed.length > 0 ? trimmed : void 0;
-}
-function readAgentIdFromMetadata(metadata) {
-	return readOptionalAgentId(metadata?.agent_id) ?? readOptionalAgentId(metadata?.agentId);
-}
-function buildPersistedLiveSessionRecord(params) {
-	const { session, sessionId, updatedAt } = params;
-	const messages = readMessages(session.stateManager.getSnapshot());
-	const metadata = withAutoSessionLabel({
-		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,
-		...agentId ? { agentId } : {},
-		messages,
-		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.service.ts
-const DEFAULT_SUPPORTED_PART_TYPES = [
-	"text",
-	"file",
-	"source",
-	"step-start",
-	"reasoning",
-	"tool-invocation",
-	"card",
-	"rich-text",
-	"action",
-	"extension"
-];
-const disposeRuntime = async (runtime) => {
-	await runtime.dispose?.();
-};
-function buildUpdatedMetadata(params) {
-	const { liveSession, patch, storedSession } = params;
-	if (patch.metadata === null) return {};
-	if (patch.metadata) return structuredClone(patch.metadata);
-	return structuredClone(liveSession?.metadata ?? storedSession?.metadata ?? {});
-}
-var DefaultNcpAgentBackend = class {
-	manifest;
-	sessionStore;
-	onSessionRunStatusChanged;
-	sessionRegistry;
-	executor;
-	publisher;
-	sessionRealtime;
-	resolveSessionContextWindow;
-	started = false;
-	constructor(config) {
-		this.sessionStore = config.sessionStore;
-		this.resolveSessionContextWindow = config.resolveSessionContextWindow;
-		this.onSessionRunStatusChanged = config.onSessionRunStatusChanged;
-		this.sessionRegistry = new AgentLiveSessionRegistry(this.sessionStore, config.createRuntime);
-		this.executor = new AgentRunExecutor();
-		this.publisher = new EventPublisher();
-		this.sessionRealtime = new AgentBackendSessionRealtime({
-			sessionRegistry: this.sessionRegistry,
-			sessionStore: this.sessionStore,
-			publishEndpointEvent: (event) => this.publisher.publish(event),
-			subscribeEndpointEvent: (listener) => this.publisher.subscribe(listener),
-			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 = {
-			endpointKind: "agent",
-			endpointId: config.endpointId?.trim() || "ncp-agent-backend",
-			version: config.version?.trim() || "0.1.0",
-			supportsStreaming: true,
-			supportsAbort: true,
-			supportsProactiveMessages: false,
-			supportsLiveSessionStream: true,
-			supportedPartTypes: config.supportedPartTypes ?? DEFAULT_SUPPORTED_PART_TYPES,
-			expectedLatency: config.expectedLatency ?? "seconds",
-			metadata: config.metadata
-		};
-	}
-	start = async () => {
-		if (this.started) return;
-		this.started = true;
-		this.publisher.publish({ type: NcpEventType.EndpointReady });
-	};
-	stop = async () => {
-		if (!this.started) return;
-		this.started = false;
-		for (const session of this.sessionRegistry.listSessions()) {
-			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();
-	};
-	emit = async (event) => {
-		await this.ensureStarted();
-		switch (event.type) {
-			case NcpEventType.MessageRequest:
-				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();
-				return;
-			case NcpEventType.MessageAbort:
-				await this.handleAbort(event.payload);
-				return;
-			default: this.publisher.publish(event);
-		}
-	};
-	subscribe = (listener) => this.publisher.subscribe(listener);
-	send = (envelope, options) => {
-		return (async function* (self) {
-			await self.ensureStarted();
-			const session = await self.sessionRegistry.ensureSession(envelope.sessionId, envelope.metadata);
-			const execution = self.startSessionExecution(session, envelope, options?.signal);
-			let completedMessageSeen = false;
-			try {
-				for await (const event of self.executor.executeRun(session, envelope, execution.controller)) {
-					const normalized = normalizeSendRunEvent({
-						session,
-						event,
-						completedMessageSeen
-					});
-					completedMessageSeen = normalized.completedMessageSeen;
-					for (const normalizedEvent of normalized.eventsToPublish) {
-						await self.sessionRealtime.publishSessionEvent(session, normalizedEvent);
-						yield normalizedEvent;
-					}
-				}
-				if (execution.controller.signal.aborted && !execution.abortHandled) {
-					const abortEvent = {
-						type: NcpEventType.MessageAbort,
-						payload: { sessionId: session.sessionId }
-					};
-					execution.abortHandled = true;
-					await self.sessionRealtime.publishSessionEvent(session, abortEvent, { dispatchToStateManager: true });
-					yield abortEvent;
-				}
-			} finally {
-				self.finishSessionExecution(session, execution);
-				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 () => {
-		return listBackendSessionSummaries({
-			sessionStore: this.sessionStore,
-			liveSessions: this.sessionRegistry.listSessions()
-		});
-	};
-	isLiveSessionRunning = (sessionId) => Boolean(this.sessionRegistry.getSession(sessionId)?.activeExecution);
-	listSessionMessages = async (sessionId) => {
-		return listBackendSessionMessages({
-			sessionStore: this.sessionStore,
-			liveSession: this.sessionRegistry.getSession(sessionId),
-			sessionId
-		});
-	};
-	getSession = async (sessionId) => {
-		return getBackendSessionSummary({
-			sessionStore: this.sessionStore,
-			liveSession: this.sessionRegistry.getSession(sessionId),
-			sessionId,
-			resolveSessionContextWindow: this.resolveSessionContextWindow
-		});
-	};
-	appendMessage = async (sessionId, message) => {
-		await this.ensureStarted();
-		return this.sessionRealtime.appendMessage(sessionId, message);
-	};
-	updateToolCallResult = async (sessionId, toolCallId, content) => {
-		await this.ensureStarted();
-		return this.sessionRealtime.updateToolCallResult(sessionId, toolCallId, content);
-	};
-	updateSession = async (sessionId, patch) => {
-		const liveSession = this.sessionRegistry.getSession(sessionId);
-		const storedSession = await this.sessionStore.getSession(sessionId);
-		if (!liveSession && !storedSession) return null;
-		const metadata = buildUpdatedMetadata({
-			liveSession,
-			patch,
-			storedSession
-		});
-		const updatedAt = now();
-		if (liveSession) liveSession.metadata = structuredClone(metadata);
-		await this.sessionStore.updateSessionMetadata({
-			sessionId,
-			metadata,
-			updatedAt
-		});
-		return this.getSession(sessionId);
-	};
-	deleteSession = async (sessionId) => {
-		const liveSession = this.sessionRegistry.deleteSession(sessionId);
-		const execution = liveSession?.activeExecution;
-		if (execution) {
-			execution.abortHandled = true;
-			execution.controller.abort();
-			execution.closed = true;
-		}
-		liveSession?.publisher.close();
-		if (liveSession) await disposeRuntime(liveSession.runtime);
-		await this.sessionStore.deleteSession(sessionId);
-	};
-	ensureStarted = async () => {
-		if (!this.started) await this.start();
-	};
-	startSessionExecution = (session, envelope, signal) => startAgentBackendSessionExecution({
-		session,
-		envelope,
-		signal,
-		onStatusChanged: this.onSessionRunStatusChanged
-	});
-	finishSessionExecution = (session, execution) => finishAgentBackendSessionExecution({
-		session,
-		execution,
-		onStatusChanged: this.onSessionRunStatusChanged
-	});
-	handleAbort = async (payload) => {
-		const session = this.sessionRegistry.getSession(payload.sessionId);
-		const execution = session?.activeExecution;
-		if (!session || !execution || execution.closed) return;
-		execution.abortHandled = true;
-		execution.controller.abort();
-		const abortEvent = {
-			type: NcpEventType.MessageAbort,
-			payload: {
-				sessionId: payload.sessionId,
-				...payload.messageId ? { messageId: payload.messageId } : {}
-			}
-		};
-		await this.sessionRealtime.publishSessionEvent(session, abortEvent, { dispatchToStateManager: true });
-		this.finishSessionExecution(session, execution);
-	};
-};
-//#endregion
 //#region src/agent/agent-backend/in-memory-agent-session.store.ts
 var InMemoryAgentSessionStore = class {
 	sessions = /* @__PURE__ */ new Map();
@@ -1510,6 +694,21 @@ var InMemoryAgentSessionStore = class {
 	};
 };
 //#endregion
+//#region src/errors/ncp-error-exception.ts
+/**
+* Throwable form of protocol error for exception-based control flows.
+*/
+var NcpErrorException = class extends Error {
+	code;
+	details;
+	constructor(code, message, details) {
+		super(message);
+		this.name = "NcpErrorException";
+		this.code = code;
+		this.details = details;
+	}
+};
+//#endregion
 //#region src/chat/ncp-reply-consumer.ts
 function isTextLikePart(part) {
 	return part.type === "text" || part.type === "rich-text";
@@ -1746,4 +945,4 @@ var NcpReplyConsumer = class {
 	};
 };
 //#endregion
-export { AgentRunExecutor, DefaultNcpAgentBackend, DefaultNcpAgentConversationStateManager, EventPublisher, InMemoryAgentSessionStore, NcpErrorException, NcpReplyConsumer, createAgentClientFromServer };
+export { DefaultNcpAgentConversationStateManager, EventPublisher, InMemoryAgentSessionStore, NcpErrorException, NcpReplyConsumer, createAgentClientFromServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-toolkit",
-  "version": "0.5.17",
+  "version": "0.5.18",
   "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.12"
+    "@nextclaw/ncp": "0.5.13"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",
     "prettier": "^3.3.3",
     "typescript": "^5.6.3",
     "vitest": "^4.1.2",
-    "@nextclaw/ncp-agent-runtime": "0.3.22"
+    "@nextclaw/ncp-agent-runtime": "0.3.23"
   },
   "scripts": {
     "build": "tsdown src/index.ts --dts --clean --target es2022 --no-fixedExtension",