@nextclaw/ncp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+# @nextclaw/ncp
+
+Core protocol types and endpoint abstractions for universal communication in NextClaw.
+
+## Build
+
+```bash
+pnpm -C packages/nextclaw-ncp build
+```
+
+## Scope
+
+- NCP manifest, message, session, and error definitions
+- Generic endpoint base class (`AbstractEndpoint`)
+
+## Usage
+
+See [docs/USAGE.md](docs/USAGE.md) for real-world scenarios and example code (in-process endpoint, bridging two endpoints, agent adapter).

package/dist/index.d.ts

@@ -0,0 +1,663 @@
+/**
+ * Participants in an NCP conversation.
+ *
+ * - `user`      — A human end-user interacting with the system.
+ * - `assistant` — An AI model generating responses.
+ * - `system`    — Configuration or instruction injected before the conversation.
+ * - `tool`      — The result returned by a tool invocation.
+ * - `service`   — A platform-side notification or event (e.g. a bot posting a card),
+ *                 distinct from an AI assistant response.
+ */
+type NcpMessageRole = "user" | "assistant" | "system" | "tool" | "service";
+/**
+ * Lifecycle state of a message.
+ *
+ * Applies to both streaming and non-streaming endpoints:
+ * - `pending`   — Created but not yet sent or received.
+ * - `streaming` — Actively receiving incremental deltas.
+ * - `final`     — Fully received; no further updates expected.
+ * - `error`     — Terminated with an error; `parts` may be incomplete.
+ */
+type NcpMessageStatus = "pending" | "streaming" | "final" | "error";
+/** Plain text content. The most common part type. */
+type NcpTextPart = {
+    type: "text";
+    text: string;
+};
+/**
+ * A file attachment, delivered either as a URL or inline Base64 content.
+ *
+ * `url` and `contentBase64` are mutually exclusive — populate exactly one.
+ */
+type NcpFilePart = {
+    type: "file";
+    name?: string;
+    mimeType?: string;
+    /** Remote URL pointing to the file. Mutually exclusive with `contentBase64`. */
+    url?: string;
+    /** Inline file content encoded as Base64. Mutually exclusive with `url`. */
+    contentBase64?: string;
+    sizeBytes?: number;
+};
+/** A cited source or reference, typically surfaced alongside AI-generated content. */
+type NcpSourcePart = {
+    type: "source";
+    title?: string;
+    url?: string;
+    /** Short excerpt from the source relevant to the message. */
+    snippet?: string;
+};
+/**
+ * Marks the beginning of a logical reasoning step in a multi-step response.
+ * Used by chain-of-thought or agentic flows to delimit discrete steps.
+ */
+type NcpStepStartPart = {
+    type: "step-start";
+    stepId?: string;
+    /** Human-readable label for the step (e.g. "Searching the web"). */
+    title?: string;
+};
+/** Internal reasoning text produced by the model before its final response. */
+type NcpReasoningPart = {
+    type: "reasoning";
+    text: string;
+};
+/**
+ * Represents a tool call and its lifecycle.
+ *
+ * State semantics (aligned with the Vercel AI SDK convention):
+ * - `"call"`         — The model has emitted a complete tool call; `args` is populated.
+ * - `"partial-call"` — Arguments are still being streamed; `args` may be incomplete.
+ * - `"result"`       — The tool has returned; `result` is populated.
+ */
+type NcpToolInvocationPart = {
+    type: "tool-invocation";
+    toolName: string;
+    toolCallId?: string;
+    state?: "call" | "partial-call" | "result";
+    /** Tool input arguments. May be partial when `state === "partial-call"`. */
+    args?: unknown;
+    /** Tool output. Populated when `state === "result"`. */
+    result?: unknown;
+};
+/**
+ * A rich card with arbitrary structured data.
+ * Rendering is delegated to the platform (e.g. Slack block kit, Teams card).
+ */
+type NcpCardPart = {
+    type: "card";
+    payload: Record<string, unknown>;
+};
+/** Formatted text with an explicit markup format hint. */
+type NcpRichTextPart = {
+    type: "rich-text";
+    format: "markdown" | "html" | "plain";
+    text: string;
+};
+/**
+ * An interactive action button or trigger exposed to the user.
+ * The platform is responsible for rendering and routing the action.
+ */
+type NcpActionPart = {
+    type: "action";
+    actionId: string;
+    /** Display label shown to the user. */
+    label: string;
+    /** Arbitrary data forwarded to the action handler. */
+    payload?: unknown;
+};
+/**
+ * Escape hatch for custom or future part types not yet in the NCP spec.
+ *
+ * Use this to avoid forking the protocol during early iterations.
+ * Once a part type stabilizes, promote it to a first-class `NcpXxxPart`.
+ */
+type NcpExtensionPart = {
+    type: "extension";
+    /** Namespaced identifier for the custom part (e.g. `"myapp.highlight"`). */
+    extensionType: string;
+    data: unknown;
+};
+/** Union of all recognized NCP message part types. */
+type NcpMessagePart = NcpTextPart | NcpFilePart | NcpSourcePart | NcpStepStartPart | NcpReasoningPart | NcpToolInvocationPart | NcpCardPart | NcpRichTextPart | NcpActionPart | NcpExtensionPart;
+/**
+ * Canonical message envelope exchanged and persisted in NCP.
+ *
+ * A message is composed of an ordered list of typed `parts`, allowing
+ * heterogeneous content (text, files, tool calls, etc.) in a single message.
+ */
+type NcpMessage = {
+    /** Globally unique message identifier. */
+    id: string;
+    /** The session this message belongs to. */
+    sessionKey: string;
+    role: NcpMessageRole;
+    status: NcpMessageStatus;
+    parts: NcpMessagePart[];
+    /** ISO 8601 timestamp (e.g. `"2024-01-15T10:30:00.000Z"`). */
+    timestamp: string;
+    /** Arbitrary transport- or application-level metadata. */
+    metadata?: Record<string, unknown>;
+};
+
+/**
+ * High-level category of an endpoint.
+ *
+ * Used for routing decisions, capability interpretation, and UI labeling.
+ * - `agent`    — An AI agent that processes and responds to messages.
+ * - `platform` — A collaboration platform (e.g. Slack, Teams, Discord).
+ * - `email`    — An email transport.
+ * - `human`    — A human operator or approval gate.
+ * - `custom`   — Any endpoint type not covered by the above.
+ */
+type NcpEndpointKind = "agent" | "platform" | "email" | "human" | "custom";
+/**
+ * Expected response latency profile of an endpoint.
+ *
+ * Used by the runtime and product layer to set user expectations,
+ * configure timeouts, and choose appropriate UX patterns.
+ */
+type NcpEndpointLatency = "realtime" | "seconds" | "minutes" | "hours" | "days";
+/**
+ * Capability manifest every endpoint adapter must expose.
+ *
+ * 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.
+ */
+type NcpEndpointManifest = {
+    /** Category of this endpoint. */
+    endpointKind: NcpEndpointKind;
+    /** Stable unique identifier for this endpoint instance. */
+    endpointId: string;
+    /** SemVer string for the adapter implementation. */
+    version: string;
+    /** Whether this endpoint supports incremental streaming of message content. */
+    supportsStreaming: boolean;
+    /** Whether in-flight requests can be cancelled via `AbortSignal`. */
+    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 `sessionKey`. */
+    supportsSessionResume: boolean;
+    /**
+     * The subset of `NcpMessagePart` types this endpoint can send or receive.
+     * Using the literal union from `NcpMessagePart["type"]` prevents typos
+     * and keeps the manifest in sync with the protocol definition.
+     */
+    supportedPartTypes: ReadonlyArray<NcpMessagePart["type"]>;
+    /** Expected response latency — informs timeouts and UX treatment. */
+    expectedLatency: NcpEndpointLatency;
+    /** Arbitrary adapter- or deployment-specific metadata. */
+    metadata?: Record<string, unknown>;
+};
+
+/**
+ * Protocol-level error categories.
+ *
+ * Uses kebab-case to be consistent with the rest of the NCP type literals
+ * (e.g. endpoint kinds, latency profiles).
+ */
+type NcpErrorCode = "config-error" | "auth-error" | "runtime-error" | "timeout-error" | "abort-error";
+/**
+ * Structured error payload used on endpoint and stream boundaries.
+ *
+ * Prefer this over raw `Error` objects when crossing async/transport
+ * boundaries so that error metadata survives serialization.
+ */
+type NcpError = {
+    /** Machine-readable category. */
+    code: NcpErrorCode;
+    /** Human-readable description intended for developers, not end-users. */
+    message: string;
+    /** Optional structured context (request ids, field paths, etc.). */
+    details?: Record<string, unknown>;
+    /** 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>);
+}
+
+/**
+ * Stable mapping between an NCP-internal session key and the endpoint's
+ * native session identifier.
+ *
+ * A single NCP session may span multiple endpoint sessions over time
+ * (e.g. after reconnects). This binding is the source of truth for that mapping.
+ */
+type NcpSessionBinding = {
+    /** The endpoint that owns this session. */
+    endpointId: string;
+    /** NCP-internal session identifier — stable across reconnects. */
+    sessionKey: string;
+    /**
+     * The session identifier used by the endpoint itself (e.g. an OpenAI thread id,
+     * a Slack channel + thread_ts pair, or a vendor-specific conversation id).
+     */
+    endpointSessionId: string;
+    /** Arbitrary metadata for adapter-specific session context. */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Lightweight snapshot of session state for orchestration and observability.
+ *
+ * Not a full history — use `NcpSessionContract.appendMessage` for the message log.
+ */
+type NcpSessionState = {
+    sessionKey: string;
+    endpointId: string;
+    /** Present once a binding has been established. */
+    endpointSessionId?: string;
+    /** Total number of messages appended to this session. */
+    messageCount: number;
+    /** ISO 8601 timestamp of the last state mutation. */
+    updatedAt: string;
+};
+/**
+ * Minimal storage contract for NCP session management.
+ *
+ * Intentionally small for early protocol iterations — implementations can
+ * extend it with querying, TTL, or event hooks as requirements grow.
+ */
+interface NcpSessionContract {
+    /**
+     * Looks up the binding for a given session key.
+     * Returns `null` if no binding exists yet.
+     */
+    resolveBinding(sessionKey: string): Promise<NcpSessionBinding | null>;
+    /**
+     * Creates or updates the binding for a session key.
+     * Implementations should treat this as an upsert (idempotent on `sessionKey`).
+     */
+    upsertBinding(binding: NcpSessionBinding): Promise<void>;
+    /**
+     * Appends a message to the session's immutable message log.
+     *
+     * Implementations MUST treat this as append-only — existing messages
+     * should never be mutated or deleted through this method.
+     */
+    appendMessage(message: NcpMessage): Promise<void>;
+}
+
+/**
+ * NCP event and payload definitions.
+ *
+ * Streaming content (text, reasoning, tool args) uses start → delta sequence → end.
+ * The same content can be sent as a single full event (e.g. message.incoming or message.completed)
+ * instead; endpoints or upper layers choose as needed.
+ */
+type NcpRequestEnvelope = {
+    sessionKey: string;
+    message: NcpMessage;
+    correlationId?: string;
+    metadata?: Record<string, unknown>;
+};
+/** Payload for message.incoming: message content from the other peer (partial or full). */
+type NcpResponseEnvelope = {
+    sessionKey: string;
+    message: NcpMessage;
+    correlationId?: string;
+    metadata?: Record<string, unknown>;
+};
+type NcpCompletedEnvelope = {
+    sessionKey: string;
+    message: NcpMessage;
+    correlationId?: string;
+    metadata?: Record<string, unknown>;
+};
+type NcpFailedEnvelope = {
+    sessionKey: string;
+    messageId?: string;
+    error: NcpError;
+    correlationId?: string;
+    metadata?: Record<string, unknown>;
+};
+type NcpMessageAcceptedPayload = {
+    messageId: string;
+    correlationId?: string;
+    transportId?: string;
+};
+type NcpMessageAbortPayload = {
+    messageId?: string;
+    correlationId?: string;
+};
+/**
+ * Payload for message.sent: the local peer has sent a message (outbound).
+ * Typically non-streaming; add the message to the local conversation state.
+ */
+type NcpMessageSentPayload = {
+    sessionKey: string;
+    message: NcpMessage;
+    metadata?: Record<string, unknown>;
+};
+type NcpTypingStartPayload = {
+    sessionKey: string;
+    /** Participant who is typing (human user or bot/assistant). */
+    userId?: string;
+};
+type NcpTypingEndPayload = {
+    sessionKey: string;
+    /** Participant who stopped typing (human user or bot/assistant). */
+    userId?: string;
+};
+type NcpPresenceUpdatedPayload = {
+    sessionKey: string;
+    /** Participant this presence applies to (human user or bot/assistant). */
+    userId?: string;
+    status: "online" | "offline" | "away";
+};
+type NcpMessageReadPayload = {
+    sessionKey: string;
+    messageId: string;
+    readAt?: string;
+    readerId?: string;
+};
+type NcpMessageDeliveredPayload = {
+    sessionKey: string;
+    messageId: string;
+};
+type NcpMessageRecalledPayload = {
+    sessionKey: string;
+    messageId: string;
+};
+type NcpMessageReactionPayload = {
+    sessionKey: string;
+    messageId: string;
+    reaction: string;
+    added: boolean;
+    /** Participant who added or removed the reaction (human user or bot/assistant). */
+    userId?: string;
+};
+type NcpRunStartedPayload = {
+    sessionKey?: string;
+    messageId?: string;
+    threadId?: string;
+    runId?: string;
+};
+type NcpRunFinishedPayload = {
+    sessionKey?: string;
+    messageId?: string;
+    threadId?: string;
+    runId?: string;
+};
+type NcpRunErrorPayload = {
+    sessionKey?: string;
+    messageId?: string;
+    error?: string;
+    threadId?: string;
+    runId?: string;
+};
+type NcpRunMetadataPayload = {
+    sessionKey?: string;
+    messageId?: string;
+    runId?: string;
+    metadata: Record<string, unknown>;
+};
+type NcpTextStartPayload = {
+    sessionKey: string;
+    messageId: string;
+};
+type NcpTextDeltaPayload = {
+    sessionKey: string;
+    messageId: string;
+    delta: string;
+};
+type NcpTextEndPayload = {
+    sessionKey: string;
+    messageId: string;
+};
+type NcpReasoningStartPayload = {
+    sessionKey: string;
+    messageId: string;
+};
+type NcpReasoningDeltaPayload = {
+    sessionKey: string;
+    messageId: string;
+    delta: string;
+};
+type NcpReasoningEndPayload = {
+    sessionKey: string;
+    messageId: string;
+};
+type NcpToolCallStartPayload = {
+    sessionKey: string;
+    messageId?: string;
+    toolCallId: string;
+    toolName: string;
+};
+type NcpToolCallArgsPayload = {
+    sessionKey: string;
+    toolCallId: string;
+    args: string;
+};
+type NcpToolCallArgsDeltaPayload = {
+    sessionKey: string;
+    messageId?: string;
+    toolCallId: string;
+    delta: string;
+};
+type NcpToolCallEndPayload = {
+    sessionKey: string;
+    toolCallId: string;
+};
+type NcpToolCallResultPayload = {
+    sessionKey: string;
+    toolCallId: string;
+    content: unknown;
+};
+type NcpEndpointEvent = {
+    type: "endpoint.ready";
+} | {
+    type: "message.request";
+    payload: NcpRequestEnvelope;
+} | {
+    type: "message.sent";
+    payload: NcpMessageSentPayload;
+} | {
+    type: "message.accepted";
+    payload: NcpMessageAcceptedPayload;
+} | {
+    type: "message.incoming";
+    payload: NcpResponseEnvelope;
+} | {
+    type: "message.completed";
+    payload: NcpCompletedEnvelope;
+} | {
+    type: "message.failed";
+    payload: NcpFailedEnvelope;
+} | {
+    type: "message.abort";
+    payload: NcpMessageAbortPayload;
+} | {
+    type: "endpoint.error";
+    payload: NcpError;
+} | {
+    type: "run.started";
+    payload: NcpRunStartedPayload;
+} | {
+    type: "run.finished";
+    payload: NcpRunFinishedPayload;
+} | {
+    type: "run.error";
+    payload: NcpRunErrorPayload;
+} | {
+    type: "run.metadata";
+    payload: NcpRunMetadataPayload;
+} | {
+    type: "message.text-start";
+    payload: NcpTextStartPayload;
+} | {
+    type: "message.text-delta";
+    payload: NcpTextDeltaPayload;
+} | {
+    type: "message.text-end";
+    payload: NcpTextEndPayload;
+} | {
+    type: "message.reasoning-start";
+    payload: NcpReasoningStartPayload;
+} | {
+    type: "message.reasoning-delta";
+    payload: NcpReasoningDeltaPayload;
+} | {
+    type: "message.reasoning-end";
+    payload: NcpReasoningEndPayload;
+} | {
+    type: "message.tool-call-start";
+    payload: NcpToolCallStartPayload;
+} | {
+    type: "message.tool-call-args";
+    payload: NcpToolCallArgsPayload;
+} | {
+    type: "message.tool-call-args-delta";
+    payload: NcpToolCallArgsDeltaPayload;
+} | {
+    type: "message.tool-call-end";
+    payload: NcpToolCallEndPayload;
+} | {
+    type: "message.tool-call-result";
+    payload: NcpToolCallResultPayload;
+} | {
+    type: "typing.start";
+    payload: NcpTypingStartPayload;
+} | {
+    type: "typing.end";
+    payload: NcpTypingEndPayload;
+} | {
+    type: "presence.updated";
+    payload: NcpPresenceUpdatedPayload;
+} | {
+    type: "message.read";
+    payload: NcpMessageReadPayload;
+} | {
+    type: "message.delivered";
+    payload: NcpMessageDeliveredPayload;
+} | {
+    type: "message.recalled";
+    payload: NcpMessageRecalledPayload;
+} | {
+    type: "message.reaction";
+    payload: NcpMessageReactionPayload;
+};
+type NcpEndpointSubscriber = (event: NcpEndpointEvent) => void;
+
+/**
+ * Core interface every NCP endpoint adapter must implement.
+ *
+ * Single primitive: emit(event) to send, subscribe(listener) to receive.
+ * Event types and payloads are defined in events.ts (aligned with agent-chat).
+ */
+interface NcpEndpoint {
+    readonly manifest: NcpEndpointManifest;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    emit(event: NcpEndpointEvent): void | Promise<void>;
+    subscribe(listener: (event: NcpEndpointEvent) => void): () => void;
+}
+
+/**
+ * Base class for NCP endpoint adapters.
+ *
+ * Lifecycle (start/stop) and subscribe/broadcast. Subclass must implement
+ * onStart, onStop, emit(); call broadcast() when an event is received from
+ * the transport. When the endpoint is ready to send/receive, call
+ * broadcast({ type: "endpoint.ready" }) — base class does not emit it.
+ */
+declare abstract class AbstractEndpoint implements NcpEndpoint {
+    abstract readonly manifest: NcpEndpointManifest;
+    private started;
+    private readonly listeners;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Subclass must implement: send event to the other peer (wire, queue, or in-process broadcast). */
+    abstract emit(event: NcpEndpointEvent): void | Promise<void>;
+    subscribe(listener: NcpEndpointSubscriber): () => void;
+    /** Call when an event is received from the transport; delivers to local subscribers. */
+    protected broadcast(event: NcpEndpointEvent): void;
+    protected abstract onStart(): Promise<void>;
+    protected abstract onStop(): Promise<void>;
+}
+
+/**
+ * Read-only snapshot of conversation state maintained by a state manager.
+ *
+ * Consumed by UI or other layers; all updates flow through dispatch(event).
+ */
+interface NcpConversationSnapshot {
+    /** Ordered list of finalized messages. */
+    readonly messages: ReadonlyArray<NcpMessage>;
+    /**
+     * Message currently being streamed (deltas apply here); null when idle.
+     * When message.completed is dispatched, this is appended to messages and cleared.
+     */
+    readonly streamingMessage: NcpMessage | null;
+    /** Latest error, if any (e.g. from message.failed or endpoint.error). */
+    readonly error: NcpError | null;
+}
+/**
+ * State manager that holds conversation state and updates it from NCP events.
+ *
+ * Feed events via dispatch(); subscribe() to be notified on state changes.
+ * Typically used by agent UIs or runtimes to keep a single source of truth for messages.
+ */
+interface NcpConversationStateManager {
+    /** Returns the current snapshot. Call after dispatch or in subscribe callback. */
+    getSnapshot(): NcpConversationSnapshot;
+    /**
+     * Applies an NCP event to internal state (messages, streamingMessage, error).
+     * Notifies subscribers after the update.
+     */
+    dispatch(event: NcpEndpointEvent): void;
+    /**
+     * Subscribes to state changes. Listener is called after each dispatch that mutates state.
+     * Returns an unsubscribe function.
+     */
+    subscribe(listener: (snapshot: NcpConversationSnapshot) => void): () => void;
+}
+
+/**
+ * Agent-scenario state manager: extends the generic conversation state manager
+ * with explicit handle methods for each NCP event type that affects agent conversation state.
+ *
+ * Implementations may route dispatch(event) to the corresponding handleXxx(payload)
+ * and use these handlers to update messages, streamingMessage, and error.
+ */
+interface NcpAgentConversationStateManager extends NcpConversationStateManager {
+    handleMessageRequest(payload: NcpRequestEnvelope): 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;
+    handleMessageTextEnd(payload: NcpTextEndPayload): void;
+    handleMessageReasoningStart(payload: NcpReasoningStartPayload): void;
+    handleMessageReasoningDelta(payload: NcpReasoningDeltaPayload): void;
+    handleMessageReasoningEnd(payload: NcpReasoningEndPayload): void;
+    handleMessageToolCallStart(payload: NcpToolCallStartPayload): void;
+    handleMessageToolCallArgs(payload: NcpToolCallArgsPayload): void;
+    handleMessageToolCallArgsDelta(payload: NcpToolCallArgsDeltaPayload): void;
+    handleMessageToolCallEnd(payload: NcpToolCallEndPayload): void;
+    handleMessageToolCallResult(payload: NcpToolCallResultPayload): void;
+    handleRunStarted(payload: NcpRunStartedPayload): void;
+    handleRunFinished(payload: NcpRunFinishedPayload): void;
+    handleRunError(payload: NcpRunErrorPayload): void;
+    handleRunMetadata(payload: NcpRunMetadataPayload): void;
+    handleEndpointError(payload: NcpError): void;
+}
+
+export { AbstractEndpoint, type NcpActionPart, type NcpAgentConversationStateManager, 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 NcpRichTextPart, type NcpRunErrorPayload, type NcpRunFinishedPayload, type NcpRunMetadataPayload, type NcpRunStartedPayload, type NcpSessionBinding, type NcpSessionContract, type NcpSessionState, 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 };

package/dist/index.js

@@ -0,0 +1,41 @@
+// 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/endpoint/abstract-endpoint.ts
+var AbstractEndpoint = class {
+  started = false;
+  listeners = /* @__PURE__ */ new Set();
+  async start() {
+    if (this.started) return;
+    await this.onStart();
+    this.started = true;
+  }
+  async stop() {
+    if (!this.started) return;
+    await this.onStop();
+    this.started = false;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+  /** Call when an event is received from the transport; delivers to local subscribers. */
+  broadcast(event) {
+    for (const listener of this.listeners) {
+      listener(event);
+    }
+  }
+};
+export {
+  AbstractEndpoint,
+  NcpErrorException
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@nextclaw/ncp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "NextClaw Communication Protocol core abstractions and types.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "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"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json"
+  }
+}