@nextclaw/ncp 0.1.0 → 0.2.0

package/README.md

@@ -5,13 +5,13 @@ 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
 
 - NCP manifest, message, session, and error definitions
-- Generic endpoint base class (`AbstractEndpoint`)
+- Endpoint interfaces (`NcpEndpoint`, `NcpAgentServerEndpoint`, `NcpAgentClientEndpoint`)
 
 ## Usage
 

package/dist/index.d.ts

@@ -130,7 +130,7 @@ type NcpMessage = {
     /** Globally unique message identifier. */
     id: string;
     /** The session this message belongs to. */
-    sessionKey: string;
+    sessionId: string;
     role: NcpMessageRole;
     status: NcpMessageStatus;
     parts: NcpMessagePart[];
@@ -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 `sessionKey`. */
-    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,80 +215,31 @@ 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>);
-}
 
-/**
- * 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. */
+type NcpSessionStatus = "idle" | "running";
+type NcpSessionSummary = {
+    sessionId: string;
     messageCount: number;
-    /** ISO 8601 timestamp of the last state mutation. */
     updatedAt: string;
+    status?: NcpSessionStatus;
+};
+type ListSessionsOptions = {
+    limit?: number;
+    cursor?: string;
+};
+type ListMessagesOptions = {
+    limit?: number;
+    cursor?: 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.
+ * API for session list, message history, and session lifecycle.
+ * Implementations that support persistence can provide this alongside NcpAgentClientEndpoint.
  */
-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>;
+interface NcpSessionApi {
+    listSessions(options?: ListSessionsOptions): Promise<NcpSessionSummary[]>;
+    listSessionMessages(sessionId: string, options?: ListMessagesOptions): Promise<NcpMessage[]>;
+    getSession(sessionId: string): Promise<NcpSessionSummary | null>;
+    deleteSession(sessionId: string): Promise<void>;
 }
 
 /**
@@ -299,26 +250,26 @@ interface NcpSessionContract {
  * instead; endpoints or upper layers choose as needed.
  */
 type NcpRequestEnvelope = {
-    sessionKey: string;
+    sessionId: 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;
+    sessionId: string;
     message: NcpMessage;
     correlationId?: string;
     metadata?: Record<string, unknown>;
 };
 type NcpCompletedEnvelope = {
-    sessionKey: string;
+    sessionId: string;
     message: NcpMessage;
     correlationId?: string;
     metadata?: Record<string, unknown>;
 };
 type NcpFailedEnvelope = {
-    sessionKey: string;
+    sessionId: string;
     messageId?: string;
     error: NcpError;
     correlationId?: string;
@@ -329,51 +280,60 @@ type NcpMessageAcceptedPayload = {
     correlationId?: string;
     transportId?: string;
 };
+/** Payload for message.abort: identifies which session's active execution to cancel. */
 type NcpMessageAbortPayload = {
+    sessionId: string;
     messageId?: string;
-    correlationId?: string;
+};
+/**
+ * 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 NcpStreamRequestPayload = {
+    sessionId: string;
+    metadata?: Record<string, unknown>;
 };
 /**
  * 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;
+    sessionId: string;
     message: NcpMessage;
     metadata?: Record<string, unknown>;
 };
 type NcpTypingStartPayload = {
-    sessionKey: string;
+    sessionId: string;
     /** Participant who is typing (human user or bot/assistant). */
     userId?: string;
 };
 type NcpTypingEndPayload = {
-    sessionKey: string;
+    sessionId: string;
     /** Participant who stopped typing (human user or bot/assistant). */
     userId?: string;
 };
 type NcpPresenceUpdatedPayload = {
-    sessionKey: string;
+    sessionId: string;
     /** Participant this presence applies to (human user or bot/assistant). */
     userId?: string;
     status: "online" | "offline" | "away";
 };
 type NcpMessageReadPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
     readAt?: string;
     readerId?: string;
 };
 type NcpMessageDeliveredPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
 };
 type NcpMessageRecalledPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
 };
 type NcpMessageReactionPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
     reaction: string;
     added: boolean;
