@nextclaw/ncp-toolkit 0.5.5 → 0.5.7

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

@@ -947,12 +947,14 @@ function toSessionSummary(session, liveSession) {
 		...readOptionalAgentId$1(session.agentId) ? { agentId: readOptionalAgentId$1(session.agentId) } : {},
 		messageCount: session.messages.length,
 		updatedAt: session.updatedAt,
+		...session.messages.length > 0 ? { lastMessageAt: session.messages[session.messages.length - 1]?.timestamp ?? session.updatedAt } : {},
 		status: liveSession?.activeExecution ? "running" : "idle",
 		...Object.keys(metadata).length > 0 ? { metadata } : {}
 	};
 }
 function toLiveSessionSummary(session) {
 	const messages = readMessages(session.stateManager.getSnapshot());
+	const updatedAt = now();
 	const metadata = withAutoSessionLabel({
 		metadata: Object.keys(session.metadata).length > 0 ? structuredClone(session.metadata) : session.activeExecution?.requestEnvelope.metadata ? structuredClone(session.activeExecution.requestEnvelope.metadata) : {},
 		messages
@@ -961,7 +963,8 @@ function toLiveSessionSummary(session) {
 		sessionId: session.sessionId,
 		...readOptionalAgentId$1(session.agentId) ? { agentId: readOptionalAgentId$1(session.agentId) } : {},
 		messageCount: messages.length,
-		updatedAt: now(),
+		updatedAt,
+		...messages.length > 0 ? { lastMessageAt: messages[messages.length - 1]?.timestamp ?? updatedAt } : {},
 		status: session.activeExecution ? "running" : "idle",
 		...Object.keys(metadata).length > 0 ? { metadata } : {}
 	};
@@ -969,7 +972,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;
@@ -983,14 +986,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 {
@@ -1331,4 +1334,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.5",
+  "version": "0.5.7",
   "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.0"
+    "@nextclaw/ncp": "0.5.2"
   },
   "devDependencies": {
     "@types/node": "^20.17.6",
     "prettier": "^3.3.3",
     "typescript": "^5.6.3",
     "vitest": "^4.1.2",
-    "@nextclaw/ncp-agent-runtime": "0.3.10"
+    "@nextclaw/ncp-agent-runtime": "0.3.12"
   },
   "scripts": {
     "build": "tsdown src/index.ts --dts --clean --target es2022 --no-fixedExtension",