@nextclaw/ncp 0.5.10 → 0.5.12

package/dist/index.d.ts

@@ -671,6 +671,14 @@ type NcpRunContext = {
   sessionId?: string;
   abortDisabledReason?: string | null;
 };
+/** Command acknowledgement returned after a user message has been accepted. */
+type NcpRunHandle = {
+  sessionId: string;
+  userMessageId: string;
+  assistantMessageId: string | null;
+  runId: string | null;
+  correlationId?: string;
+};
 /** Schema for run.metadata.metadata when kind is "ready" (run started, backend ready). */
 type NcpRunReadyMetadata = {
   kind: "ready";
@@ -742,8 +750,8 @@ interface NcpEndpoint {
  * (e.g. frontend, CLI) that sends user messages and receives agent responses.
  */
 interface NcpAgentClientEndpoint extends NcpEndpoint {
-  /** Sends a new message request to the agent. Emits `message.request`. */
-  send(envelope: NcpAgentSendEnvelope): Promise<void>;
+  /** Sends a command-only message request to the agent and returns the run handle. */
+  send(envelope: NcpAgentSendEnvelope): Promise<NcpRunHandle>;
   /** Attaches to the live event stream of a session. Emits `message.stream-request`. */
   stream(payload: NcpStreamRequestPayload): Promise<void>;
   /** Aborts the active execution of a session. Emits `message.abort`. */
@@ -1014,4 +1022,8 @@ declare function normalizeAssistantText(text: string, mode: NcpAssistantReasonin
   parts: NcpAssistantReasoningSegment[];
 };
 //#endregion
-export { ListMessagesOptions, ListSessionsOptions, NCP_INTERNAL_VISIBILITY_METADATA_KEY, NcpActionPart, NcpAgentClientEndpoint, NcpAgentConversationHydrationParams, NcpAgentConversationSnapshot, NcpAgentConversationStateManager, NcpAgentRunApi, NcpAgentRunInput, NcpAgentRunOptions, NcpAgentRunSendOptions, NcpAgentRunStreamOptions, NcpAgentRuntime, NcpAgentSendEnvelope, NcpAgentServerEndpoint, NcpAgentStreamProvider, NcpAssistantReasoningNormalizationMode, NcpAssistantReasoningSegment, NcpAssistantTextStreamNormalizer, NcpCardPart, NcpCompletedEnvelope, NcpContextBuilder, NcpContextPrepareOptions, NcpContextWindowUpdatedPayload, NcpConversationSnapshot, NcpConversationStateManager, NcpEncodeContext, NcpEndpoint, NcpEndpointEvent, NcpEndpointKind, NcpEndpointLatency, NcpEndpointManifest, NcpEndpointSubscriber, NcpError, NcpErrorCode, NcpEventType, NcpExtensionPart, NcpFailedEnvelope, NcpFilePart, NcpInvalidToolArgumentsResult, NcpLLMApi, NcpLLMApiInput, NcpLLMApiOptions, NcpMessage, NcpMessageAbortPayload, NcpMessageAcceptedPayload, NcpMessageDeliveredPayload, NcpMessagePart, NcpMessageReactionPayload, NcpMessageReadPayload, NcpMessageRecalledPayload, NcpMessageRole, NcpMessageSentPayload, NcpMessageStatus, NcpOutboundMessageDraft, NcpPendingToolCall, NcpPresenceUpdatedPayload, NcpProviderRuntimeRoute, NcpReasoningDeltaPayload, NcpReasoningEndPayload, NcpReasoningPart, NcpReasoningStartPayload, NcpReplyTagParseResult, NcpRequestEnvelope, NcpResponseEnvelope, NcpRichTextPart, NcpRoundBuffer, NcpRunContext, NcpRunErrorPayload, NcpRunFinalMetadata, NcpRunFinishedPayload, NcpRunMetadataPayload, NcpRunReadyMetadata, NcpRunStartedPayload, NcpSessionApi, NcpSessionPatch, NcpSessionStatus, NcpSessionSummary, NcpSourcePart, NcpStepStartPart, NcpStreamEncoder, NcpStreamRequestPayload, NcpTextDeltaPayload, NcpTextEndPayload, NcpTextPart, NcpTextStartPayload, NcpTool, NcpToolCallArgsDeltaPayload, NcpToolCallArgsPayload, NcpToolCallEndPayload, NcpToolCallResult, NcpToolCallResultPayload, NcpToolCallStartPayload, NcpToolDefinition, NcpToolInvocationPart, NcpToolOutputContentItem, NcpToolOutputImageItem, NcpToolOutputTextItem, NcpToolRegistry, NcpTypingEndPayload, NcpTypingStartPayload, OpenAIChatChunk, OpenAIChatMessage, OpenAIContentPart, OpenAITool, OpenAIToolCall, OpenAIToolCallDelta, isHiddenNcpMessage, normalizeAssistantText, readAssistantReasoningNormalizationMode, readAssistantReasoningNormalizationModeFromMetadata, sanitizeAssistantReplyTags, stripReplyTagsFromText, writeAssistantReasoningNormalizationModeToMetadata };
+//#region src/toolkit/run-handle.d.ts
+declare function createNcpRunHandle(envelope: NcpRequestEnvelope): NcpRunHandle;
+declare function consumeNcpRunHandle(events: AsyncIterable<NcpEndpointEvent>, fallback: NcpRunHandle): Promise<NcpRunHandle>;
+//#endregion
+export { ListMessagesOptions, ListSessionsOptions, NCP_INTERNAL_VISIBILITY_METADATA_KEY, NcpActionPart, NcpAgentClientEndpoint, NcpAgentConversationHydrationParams, NcpAgentConversationSnapshot, NcpAgentConversationStateManager, NcpAgentRunApi, NcpAgentRunInput, NcpAgentRunOptions, NcpAgentRunSendOptions, NcpAgentRunStreamOptions, NcpAgentRuntime, NcpAgentSendEnvelope, NcpAgentServerEndpoint, NcpAgentStreamProvider, NcpAssistantReasoningNormalizationMode, NcpAssistantReasoningSegment, NcpAssistantTextStreamNormalizer, NcpCardPart, NcpCompletedEnvelope, NcpContextBuilder, NcpContextPrepareOptions, NcpContextWindowUpdatedPayload, NcpConversationSnapshot, NcpConversationStateManager, NcpEncodeContext, NcpEndpoint, NcpEndpointEvent, NcpEndpointKind, NcpEndpointLatency, NcpEndpointManifest, NcpEndpointSubscriber, NcpError, NcpErrorCode, NcpEventType, NcpExtensionPart, NcpFailedEnvelope, NcpFilePart, NcpInvalidToolArgumentsResult, NcpLLMApi, NcpLLMApiInput, NcpLLMApiOptions, NcpMessage, NcpMessageAbortPayload, NcpMessageAcceptedPayload, NcpMessageDeliveredPayload, NcpMessagePart, NcpMessageReactionPayload, NcpMessageReadPayload, NcpMessageRecalledPayload, NcpMessageRole, NcpMessageSentPayload, NcpMessageStatus, NcpOutboundMessageDraft, NcpPendingToolCall, NcpPresenceUpdatedPayload, NcpProviderRuntimeRoute, NcpReasoningDeltaPayload, NcpReasoningEndPayload, NcpReasoningPart, NcpReasoningStartPayload, NcpReplyTagParseResult, NcpRequestEnvelope, NcpResponseEnvelope, NcpRichTextPart, NcpRoundBuffer, NcpRunContext, NcpRunErrorPayload, NcpRunFinalMetadata, NcpRunFinishedPayload, NcpRunHandle, NcpRunMetadataPayload, NcpRunReadyMetadata, NcpRunStartedPayload, NcpSessionApi, NcpSessionPatch, NcpSessionStatus, NcpSessionSummary, NcpSourcePart, NcpStepStartPart, NcpStreamEncoder, NcpStreamRequestPayload, NcpTextDeltaPayload, NcpTextEndPayload, NcpTextPart, NcpTextStartPayload, NcpTool, NcpToolCallArgsDeltaPayload, NcpToolCallArgsPayload, NcpToolCallEndPayload, NcpToolCallResult, NcpToolCallResultPayload, NcpToolCallStartPayload, NcpToolDefinition, NcpToolInvocationPart, NcpToolOutputContentItem, NcpToolOutputImageItem, NcpToolOutputTextItem, NcpToolRegistry, NcpTypingEndPayload, NcpTypingStartPayload, OpenAIChatChunk, OpenAIChatMessage, OpenAIContentPart, OpenAITool, OpenAIToolCall, OpenAIToolCallDelta, consumeNcpRunHandle, createNcpRunHandle, isHiddenNcpMessage, normalizeAssistantText, readAssistantReasoningNormalizationMode, readAssistantReasoningNormalizationModeFromMetadata, sanitizeAssistantReplyTags, stripReplyTagsFromText, writeAssistantReasoningNormalizationModeToMetadata };

package/dist/index.js

@@ -282,4 +282,41 @@ function normalizeAssistantText(text, mode) {
 	};
 }
 //#endregion
-export { NCP_INTERNAL_VISIBILITY_METADATA_KEY, NcpAssistantTextStreamNormalizer, NcpEventType, isHiddenNcpMessage, normalizeAssistantText, readAssistantReasoningNormalizationMode, readAssistantReasoningNormalizationModeFromMetadata, sanitizeAssistantReplyTags, stripReplyTagsFromText, writeAssistantReasoningNormalizationModeToMetadata };
+//#region src/toolkit/run-handle.ts
+function createNcpRunHandle(envelope) {
+	return {
+		sessionId: envelope.sessionId,
+		userMessageId: envelope.message.id,
+		assistantMessageId: null,
+		runId: null,
+		...envelope.correlationId ? { correlationId: envelope.correlationId } : {}
+	};
+}
+function consumeNcpRunHandle(events, fallback) {
+	let resolved = false;
+	let handle = fallback;
+	return new Promise((resolve, reject) => {
+		const resolveOnce = () => {
+			if (resolved) return;
+			resolved = true;
+			resolve(handle);
+		};
+		(async () => {
+			try {
+				for await (const event of events) if (event.type === NcpEventType.RunStarted) {
+					handle = {
+						...handle,
+						assistantMessageId: event.payload.messageId ?? null,
+						runId: event.payload.runId ?? null
+					};
+					resolveOnce();
+				}
+				resolveOnce();
+			} catch (error) {
+				if (!resolved) reject(error);
+			}
+		})();
+	});
+}
+//#endregion
+export { NCP_INTERNAL_VISIBILITY_METADATA_KEY, NcpAssistantTextStreamNormalizer, NcpEventType, consumeNcpRunHandle, createNcpRunHandle, isHiddenNcpMessage, normalizeAssistantText, readAssistantReasoningNormalizationMode, readAssistantReasoningNormalizationModeFromMetadata, sanitizeAssistantReplyTags, stripReplyTagsFromText, writeAssistantReasoningNormalizationModeToMetadata };

package/package.json

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