@nextclaw/ncp 0.1.1 → 0.3.0

package/README.md

@@ -5,7 +5,7 @@ Core protocol types and endpoint abstractions for universal communication in Nex
 ## Build
 
 ```bash
-pnpm -C packages/nextclaw-ncp build
+pnpm -C packages/ncp-packages/nextclaw-ncp build
 ```
 
 ## Scope

package/dist/index.d.ts

@@ -163,7 +163,7 @@ type NcpEndpointLatency = "realtime" | "seconds" | "minutes" | "hours" | "days";
  *
  * Consumers use the manifest for runtime capability discovery —
  * e.g. whether to show a typing indicator, whether to offer file uploads,
- * or whether session resume is available.
+ * or whether an existing run can be streamed again.
  */
 type NcpEndpointManifest = {
     /** Category of this endpoint. */
@@ -178,8 +178,8 @@ type NcpEndpointManifest = {
     supportsAbort: boolean;
     /** Whether this endpoint can push messages without a prior user request. */
     supportsProactiveMessages: boolean;
-    /** Whether a disconnected session can be resumed by the same `sessionId`. */
-    supportsSessionResume: boolean;
+    /** Whether this endpoint can stream the live events of an active session by `sessionId`. */
+    supportsLiveSessionStream: boolean;
     /**
      * The subset of `NcpMessagePart` types this endpoint can send or receive.
      * Using the literal union from `NcpMessagePart["type"]` prevents typos
@@ -215,20 +215,6 @@ type NcpError = {
     /** Original cause — preserved for debugging but not guaranteed serializable. */
     cause?: unknown;
 };
-/**
- * Throwable form of `NcpError` for use in exception-based control flows.
- *
- * Bridges typed protocol errors with standard JS `Error` hierarchies so that
- * `instanceof` checks and stack traces work as expected.
- *
- * @example
- * throw new NcpErrorException("auth-error", "Missing API key");
- */
-declare class NcpErrorException extends Error {
-    readonly code: NcpErrorCode;
-    readonly details?: Record<string, unknown>;
-    constructor(code: NcpErrorCode, message: string, details?: Record<string, unknown>);
-}
 
 type NcpSessionStatus = "idle" | "running";
 type NcpSessionSummary = {
@@ -236,7 +222,7 @@ type NcpSessionSummary = {
     messageCount: number;
     updatedAt: string;
     status?: NcpSessionStatus;
-    activeRunId?: string;
+    metadata?: Record<string, unknown>;
 };
 type ListSessionsOptions = {
     limit?: number;
@@ -295,20 +281,17 @@ type NcpMessageAcceptedPayload = {
     correlationId?: string;
     transportId?: string;
 };
-/** Payload for message.abort: identifies which request or run to cancel. */
+/** Payload for message.abort: identifies which session's active execution to cancel. */
 type NcpMessageAbortPayload = {
+    sessionId: string;
     messageId?: string;
-    correlationId?: string;
-    runId?: string;
 };
 /**
- * Payload for message.resume-request: resume an existing run by its remote id.
- * Used when reconnecting to a stream (e.g. after page refresh).
+ * Payload for message.stream-request: attach to the live event stream of a session.
+ * Used when reconnecting during an active response or attaching another live reader.
  */
-type NcpResumeRequestPayload = {
+type NcpStreamRequestPayload = {
     sessionId: string;
-    remoteRunId: string;
-    fromEventIndex?: number;
     metadata?: Record<string, unknown>;
 };
 /**
@@ -435,100 +418,134 @@ type NcpToolCallResultPayload = {
     toolCallId: string;
     content: unknown;
 };
+declare enum NcpEventType {
+    EndpointReady = "endpoint.ready",
+    EndpointError = "endpoint.error",
+    MessageRequest = "message.request",
+    MessageStreamRequest = "message.stream-request",
+    MessageSent = "message.sent",
+    MessageAccepted = "message.accepted",
+    MessageIncoming = "message.incoming",
+    MessageCompleted = "message.completed",
+    MessageFailed = "message.failed",
+    MessageAbort = "message.abort",
+    MessageTextStart = "message.text-start",
+    MessageTextDelta = "message.text-delta",
+    MessageTextEnd = "message.text-end",
+    MessageReasoningStart = "message.reasoning-start",
+    MessageReasoningDelta = "message.reasoning-delta",
+    MessageReasoningEnd = "message.reasoning-end",
+    MessageToolCallStart = "message.tool-call-start",
+    MessageToolCallArgs = "message.tool-call-args",
+    MessageToolCallArgsDelta = "message.tool-call-args-delta",
+    MessageToolCallEnd = "message.tool-call-end",
+    MessageToolCallResult = "message.tool-call-result",
+    MessageRead = "message.read",
+    MessageDelivered = "message.delivered",
+    MessageRecalled = "message.recalled",
+    MessageReaction = "message.reaction",
+    RunStarted = "run.started",
+    RunFinished = "run.finished",
+    RunError = "run.error",
+    RunMetadata = "run.metadata",
+    TypingStart = "typing.start",
+    TypingEnd = "typing.end",
+    PresenceUpdated = "presence.updated"
+}
 type NcpEndpointEvent = {
-    type: "endpoint.ready";
+    type: NcpEventType.EndpointReady;
 } | {
-    type: "message.request";
+    type: NcpEventType.MessageRequest;
     payload: NcpRequestEnvelope;
 } | {
-    type: "message.resume-request";
-    payload: NcpResumeRequestPayload;
+    type: NcpEventType.MessageStreamRequest;
+    payload: NcpStreamRequestPayload;
 } | {
-    type: "message.sent";
+    type: NcpEventType.MessageSent;
     payload: NcpMessageSentPayload;
 } | {
-    type: "message.accepted";
+    type: NcpEventType.MessageAccepted;
     payload: NcpMessageAcceptedPayload;
 } | {
-    type: "message.incoming";
+    type: NcpEventType.MessageIncoming;
     payload: NcpResponseEnvelope;
 } | {
-    type: "message.completed";
+    type: NcpEventType.MessageCompleted;
     payload: NcpCompletedEnvelope;
 } | {
-    type: "message.failed";
+    type: NcpEventType.MessageFailed;
     payload: NcpFailedEnvelope;
 } | {
-    type: "message.abort";
+    type: NcpEventType.MessageAbort;
     payload: NcpMessageAbortPayload;
 } | {
-    type: "endpoint.error";
+    type: NcpEventType.EndpointError;
     payload: NcpError;
 } | {
-    type: "run.started";
+    type: NcpEventType.RunStarted;
     payload: NcpRunStartedPayload;
 } | {
-    type: "run.finished";
+    type: NcpEventType.RunFinished;
     payload: NcpRunFinishedPayload;
 } | {
-    type: "run.error";
+    type: NcpEventType.RunError;
     payload: NcpRunErrorPayload;
 } | {
-    type: "run.metadata";
+    type: NcpEventType.RunMetadata;
     payload: NcpRunMetadataPayload;
 } | {
-    type: "message.text-start";
+    type: NcpEventType.MessageTextStart;
     payload: NcpTextStartPayload;
 } | {
-    type: "message.text-delta";
+    type: NcpEventType.MessageTextDelta;
     payload: NcpTextDeltaPayload;
 } | {
-    type: "message.text-end";
+    type: NcpEventType.MessageTextEnd;
     payload: NcpTextEndPayload;
 } | {
-    type: "message.reasoning-start";
+    type: NcpEventType.MessageReasoningStart;
     payload: NcpReasoningStartPayload;
 } | {
-    type: "message.reasoning-delta";
+    type: NcpEventType.MessageReasoningDelta;
     payload: NcpReasoningDeltaPayload;
 } | {
-    type: "message.reasoning-end";
+    type: NcpEventType.MessageReasoningEnd;
     payload: NcpReasoningEndPayload;
 } | {
-    type: "message.tool-call-start";
+    type: NcpEventType.MessageToolCallStart;
     payload: NcpToolCallStartPayload;
 } | {
-    type: "message.tool-call-args";
+    type: NcpEventType.MessageToolCallArgs;
     payload: NcpToolCallArgsPayload;
 } | {
-    type: "message.tool-call-args-delta";
+    type: NcpEventType.MessageToolCallArgsDelta;
     payload: NcpToolCallArgsDeltaPayload;
 } | {
-    type: "message.tool-call-end";
+    type: NcpEventType.MessageToolCallEnd;
     payload: NcpToolCallEndPayload;
 } | {
-    type: "message.tool-call-result";
+    type: NcpEventType.MessageToolCallResult;
     payload: NcpToolCallResultPayload;
 } | {
-    type: "typing.start";
+    type: NcpEventType.TypingStart;
     payload: NcpTypingStartPayload;
 } | {
-    type: "typing.end";
+    type: NcpEventType.TypingEnd;
     payload: NcpTypingEndPayload;
 } | {
-    type: "presence.updated";
+    type: NcpEventType.PresenceUpdated;
     payload: NcpPresenceUpdatedPayload;
 } | {
-    type: "message.read";
+    type: NcpEventType.MessageRead;
     payload: NcpMessageReadPayload;
 } | {
-    type: "message.delivered";
+    type: NcpEventType.MessageDelivered;
     payload: NcpMessageDeliveredPayload;
 } | {
-    type: "message.recalled";
+    type: NcpEventType.MessageRecalled;
     payload: NcpMessageRecalledPayload;
 } | {
-    type: "message.reaction";
+    type: NcpEventType.MessageReaction;
     payload: NcpMessageReactionPayload;
 };
 type NcpEndpointSubscriber = (event: NcpEndpointEvent) => void;
@@ -568,7 +585,7 @@ type NcpRunFinalMetadata = {
  * const endpoint: NcpEndpoint = new MyAgentEndpoint(options);
  * await endpoint.start();
  * endpoint.subscribe((event) => { ... });
- * await endpoint.emit({ type: "message.request", payload: envelope });
+ * await endpoint.emit({ type: NcpEventType.MessageRequest, payload: envelope });
  */
 interface NcpEndpoint {
     /** Static capability declaration — available before `start()` is called. */
@@ -598,7 +615,7 @@ interface NcpEndpoint {
      *
      * @example
      * const unsubscribe = endpoint.subscribe((event) => {
-     *   if (event.type === "message.completed") handleReply(event.payload);
+     *   if (event.type === NcpEventType.MessageCompleted) handleReply(event.payload);
      * });
      * unsubscribe();
      */
@@ -614,60 +631,222 @@ interface NcpEndpoint {
 interface NcpAgentClientEndpoint extends NcpEndpoint {
     /** Sends a new message request to the agent. Emits `message.request`. */
     send(envelope: NcpRequestEnvelope): Promise<void>;
-    /** Resumes an existing run by remote run id. Emits `message.resume-request`. */
-    resume(payload: NcpResumeRequestPayload): Promise<void>;
-    /** Aborts the current or specified run. Emits `message.abort`. */
-    abort(payload?: NcpMessageAbortPayload): Promise<void>;
+    /** 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`. */
+    abort(payload: NcpMessageAbortPayload): Promise<void>;
 }
 
 /**
- * Agent server-side endpoint: receives requests and emits responses.
+ * Agent server-side endpoint: receives requests and produces downstream events.
  *
  * Extends `NcpEndpoint` with a manifest constraint (`endpointKind: "agent"`).
- * Use this on the server side that processes `message.request` / `message.resume-request`
- * and emits `message.incoming`, streaming deltas, `message.completed`, etc.
+ * Use this on the server side that handles send/stream/abort requests and emits
+ * downstream events (`message.incoming`, streaming deltas, `message.completed`, etc.).
  */
 interface NcpAgentServerEndpoint extends NcpEndpoint {
     readonly manifest: NcpEndpointManifest & {
         endpointKind: "agent";
     };
+    /** Handles a new message request from client side and yields produced events. */
+    send(envelope: NcpRequestEnvelope, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<NcpEndpointEvent>;
+    /** Streams live events for an active session and yields produced events. */
+    stream(payload: NcpStreamRequestPayload, options?: {
+        signal?: AbortSignal;
+    }): AsyncIterable<NcpEndpointEvent>;
+    /** Aborts the active execution of a session on server side. */
+    abort(payload: NcpMessageAbortPayload): Promise<void>;
+    /**
+     * Publishes server-downstream events (typically sent to frontend subscribers/transports).
+     * For handling client requests, prefer `send` / `stream` / `abort`.
+     */
+    emit(event: NcpEndpointEvent): Promise<void>;
 }
 
-/**
- * Creates an NcpAgentClientEndpoint that forwards to an in-process NcpAgentServerEndpoint.
- * Use when the agent runs in-process and you need to pass a client endpoint to the HTTP server.
- */
-declare function createAgentClientFromServer(server: NcpAgentServerEndpoint): NcpAgentClientEndpoint;
-
 type NcpAgentRunInput = {
-    kind: "request";
-    payload: NcpRequestEnvelope;
-} | {
-    kind: "resume";
-    payload: NcpResumeRequestPayload;
+    sessionId: string;
+    messages: ReadonlyArray<NcpMessage>;
+    correlationId?: string;
+    metadata?: Record<string, unknown>;
 };
 type NcpAgentRunOptions = {
     signal?: AbortSignal;
-    sessionMessages?: ReadonlyArray<NcpMessage>;
 };
 interface NcpAgentRuntime {
     run(input: NcpAgentRunInput, options?: NcpAgentRunOptions): AsyncIterable<NcpEndpointEvent>;
 }
 
-type NcpAgentBackendSendOptions = {
+type OpenAIContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "low" | "high" | "auto";
+    };
+};
+type OpenAIToolCall = {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+type OpenAIChatMessage = {
+    role: "system";
+    content: string;
+} | {
+    role: "user";
+    content: string | OpenAIContentPart[];
+} | {
+    role: "assistant";
+    content?: string | null;
+    reasoning_content?: string;
+    tool_calls?: OpenAIToolCall[];
+} | {
+    role: "tool";
+    content: string;
+    tool_call_id: string;
+};
+type OpenAITool = {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+};
+type OpenAIToolCallDelta = {
+    index?: number;
+    id?: string;
+    type?: "function";
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+};
+type OpenAIChatChunk = {
+    id?: string;
+    choices?: Array<{
+        index?: number;
+        delta?: {
+            content?: string | null;
+            tool_calls?: OpenAIToolCallDelta[];
+            reasoning_content?: string;
+            reasoning?: string;
+        };
+        finish_reason?: string | null;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+    };
+};
+type NcpLLMApiInput = {
+    messages: OpenAIChatMessage[];
+    tools?: OpenAITool[];
+    model?: string;
+    thinkingLevel?: string | null;
+    max_tokens?: number;
+};
+type NcpLLMApiOptions = {
     signal?: AbortSignal;
+    temperature?: number;
+};
+interface NcpLLMApi {
+    generate(input: NcpLLMApiInput, options?: NcpLLMApiOptions): AsyncIterable<OpenAIChatChunk>;
+}
+
+type NcpContextPrepareOptions = {
+    sessionMessages?: ReadonlyArray<NcpMessage>;
+    systemPrompt?: string;
+    maxMessages?: number;
+};
+interface NcpContextBuilder {
+    prepare(input: NcpAgentRunInput, options?: NcpContextPrepareOptions): NcpLLMApiInput;
+}
+
+type NcpToolDefinition = {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+};
+interface NcpTool {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters?: Record<string, unknown>;
+    execute(args: unknown): Promise<unknown>;
+}
+type NcpToolCallResult = {
+    toolCallId: string;
+    toolName: string;
+    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[];
+    };
 };
-type NcpAgentBackendReconnectOptions = {
+interface NcpToolRegistry {
+    listTools(): ReadonlyArray<NcpTool>;
+    getTool(name: string): NcpTool | undefined;
+    getToolDefinitions(): ReadonlyArray<NcpToolDefinition>;
+    execute(toolCallId: string, toolName: string, args: unknown): Promise<unknown>;
+}
+
+type NcpEncodeContext = {
+    sessionId: string;
+    messageId: string;
+    runId: string;
+    correlationId?: string;
+};
+interface NcpStreamEncoder {
+    encode(stream: AsyncIterable<OpenAIChatChunk>, context: NcpEncodeContext): AsyncIterable<NcpEndpointEvent>;
+}
+
+type NcpPendingToolCall = {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+};
+interface NcpRoundBuffer {
+    appendText(delta: string): void;
+    getText(): string;
+    appendToolCall(result: NcpToolCallResult): void;
+    getToolCalls(): ReadonlyArray<NcpToolCallResult>;
+    startToolCall(toolCallId: string, toolName: string): void;
+    appendToolCallArgs(args: unknown): void;
+    consumePendingToolCall(): NcpPendingToolCall | null;
+    clear(): void;
+}
+
+type NcpAgentRunSendOptions = {
+    signal?: AbortSignal;
+};
+type NcpAgentRunStreamOptions = {
     signal?: AbortSignal;
 };
-interface NcpAgentBackendController extends NcpSessionApi {
-    send(envelope: NcpRequestEnvelope, options?: NcpAgentBackendSendOptions): AsyncIterable<NcpEndpointEvent>;
-    reconnect(payload: NcpResumeRequestPayload, options?: NcpAgentBackendReconnectOptions): AsyncIterable<NcpEndpointEvent>;
+interface NcpAgentRunApi {
+    send(envelope: NcpRequestEnvelope, options?: NcpAgentRunSendOptions): AsyncIterable<NcpEndpointEvent>;
+    stream(payload: NcpStreamRequestPayload, options?: NcpAgentRunStreamOptions): AsyncIterable<NcpEndpointEvent>;
     abort(payload: NcpMessageAbortPayload): Promise<void>;
 }
-type NcpAgentReplayProvider = {
+type NcpAgentStreamProvider = {
     stream(params: {
-        payload: NcpResumeRequestPayload;
+        payload: NcpStreamRequestPayload;
         signal: AbortSignal;
     }): AsyncIterable<NcpEndpointEvent>;
 };
@@ -716,6 +895,11 @@ interface NcpConversationStateManager {
     subscribe(listener: (snapshot: NcpConversationSnapshot) => void): () => void;
 }
 
+type NcpAgentConversationHydrationParams = {
+    sessionId: string;
+    messages: ReadonlyArray<NcpMessage>;
+    activeRun?: NcpRunContext | null;
+};
 /**
  * Agent-scenario state manager: extends the generic conversation state manager
  * with explicit handle methods for each NCP event type that affects agent conversation state.
@@ -725,13 +909,10 @@ interface NcpConversationStateManager {
  */
 interface NcpAgentConversationStateManager extends NcpConversationStateManager {
     getSnapshot(): NcpAgentConversationSnapshot;
-    handleMessageRequest(payload: NcpRequestEnvelope): void;
+    reset(): void;
+    hydrate(payload: NcpAgentConversationHydrationParams): void;
     /** Local peer sent a message (outbound); typically non-streaming. Add to messages. */
     handleMessageSent(payload: NcpMessageSentPayload): void;
-    handleMessageAccepted(payload: NcpMessageAcceptedPayload): void;
-    handleMessageIncoming(payload: NcpResponseEnvelope): void;
-    handleMessageCompleted(payload: NcpCompletedEnvelope): void;
-    handleMessageFailed(payload: NcpFailedEnvelope): void;
     handleMessageAbort(payload: NcpMessageAbortPayload): void;
     handleMessageTextStart(payload: NcpTextStartPayload): void;
     handleMessageTextDelta(payload: NcpTextDeltaPayload): void;
@@ -751,4 +932,11 @@ interface NcpAgentConversationStateManager extends NcpConversationStateManager {
     handleEndpointError(payload: NcpError): void;
 }
 
-export { type ListMessagesOptions, type ListSessionsOptions, type NcpActionPart, type NcpAgentBackendController, type NcpAgentBackendReconnectOptions, type NcpAgentBackendSendOptions, type NcpAgentClientEndpoint, type NcpAgentConversationSnapshot, type NcpAgentConversationStateManager, type NcpAgentReplayProvider, type NcpAgentRunInput, type NcpAgentRunOptions, type NcpAgentRuntime, type NcpAgentServerEndpoint, type NcpCardPart, type NcpCompletedEnvelope, type NcpConversationSnapshot, type NcpConversationStateManager, type NcpEndpoint, type NcpEndpointEvent, type NcpEndpointKind, type NcpEndpointLatency, type NcpEndpointManifest, type NcpEndpointSubscriber, type NcpError, type NcpErrorCode, NcpErrorException, type NcpExtensionPart, type NcpFailedEnvelope, type NcpFilePart, type NcpMessage, type NcpMessageAbortPayload, type NcpMessageAcceptedPayload, type NcpMessageDeliveredPayload, type NcpMessagePart, type NcpMessageReactionPayload, type NcpMessageReadPayload, type NcpMessageRecalledPayload, type NcpMessageRole, type NcpMessageSentPayload, type NcpMessageStatus, type NcpPresenceUpdatedPayload, type NcpReasoningDeltaPayload, type NcpReasoningEndPayload, type NcpReasoningPart, type NcpReasoningStartPayload, type NcpRequestEnvelope, type NcpResponseEnvelope, type NcpResumeRequestPayload, type NcpRichTextPart, 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 NcpTextDeltaPayload, type NcpTextEndPayload, type NcpTextPart, type NcpTextStartPayload, type NcpToolCallArgsDeltaPayload, type NcpToolCallArgsPayload, type NcpToolCallEndPayload, type NcpToolCallResultPayload, type NcpToolCallStartPayload, type NcpToolInvocationPart, type NcpTypingEndPayload, type NcpTypingStartPayload, createAgentClientFromServer };
+type NcpReplyTagParseResult = {
+    content: string;
+    replyTo?: string;
+};
+declare function stripReplyTagsFromText(content: string, currentMessageId?: string): NcpReplyTagParseResult;
+declare function sanitizeAssistantReplyTags(message: NcpMessage, currentMessageId?: string): NcpMessage;
+
+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 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 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, sanitizeAssistantReplyTags, stripReplyTagsFromText };

package/dist/index.js

@@ -1,31 +1,119 @@
-// src/types/errors.ts
-var NcpErrorException = class extends Error {
-  code;
-  details;
-  constructor(code, message, details) {
-    super(message);
-    this.name = "NcpErrorException";
-    this.code = code;
-    this.details = details;
-  }
-};
+// src/types/events.ts
+var NcpEventType = /* @__PURE__ */ ((NcpEventType2) => {
+  NcpEventType2["EndpointReady"] = "endpoint.ready";
+  NcpEventType2["EndpointError"] = "endpoint.error";
+  NcpEventType2["MessageRequest"] = "message.request";
+  NcpEventType2["MessageStreamRequest"] = "message.stream-request";
+  NcpEventType2["MessageSent"] = "message.sent";
+  NcpEventType2["MessageAccepted"] = "message.accepted";
+  NcpEventType2["MessageIncoming"] = "message.incoming";
+  NcpEventType2["MessageCompleted"] = "message.completed";
+  NcpEventType2["MessageFailed"] = "message.failed";
+  NcpEventType2["MessageAbort"] = "message.abort";
+  NcpEventType2["MessageTextStart"] = "message.text-start";
+  NcpEventType2["MessageTextDelta"] = "message.text-delta";
+  NcpEventType2["MessageTextEnd"] = "message.text-end";
+  NcpEventType2["MessageReasoningStart"] = "message.reasoning-start";
+  NcpEventType2["MessageReasoningDelta"] = "message.reasoning-delta";
+  NcpEventType2["MessageReasoningEnd"] = "message.reasoning-end";
+  NcpEventType2["MessageToolCallStart"] = "message.tool-call-start";
+  NcpEventType2["MessageToolCallArgs"] = "message.tool-call-args";
+  NcpEventType2["MessageToolCallArgsDelta"] = "message.tool-call-args-delta";
+  NcpEventType2["MessageToolCallEnd"] = "message.tool-call-end";
+  NcpEventType2["MessageToolCallResult"] = "message.tool-call-result";
+  NcpEventType2["MessageRead"] = "message.read";
+  NcpEventType2["MessageDelivered"] = "message.delivered";
+  NcpEventType2["MessageRecalled"] = "message.recalled";
+  NcpEventType2["MessageReaction"] = "message.reaction";
+  NcpEventType2["RunStarted"] = "run.started";
+  NcpEventType2["RunFinished"] = "run.finished";
+  NcpEventType2["RunError"] = "run.error";
+  NcpEventType2["RunMetadata"] = "run.metadata";
+  NcpEventType2["TypingStart"] = "typing.start";
+  NcpEventType2["TypingEnd"] = "typing.end";
+  NcpEventType2["PresenceUpdated"] = "presence.updated";
+  return NcpEventType2;
+})(NcpEventType || {});
 
-// src/endpoint/agent-client-from-server.ts
-function createAgentClientFromServer(server) {
-  return {
-    ...server,
-    async send(envelope) {
-      await server.emit({ type: "message.request", payload: envelope });
-    },
-    async resume(payload) {
-      await server.emit({ type: "message.resume-request", payload });
-    },
-    async abort(payload) {
-      await server.emit({ type: "message.abort", payload: payload ?? {} });
+// 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
   };
 }
 export {
-  NcpErrorException,
-  createAgentClientFromServer
+  NcpEventType,
+  sanitizeAssistantReplyTags,
+  stripReplyTagsFromText
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "private": false,
   "description": "NextClaw Communication Protocol core abstractions and types.",
   "type": "module",
@@ -16,10 +16,6 @@
   ],
   "devDependencies": {
     "@types/node": "^20.17.6",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "eslint": "^8.57.1",
-    "eslint-config-prettier": "^9.1.0",
     "prettier": "^3.3.3",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3"