@nextclaw/ncp-toolkit 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NcpAgentConversationStateManager, NcpAgentConversationSnapshot, NcpAgentConversationHydrationParams, NcpEndpointEvent, NcpMessageSentPayload, NcpMessageAbortPayload, NcpTextStartPayload, NcpTextDeltaPayload, NcpTextEndPayload, NcpReasoningStartPayload, NcpReasoningDeltaPayload, NcpReasoningEndPayload, NcpToolCallStartPayload, NcpToolCallArgsPayload, NcpToolCallArgsDeltaPayload, NcpToolCallEndPayload, NcpToolCallResultPayload, NcpRunStartedPayload, NcpRunFinishedPayload, NcpRunErrorPayload, NcpRunMetadataPayload, NcpError, NcpAgentServerEndpoint, NcpAgentClientEndpoint, NcpEndpointSubscriber, NcpAgentRuntime, NcpRequestEnvelope, NcpMessage, NcpSessionApi, NcpAgentStreamProvider, NcpAgentRunApi, NcpEndpointManifest, NcpAgentRunSendOptions, NcpStreamRequestPayload, NcpAgentRunStreamOptions, NcpSessionSummary, NcpErrorCode } from '@nextclaw/ncp';
+import { NcpAgentConversationStateManager, NcpAgentConversationSnapshot, NcpAgentConversationHydrationParams, NcpEndpointEvent, NcpMessageSentPayload, NcpMessageAbortPayload, NcpTextStartPayload, NcpTextDeltaPayload, NcpTextEndPayload, NcpReasoningStartPayload, NcpReasoningDeltaPayload, NcpReasoningEndPayload, NcpToolCallStartPayload, NcpToolCallArgsPayload, NcpToolCallArgsDeltaPayload, NcpToolCallEndPayload, NcpToolCallResultPayload, NcpRunStartedPayload, NcpRunFinishedPayload, NcpRunErrorPayload, NcpRunMetadataPayload, NcpError, NcpAgentServerEndpoint, NcpAgentClientEndpoint, NcpEndpointSubscriber, NcpAgentRuntime, NcpRequestEnvelope, NcpMessage, NcpSessionApi, NcpAgentStreamProvider, NcpAgentRunApi, NcpEndpointManifest, NcpAgentRunSendOptions, NcpStreamRequestPayload, NcpAgentRunStreamOptions, NcpSessionSummary, NcpSessionPatch, NcpErrorCode } from '@nextclaw/ncp';
 
 declare class DefaultNcpAgentConversationStateManager implements NcpAgentConversationStateManager {
     private messages;
@@ -38,14 +38,10 @@ declare class DefaultNcpAgentConversationStateManager implements NcpAgentConvers
     private ensureStreamingMessage;
     private resolveToolCallTargetMessage;
     private updateMessageContainingToolCall;
-    private findToolInvocationPart;
-    private findToolNameByCallId;
-    private upsertToolInvocationPart;
     private upsertMessage;
     private replaceStreamingMessage;
     private setError;
     private clearActiveRun;
-    private clearToolCallTrackingByMessageId;
     private notifyListeners;
 }
 
