@nextclaw/ncp-toolkit 0.4.16 → 0.5.0

package/dist/index.d.ts

@@ -69,6 +69,7 @@ declare class EventPublisher {
 
 type RuntimeFactoryParams = {
     sessionId: string;
+    agentId?: string;
     stateManager: NcpAgentConversationStateManager;
     sessionMetadata: Record<string, unknown>;
     setSessionMetadata: (nextMetadata: Record<string, unknown>) => void;
@@ -76,22 +77,24 @@ type RuntimeFactoryParams = {
 type CreateRuntimeFn = (params: RuntimeFactoryParams) => NcpAgentRuntime;
 type AgentSessionRecord = {
     sessionId: string;
+    agentId?: string;
     messages: NcpMessage[];
     updatedAt: string;
     metadata?: Record<string, unknown>;
 };
 type LiveSessionExecution = {
     controller: AbortController;
-    publisher: EventPublisher;
     requestEnvelope: NcpRequestEnvelope;
     abortHandled: boolean;
     closed: boolean;
 };
 type LiveSessionState = {
     sessionId: string;
+    agentId?: string;
     runtime: NcpAgentRuntime;
     stateManager: NcpAgentConversationStateManager;
     metadata: Record<string, unknown>;
+    publisher: EventPublisher;
     activeExecution: LiveSessionExecution | null;
 };
 interface AgentSessionStore {
@@ -124,12 +127,13 @@ declare class DefaultNcpAgentBackend implements NcpAgentServerEndpoint, NcpSessi
     private readonly sessionRegistry;
     private readonly executor;
     private readonly publisher;
+    private readonly sessionRealtime;
     private started;
     constructor(config: DefaultNcpAgentBackendConfig);
     start: () => Promise<void>;
     stop: () => Promise<void>;
     emit: (event: NcpEndpointEvent) => Promise<void>;
-    subscribe: (listener: (event: NcpEndpointEvent) => void) => () => void;
+    subscribe: (listener: (event: NcpEndpointEvent) => void) => (() => void);
     send: (envelope: NcpRequestEnvelope, options?: NcpAgentRunSendOptions) => AsyncIterable<NcpEndpointEvent>;
     abort: (payload: NcpMessageAbortPayload) => Promise<void>;
     stream: (payloadOrParams: NcpStreamRequestPayload | {
@@ -146,18 +150,12 @@ declare class DefaultNcpAgentBackend implements NcpAgentServerEndpoint, NcpSessi
     private ensureStarted;
     private startSessionExecution;
     private finishSessionExecution;
-    private closeExecution;
-    private publishLiveEvent;
-    private handleRequest;
-    private streamToSubscribers;
+    private publishEndpointEvent;
     private handleAbort;
-    private createAbortEvent;
     private persistSession;
 }
 
 declare class AgentRunExecutor {
-    private readonly persistSession;
-    constructor(persistSession: (sessionId: string) => Promise<void>);
     executeRun(session: LiveSessionState, envelope: NcpRequestEnvelope, controller: AbortController): AsyncGenerator<NcpEndpointEvent>;
     private publishFailure;
 }

package/dist/index.js

@@ -702,31 +702,77 @@ async function consume(events) {
 
 // src/agent/agent-backend/agent-backend.ts
 import {
-  NcpEventType as NcpEventType8
+  NcpEventType as NcpEventType6
 } from "@nextclaw/ncp";
 
-// src/errors/ncp-error-exception.ts
-var NcpErrorException = class extends Error {
-  code;
-  details;
-  constructor(code, message, details) {
-    super(message);
-    this.name = "NcpErrorException";
-    this.code = code;
-    this.details = details;
+// src/agent/agent-backend/event-publisher.ts
+var EventPublisher = class {
+  listeners = /* @__PURE__ */ new Set();
+  closeListeners = /* @__PURE__ */ new Set();
+  closed = false;
+  subscribe(listener) {
+    if (this.closed) {
+      return () => void 0;
+    }
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  onClose(listener) {
+    if (this.closed) {
+      listener();
+      return () => void 0;
+    }
+    this.closeListeners.add(listener);
+    return () => {
+      this.closeListeners.delete(listener);
+    };
+  }
+  publish(event) {
+    if (this.closed) {
+      return;
+    }
+    for (const listener of this.listeners) {
+      listener(structuredClone(event));
+    }
+  }
+  close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.listeners.clear();
+    for (const listener of this.closeListeners) {
+      listener();
+    }
+    this.closeListeners.clear();
   }
 };
 
 // src/agent/agent-backend/agent-live-session-registry.ts
+function readOptionalAgentId(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim().toLowerCase();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function readAgentIdFromMetadata(metadata) {
+  return readOptionalAgentId(metadata?.agent_id) ?? readOptionalAgentId(metadata?.agentId);
+}
 var AgentLiveSessionRegistry = class {
   constructor(sessionStore, createRuntime) {
     this.sessionStore = sessionStore;
     this.createRuntime = createRuntime;
   }
   sessions = /* @__PURE__ */ new Map();
-  async ensureSession(sessionId, initialMetadata) {
+  ensureSession = async (sessionId, initialMetadata) => {
     const existing = this.sessions.get(sessionId);
     if (existing) {
+      if (!existing.agentId) {
+        existing.agentId = readAgentIdFromMetadata(initialMetadata) ?? existing.agentId;
+      }
       if (initialMetadata && Object.keys(initialMetadata).length > 0) {
         existing.metadata = {
           ...existing.metadata,
@@ -745,15 +791,19 @@ var AgentLiveSessionRegistry = class {
       ...storedSession?.metadata ? structuredClone(storedSession.metadata) : {},
       ...initialMetadata ? structuredClone(initialMetadata) : {}
     };
+    const sessionAgentId = readOptionalAgentId(storedSession?.agentId) ?? readAgentIdFromMetadata(initialMetadata);
     const session = {
       sessionId,
+      ...sessionAgentId ? { agentId: sessionAgentId } : {},
       stateManager,
       metadata: sessionMetadata,
       runtime: null,
+      publisher: new EventPublisher(),
       activeExecution: null
     };
     session.runtime = this.createRuntime({
       sessionId,
+      ...sessionAgentId ? { agentId: sessionAgentId } : {},
       stateManager,
       sessionMetadata,
       setSessionMetadata: (nextMetadata) => {
@@ -764,37 +814,87 @@ var AgentLiveSessionRegistry = class {
     });
     this.sessions.set(sessionId, session);
     return session;
-  }
-  getSession(sessionId) {
+  };
+  getSession = (sessionId) => {
     return this.sessions.get(sessionId) ?? null;
-  }
-  deleteSession(sessionId) {
+  };
+  deleteSession = (sessionId) => {
     const session = this.sessions.get(sessionId) ?? null;
     if (session) {
       this.sessions.delete(sessionId);
     }
     return session;
-  }
-  clear() {
+  };
+  clear = () => {
     this.sessions.clear();
-  }
-  listSessions() {
+  };
+  listSessions = () => {
     return [...this.sessions.values()];
-  }
+  };
 };
 function cloneMessages(messages) {
   return messages.map((message) => structuredClone(message));
 }
 
+// src/errors/ncp-error-exception.ts
+var NcpErrorException = class extends Error {
+  code;
+  details;
+  constructor(code, message, details) {
+    super(message);
+    this.name = "NcpErrorException";
+    this.code = code;
+    this.details = details;
+  }
+};
+
+// 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" });
+  }
+  closeAgentBackendSessionExecution(execution);
+}
+function closeAgentBackendSessionExecution(execution) {
+  if (execution.closed) {
+    return;
+  }
+  execution.closed = true;
+}
+
 // src/agent/agent-backend/agent-run-executor.ts
 import {
   isHiddenNcpMessage
 } from "@nextclaw/ncp";
 import { NcpEventType as NcpEventType3 } from "@nextclaw/ncp";
 var AgentRunExecutor = class {
-  constructor(persistSession) {
-    this.persistSession = persistSession;
-  }
   async *executeRun(session, envelope, controller) {
     if (!isHiddenNcpMessage(envelope.message)) {
       const messageSent = {
@@ -806,7 +906,6 @@ var AgentRunExecutor = class {
         }
       };
       await session.stateManager.dispatch(messageSent);
-      await this.persistSession(envelope.sessionId);
       yield structuredClone(messageSent);
     }
     try {
@@ -819,16 +918,17 @@ var AgentRunExecutor = class {
         },
         { signal: controller.signal }
       )) {
-        await this.persistSession(envelope.sessionId);
         yield structuredClone(event);
       }
     } catch (error) {
       if (!controller.signal.aborted) {
-        const runErrorEvent = await this.publishFailure(error, envelope, session);
+        const runErrorEvent = await this.publishFailure(
+          error,
+          envelope,
+          session
+        );
         yield structuredClone(runErrorEvent);
       }
-    } finally {
-      await this.persistSession(envelope.sessionId);
     }
   }
   async publishFailure(error, envelope, session) {
@@ -841,14 +941,187 @@ var AgentRunExecutor = class {
       }
     };
     await session.stateManager.dispatch(runErrorEvent);
-    await this.persistSession(envelope.sessionId);
     return runErrorEvent;
   }
 };
 
-// src/agent/agent-backend/agent-backend-session-utils.ts
+// src/agent/agent-backend/agent-backend-session-realtime.ts
 import { NcpEventType as NcpEventType4 } from "@nextclaw/ncp";
+
+// src/agent/agent-backend/async-queue.ts
+function createAsyncQueue() {
+  const items = [];
+  let closed = false;
+  let pendingResolve = null;
+  const 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;
+          });
+        }
+      };
+    }
+  };
+  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
+  };
+}
+
+// src/agent/agent-backend/agent-backend-session-realtime.ts
+var AgentBackendSessionRealtime = class {
+  constructor(params) {
+    this.params = params;
+  }
+  publishSessionEvent = async (session, event, options = {}) => {
+    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);
+    }
+  };
+  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 session = await self.params.sessionRegistry.ensureSession(
+        payload.sessionId
+      );
+      const queue = createAsyncQueue();
+      const unsubscribe = session.publisher.subscribe((event) => {
+        queue.push(event);
+      });
+      const unsubscribeClose = session.publisher.onClose(() => {
+        queue.close();
+      });
+      const stop = () => {
+        unsubscribe();
+        unsubscribeClose();
+        queue.close();
+        signal.removeEventListener("abort", stop);
+      };
+      signal.addEventListener("abort", stop, { once: true });
+      try {
+        for await (const event of queue.iterable) {
+          if (signal.aborted) {
+            break;
+          }
+          yield event;
+        }
+      } finally {
+        stop();
+      }
+    })(this);
+  };
+  appendMessage = async (sessionId, message) => {
+    const normalizedSessionId = sessionId.trim();
+    if (!normalizedSessionId) {
+      return null;
+    }
+    let liveSession = this.params.sessionRegistry.getSession(normalizedSessionId);
+    if (!liveSession) {
+      const storedSession = await this.params.sessionStore.getSession(normalizedSessionId);
+      if (!storedSession) {
+        return null;
+      }
+      liveSession = await this.params.sessionRegistry.ensureSession(normalizedSessionId);
+    }
+    const nextMessage = {
+      ...structuredClone(message),
+      sessionId: normalizedSessionId
+    };
+    await this.publishSessionEvent(
+      liveSession,
+      {
+        type: NcpEventType4.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: NcpEventType4.MessageToolCallResult,
+        payload: {
+          sessionId: normalizedSessionId,
+          toolCallId: normalizedToolCallId,
+          content
+        }
+      },
+      {
+        dispatchToStateManager: true
+      }
+    );
+    return this.params.getSessionSummary(normalizedSessionId);
+  };
+};
+
+// src/agent/agent-backend/agent-backend-session-utils.ts
+import { NcpEventType as NcpEventType5 } from "@nextclaw/ncp";
 var AUTO_SESSION_LABEL_MAX_LENGTH = 64;