@@ -381,214 +341,500 @@ type NcpMessageReactionPayload = {
     userId?: string;
 };
 type NcpRunStartedPayload = {
-    sessionKey?: string;
+    sessionId?: string;
     messageId?: string;
     threadId?: string;
     runId?: string;
 };
 type NcpRunFinishedPayload = {
-    sessionKey?: string;
+    sessionId?: string;
     messageId?: string;
     threadId?: string;
     runId?: string;
 };
 type NcpRunErrorPayload = {
-    sessionKey?: string;
+    sessionId?: string;
     messageId?: string;
     error?: string;
     threadId?: string;
     runId?: string;
 };
 type NcpRunMetadataPayload = {
-    sessionKey?: string;
+    sessionId?: string;
     messageId?: string;
     runId?: string;
     metadata: Record<string, unknown>;
 };
 type NcpTextStartPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
 };
 type NcpTextDeltaPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
     delta: string;
 };
 type NcpTextEndPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
 };
 type NcpReasoningStartPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
 };
 type NcpReasoningDeltaPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
     delta: string;
 };
 type NcpReasoningEndPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId: string;
 };
 type NcpToolCallStartPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId?: string;
     toolCallId: string;
     toolName: string;
 };
 type NcpToolCallArgsPayload = {
-    sessionKey: string;
+    sessionId: string;
     toolCallId: string;
     args: string;
 };
 type NcpToolCallArgsDeltaPayload = {
-    sessionKey: string;
+    sessionId: string;
     messageId?: string;
     toolCallId: string;
     delta: string;
 };
 type NcpToolCallEndPayload = {
-    sessionKey: string;
+    sessionId: string;
     toolCallId: string;
 };
 type NcpToolCallResultPayload = {
-    sessionKey: string;
+    sessionId: string;
     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.sent";
+    type: NcpEventType.MessageStreamRequest;
+    payload: NcpStreamRequestPayload;
+} | {
+    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;
 
+/**
+ * Run-related types: snapshot state and run.metadata schema conventions.
+ * Not event payloads — event payloads live in events.ts.
+ */
+/** Current run state for agent snapshot. Used by UI for run status and abort. */
+type NcpRunContext = {
+    runId: string | null;
+    sessionId?: string;
+    abortDisabledReason?: string | null;
+};
+/** Schema for run.metadata.metadata when kind is "ready" (run started, backend ready). */
+type NcpRunReadyMetadata = {
+    kind: "ready";
+    runId?: string;
+    sessionId?: string;
+    supportsAbort?: boolean;
+    abortDisabledReason?: string;
+};
+/** Schema for run.metadata.metadata when kind is "final" (run finished). */
+type NcpRunFinalMetadata = {
+    kind: "final";
+    sessionId?: string;
+};
+
 /**
  * Core interface every NCP endpoint adapter must implement.
  *
+ * An endpoint is a named, lifecycle-managed communication channel.
  * Single primitive: emit(event) to send, subscribe(listener) to receive.
  * Event types and payloads are defined in events.ts (aligned with agent-chat).
+ *
+ * @example
+ * const endpoint: NcpEndpoint = new MyAgentEndpoint(options);
+ * await endpoint.start();
+ * endpoint.subscribe((event) => { ... });
+ * await endpoint.emit({ type: NcpEventType.MessageRequest, payload: envelope });
  */
 interface NcpEndpoint {
+    /** Static capability declaration — available before `start()` is called. */
     readonly manifest: NcpEndpointManifest;
+    /**
+     * Initializes the endpoint (opens connections, authenticates, etc.).
+     * Must be called before `emit`. Idempotent — safe to call more than once.
+     */
     start(): Promise<void>;
+    /**
+     * Gracefully shuts down the endpoint and releases resources.
+     * Idempotent — safe to call more than once.
+     */
     stop(): Promise<void>;
-    emit(event: NcpEndpointEvent): void | Promise<void>;
-    subscribe(listener: (event: NcpEndpointEvent) => void): () => void;
+    /**
+     * Sends an event to the remote participant (or broadcasts to local subscribers).
+     *
+     * For outbound events (e.g. message.request, message.abort), the implementation
+     * forwards to the wire. For symmetric in-process setups, it may broadcast locally.
+     */
+    emit(event: NcpEndpointEvent): Promise<void>;
+    /**
+     * Subscribes to endpoint events.
+     *
+     * @param listener - Called for every event emitted by this endpoint.
+     * @returns An unsubscribe function. Call it to stop receiving events.
+     *
+     * @example
+     * const unsubscribe = endpoint.subscribe((event) => {
+     *   if (event.type === NcpEventType.MessageCompleted) handleReply(event.payload);
+     * });
+     * unsubscribe();
+     */
+    subscribe(listener: NcpEndpointSubscriber): () => void;
 }
 
 /**
- * Base class for NCP endpoint adapters.
+ * Client-side endpoint for agent chat: initiates requests and can cancel in-flight runs.
  *
- * 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.
+ * Extends `NcpEndpoint` with role-specific methods. Use this on the caller side
+ * (e.g. frontend, CLI) that sends user messages and receives agent responses.
  */
-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>;
+interface NcpAgentClientEndpoint extends NcpEndpoint {
+    /** Sends a new message request to the agent. Emits `message.request`. */
+    send(envelope: NcpRequestEnvelope): 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 produces downstream events.
+ *
+ * Extends `NcpEndpoint` with a manifest constraint (`endpointKind: "agent"`).
+ * 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>;
+}
+
+type NcpAgentRunInput = {
+    sessionId: string;
+    messages: ReadonlyArray<NcpMessage>;
+    correlationId?: string;
+};
+type NcpAgentRunOptions = {
+    signal?: AbortSignal;
+};
+interface NcpAgentRuntime {
+    run(input: NcpAgentRunInput, options?: NcpAgentRunOptions): AsyncIterable<NcpEndpointEvent>;
+}
+
+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;
+    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;
+    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: unknown;
+    result: unknown;
+};
+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 NcpAgentRunApi {
+    send(envelope: NcpRequestEnvelope, options?: NcpAgentRunSendOptions): AsyncIterable<NcpEndpointEvent>;
+    stream(payload: NcpStreamRequestPayload, options?: NcpAgentRunStreamOptions): AsyncIterable<NcpEndpointEvent>;
+    abort(payload: NcpMessageAbortPayload): Promise<void>;
+}
+type NcpAgentStreamProvider = {
+    stream(params: {
+        payload: NcpStreamRequestPayload;
+        signal: AbortSignal;
+    }): AsyncIterable<NcpEndpointEvent>;
+};
+
 /**
  * Read-only snapshot of conversation state maintained by a state manager.
  *
@@ -605,6 +851,13 @@ interface NcpConversationSnapshot {
     /** Latest error, if any (e.g. from message.failed or endpoint.error). */
     readonly error: NcpError | null;
 }
