@nextclaw/ncp 0.1.0 → 0.1.1

package/README.md

@@ -11,7 +11,7 @@ pnpm -C 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[];
@@ -178,7 +178,7 @@ 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`. */
+    /** Whether a disconnected session can be resumed by the same `sessionId`. */
     supportsSessionResume: boolean;
     /**
      * The subset of `NcpMessagePart` types this endpoint can send or receive.
@@ -230,65 +230,31 @@ declare class NcpErrorException extends Error {
     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;
+    activeRunId?: string;
+};
+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 +265,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 +295,63 @@ type NcpMessageAcceptedPayload = {
     correlationId?: string;
     transportId?: string;
 };
+/** Payload for message.abort: identifies which request or run to cancel. */
 type NcpMessageAbortPayload = {
     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).
+ */
+type NcpResumeRequestPayload = {
+    sessionId: string;
+    remoteRunId: string;
+    fromEventIndex?: number;
+    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,79 +359,79 @@ 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;
 };
@@ -462,6 +440,9 @@ type NcpEndpointEvent = {
 } | {
     type: "message.request";
     payload: NcpRequestEnvelope;
+} | {
+    type: "message.resume-request";
+    payload: NcpResumeRequestPayload;
 } | {
     type: "message.sent";
     payload: NcpMessageSentPayload;
@@ -552,43 +533,145 @@ type NcpEndpointEvent = {
 };
 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: "message.request", 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 === "message.completed") 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>;
+    /** 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>;
+}
+
+/**
+ * Agent server-side endpoint: receives requests and emits responses.
+ *
+ * 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.
+ */
+interface NcpAgentServerEndpoint extends NcpEndpoint {
+    readonly manifest: NcpEndpointManifest & {
+        endpointKind: "agent";
+    };
+}
+
+/**
+ * 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;
+};
+type NcpAgentRunOptions = {
+    signal?: AbortSignal;
+    sessionMessages?: ReadonlyArray<NcpMessage>;
+};
+interface NcpAgentRuntime {
+    run(input: NcpAgentRunInput, options?: NcpAgentRunOptions): AsyncIterable<NcpEndpointEvent>;
 }
 
+type NcpAgentBackendSendOptions = {
+    signal?: AbortSignal;
+};
+type NcpAgentBackendReconnectOptions = {
+    signal?: AbortSignal;
+};
+interface NcpAgentBackendController extends NcpSessionApi {
+    send(envelope: NcpRequestEnvelope, options?: NcpAgentBackendSendOptions): AsyncIterable<NcpEndpointEvent>;
+    reconnect(payload: NcpResumeRequestPayload, options?: NcpAgentBackendReconnectOptions): AsyncIterable<NcpEndpointEvent>;
+    abort(payload: NcpMessageAbortPayload): Promise<void>;
+}
+type NcpAgentReplayProvider = {
+    stream(params: {
+        payload: NcpResumeRequestPayload;
+        signal: AbortSignal;
+    }): AsyncIterable<NcpEndpointEvent>;
+};
+
 /**
  * Read-only snapshot of conversation state maintained by a state manager.
  *
@@ -605,6 +688,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 +708,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.
@@ -634,6 +724,7 @@ interface NcpConversationStateManager {
  * and use these handlers to update messages, streamingMessage, and error.
  */
 interface NcpAgentConversationStateManager extends NcpConversationStateManager {
+    getSnapshot(): NcpAgentConversationSnapshot;
     handleMessageRequest(payload: NcpRequestEnvelope): void;
     /** Local peer sent a message (outbound); typically non-streaming. Add to messages. */
     handleMessageSent(payload: NcpMessageSentPayload): void;
@@ -660,4 +751,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 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 };

package/dist/index.js

@@ -10,32 +10,22 @@ var NcpErrorException = class extends Error {
   }
 };
 
-// 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/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 ?? {} });
     }
-  }
-};
+  };
+}
 export {
-  AbstractEndpoint,
-  NcpErrorException
+  NcpErrorException,
+  createAgentClientFromServer
 };

package/package.json

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