+function readOptionalAgentId2(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  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) {
@@ -866,6 +1139,7 @@ function toSessionSummary(session, liveSession) {
   });
   return {
     sessionId: session.sessionId,
+    ...readOptionalAgentId2(session.agentId) ? { agentId: readOptionalAgentId2(session.agentId) } : {},
     messageCount: session.messages.length,
     updatedAt: session.updatedAt,
     status: liveSession?.activeExecution ? "running" : "idle",
@@ -881,6 +1155,7 @@ function toLiveSessionSummary(session) {
   });
   return {
     sessionId: session.sessionId,
+    ...readOptionalAgentId2(session.agentId) ? { agentId: readOptionalAgentId2(session.agentId) } : {},
     messageCount: messages.length,
     updatedAt: now(),
     status: session.activeExecution ? "running" : "idle",
@@ -934,18 +1209,21 @@ function withAutoSessionLabel(params) {
     label: nextLabel
   };
 }
-function isTerminalEvent(event) {
-  switch (event.type) {
-    case NcpEventType4.MessageAbort:
-    case NcpEventType4.RunFinished:
-    case NcpEventType4.RunError:
-      return true;
-    default:
-      return false;
-  }
-}
 
 // src/agent/agent-backend/agent-backend-session-persistence.ts
+function readOptionalAgentId3(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim().toLowerCase();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function readAgentIdFromMetadata2(metadata) {
+  return readOptionalAgentId3(metadata?.agent_id) ?? readOptionalAgentId3(metadata?.agentId);
+}
+function resolvePersistedAgentId(params) {
+  return readOptionalAgentId3(params.liveSession?.agentId) ?? readOptionalAgentId3(params.storedSession?.agentId) ?? readAgentIdFromMetadata2(params.liveSession?.metadata) ?? readAgentIdFromMetadata2(params.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) {
@@ -953,6 +1231,15 @@ function buildUpdatedSessionRecord(params) {
   }
   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,
     metadata: nextMetadata
@@ -969,228 +1256,28 @@ function buildPersistedLiveSessionRecord(params) {
   });
   return {
     sessionId: params.sessionId,
+    ...readOptionalAgentId3(params.session.agentId) ?? readAgentIdFromMetadata2(params.session.metadata) ?? readAgentIdFromMetadata2(params.session.activeExecution?.requestEnvelope.metadata) ? {
+      agentId: readOptionalAgentId3(params.session.agentId) ?? readAgentIdFromMetadata2(params.session.metadata) ?? readAgentIdFromMetadata2(params.session.activeExecution?.requestEnvelope.metadata)
+    } : {},
     messages,
     updatedAt: params.updatedAt,
     metadata
   };
 }
 
-// src/agent/agent-backend/agent-backend-update-tool-call-result.ts
-import { NcpEventType as NcpEventType5 } from "@nextclaw/ncp";
-async function updateAgentBackendToolCallResult(params) {
-  const normalizedSessionId = params.sessionId.trim();
-  const normalizedToolCallId = params.toolCallId.trim();
-  if (!normalizedSessionId || !normalizedToolCallId) {
-    return null;
-  }
-  const liveSession = await params.sessionRegistry.ensureSession(normalizedSessionId);
-  const event = {
-    type: NcpEventType5.MessageToolCallResult,
-    payload: {
-      sessionId: normalizedSessionId,
-      toolCallId: normalizedToolCallId,
-      content: params.content
-    }
-  };
-  await liveSession.stateManager.dispatch(event);
-  params.publisher.publish(event);
-  if (liveSession.activeExecution && !liveSession.activeExecution.closed) {
-    liveSession.activeExecution.publisher.publish(event);
-  }
-  await params.persistSession(normalizedSessionId);
-  return params.getSession(normalizedSessionId);
-}
-
-// src/agent/agent-backend/agent-backend-append-message.ts
-import { NcpEventType as NcpEventType6 } from "@nextclaw/ncp";
-async function appendAgentBackendMessage(params) {
-  const normalizedSessionId = params.sessionId.trim();
-  if (!normalizedSessionId) {
-    return null;
-  }
-  let liveSession = params.sessionRegistry.getSession(normalizedSessionId);
-  if (!liveSession) {
-    const storedSession = await params.sessionStore.getSession(normalizedSessionId);
-    if (!storedSession) {
-      return null;
-    }
-    liveSession = await params.sessionRegistry.ensureSession(normalizedSessionId);
-  }
-  const nextMessage = {
-    ...structuredClone(params.message),
-    sessionId: normalizedSessionId
-  };
-  const event = {
-    type: NcpEventType6.MessageSent,
-    payload: {
-      sessionId: normalizedSessionId,
-      message: nextMessage
-    }
-  };
-  await liveSession.stateManager.dispatch(event);
-  params.publisher.publish(event);
-  if (liveSession.activeExecution && !liveSession.activeExecution.closed) {
-    liveSession.activeExecution.publisher.publish(event);
-  }
-  await params.persistSession(normalizedSessionId);
-  return params.getSession(normalizedSessionId);
-}
-
-// src/agent/agent-backend/agent-backend-stream.ts
-import { NcpEventType as NcpEventType7 } from "@nextclaw/ncp";
-
-// src/agent/agent-backend/async-queue.ts
-function createAsyncQueue() {
-  const items = [];
-  let closed = false;
-  let pendingResolve = null;
-  const 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;
-          });
-        }
-      };
-    }
-  };
-  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
-  };
-}
-
-// src/agent/agent-backend/agent-backend-stream.ts
-async function* streamAgentBackendExecution(params) {
-  const payload = "payload" in params.payloadOrParams && "signal" in params.payloadOrParams ? params.payloadOrParams.payload : params.payloadOrParams;
-  const signal = "payload" in params.payloadOrParams && "signal" in params.payloadOrParams ? params.payloadOrParams.signal : params.opts?.signal ?? new AbortController().signal;
-  const session = params.sessionRegistry.getSession(payload.sessionId);
-  const execution = session?.activeExecution;
-  if (!session || !execution || execution.closed) {
-    if (session) {
-      yield {
-        type: NcpEventType7.RunFinished,
-        payload: {
-          sessionId: payload.sessionId
-        }
-      };
-    }
-    return;
-  }
-  const queue = createAsyncQueue();
-  const unsubscribe = execution.publisher.subscribe((event) => {
-    queue.push(event);
-  });
-  const unsubscribeClose = execution.publisher.onClose(() => {
-    queue.close();
-  });
-  const stop = () => {
-    unsubscribe();
-    unsubscribeClose();
-    queue.close();
-    signal.removeEventListener("abort", stop);
-  };
-  signal.addEventListener("abort", stop, { once: true });
-  try {
-    for await (const event of queue.iterable) {
-      if (signal.aborted) {
-        break;
-      }
-      yield event;
-      if (isTerminalEvent(event)) {
-        break;
-      }
-    }
-  } finally {
-    stop();
-  }
-}
-
-// src/agent/agent-backend/event-publisher.ts
-var EventPublisher = class {
-  listeners = /* @__PURE__ */ new Set();
-  closeListeners = /* @__PURE__ */ new Set();
-  closed = false;
-  subscribe(listener) {
-    if (this.closed) {
-      return () => void 0;
-    }
-    this.listeners.add(listener);
-    return () => {
-      this.listeners.delete(listener);
-    };
-  }
-  onClose(listener) {
-    if (this.closed) {
-      listener();
-      return () => void 0;
-    }
-    this.closeListeners.add(listener);
-    return () => {
-      this.closeListeners.delete(listener);
-    };
-  }
-  publish(event) {
-    if (this.closed) {
-      return;
-    }
-    for (const listener of this.listeners) {
-      listener(structuredClone(event));
-    }
-  }
-  close() {
-    if (this.closed) {
-      return;
-    }
-    this.closed = true;
-    this.listeners.clear();
-    for (const listener of this.closeListeners) {
-      listener();
-    }
-    this.closeListeners.clear();
-  }
-};
-
 // src/agent/agent-backend/agent-backend.ts
