@nextclaw/ncp-toolkit 0.5.6 → 0.5.8

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NcpAgentClientEndpoint, NcpAgentConversationHydrationParams, NcpAgentConversationSnapshot, NcpAgentConversationStateManager, NcpAgentRunApi, NcpAgentRunSendOptions, NcpAgentRunStreamOptions, NcpAgentRuntime, NcpAgentServerEndpoint, NcpAgentStreamProvider, NcpEndpointEvent, NcpEndpointManifest, NcpEndpointSubscriber, NcpError, NcpErrorCode, NcpMessage, NcpMessageAbortPayload, NcpMessageSentPayload, NcpReasoningDeltaPayload, NcpReasoningEndPayload, NcpReasoningStartPayload, NcpRequestEnvelope, NcpRunErrorPayload, NcpRunFinishedPayload, NcpRunMetadataPayload, NcpRunStartedPayload, NcpSessionApi, NcpSessionPatch, NcpSessionSummary, NcpStreamRequestPayload, NcpTextDeltaPayload, NcpTextEndPayload, NcpTextStartPayload, NcpToolCallArgsDeltaPayload, NcpToolCallArgsPayload, NcpToolCallEndPayload, NcpToolCallResultPayload, NcpToolCallStartPayload } from "@nextclaw/ncp";
+import { NcpAgentClientEndpoint, NcpAgentConversationHydrationParams, NcpAgentConversationSnapshot, NcpAgentConversationStateManager, NcpAgentRunApi, NcpAgentRunInput, NcpAgentRunSendOptions, NcpAgentRunStreamOptions, NcpAgentRuntime, NcpAgentServerEndpoint, NcpAgentStreamProvider, 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";
 
 //#region src/agent/agent-conversation-state-manager.d.ts
 declare class DefaultNcpAgentConversationStateManager implements NcpAgentConversationStateManager {
@@ -78,6 +78,7 @@ type RuntimeFactoryParams = {
   sessionMetadata: Record<string, unknown>;
   setSessionMetadata: (nextMetadata: Record<string, unknown>) => void;
   resolveAssetContentPath?: (assetUri: string) => string | null;
+  resolveTools?: (input: NcpAgentRunInput) => ReadonlyArray<OpenAITool> | undefined;
 };
 type CreateRuntimeFn = (params: RuntimeFactoryParams) => NcpAgentRuntime;
 type AgentSessionRecord = {
@@ -186,4 +187,30 @@ declare class NcpErrorException extends Error {
   constructor(code: NcpErrorCode, message: string, details?: Record<string, unknown>);
 }
 //#endregion
-export { AgentRunExecutor, type AgentSessionRecord, type AgentSessionStore, type CreateRuntimeFn, DefaultNcpAgentBackend, type DefaultNcpAgentBackendConfig, DefaultNcpAgentConversationStateManager, EventPublisher, InMemoryAgentSessionStore, type LiveSessionExecution, type LiveSessionState, NcpErrorException, type RuntimeFactoryParams, createAgentClientFromServer };
+//#region src/chat/chat.types.d.ts
+type NcpEventStream = AsyncIterable<NcpEndpointEvent>;
+type ChatTarget = {
+  conversationId: string;
+  accountId?: string;
+  resolveAssetContentPath?: (assetUri: string) => string | null;
+  metadata?: Record<string, unknown>;
+};
+type NcpReplyInput = {
+  target: ChatTarget;
+  eventStream: NcpEventStream;
+};
+interface Chat {
+  startTyping(target: ChatTarget): Promise<void>;
+  sendPart(target: ChatTarget, part: NcpMessagePart): Promise<void>;
+  sendError(target: ChatTarget, message: string): Promise<void>;
+  stopTyping(target: ChatTarget): Promise<void>;
+}
+//#endregion
+//#region src/chat/ncp-reply-consumer.d.ts
+declare class NcpReplyConsumer {
+  private readonly chat;
+  constructor(chat: Chat);
+  consume: (input: NcpReplyInput) => Promise<void>;
+}
+//#endregion
+export { AgentRunExecutor, type AgentSessionRecord, type AgentSessionStore, Chat, ChatTarget, type CreateRuntimeFn, DefaultNcpAgentBackend, type DefaultNcpAgentBackendConfig, DefaultNcpAgentConversationStateManager, EventPublisher, InMemoryAgentSessionStore, type LiveSessionExecution, type LiveSessionState, NcpErrorException, NcpEventStream, NcpReplyConsumer, NcpReplyInput, type RuntimeFactoryParams, createAgentClientFromServer };

package/dist/index.js

@@ -12,6 +12,7 @@ function normalizeConversationMessage(message) {
 }
 //#endregion
 //#region src/agent/agent-conversation-state-manager.utils.ts
+const ABORTED_TOOL_CALL_SENTINEL = "__nextclaw_aborted_tool_call__";
 function buildRuntimeError(payload) {
 	const message = payload.error?.trim();
 	return {
@@ -68,6 +69,20 @@ function upsertToolInvocationPart(parts, toolPart) {
 	nextParts.push(toolPart);
 	return nextParts;
 }
+function cancelInFlightToolInvocations(parts) {
+	const toolCallIds = [];
+	return {
+		parts: parts.map((part) => {
+			if (part.type !== "tool-invocation" || !part.toolCallId || part.state === "result" || part.state === "cancelled") return part;
+			toolCallIds.push(part.toolCallId);
+			return {
+				...part,
+				state: "cancelled"
+			};
+		}),
+		toolCallIds
+	};
+}
 //#endregion
 //#region src/agent/agent-conversation-state-manager.ts
 const DEFAULT_ASSISTANT_ROLE = "assistant";
@@ -205,13 +220,16 @@ var DefaultNcpAgentConversationStateManager = class {
 		this.setError(null);
 		if (this.streamingMessage && (!targetMessageId || this.streamingMessage.id === targetMessageId)) {
 			const streamingMessageId = this.streamingMessage.id;
+			const { parts: nextParts, toolCallIds } = cancelInFlightToolInvocations(this.streamingMessage.parts);
 			this.upsertMessage({
 				...this.streamingMessage,
-				status: "final"
+				status: "final",
+				parts: nextParts
 			});
 			this.replaceStreamingMessage(null);
 			if (targetMessageId) clearToolCallTrackingByMessageId(this.toolCallMessageIdByCallId, this.toolCallArgsRawByCallId, targetMessageId);
 			else clearToolCallTrackingByMessageId(this.toolCallMessageIdByCallId, this.toolCallArgsRawByCallId, streamingMessageId);
+			toolCallIds.forEach((toolCallId) => this.toolCallArgsRawByCallId.set(toolCallId, ABORTED_TOOL_CALL_SENTINEL));
 		}
 	};
 	handleMessageTextStart = (payload) => {
@@ -271,6 +289,7 @@ var DefaultNcpAgentConversationStateManager = class {
 		if (this.streamingMessage?.id !== payload.messageId) return;
 	};
 	handleMessageToolCallStart = (payload) => {
+		if (this.toolCallArgsRawByCallId.get(payload.toolCallId) === "__nextclaw_aborted_tool_call__") return;
 		const targetMessage = this.resolveToolCallTargetMessage(payload.sessionId, payload.toolCallId, payload.messageId);
 		this.toolCallArgsRawByCallId.set(payload.toolCallId, "");
 		const nextParts = upsertToolInvocationPart(targetMessage.parts, {
@@ -288,15 +307,18 @@ var DefaultNcpAgentConversationStateManager = class {
 		this.setError(null);
 	};
 	handleMessageToolCallArgs = (payload) => {
+		if (this.toolCallArgsRawByCallId.get(payload.toolCallId) === "__nextclaw_aborted_tool_call__") return;
 		this.toolCallArgsRawByCallId.set(payload.toolCallId, payload.args);
 		this.applyToolCallArgs(payload.sessionId, payload.toolCallId, payload.args);
 	};
 	handleMessageToolCallArgsDelta = (payload) => {
+		if (this.toolCallArgsRawByCallId.get(payload.toolCallId) === "__nextclaw_aborted_tool_call__") return;
 		const nextArgs = `${this.toolCallArgsRawByCallId.get(payload.toolCallId) ?? ""}${payload.delta}`;
 		this.toolCallArgsRawByCallId.set(payload.toolCallId, nextArgs);
 		this.applyToolCallArgs(payload.sessionId, payload.toolCallId, nextArgs, payload.messageId);
 	};
 	handleMessageToolCallEnd = (payload) => {
+		if (this.toolCallArgsRawByCallId.get(payload.toolCallId) === "__nextclaw_aborted_tool_call__") return;
 		const targetMessage = this.resolveToolCallTargetMessage(payload.sessionId, payload.toolCallId);
 		const args = this.toolCallArgsRawByCallId.get(payload.toolCallId) ?? "";
 		const nextParts = upsertToolInvocationPart(targetMessage.parts, {
@@ -313,6 +335,7 @@ var DefaultNcpAgentConversationStateManager = class {
 		});
 	};
 	handleMessageToolCallResult = (payload) => {
+		if (this.toolCallArgsRawByCallId.get(payload.toolCallId) === "__nextclaw_aborted_tool_call__") return;
 		if (!this.updateMessageContainingToolCall(payload.toolCallId, (targetMessage, existingPart) => {
 			const mergedPart = {
 				type: "tool-invocation",
@@ -972,7 +995,7 @@ function toLiveSessionSummary(session) {
 function now() {
 	return (/* @__PURE__ */ new Date()).toISOString();
 }
-function readOptionalString(value) {
+function readOptionalString$1(value) {
 	if (typeof value !== "string") return null;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : null;
@@ -986,14 +1009,14 @@ 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(part.text);
+			const text = readOptionalString$1(part.text);
 			if (text) return truncateLabel(text);
 		}
 	}
 	return null;
 }
 function withAutoSessionLabel(params) {
-	if (readOptionalString(params.metadata.label)) return params.metadata;
+	if (readOptionalString$1(params.metadata.label)) return params.metadata;
 	const nextLabel = resolveAutoSessionLabelFromMessages(params.messages);
 	if (!nextLabel) return params.metadata;
 	return {
@@ -1334,4 +1357,240 @@ var InMemoryAgentSessionStore = class {
 	};
 };
 //#endregion
-export { AgentRunExecutor, DefaultNcpAgentBackend, DefaultNcpAgentConversationStateManager, EventPublisher, InMemoryAgentSessionStore, NcpErrorException, createAgentClientFromServer };
+//#region src/chat/ncp-reply-consumer.ts
+function isTextLikePart(part) {
+	return part.type === "text" || part.type === "rich-text";
+}
+function normalizeMessageParts(message) {
+	return (message.role === "assistant" ? sanitizeAssistantReplyTags(message) : message).parts;
+}
+function cloneTextLikePartTail(part, skipChars) {
+	const nextText = part.text.slice(skipChars);
+	if (!nextText) return null;
+	if (part.type === "text") return {
+		type: "text",
+		text: nextText
+	};
+	return {
+		...part,
+		text: nextText
+	};
+}
+function resolveFallbackUnsentParts(fallbackText, sentText) {
+	if (!fallbackText || fallbackText === sentText) return [];
+	const nextText = sentText && fallbackText.startsWith(sentText) ? fallbackText.slice(sentText.length) : fallbackText;
+	return nextText ? [{
+		type: "text",
+		text: nextText
+	}] : [];
+}
+function canReuseCompletedTextPrefix(normalizedParts, sentText) {
+	const finalText = normalizedParts.filter(isTextLikePart).map((part) => part.text).join("");
+	return !(sentText && finalText && !finalText.startsWith(sentText));
+}
+function collectUnsentPartsFromNormalizedParts(normalizedParts, sentText) {
+	let remainingSentChars = sentText.length;
+	const unsentParts = [];
+	for (const part of normalizedParts) {
+		if (!isTextLikePart(part)) {
+			unsentParts.push(part);
+			continue;
+		}
+		if (remainingSentChars >= part.text.length) {
+			remainingSentChars -= part.text.length;
+			continue;
+		}
+		if (remainingSentChars > 0) {
+			const tail = cloneTextLikePartTail(part, remainingSentChars);
+			remainingSentChars = 0;
+			if (tail) unsentParts.push(tail);
+			continue;
+		}
+		unsentParts.push(part);
+	}
+	return unsentParts;
+}
+function resolveUnsentMessageParts(message, sentText, fallbackText) {
+	const normalizedParts = normalizeMessageParts(message);
+	if (normalizedParts.length === 0) return resolveFallbackUnsentParts(fallbackText, sentText);
+	if (!canReuseCompletedTextPrefix(normalizedParts, sentText)) return normalizedParts;
+	return collectUnsentPartsFromNormalizedParts(normalizedParts, sentText);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function readOptionalString(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function readOptionalNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+function projectAssetPutFiles(result) {
+	if (!isRecord(result)) return [];
+	return (isRecord(result.asset) ? [result.asset] : Array.isArray(result.assets) ? result.assets.filter(isRecord) : []).flatMap((asset) => {
+		const assetUri = readOptionalString(asset.uri);
+		const url = readOptionalString(asset.url);
+		if (!assetUri && !url) return [];
+		return [{
+			type: "file",
+			...readOptionalString(asset.name) ? { name: readOptionalString(asset.name) } : {},
+			...readOptionalString(asset.mimeType) ? { mimeType: readOptionalString(asset.mimeType) } : {},
+			...assetUri ? { assetUri } : {},
+			...url ? { url } : {},
+			...readOptionalNumber(asset.sizeBytes) != null ? { sizeBytes: readOptionalNumber(asset.sizeBytes) } : {}
+		}];
+	});
+}
+function projectToolResultParts(params) {
+	if (params.toolName !== "asset_put" || !params.toolCallId || params.projectedToolCallIds.has(params.toolCallId)) return [];
+	const projectedFiles = projectAssetPutFiles(params.content);
+	if (projectedFiles.length > 0) params.projectedToolCallIds.add(params.toolCallId);
+	return projectedFiles;
+}
+function projectChannelOutputParts(parts, projectedToolCallIds) {
+	return parts.flatMap((part) => {
+		if (part.type === "tool-invocation" && part.toolName === "asset_put" && part.result) {
+			if (part.toolCallId && projectedToolCallIds.has(part.toolCallId)) return [];
+			const projectedFiles = projectAssetPutFiles(part.result);
+			if (projectedFiles.length > 0) {
+				if (part.toolCallId) projectedToolCallIds.add(part.toolCallId);
+				return projectedFiles;
+			}
+		}
+		return [part];
+	});
+}
+var NcpReplySession = class {
+	activeText = "";
+	fullText = "";
+	sentText = "";
+	typingStarted = false;
+	closed = false;
+	toolNameByCallId = /* @__PURE__ */ new Map();
+	projectedToolCallIds = /* @__PURE__ */ new Set();
+	constructor(chat, target) {
+		this.chat = chat;
+		this.target = target;
+	}
+	consume = async (eventStream) => {
+		try {
+			for await (const event of eventStream) {
+				if (this.closed) break;
+				await this.applyEvent(event);
+			}
+		} finally {
+			await this.stopTyping();
+		}
+	};
+	applyEvent = async (event) => {
+		switch (event.type) {
+			case NcpEventType.MessageTextStart:
+				await this.handleTextStart();
+				return;
+			case NcpEventType.MessageTextDelta:
+				await this.handleTextDelta(event.payload.delta);
+				return;
+			case NcpEventType.MessageTextEnd:
+				await this.handleTextEnd();
+				return;
+			case NcpEventType.MessageToolCallStart:
+				await this.handleToolCallStart(event.payload.toolCallId, event.payload.toolName);
+				return;
+			case NcpEventType.MessageReasoningStart:
+				await this.flushTextPart();
+				return;
+			case NcpEventType.MessageToolCallResult:
+				await this.handleToolCallResult(event.payload.toolCallId, event.payload.content);
+				return;
+			case NcpEventType.MessageCompleted:
+				await this.handleCompleted(event.payload.message);
+				return;
+			case NcpEventType.MessageFailed:
+				await this.handleReplyFailure(event.payload.error.message.trim());
+				return;
+			case NcpEventType.RunError:
+				await this.handleReplyFailure(String(event.payload.error ?? "NCP run failed.").trim());
+				return;
+			default: return;
+		}
+	};
+	handleTextStart = async () => {
+		await this.ensureTypingStarted();
+		if (this.activeText) await this.flushTextPart();
+		this.activeText = "";
+	};
+	handleTextDelta = async (delta) => {
+		await this.ensureTypingStarted();
+		this.activeText += delta;
+		this.fullText += delta;
+	};
+	handleTextEnd = async () => this.flushTextPart();
+	handleToolCallStart = async (toolCallId, toolName) => {
+		this.toolNameByCallId.set(toolCallId, toolName);
+		await this.ensureTypingStarted();
+		await this.flushTextPart();
+	};
+	handleToolCallResult = async (toolCallId, content) => {
+		await this.ensureTypingStarted();
+		const projectedParts = projectToolResultParts({
+			toolCallId,
+			toolName: this.toolNameByCallId.get(toolCallId),
+			content,
+			projectedToolCallIds: this.projectedToolCallIds
+		});
+		if (projectedParts.length === 0) return;
+		await this.flushTextPart();
+		for (const part of projectedParts) await this.chat.sendPart(this.target, part);
+	};
+	handleCompleted = async (message) => {
+		await this.flushTextPart();
+		const unsentParts = projectChannelOutputParts(resolveUnsentMessageParts(message, this.sentText, this.fullText), this.projectedToolCallIds);
+		for (const part of unsentParts) {
+			await this.ensureTypingStarted();
+			await this.chat.sendPart(this.target, part);
+			if (isTextLikePart(part)) this.sentText += part.text;
+		}
+		await this.stopTyping();
+	};
+	handleReplyFailure = async (message) => {
+		if (message) {
+			await this.ensureTypingStarted();
+			await this.chat.sendError(this.target, message);
+		}
+		await this.stopTyping();
+	};
+	flushTextPart = async () => {
+		if (!this.activeText.trim()) {
+			this.activeText = "";
+			return;
+		}
+		await this.ensureTypingStarted();
+		await this.chat.sendPart(this.target, {
+			type: "text",
+			text: this.activeText
+		});
+		this.sentText += this.activeText;
+		this.activeText = "";
+	};
+	ensureTypingStarted = async () => {
+		if (this.typingStarted) return;
+		await this.chat.startTyping(this.target);
+		this.typingStarted = true;
+	};
+	stopTyping = async () => {
+		if (this.closed || !this.typingStarted) return;
+		await this.chat.stopTyping(this.target);
+		this.closed = true;
+	};
+};
+var NcpReplyConsumer = class {
+	constructor(chat) {
+		this.chat = chat;
+	}
+	consume = async (input) => {
+		await new NcpReplySession(this.chat, input.target).consume(input.eventStream);
+	};
+};
+//#endregion
+export { AgentRunExecutor, DefaultNcpAgentBackend, DefaultNcpAgentConversationStateManager, EventPublisher, InMemoryAgentSessionStore, NcpErrorException, NcpReplyConsumer, createAgentClientFromServer };

package/package.json

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