+/**
+ * Agent snapshot: extends base snapshot with active run state.
+ * Use for UI run status, abort button enable/disable, and abort payload.
+ */
+interface NcpAgentConversationSnapshot extends NcpConversationSnapshot {
+    readonly activeRun: NcpRunContext | null;
+}
 /**
  * State manager that holds conversation state and updates it from NCP events.
  *
@@ -618,7 +871,7 @@ interface NcpConversationStateManager {
      * Applies an NCP event to internal state (messages, streamingMessage, error).
      * Notifies subscribers after the update.
      */
-    dispatch(event: NcpEndpointEvent): void;
+    dispatch(event: NcpEndpointEvent): Promise<void>;
     /**
      * Subscribes to state changes. Listener is called after each dispatch that mutates state.
      * Returns an unsubscribe function.
@@ -626,6 +879,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.
@@ -634,13 +892,11 @@ interface NcpConversationStateManager {
  * and use these handlers to update messages, streamingMessage, and error.
  */
 interface NcpAgentConversationStateManager extends NcpConversationStateManager {
-    handleMessageRequest(payload: NcpRequestEnvelope): void;
+    getSnapshot(): NcpAgentConversationSnapshot;
+    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;
@@ -660,4 +916,4 @@ interface NcpAgentConversationStateManager extends NcpConversationStateManager {
     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 };
+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 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 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 };

package/dist/index.js

@@ -1,41 +1,39 @@
-// 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);
-    }
-  }
-};
+// 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 || {});
 export {
-  AbstractEndpoint,
-  NcpErrorException
+  NcpEventType
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextclaw/ncp",
-  "version": "0.1.0",
+  "version": "0.2.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"