-var DEFAULT_SUPPORTED_PART_TYPES = ["text", "file", "source", "step-start", "reasoning", "tool-invocation", "card", "rich-text", "action", "extension"];
+var DEFAULT_SUPPORTED_PART_TYPES = [
+  "text",
+  "file",
+  "source",
+  "step-start",
+  "reasoning",
+  "tool-invocation",
+  "card",
+  "rich-text",
+  "action",
+  "extension"
+];
 var DefaultNcpAgentBackend = class {
   manifest;
   sessionStore;
@@ -1198,13 +1285,24 @@ var DefaultNcpAgentBackend = class {
   sessionRegistry;
   executor;
   publisher;
+  sessionRealtime;
   started = false;
   constructor(config) {
     this.sessionStore = config.sessionStore;
     this.onSessionRunStatusChanged = config.onSessionRunStatusChanged;
-    this.sessionRegistry = new AgentLiveSessionRegistry(this.sessionStore, config.createRuntime);
-    this.executor = new AgentRunExecutor(async (sessionId) => this.persistSession(sessionId));
+    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.publishEndpointEvent(event),
+      persistSession: (sessionId) => this.persistSession(sessionId),
+      getSessionSummary: (sessionId) => this.getSession(sessionId)
+    });
     this.manifest = {
       endpointKind: "agent",
       endpointId: config.endpointId?.trim() || "ncp-agent-backend",
@@ -1223,7 +1321,7 @@ var DefaultNcpAgentBackend = class {
       return;
     }
     this.started = true;
-    this.publisher.publish({ type: NcpEventType8.EndpointReady });
+    this.publisher.publish({ type: NcpEventType6.EndpointReady });
   };
   stop = async () => {
     if (!this.started) {
@@ -1233,24 +1331,28 @@ var DefaultNcpAgentBackend = class {
     for (const session of this.sessionRegistry.listSessions()) {
       const execution = session.activeExecution;
       if (!execution) {
+        session.publisher.close();
         continue;
       }
       execution.abortHandled = true;
       execution.controller.abort();
       this.finishSessionExecution(session, execution);
+      session.publisher.close();
     }
     this.sessionRegistry.clear();
   };
   emit = async (event) => {
     await this.ensureStarted();
     switch (event.type) {
-      case NcpEventType8.MessageRequest:
-        await this.handleRequest(event.payload);
+      case NcpEventType6.MessageRequest:
+        for await (const emittedEvent of this.send(event.payload)) {
+          void emittedEvent;
+        }
         return;
-      case NcpEventType8.MessageStreamRequest:
-        await this.streamToSubscribers(event.payload);
+      case NcpEventType6.MessageStreamRequest:
+        await this.ensureStarted();
         return;
-      case NcpEventType8.MessageAbort:
+      case NcpEventType6.MessageAbort:
         await this.handleAbort(event.payload);
         return;
       default:
@@ -1278,13 +1380,20 @@ var DefaultNcpAgentBackend = class {
           envelope,
           execution.controller
         )) {
-          self.publishLiveEvent(execution, event);
+          await self.sessionRealtime.publishSessionEvent(session, event);
           yield event;
         }
         if (execution.controller.signal.aborted && !execution.abortHandled) {
-          const abortEvent = await self.createAbortEvent(session.sessionId);
+          const abortEvent = {
+            type: NcpEventType6.MessageAbort,
+            payload: {
+              sessionId: session.sessionId
+            }
+          };
           execution.abortHandled = true;
-          self.publishLiveEvent(execution, abortEvent);
+          await self.sessionRealtime.publishSessionEvent(session, abortEvent, {
+            dispatchToStateManager: true
+          });
           yield abortEvent;
         }
       } finally {
@@ -1296,15 +1405,14 @@ var DefaultNcpAgentBackend = class {
   abort = async (payload) => {
     await this.handleAbort(payload);
   };
-  stream = (payloadOrParams, opts) => streamAgentBackendExecution({
-    payloadOrParams,
-    opts,
-    sessionRegistry: this.sessionRegistry
-  });
+  stream = (payloadOrParams, opts) => this.sessionRealtime.streamSessionEvents(payloadOrParams, opts);
   listSessions = async () => {
     const storedSessions = await this.sessionStore.listSessions();
     const summaries = storedSessions.map(
-      (session) => toSessionSummary(session, this.sessionRegistry.getSession(session.sessionId))
+      (session) => toSessionSummary(
+        session,
+        this.sessionRegistry.getSession(session.sessionId)
+      )
     );
     for (const liveSession of this.sessionRegistry.listSessions()) {
       if (summaries.some((session) => session.sessionId === liveSession.sessionId)) {
@@ -1312,11 +1420,14 @@ var DefaultNcpAgentBackend = class {
       }
       summaries.push(toLiveSessionSummary(liveSession));
     }
-    return summaries.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    return summaries.sort(
+      (left, right) => right.updatedAt.localeCompare(left.updatedAt)
+    );
   };
   listSessionMessages = async (sessionId) => {
     const liveSession = this.sessionRegistry.getSession(sessionId);
-    if (liveSession) return readMessages(liveSession.stateManager.getSnapshot());
+    if (liveSession)
+      return readMessages(liveSession.stateManager.getSnapshot());
     const session = await this.sessionStore.getSession(sessionId);
     return session ? session.messages.map((message) => structuredClone(message)) : [];
   };
@@ -1327,39 +1438,29 @@ var DefaultNcpAgentBackend = class {
   };
   appendMessage = async (sessionId, message) => {
     await this.ensureStarted();
-    return appendAgentBackendMessage({
-      sessionId,
-      message,
-      sessionRegistry: this.sessionRegistry,
-      sessionStore: this.sessionStore,
-      publisher: this.publisher,
-      persistSession: async (nextSessionId) => this.persistSession(nextSessionId),
-      getSession: async (nextSessionId) => this.getSession(nextSessionId)
-    });
+    return this.sessionRealtime.appendMessage(sessionId, message);
   };
   updateToolCallResult = async (sessionId, toolCallId, content) => {
     await this.ensureStarted();
-    return updateAgentBackendToolCallResult({
+    return this.sessionRealtime.updateToolCallResult(
       sessionId,
       toolCallId,
-      content,
-      sessionRegistry: this.sessionRegistry,
-      publisher: this.publisher,
-      persistSession: async (nextSessionId) => this.persistSession(nextSessionId),
-      getSession: async (nextSessionId) => this.getSession(nextSessionId)
-    });
+      content
+    );
   };
   updateSession = async (sessionId, patch) => {
     const liveSession = this.sessionRegistry.getSession(sessionId);
     const storedSession = await this.sessionStore.getSession(sessionId);
     if (!liveSession && !storedSession) return null;
-    await this.sessionStore.replaceSession(buildUpdatedSessionRecord({
-      sessionId,
-      patch,
-      liveSession,
-      storedSession,
-      updatedAt: now()
-    }));
+    await this.sessionStore.replaceSession(
+      buildUpdatedSessionRecord({
+        sessionId,
+        patch,
+        liveSession,
+        storedSession,
+        updatedAt: now()
+      })
+    );
     return this.getSession(sessionId);
   };
   deleteSession = async (sessionId) => {
@@ -1368,8 +1469,9 @@ var DefaultNcpAgentBackend = class {
     if (execution) {
       execution.abortHandled = true;
       execution.controller.abort();
-      this.closeExecution(execution);
+      closeAgentBackendSessionExecution(execution);
     }
+    liveSession?.publisher.close();
     await this.sessionStore.deleteSession(sessionId);
   };
   ensureStarted = async () => {
@@ -1377,61 +1479,19 @@ var DefaultNcpAgentBackend = class {
       await this.start();
     }
   };
-  startSessionExecution = (session, envelope, signal) => {
-    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,
-      publisher: new EventPublisher(),
-      requestEnvelope: structuredClone(envelope),
-      abortHandled: false,
-      closed: false
-    };
-    session.activeExecution = execution;
-    this.onSessionRunStatusChanged?.({ sessionKey: session.sessionId, status: "running" });
-    return execution;
-  };
-  finishSessionExecution = (session, execution) => {
-    if (session.activeExecution === execution) {
-      session.activeExecution = null;
-      this.onSessionRunStatusChanged?.({ sessionKey: session.sessionId, status: "idle" });
-    }
-    this.closeExecution(execution);
-  };
-  closeExecution = (execution) => {
-    if (execution.closed) {
-      return;
-    }
-    execution.closed = true;
-    execution.publisher.close();
-  };
-  publishLiveEvent = (execution, event) => {
+  startSessionExecution = (session, envelope, signal) => startAgentBackendSessionExecution({
+    session,
+    envelope,
+    signal,
+    onStatusChanged: this.onSessionRunStatusChanged
+  });
+  finishSessionExecution = (session, execution) => finishAgentBackendSessionExecution({
+    session,
+    execution,
+    onStatusChanged: this.onSessionRunStatusChanged
+  });
+  publishEndpointEvent = (event) => {
     this.publisher.publish(event);
-    if (!execution.closed) {
-      execution.publisher.publish(event);
-    }
-  };
-  handleRequest = async (envelope) => {
-    for await (const event of this.send(envelope)) {
-      void event;
-    }
-  };
-  streamToSubscribers = async (payload) => {
-    const signal = new AbortController().signal;
-    for await (const event of this.stream({ payload, signal })) {
-      void event;
-    }
   };
   handleAbort = async (payload) => {
     const session = this.sessionRegistry.getSession(payload.sessionId);
@@ -1441,33 +1501,28 @@ var DefaultNcpAgentBackend = class {
     }
     execution.abortHandled = true;
     execution.controller.abort();
-    const abortEvent = await this.createAbortEvent(payload.sessionId, payload.messageId);
-    this.publishLiveEvent(execution, abortEvent);
-    this.finishSessionExecution(session, execution);
-  };
-  createAbortEvent = async (sessionId, messageId) => {
     const abortEvent = {
-      type: NcpEventType8.MessageAbort,
+      type: NcpEventType6.MessageAbort,
       payload: {
-        sessionId,
-        ...messageId ? { messageId } : {}
+        sessionId: payload.sessionId,
+        ...payload.messageId ? { messageId: payload.messageId } : {}
       }
     };
-    const liveSession = this.sessionRegistry.getSession(sessionId);
-    if (liveSession) {
-      await liveSession.stateManager.dispatch(abortEvent);
-    }
-    await this.persistSession(sessionId);
-    return abortEvent;
+    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()
-    }));
+    await this.sessionStore.saveSession(
+      buildPersistedLiveSessionRecord({
+        sessionId,
+        session,
+        updatedAt: now()
+      })
+    );
   };
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-toolkit",
-  "version": "0.4.16",
+  "version": "0.5.0",
   "private": false,
   "description": "Toolkit implementations built on top of the NextClaw Communication Protocol.",
   "type": "module",
@@ -15,7 +15,7 @@
     "dist"
   ],
   "dependencies": {
-    "@nextclaw/ncp": "0.4.6"
+    "@nextclaw/ncp": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",
@@ -23,7 +23,7 @@
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "vitest": "^4.1.2",
-    "@nextclaw/ncp-agent-runtime": "0.3.6"
+    "@nextclaw/ncp-agent-runtime": "0.3.7"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --out-dir dist",