@nextclaw/ncp 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -222,6 +222,7 @@ type NcpSessionSummary = {
     messageCount: number;
     updatedAt: string;
     status?: NcpSessionStatus;
+    metadata?: Record<string, unknown>;
 };
 type ListSessionsOptions = {
     limit?: number;
@@ -231,6 +232,9 @@ type ListMessagesOptions = {
     limit?: number;
     cursor?: string;
 };
+type NcpSessionPatch = {
+    metadata?: Record<string, unknown> | null;
+};
 /**
  * API for session list, message history, and session lifecycle.
  * Implementations that support persistence can provide this alongside NcpAgentClientEndpoint.
@@ -239,6 +243,7 @@ interface NcpSessionApi {
     listSessions(options?: ListSessionsOptions): Promise<NcpSessionSummary[]>;
     listSessionMessages(sessionId: string, options?: ListMessagesOptions): Promise<NcpMessage[]>;
     getSession(sessionId: string): Promise<NcpSessionSummary | null>;
+    updateSession(sessionId: string, patch: NcpSessionPatch): Promise<NcpSessionSummary | null>;
     deleteSession(sessionId: string): Promise<void>;
 }
 
@@ -668,6 +673,7 @@ type NcpAgentRunInput = {
     sessionId: string;
     messages: ReadonlyArray<NcpMessage>;
     correlationId?: string;
+    metadata?: Record<string, unknown>;
 };
 type NcpAgentRunOptions = {
     signal?: AbortSignal;
@@ -703,6 +709,7 @@ type OpenAIChatMessage = {
 } | {
     role: "assistant";
     content?: string | null;
+    reasoning_content?: string;
     tool_calls?: OpenAIToolCall[];
 } | {
     role: "tool";
@@ -748,6 +755,7 @@ type NcpLLMApiInput = {
     messages: OpenAIChatMessage[];
     tools?: OpenAITool[];
     model?: string;
+    thinkingLevel?: string | null;
     max_tokens?: number;
 };
 type NcpLLMApiOptions = {
@@ -781,9 +789,21 @@ interface NcpTool {
 type NcpToolCallResult = {
     toolCallId: string;
     toolName: string;
-    args: unknown;
+    args: Record<string, unknown> | null;
+    rawArgsText: string;
     result: unknown;
 };
+type NcpInvalidToolArgumentsResult = {
+    ok: false;
+    error: {
+        code: "invalid_tool_arguments";
+        message: string;
+        toolCallId: string;
+        toolName: string;
+        rawArgumentsText: string;
+        issues: string[];
+    };
+};
 interface NcpToolRegistry {
     listTools(): ReadonlyArray<NcpTool>;
     getTool(name: string): NcpTool | undefined;
@@ -916,4 +936,35 @@ interface NcpAgentConversationStateManager extends NcpConversationStateManager {
     handleEndpointError(payload: NcpError): void;
 }
 
-export { type ListMessagesOptions, type ListSessionsOptions, type NcpActionPart, type NcpAgentClientEndpoint, type NcpAgentConversationHydrationParams, type NcpAgentConversationSnapshot, type NcpAgentConversationStateManager, type NcpAgentRunApi, type NcpAgentRunInput, type NcpAgentRunOptions, type NcpAgentRunSendOptions, type NcpAgentRunStreamOptions, type NcpAgentRuntime, type NcpAgentServerEndpoint, type NcpAgentStreamProvider, type NcpCardPart, type NcpCompletedEnvelope, type NcpContextBuilder, type NcpContextPrepareOptions, type NcpConversationSnapshot, type NcpConversationStateManager, type NcpEncodeContext, type NcpEndpoint, type NcpEndpointEvent, type NcpEndpointKind, type NcpEndpointLatency, type NcpEndpointManifest, type NcpEndpointSubscriber, type NcpError, type NcpErrorCode, NcpEventType, type NcpExtensionPart, type NcpFailedEnvelope, type NcpFilePart, type NcpLLMApi, type NcpLLMApiInput, type NcpLLMApiOptions, type NcpMessage, type NcpMessageAbortPayload, type NcpMessageAcceptedPayload, type NcpMessageDeliveredPayload, type NcpMessagePart, type NcpMessageReactionPayload, type NcpMessageReadPayload, type NcpMessageRecalledPayload, type NcpMessageRole, type NcpMessageSentPayload, type NcpMessageStatus, type NcpPendingToolCall, type NcpPresenceUpdatedPayload, type NcpReasoningDeltaPayload, type NcpReasoningEndPayload, type NcpReasoningPart, type NcpReasoningStartPayload, type NcpRequestEnvelope, type NcpResponseEnvelope, type NcpRichTextPart, type NcpRoundBuffer, type NcpRunContext, type NcpRunErrorPayload, type NcpRunFinalMetadata, type NcpRunFinishedPayload, type NcpRunMetadataPayload, type NcpRunReadyMetadata, type NcpRunStartedPayload, type NcpSessionApi, type NcpSessionStatus, type NcpSessionSummary, type NcpSourcePart, type NcpStepStartPart, type NcpStreamEncoder, type NcpStreamRequestPayload, type NcpTextDeltaPayload, type NcpTextEndPayload, type NcpTextPart, type NcpTextStartPayload, type NcpTool, type NcpToolCallArgsDeltaPayload, type NcpToolCallArgsPayload, type NcpToolCallEndPayload, type NcpToolCallResult, type NcpToolCallResultPayload, type NcpToolCallStartPayload, type NcpToolDefinition, type NcpToolInvocationPart, type NcpToolRegistry, type NcpTypingEndPayload, type NcpTypingStartPayload, type OpenAIChatChunk, type OpenAIChatMessage, type OpenAIContentPart, type OpenAITool, type OpenAIToolCall, type OpenAIToolCallDelta };
+type NcpReplyTagParseResult = {
+    content: string;
+    replyTo?: string;
+};
+declare function stripReplyTagsFromText(content: string, currentMessageId?: string): NcpReplyTagParseResult;
+declare function sanitizeAssistantReplyTags(message: NcpMessage, currentMessageId?: string): NcpMessage;
+
+type NcpAssistantReasoningNormalizationMode = "off" | "think-tags";
+type NcpAssistantReasoningSegment = {
+    type: "text" | "reasoning";
+    text: string;
+};
+declare function readAssistantReasoningNormalizationMode(value: unknown): NcpAssistantReasoningNormalizationMode | null;
+declare function readAssistantReasoningNormalizationModeFromMetadata(metadata: Record<string, unknown> | null | undefined): NcpAssistantReasoningNormalizationMode | null;
+declare function writeAssistantReasoningNormalizationModeToMetadata(metadata: Record<string, unknown>, mode: NcpAssistantReasoningNormalizationMode): Record<string, unknown>;
+declare class NcpAssistantTextStreamNormalizer {
+    private readonly mode;
+    private buffer;
+    private phase;
+    private stripLeadingTextControlTags;
+    constructor(mode?: NcpAssistantReasoningNormalizationMode);
+    push(delta: string): NcpAssistantReasoningSegment[];
+    finish(): NcpAssistantReasoningSegment[];
+    private flush;
+}
+declare function normalizeAssistantText(text: string, mode: NcpAssistantReasoningNormalizationMode): {
+    text: string;
+    reasoning: string;
+    parts: NcpAssistantReasoningSegment[];
+};
+
+export { type ListMessagesOptions, type ListSessionsOptions, type NcpActionPart, type NcpAgentClientEndpoint, type NcpAgentConversationHydrationParams, type NcpAgentConversationSnapshot, type NcpAgentConversationStateManager, type NcpAgentRunApi, type NcpAgentRunInput, type NcpAgentRunOptions, type NcpAgentRunSendOptions, type NcpAgentRunStreamOptions, type NcpAgentRuntime, type NcpAgentServerEndpoint, type NcpAgentStreamProvider, type NcpAssistantReasoningNormalizationMode, type NcpAssistantReasoningSegment, NcpAssistantTextStreamNormalizer, type NcpCardPart, type NcpCompletedEnvelope, type NcpContextBuilder, type NcpContextPrepareOptions, type NcpConversationSnapshot, type NcpConversationStateManager, type NcpEncodeContext, type NcpEndpoint, type NcpEndpointEvent, type NcpEndpointKind, type NcpEndpointLatency, type NcpEndpointManifest, type NcpEndpointSubscriber, type NcpError, type NcpErrorCode, NcpEventType, type NcpExtensionPart, type NcpFailedEnvelope, type NcpFilePart, type NcpInvalidToolArgumentsResult, type NcpLLMApi, type NcpLLMApiInput, type NcpLLMApiOptions, type NcpMessage, type NcpMessageAbortPayload, type NcpMessageAcceptedPayload, type NcpMessageDeliveredPayload, type NcpMessagePart, type NcpMessageReactionPayload, type NcpMessageReadPayload, type NcpMessageRecalledPayload, type NcpMessageRole, type NcpMessageSentPayload, type NcpMessageStatus, type NcpPendingToolCall, type NcpPresenceUpdatedPayload, type NcpReasoningDeltaPayload, type NcpReasoningEndPayload, type NcpReasoningPart, type NcpReasoningStartPayload, type NcpReplyTagParseResult, type NcpRequestEnvelope, type NcpResponseEnvelope, type NcpRichTextPart, type NcpRoundBuffer, type NcpRunContext, type NcpRunErrorPayload, type NcpRunFinalMetadata, type NcpRunFinishedPayload, type NcpRunMetadataPayload, type NcpRunReadyMetadata, type NcpRunStartedPayload, type NcpSessionApi, type NcpSessionPatch, type NcpSessionStatus, type NcpSessionSummary, type NcpSourcePart, type NcpStepStartPart, type NcpStreamEncoder, type NcpStreamRequestPayload, type NcpTextDeltaPayload, type NcpTextEndPayload, type NcpTextPart, type NcpTextStartPayload, type NcpTool, type NcpToolCallArgsDeltaPayload, type NcpToolCallArgsPayload, type NcpToolCallEndPayload, type NcpToolCallResult, type NcpToolCallResultPayload, type NcpToolCallStartPayload, type NcpToolDefinition, type NcpToolInvocationPart, type NcpToolRegistry, type NcpTypingEndPayload, type NcpTypingStartPayload, type OpenAIChatChunk, type OpenAIChatMessage, type OpenAIContentPart, type OpenAITool, type OpenAIToolCall, type OpenAIToolCallDelta, normalizeAssistantText, readAssistantReasoningNormalizationMode, readAssistantReasoningNormalizationModeFromMetadata, sanitizeAssistantReplyTags, stripReplyTagsFromText, writeAssistantReasoningNormalizationModeToMetadata };

package/dist/index.js

@@ -34,6 +34,280 @@ var NcpEventType = /* @__PURE__ */ ((NcpEventType2) => {
   NcpEventType2["PresenceUpdated"] = "presence.updated";
   return NcpEventType2;
 })(NcpEventType || {});
+
+// src/toolkit/reply-tags.ts
+var REPLY_TO_CURRENT_PATTERN = /\[\[\s*reply_to_current\s*\]\]/gi;
+var REPLY_TO_ID_PATTERN = /\[\[\s*reply_to\s*:\s*([^\]]+?)\s*\]\]/i;
+function normalizeReplyTarget(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function stripReplyTagsFromText(content, currentMessageId) {
+  let nextContent = content;
+  let replyTo;
+  if (REPLY_TO_CURRENT_PATTERN.test(nextContent)) {
+    replyTo = normalizeReplyTarget(currentMessageId);
+    nextContent = nextContent.replace(REPLY_TO_CURRENT_PATTERN, "").trim();
+  }
+  const explicitReplyTarget = nextContent.match(REPLY_TO_ID_PATTERN)?.[1];
+  if (explicitReplyTarget) {
+    replyTo = normalizeReplyTarget(explicitReplyTarget);
+    nextContent = nextContent.replace(REPLY_TO_ID_PATTERN, "").trim();
+  }
+  return replyTo ? { content: nextContent, replyTo } : { content: nextContent };
+}
+function sanitizeAssistantReplyTags(message, currentMessageId = message.id) {
+  if (message.role !== "assistant") {
+    return {
+      ...message,
+      parts: [...message.parts],
+      metadata: message.metadata ? { ...message.metadata } : void 0
+    };
+  }
+  const firstTextIndex = message.parts.findIndex((part) => part.type === "text");
+  const nextMetadata = message.metadata ? { ...message.metadata } : void 0;
+  const existingReplyTo = normalizeReplyTarget(nextMetadata?.reply_to);
+  if (firstTextIndex < 0) {
+    return {
+      ...message,
+      parts: [...message.parts],
+      metadata: nextMetadata
+    };
+  }
+  const firstTextPart = message.parts[firstTextIndex];
+  if (!firstTextPart || firstTextPart.type !== "text") {
+    return {
+      ...message,
+      parts: [...message.parts],
+      metadata: nextMetadata
+    };
+  }
+  const { content, replyTo } = stripReplyTagsFromText(firstTextPart.text, currentMessageId);
+  const effectiveReplyTo = replyTo ?? existingReplyTo;
+  const nextParts = message.parts.flatMap((part, index) => {
+    if (index !== firstTextIndex || part.type !== "text") {
+      return [part];
+    }
+    if (content.length === 0) {
+      return [];
+    }
+    return [{ ...part, text: content }];
+  });
+  if (effectiveReplyTo) {
+    return {
+      ...message,
+      parts: nextParts,
+      metadata: {
+        ...nextMetadata,
+        reply_to: effectiveReplyTo
+      }
+    };
+  }
+  return {
+    ...message,
+    parts: nextParts,
+    metadata: nextMetadata
+  };
+}
+
+// src/toolkit/reasoning-normalization.ts
+var THINK_OPEN_TAG = "<think>";
+var THINK_CLOSE_TAG = "</think>";
+var FINAL_OPEN_TAG = "<final>";
+var FINAL_CLOSE_TAG = "</final>";
+var LEADING_CONTROL_TAGS = [THINK_CLOSE_TAG, FINAL_OPEN_TAG, FINAL_CLOSE_TAG];
+var MAX_REASONING_DELIMITER_TAIL = THINK_CLOSE_TAG.length - 1;
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isWhitespace(char) {
+  return /\s/.test(char);
+}
+function normalizeMode(value) {
+  if (value === "off" || value === "think-tags") {
+    return value;
+  }
+  return null;
+}
+function readLeadingThinkTagState(buffer) {
+  let cursor = 0;
+  while (cursor < buffer.length && isWhitespace(buffer[cursor])) {
+    cursor += 1;
+  }
+  const rest = buffer.slice(cursor);
+  if (rest.startsWith(THINK_OPEN_TAG)) {
+    return {
+      status: "matched",
+      consumed: cursor + THINK_OPEN_TAG.length
+    };
+  }
+  if (THINK_OPEN_TAG.startsWith(rest)) {
+    return { status: "pending" };
+  }
+  return { status: "rejected" };
+}
+function stripLeadingControlTags(buffer) {
+  let nextBuffer = buffer;
+  while (true) {
+    let cursor = 0;
+    while (cursor < nextBuffer.length && isWhitespace(nextBuffer[cursor])) {
+      cursor += 1;
+    }
+    const rest = nextBuffer.slice(cursor);
+    if (rest.length === 0) {
+      return { buffer: "", pending: false };
+    }
+    const matchedTag = LEADING_CONTROL_TAGS.find((tag) => rest.startsWith(tag));
+    if (matchedTag) {
+      nextBuffer = rest.slice(matchedTag.length);
+      continue;
+    }
+    if (LEADING_CONTROL_TAGS.some((tag) => tag.startsWith(rest))) {
+      return { buffer: rest, pending: true };
+    }
+    return { buffer: rest, pending: false };
+  }
+}
+function findReasoningBoundary(buffer) {
+  const indices = [
+    { index: buffer.indexOf(THINK_CLOSE_TAG), tag: THINK_CLOSE_TAG },
+    { index: buffer.indexOf(FINAL_OPEN_TAG), tag: FINAL_OPEN_TAG }
+  ].filter((entry) => entry.index >= 0);
+  if (indices.length === 0) {
+    return null;
+  }
+  return indices.reduce((left, right) => right.index < left.index ? right : left);
+}
+function readAssistantReasoningNormalizationMode(value) {
+  if (typeof value === "string") {
+    return normalizeMode(value);
+  }
+  if (isRecord(value)) {
+    return normalizeMode(value.mode);
+  }
+  return null;
+}
+function readAssistantReasoningNormalizationModeFromMetadata(metadata) {
+  if (!metadata) {
+    return null;
+  }
+  return readAssistantReasoningNormalizationMode(metadata.reasoning_normalization) ?? readAssistantReasoningNormalizationMode(metadata.reasoningNormalization) ?? normalizeMode(metadata.reasoning_normalization_mode) ?? normalizeMode(metadata.reasoningNormalizationMode);
+}
+function writeAssistantReasoningNormalizationModeToMetadata(metadata, mode) {
+  const nextMetadata = {
+    ...metadata
+  };
+  delete nextMetadata.reasoningNormalization;
+  delete nextMetadata.reasoningNormalizationMode;
+  delete nextMetadata.reasoning_normalization_mode;
+  nextMetadata.reasoning_normalization = { mode };
+  return nextMetadata;
+}
+var NcpAssistantTextStreamNormalizer = class {
+  constructor(mode = "off") {
+    this.mode = mode;
+  }
+  buffer = "";
+  phase = "initial";
+  stripLeadingTextControlTags = false;
+  push(delta) {
+    if (!delta) {
+      return [];
+    }
+    if (this.mode !== "think-tags") {
+      return [{ type: "text", text: delta }];
+    }
+    this.buffer += delta;
+    return this.flush(false);
+  }
+  finish() {
+    if (this.mode !== "think-tags") {
+      return [];
+    }
+    return this.flush(true);
+  }
+  flush(final) {
+    const segments = [];
+    while (true) {
+      if (this.phase === "initial") {
+        const leadingState = readLeadingThinkTagState(this.buffer);
+        if (leadingState.status === "matched") {
+          this.buffer = this.buffer.slice(leadingState.consumed);
+          this.phase = "reasoning";
+          continue;
+        }
+        if (leadingState.status === "pending" && !final) {
+          return segments;
+        }
+        this.phase = "text";
+        continue;
+      }
+      if (this.phase === "reasoning") {
+        const boundary = findReasoningBoundary(this.buffer);
+        if (boundary) {
+          const reasoningText = this.buffer.slice(0, boundary.index);
+          if (reasoningText.length > 0) {
+            segments.push({ type: "reasoning", text: reasoningText });
+          }
+          this.buffer = this.buffer.slice(boundary.index + boundary.tag.length);
+          this.phase = "text";
+          this.stripLeadingTextControlTags = true;
+          continue;
+        }
+        const safeLength = final ? this.buffer.length : Math.max(0, this.buffer.length - MAX_REASONING_DELIMITER_TAIL);
+        if (safeLength === 0) {
+          return segments;
+        }
+        segments.push({
+          type: "reasoning",
+          text: this.buffer.slice(0, safeLength)
+        });
+        this.buffer = this.buffer.slice(safeLength);
+        if (!final) {
+          return segments;
+        }
+        continue;
+      }
+      if (this.stripLeadingTextControlTags) {
+        const stripped = stripLeadingControlTags(this.buffer);
+        if (stripped.pending && !final) {
+          this.buffer = stripped.buffer;
+          return segments;
+        }
+        this.buffer = stripped.buffer;
+        this.stripLeadingTextControlTags = false;
+      }
+      if (this.buffer.length === 0) {
+        return segments;
+      }
+      segments.push({
+        type: "text",
+        text: this.buffer
+      });
+      this.buffer = "";
+      return segments;
+    }
+  }
+};
+function normalizeAssistantText(text, mode) {
+  const normalizer = new NcpAssistantTextStreamNormalizer(mode);
+  const parts = [...normalizer.push(text), ...normalizer.finish()].filter((part) => part.text.length > 0);
+  return {
+    text: parts.filter((part) => part.type === "text").map((part) => part.text).join(""),
+    reasoning: parts.filter((part) => part.type === "reasoning").map((part) => part.text).join(""),
+    parts
+  };
+}
 export {
-  NcpEventType
+  NcpAssistantTextStreamNormalizer,
+  NcpEventType,
+  normalizeAssistantText,
+  readAssistantReasoningNormalizationMode,
+  readAssistantReasoningNormalizationModeFromMetadata,
+  sanitizeAssistantReplyTags,
+  stripReplyTagsFromText,
+  writeAssistantReasoningNormalizationModeToMetadata
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "private": false,
   "description": "NextClaw Communication Protocol core abstractions and types.",
   "type": "module",