@@ -68,12 +64,15 @@ declare class EventPublisher {
 type RuntimeFactoryParams = {
     sessionId: string;
     stateManager: NcpAgentConversationStateManager;
+    sessionMetadata: Record<string, unknown>;
+    setSessionMetadata: (nextMetadata: Record<string, unknown>) => void;
 };
 type CreateRuntimeFn = (params: RuntimeFactoryParams) => NcpAgentRuntime;
 type AgentSessionRecord = {
     sessionId: string;
     messages: NcpMessage[];
     updatedAt: string;
+    metadata?: Record<string, unknown>;
 };
 type LiveSessionExecution = {
     controller: AbortController;
@@ -86,6 +85,7 @@ type LiveSessionState = {
     sessionId: string;
     runtime: NcpAgentRuntime;
     stateManager: NcpAgentConversationStateManager;
+    metadata: Record<string, unknown>;
     activeExecution: LiveSessionExecution | null;
 };
 interface AgentSessionStore {
@@ -127,6 +127,7 @@ declare class DefaultNcpAgentBackend implements NcpAgentServerEndpoint, NcpSessi
     listSessions(): Promise<NcpSessionSummary[]>;
     listSessionMessages(sessionId: string): Promise<NcpMessage[]>;
     getSession(sessionId: string): Promise<NcpSessionSummary | null>;
+    updateSession(sessionId: string, patch: NcpSessionPatch): Promise<NcpSessionSummary | null>;
     deleteSession(sessionId: string): Promise<void>;
     private ensureStarted;
     private startSessionExecution;

package/dist/index.js

@@ -2,15 +2,22 @@
 import {
   NcpEventType
 } from "@nextclaw/ncp";
-var DEFAULT_ASSISTANT_ROLE = "assistant";
-var cloneMessage = (message) => {
+
+// src/agent/agent-conversation-message-normalizer.ts
+import { sanitizeAssistantReplyTags } from "@nextclaw/ncp";
+function cloneConversationMessage(message) {
   return {
     ...message,
     parts: [...message.parts],
     metadata: message.metadata ? { ...message.metadata } : void 0
   };
-};
-var buildRuntimeError = (payload) => {
+}
+function normalizeConversationMessage(message) {
+  return cloneConversationMessage(sanitizeAssistantReplyTags(message));
+}
+
+// src/agent/agent-conversation-state-manager.utils.ts
+function buildRuntimeError(payload) {
   const message = payload.error?.trim();
   return {
     code: "runtime-error",
@@ -22,7 +29,64 @@ var buildRuntimeError = (payload) => {
       runId: payload.runId
     }
   };
-};
+}
+function shouldPromoteStreamingMessageId(message, nextMessageId) {
+  if (!nextMessageId.trim()) {
+    return false;
+  }
+  if (message.id.startsWith("tool-")) {
+    return true;
+  }
+  return message.parts.some((part) => part.type === "tool-invocation");
+}
+function remapTrackedToolCallsToMessageId(toolCallMessageIdByCallId, fromMessageId, toMessageId) {
+  for (const [toolCallId, trackedMessageId] of toolCallMessageIdByCallId) {
+    if (trackedMessageId !== fromMessageId) {
+      continue;
+    }
+    toolCallMessageIdByCallId.set(toolCallId, toMessageId);
+  }
+}
+function clearToolCallTrackingByMessageId(toolCallMessageIdByCallId, toolCallArgsRawByCallId, messageId) {
+  for (const [toolCallId, trackedMessageId] of toolCallMessageIdByCallId) {
+    if (trackedMessageId !== messageId) {
+      continue;
+    }
+    toolCallMessageIdByCallId.delete(toolCallId);
+    toolCallArgsRawByCallId.delete(toolCallId);
+  }
+}
+function findToolInvocationPart(parts, toolCallId) {
+  for (let index = parts.length - 1; index >= 0; index -= 1) {
+    const part = parts[index];
+    if (part.type === "tool-invocation" && part.toolCallId === toolCallId) {
+      return part;
+    }
+  }
+  return null;
+}
+function findToolNameByCallId(parts, toolCallId) {
+  const part = findToolInvocationPart(parts, toolCallId);
+  return part?.toolName ?? null;
+}
+function upsertToolInvocationPart(parts, toolPart) {
+  const nextParts = [...parts];
+  for (let index = nextParts.length - 1; index >= 0; index -= 1) {
+    const part = nextParts[index];
+    if (part.type === "tool-invocation" && part.toolCallId === toolPart.toolCallId) {
+      nextParts[index] = {
+        ...part,
+        ...toolPart
+      };
+      return nextParts;
+    }
+  }
+  nextParts.push(toolPart);
+  return nextParts;
+}
+
+// src/agent/agent-conversation-state-manager.ts
+var DEFAULT_ASSISTANT_ROLE = "assistant";
 var DefaultNcpAgentConversationStateManager = class {
   messages = [];
   streamingMessage = null;
@@ -39,8 +103,8 @@ var DefaultNcpAgentConversationStateManager = class {
       return this.snapshotCache;
     }
     const snapshot = {
-      messages: this.messages.map((message) => cloneMessage(message)),
-      streamingMessage: this.streamingMessage ? cloneMessage(this.streamingMessage) : null,
+      messages: this.messages.map((message) => cloneConversationMessage(message)),
+      streamingMessage: this.streamingMessage ? cloneConversationMessage(this.streamingMessage) : null,
       error: this.error ? { ...this.error, details: this.error.details ? { ...this.error.details } : void 0 } : null,
       activeRun: this.activeRun ? { ...this.activeRun } : null
     };
@@ -66,7 +130,7 @@ var DefaultNcpAgentConversationStateManager = class {
     this.notifyListeners();
   }
   hydrate(payload) {
-    this.messages = payload.messages.map((message) => cloneMessage(message));
+    this.messages = payload.messages.map((message) => normalizeConversationMessage(message));
     this.streamingMessage = null;
     this.error = null;
     this.activeRun = payload.activeRun ? {
@@ -159,9 +223,17 @@ var DefaultNcpAgentConversationStateManager = class {
       });
       this.replaceStreamingMessage(null);
       if (targetMessageId) {
-        this.clearToolCallTrackingByMessageId(targetMessageId);
+        clearToolCallTrackingByMessageId(
+          this.toolCallMessageIdByCallId,
+          this.toolCallArgsRawByCallId,
+          targetMessageId
+        );
       } else {
-        this.clearToolCallTrackingByMessageId(streamingMessageId);
+        clearToolCallTrackingByMessageId(
+          this.toolCallMessageIdByCallId,
+          this.toolCallArgsRawByCallId,
+          streamingMessageId
+        );
       }
     }
   }
@@ -238,7 +310,7 @@ var DefaultNcpAgentConversationStateManager = class {
       payload.messageId
     );
     this.toolCallArgsRawByCallId.set(payload.toolCallId, "");
-    const nextParts = this.upsertToolInvocationPart(targetMessage.parts, {
+    const nextParts = upsertToolInvocationPart(targetMessage.parts, {
       type: "tool-invocation",
       toolCallId: payload.toolCallId,
       toolName: payload.toolName,
@@ -265,10 +337,10 @@ var DefaultNcpAgentConversationStateManager = class {
   handleMessageToolCallEnd(payload) {
     const targetMessage = this.resolveToolCallTargetMessage(payload.sessionId, payload.toolCallId);
     const args = this.toolCallArgsRawByCallId.get(payload.toolCallId) ?? "";
-    const nextParts = this.upsertToolInvocationPart(targetMessage.parts, {
+    const nextParts = upsertToolInvocationPart(targetMessage.parts, {
       type: "tool-invocation",
       toolCallId: payload.toolCallId,
-      toolName: this.findToolNameByCallId(targetMessage.parts, payload.toolCallId) ?? "unknown",
+      toolName: findToolNameByCallId(targetMessage.parts, payload.toolCallId) ?? "unknown",
       state: "call",
       args
     });
@@ -288,11 +360,11 @@ var DefaultNcpAgentConversationStateManager = class {
         args: existingPart.args,
         result: payload.content
       };
-      return this.upsertToolInvocationPart(targetMessage.parts, mergedPart);
+      return upsertToolInvocationPart(targetMessage.parts, mergedPart);
     });
     if (!updated) {
       const fallbackMessage = this.resolveToolCallTargetMessage(payload.sessionId, payload.toolCallId);
-      const nextParts = this.upsertToolInvocationPart(fallbackMessage.parts, {
+      const nextParts = upsertToolInvocationPart(fallbackMessage.parts, {
         type: "tool-invocation",
         toolCallId: payload.toolCallId,
         toolName: "unknown",
@@ -322,7 +394,11 @@ var DefaultNcpAgentConversationStateManager = class {
       };
       this.upsertMessage(finalizedMessage);
       this.replaceStreamingMessage(null);
-      this.clearToolCallTrackingByMessageId(finalizedMessage.id);
+      clearToolCallTrackingByMessageId(
+        this.toolCallMessageIdByCallId,
+        this.toolCallArgsRawByCallId,
+        finalizedMessage.id
+      );
     }
     this.setError(null);
     this.clearActiveRun();
@@ -335,7 +411,11 @@ var DefaultNcpAgentConversationStateManager = class {
       };
       this.upsertMessage(failedMessage);
       this.replaceStreamingMessage(null);
-      this.clearToolCallTrackingByMessageId(failedMessage.id);
+      clearToolCallTrackingByMessageId(
+        this.toolCallMessageIdByCallId,
+        this.toolCallArgsRawByCallId,
+        failedMessage.id
+      );
     }
     this.setError(buildRuntimeError(payload));
     this.clearActiveRun();
@@ -359,8 +439,8 @@ var DefaultNcpAgentConversationStateManager = class {
   }
   applyToolCallArgs(sessionId, toolCallId, args, messageId) {
     const targetMessage = this.resolveToolCallTargetMessage(sessionId, toolCallId, messageId);
-    const toolName = this.findToolNameByCallId(targetMessage.parts, toolCallId) ?? "unknown";
-    const nextParts = this.upsertToolInvocationPart(targetMessage.parts, {
+    const toolName = findToolNameByCallId(targetMessage.parts, toolCallId) ?? "unknown";
+    const nextParts = upsertToolInvocationPart(targetMessage.parts, {
       type: "tool-invocation",
       toolCallId,
       toolName,
@@ -387,7 +467,7 @@ var DefaultNcpAgentConversationStateManager = class {
     }
     const messageIndex = this.messages.findIndex((message) => message.id === messageId);
     if (messageIndex >= 0) {
-      const existingMessage = cloneMessage(this.messages[messageIndex]);
+      const existingMessage = cloneConversationMessage(this.messages[messageIndex]);
       const nextMessages = [...this.messages];
       nextMessages.splice(messageIndex, 1);
       this.messages = nextMessages;
@@ -400,6 +480,22 @@ var DefaultNcpAgentConversationStateManager = class {
       this.replaceStreamingMessage(nextStreamingMessage2);
       return nextStreamingMessage2;
     }
+    const existingStreamingMessage = this.streamingMessage;
+    if (existingStreamingMessage && existingStreamingMessage.id !== messageId && existingStreamingMessage.sessionId === sessionId && shouldPromoteStreamingMessageId(existingStreamingMessage, messageId)) {
+      const nextStreamingMessage2 = {
+        ...existingStreamingMessage,
+        id: messageId,
+        sessionId,
+        status
+      };
+      remapTrackedToolCallsToMessageId(
+        this.toolCallMessageIdByCallId,
+        existingStreamingMessage.id,
+        messageId
+      );
+      this.replaceStreamingMessage(nextStreamingMessage2);
+      return nextStreamingMessage2;
+    }
     const nextStreamingMessage = {
       id: messageId,
       sessionId,
@@ -418,7 +514,7 @@ var DefaultNcpAgentConversationStateManager = class {
   }
   updateMessageContainingToolCall(toolCallId, updater) {
     if (this.streamingMessage) {
-      const part = this.findToolInvocationPart(this.streamingMessage.parts, toolCallId);
+      const part = findToolInvocationPart(this.streamingMessage.parts, toolCallId);
       if (part) {
         const nextParts = updater(this.streamingMessage, part);
         this.replaceStreamingMessage({ ...this.streamingMessage, parts: nextParts });
@@ -427,7 +523,7 @@ var DefaultNcpAgentConversationStateManager = class {
     }
     for (let index = this.messages.length - 1; index >= 0; index -= 1) {
       const candidateMessage = this.messages[index];
-      const part = this.findToolInvocationPart(candidateMessage.parts, toolCallId);
+      const part = findToolInvocationPart(candidateMessage.parts, toolCallId);
       if (!part) {
         continue;
       }
@@ -442,36 +538,8 @@ var DefaultNcpAgentConversationStateManager = class {
     }
     return false;
   }
-  findToolInvocationPart(parts, toolCallId) {
-    for (let index = parts.length - 1; index >= 0; index -= 1) {
-      const part = parts[index];
-      if (part.type === "tool-invocation" && part.toolCallId === toolCallId) {
-        return part;
-      }
-    }
-    return null;
-  }
-  findToolNameByCallId(parts, toolCallId) {
-    const part = this.findToolInvocationPart(parts, toolCallId);
-    return part?.toolName ?? null;
-  }
-  upsertToolInvocationPart(parts, toolPart) {
-    const nextParts = [...parts];
-    for (let index = nextParts.length - 1; index >= 0; index -= 1) {
-      const part = nextParts[index];
-      if (part.type === "tool-invocation" && part.toolCallId === toolPart.toolCallId) {
-        nextParts[index] = {
-          ...part,
-          ...toolPart
-        };
-        return nextParts;
-      }
-    }
-    nextParts.push(toolPart);
-    return nextParts;
-  }
   upsertMessage(message) {
-    const normalizedMessage = cloneMessage(message);
+    const normalizedMessage = normalizeConversationMessage(message);
     const messageIndex = this.messages.findIndex((item) => item.id === normalizedMessage.id);
     if (messageIndex < 0) {
       this.messages = [...this.messages, normalizedMessage];
@@ -487,7 +555,7 @@ var DefaultNcpAgentConversationStateManager = class {
     if (!nextStreamingMessage && !this.streamingMessage) {
       return;
     }
-    this.streamingMessage = nextStreamingMessage ? cloneMessage(nextStreamingMessage) : null;
+    this.streamingMessage = nextStreamingMessage ? normalizeConversationMessage(nextStreamingMessage) : null;
     this.stateVersion += 1;
   }
   setError(nextError) {
@@ -505,15 +573,6 @@ var DefaultNcpAgentConversationStateManager = class {
     this.activeRun = null;
     this.stateVersion += 1;
   }
-  clearToolCallTrackingByMessageId(messageId) {
-    for (const [toolCallId, trackedMessageId] of this.toolCallMessageIdByCallId) {
-      if (trackedMessageId !== messageId) {
-        continue;
-      }
-      this.toolCallMessageIdByCallId.delete(toolCallId);
-      this.toolCallArgsRawByCallId.delete(toolCallId);
-    }
-  }
   notifyListeners() {
     const snapshot = this.getSnapshot();
     for (const listener of this.listeners) {
@@ -574,7 +633,7 @@ async function consume(events) {
 
 // src/agent/agent-backend/agent-backend.ts
 import {
-  NcpEventType as NcpEventType4
+  NcpEventType as NcpEventType5
 } from "@nextclaw/ncp";
 
 // src/errors/ncp-error-exception.ts
@@ -596,9 +655,15 @@ var AgentLiveSessionRegistry = class {
     this.createRuntime = createRuntime;
   }
   sessions = /* @__PURE__ */ new Map();
-  async ensureSession(sessionId) {
+  async ensureSession(sessionId, initialMetadata) {
     const existing = this.sessions.get(sessionId);
     if (existing) {
+      if (initialMetadata && Object.keys(initialMetadata).length > 0) {
+        existing.metadata = {
+          ...existing.metadata,
+          ...structuredClone(initialMetadata)
+        };
+      }
       return existing;
     }
     const storedSession = await this.sessionStore.getSession(sessionId);
@@ -607,12 +672,27 @@ var AgentLiveSessionRegistry = class {
       sessionId,
       messages: cloneMessages(storedSession?.messages ?? [])
     });
+    const sessionMetadata = {
+      ...storedSession?.metadata ? structuredClone(storedSession.metadata) : {},
+      ...initialMetadata ? structuredClone(initialMetadata) : {}
+    };
     const session = {
       sessionId,
       stateManager,
-      runtime: this.createRuntime({ sessionId, stateManager }),
+      metadata: sessionMetadata,
+      runtime: null,
       activeExecution: null
     };
+    session.runtime = this.createRuntime({
+      sessionId,
+      stateManager,
+      sessionMetadata,
+      setSessionMetadata: (nextMetadata) => {
+        session.metadata = {
+          ...structuredClone(nextMetadata)
+        };
+      }
+    });
     this.sessions.set(sessionId, session);
     return session;
   }
@@ -652,21 +732,19 @@ var AgentRunExecutor = class {
         metadata: envelope.metadata
       }
     };
-    let messageSentPublished = false;
+    await session.stateManager.dispatch(messageSent);
+    await this.persistSession(envelope.sessionId);
+    yield structuredClone(messageSent);
     try {
       for await (const event of session.runtime.run(
         {
           sessionId: envelope.sessionId,
           messages: [envelope.message],
-          correlationId: envelope.correlationId
+          correlationId: envelope.correlationId,
+          metadata: envelope.metadata
         },
         { signal: controller.signal }
       )) {
-        if (!messageSentPublished) {
-          messageSentPublished = true;
-          await this.persistSession(envelope.sessionId);
-          yield structuredClone(messageSent);
-        }
         await this.persistSession(envelope.sessionId);
         yield structuredClone(event);
       }
@@ -753,6 +831,78 @@ function createAsyncQueue() {
   };
 }
 
+// src/agent/agent-backend/agent-backend-session-utils.ts
+import { NcpEventType as NcpEventType4 } from "@nextclaw/ncp";
+function readMessages(snapshot) {
+  const messages = snapshot.messages.map((message) => structuredClone(message));
+  if (snapshot.streamingMessage) {
+    messages.push(structuredClone(snapshot.streamingMessage));
+  }
+  return messages;
+}
+function toSessionSummary(session, liveSession) {
+  return {
+    sessionId: session.sessionId,
+    messageCount: session.messages.length,
+    updatedAt: session.updatedAt,
+    status: liveSession?.activeExecution ? "running" : "idle",
+    ...session.metadata ? {
+      metadata: structuredClone({
+        ...session.metadata,
+        ...liveSession?.metadata ? liveSession.metadata : {}
+      })
+    } : liveSession?.metadata ? { metadata: structuredClone(liveSession.metadata) } : {}
+  };
+}
+function toLiveSessionSummary(session) {
+  const snapshot = session.stateManager.getSnapshot();
+  return {
+    sessionId: session.sessionId,
+    messageCount: readMessages(snapshot).length,
+    updatedAt: now(),
+    status: session.activeExecution ? "running" : "idle",
+    ...Object.keys(session.metadata).length > 0 ? { metadata: structuredClone(session.metadata) } : session.activeExecution?.requestEnvelope.metadata ? { metadata: structuredClone(session.activeExecution.requestEnvelope.metadata) } : {}
+  };
+}
+function now() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+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 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);
+  }
+  return {
+    sessionId: params.sessionId,
+    messages: params.liveSession ? readMessages(params.liveSession.stateManager.getSnapshot()) : params.storedSession?.messages.map((message) => structuredClone(message)) ?? [],
+    updatedAt: params.updatedAt,
+    metadata: nextMetadata
+  };
+}
+function buildPersistedLiveSessionRecord(params) {
+  return {
+    sessionId: params.sessionId,
+    messages: readMessages(params.session.stateManager.getSnapshot()),
+    updatedAt: params.updatedAt,
+    metadata: {
+      ...params.session.metadata ? structuredClone(params.session.metadata) : {},
+      ...params.session.activeExecution?.requestEnvelope.metadata ? structuredClone(params.session.activeExecution.requestEnvelope.metadata) : {}
+    }
+  };
+}
+
 // src/agent/agent-backend/event-publisher.ts
 var EventPublisher = class {
   listeners = /* @__PURE__ */ new Set();
@@ -844,7 +994,7 @@ var DefaultNcpAgentBackend = class {
       return;
     }
     this.started = true;
-    this.publisher.publish({ type: NcpEventType4.EndpointReady });
+    this.publisher.publish({ type: NcpEventType5.EndpointReady });
   }
   async stop() {
     if (!this.started) {
@@ -865,13 +1015,13 @@ var DefaultNcpAgentBackend = class {
   async emit(event) {
     await this.ensureStarted();
     switch (event.type) {
-      case NcpEventType4.MessageRequest:
+      case NcpEventType5.MessageRequest:
         await this.handleRequest(event.payload);
         return;
-      case NcpEventType4.MessageStreamRequest:
+      case NcpEventType5.MessageStreamRequest:
         await this.streamToSubscribers(event.payload);
         return;
-      case NcpEventType4.MessageAbort:
+      case NcpEventType5.MessageAbort:
         await this.handleAbort(event.payload);
         return;
       default:
@@ -883,7 +1033,10 @@ var DefaultNcpAgentBackend = class {
   }
   async *send(envelope, options) {
     await this.ensureStarted();
-    const session = await this.sessionRegistry.ensureSession(envelope.sessionId);
+    const session = await this.sessionRegistry.ensureSession(
+      envelope.sessionId,
+      envelope.metadata
+    );
     const execution = this.startSessionExecution(session, envelope, options?.signal);
     try {
       for await (const event of this.executor.executeRun(session, envelope, execution.controller)) {
@@ -954,22 +1107,27 @@ var DefaultNcpAgentBackend = class {
   }
   async listSessionMessages(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)) : [];
   }
   async getSession(sessionId) {
     const liveSession = this.sessionRegistry.getSession(sessionId);
     const storedSession = await this.sessionStore.getSession(sessionId);
-    if (storedSession) {
-      return toSessionSummary(storedSession, liveSession);
-    }
-    if (liveSession) {
-      return toLiveSessionSummary(liveSession);
-    }
-    return null;
+    return storedSession ? toSessionSummary(storedSession, liveSession) : liveSession ? toLiveSessionSummary(liveSession) : null;
+  }
+  async updateSession(sessionId, patch) {
+    const liveSession = this.sessionRegistry.getSession(sessionId);
+    const storedSession = await this.sessionStore.getSession(sessionId);
+    if (!liveSession && !storedSession) return null;
+    await this.sessionStore.saveSession(buildUpdatedSessionRecord({
+      sessionId,
+      patch,
+      liveSession,
+      storedSession,
+      updatedAt: now()
+    }));
+    return this.getSession(sessionId);
   }
   async deleteSession(sessionId) {
     const liveSession = this.sessionRegistry.deleteSession(sessionId);
@@ -1054,7 +1212,7 @@ var DefaultNcpAgentBackend = class {
   }
   async createAbortEvent(sessionId, messageId) {
     const abortEvent = {
-      type: NcpEventType4.MessageAbort,
+      type: NcpEventType5.MessageAbort,
       payload: {
         sessionId,
         ...messageId ? { messageId } : {}
@@ -1069,54 +1227,14 @@ var DefaultNcpAgentBackend = class {
   }
   async persistSession(sessionId) {
     const session = this.sessionRegistry.getSession(sessionId);
-    if (!session) {
-      return;
-    }
-    const snapshot = session.stateManager.getSnapshot();
-    await this.sessionStore.saveSession({
+    if (!session) return;
+    await this.sessionStore.saveSession(buildPersistedLiveSessionRecord({
       sessionId,
-      messages: readMessages(snapshot),
+      session,
       updatedAt: now()
-    });
+    }));
   }
 };
-function readMessages(snapshot) {
-  const messages = snapshot.messages.map((message) => structuredClone(message));
-  if (snapshot.streamingMessage) {
-    messages.push(structuredClone(snapshot.streamingMessage));
-  }
-  return messages;
-}
-function toSessionSummary(session, liveSession) {
-  return {
-    sessionId: session.sessionId,
-    messageCount: session.messages.length,
-    updatedAt: session.updatedAt,
-    status: liveSession?.activeExecution ? "running" : "idle"
-  };
-}
-function toLiveSessionSummary(session) {
-  const snapshot = session.stateManager.getSnapshot();
-  return {
-    sessionId: session.sessionId,
-    messageCount: readMessages(snapshot).length,
-    updatedAt: now(),
-    status: session.activeExecution ? "running" : "idle"
-  };
-}
-function now() {
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-function isTerminalEvent(event) {
-  switch (event.type) {
-    case NcpEventType4.MessageAbort:
-    case NcpEventType4.RunFinished:
-    case NcpEventType4.RunError:
-      return true;
-    default:
-      return false;
-  }
-}
 
 // src/agent/agent-backend/in-memory-agent-session-store.ts
 var InMemoryAgentSessionStore = class {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp-toolkit",
-  "version": "0.2.0",
+  "version": "0.4.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.2.0"
+    "@nextclaw/ncp": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",
@@ -23,7 +23,7 @@
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "vitest": "^2.1.2",
-    "@nextclaw/ncp-agent-runtime": "0.1.1"
+    "@nextclaw/ncp-agent-runtime": "0.2.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --out-dir dist",