@pacerelle/mcp-server 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -1,41 +1,14 @@
 # Pacerelle MCP Server
 
-MCP server for Pacerelle encrypted local agent relays.
+A local encrypted inbox for an assistant running in an MCP host. Pacerelle
+transports messages; your host remains responsible for starting the assistant,
+running tools, applying permissions, and deciding when its processing loop ends.
+Connecting this server alone does not wake Claude Desktop, Cursor, Codex, or Zed.
 
-Run it from any MCP-compatible client that can spawn a local stdio server, such
-as Claude Desktop, Cursor, Zed, or other MCP hosts.
+## Connect and verify a real reply
 
-## Install
-
-```bash
-npx -y @pacerelle/mcp-server
-```
-
-## Configuration
-
-Create an agent in Pacerelle, copy its id and token, then expose them to the MCP
-process:
-
-```env
-PACERELLE_AGENT_ID=agent_...
-PACERELLE_AGENT_TOKEN=...
-```
-
-The published package connects to `https://api.pacerelle.com` by default. For
-local development, set:
-
-```env
-PACERELLE_BASE_URL=http://localhost:8080
-```
-
-Optional:
-
-```env
-PACERELLE_WS_URL=ws://localhost:8080
-PACERELLE_STORE_ROOT=.pacerelle/mcp
-```
-
-## Claude Desktop Example
+Create or resume an agent in Pacerelle. Copy both its ID and authentication token
+into the host's local MCP configuration:
 
 ```json
 {
@@ -52,31 +25,132 @@ PACERELLE_STORE_ROOT=.pacerelle/mcp
 }
 ```
 
-## Tools
+Use the configuration format supported by your host. Then start a conversation
+with its assistant and select the `start_pacerelle` prompt, or ask:
 
-- `send_message`: send an encrypted text reply to the current or provided conversation.
-- `send_widget`: send a `widget.standard` v1 payload.
-- `get_history`: return recent plaintext messages observed by this MCP process.
+> Start or resume my Pacerelle work. Read get_status and get_checkpoints, then
+> wait_for_messages without a cursor. Handle each authorized request, reply
+> using its sourceMessageId, and mark_processed after handling it. Save a
+> checkpoint before an interruption. Keep listening while this host session can
+> continue; tell me if listening stops or needs my intervention.
 
-## Resources
+Send a test message from Pacerelle and verify a readable reply before leaving
+your computer. Keep the computer, host, and assistant loop running. Hosts may
+stop at a turn limit, require approval, or not support continuous waiting. For
+unattended execution, use the SDK with your own continuously running agent.
+MCP resource notifications or sampling are not a universal assistant wake-up API.
 
-- `conversation://current`: most recent conversation message seen by this process.
-- `widget://pending`: latest widget response observed by this process.
+These instructions describe the source implementation. To test an unreleased
+checkout, build `sdk-js` and `mcp-server`, then configure the host with `node`
+and the absolute path to `mcp-server/dist/cli.js` instead of `npx`.
 
-## CLI
+## Tools
 
-Environment variables are recommended, but explicit flags are supported:
+| Tool | Meaning |
+| --- | --- |
+| `get_status` | Relay state, number of pending requests, and uncertain outgoing sends. |
+| `wait_for_messages` | Return pending requests, or wait 0–30 seconds for a matching request. |
+| `send_message` | Submit an encrypted reply; use `sourceMessageId` from the incoming request. |
+| `send_widget` | Submit a `widget.standard` v1 payload to the same source target. |
+| `mark_processed` | Record that a received request has been handled. Reading does not do this. |
+| `get_history` | Recent locally retained incoming requests and outgoing replies. |
+| `save_checkpoint` | Save summary, next action, and optional host session label for a received request. |
+| `get_checkpoints` | Retrieve active saved work; optionally include completed work. |
+
+`wait_for_messages` accepts `conversationId`, `afterCursor`, `limit` (1–50), and
+`timeoutMs` (0–30000, default 25000). Its result includes `messages`, `cursor`,
+`has_more`, and `connection`. Canceling the MCP request cancels its wait. Reading,
+waiting, and sending replies never mark an incoming request processed. Use a
+single processing loop for each agent.
+
+A cursor skips earlier requests, including unfinished ones. Omit it when
+resuming a session; use it only to paginate a batch that your loop has tracked.
+Pending requests are retained until explicitly processed. The local history
+retains 50 recent processed messages, 50 outgoing replies, and source messages
+needed by retained checkpoints. Duplicate IDs are ignored while retained.
+
+Replies using `sourceMessageId` stay attached to the original conversation,
+device, or group even if another message arrives meanwhile. Unknown sources and
+conflicting targets are rejected. Without a source, the conversation target must
+be unambiguous; explicit `conversationId` and `to` remain available for advanced
+use. `conversation://current` is merely the latest observation, not ownership of
+an assistant session. `widget://pending` is the latest unprocessed widget response.
+
+## Resume in another assistant session
+
+Before an interruption, the host can call:
 
-```bash
-npx -y @pacerelle/mcp-server \
-  --agent-id "$PACERELLE_AGENT_ID" \
-  --token "$PACERELLE_AGENT_TOKEN"
+```json
+{
+  "sourceMessageId": "received-message-id",
+  "summary": "Draft complete. Figures checked. Waiting for the user's approval.",
+  "nextAction": "Read the approval response before publishing the report.",
+  "hostSessionLabel": "Report preparation",
+  "status": "active"
+}
+```
+
+The next session calls `get_checkpoints`, `wait_for_messages` without a cursor,
+and `get_history` for the selected conversation. It receives the saved working
+context and remaining requests without asking you to copy a transcript. Update
+the checkpoint with `status: "completed"` when its work ends. Checkpoint updates
+do not automatically mark messages processed, and processing a message does not
+automatically complete a longer task.
+
+This preserves context explicitly saved by the host. It does not access private
+Codex, Claude, or Cursor transcripts, and cannot recover unsaved model reasoning.
+The host's permissions and approval rules continue to apply after resumption.
+
+## Local state and connection recovery
+
+The default directory is `~/.pacerelle/mcp`; override it with
+`PACERELLE_STORE_ROOT`. Use the same directory when moving between host sessions.
+Each agent and gateway has its own AES-256-GCM encrypted file containing the
+Signal snapshot, inbox, replies, and checkpoints. Writes use a temporary file,
+flush, and atomic replacement. A separate random local key is needed to decrypt
+it. Back up the key and encrypted file together. Do not copy live state between
+two running processes.
+
+Directory mode is `0700` and files use `0600` on POSIX. On Windows, filesystem
+protection depends on the account's directory ACLs; use your private user profile
+directory. Encryption with a locally stored key does not protect against another
+process already running as your account. Tokens are not saved by this server.
+
+Only one local MCP process can own an agent's state on a gateway. Close its
+Pacerelle server in the old host before opening it in another. Normal process
+crash locks are reclaimed when the recorded PID no longer exists. A crash during
+the brief lock-opening operation can leave an `.opening` gate; the startup error
+identifies it, and it must only be removed after checking no bridge is starting.
+This local lock does not prevent an independent process on another computer
+from using the same agent credentials.
+
+The CLI reconnects with increasing delays (up to 30 seconds), creating a fresh
+SDK client with the latest saved Signal state. The old production snapshot is
+migrated into encrypted storage before its plaintext file is removed. A legacy
+snapshot from an unknown gateway requires gateway verification instead of
+silently creating a new identity. A lost key or corrupt state stops startup.
+
+An outgoing `submitted` result means SDK submission, not verified execution or
+recipient display. If a send or interruption leaves the outcome uncertain,
+`get_status.uncertain_sends` and history expose it. Check the actual outcome
+before repeating consequential work. The bridge does not guarantee exactly-once
+external actions or atomicity between Signal decryption and inbox persistence.
+
+## Local development
+
+```env
+PACERELLE_AGENT_ID=agent_...
+PACERELLE_AGENT_TOKEN=...
+PACERELLE_BASE_URL=http://localhost:8080
+PACERELLE_STORE_ROOT=/absolute/private/directory
 ```
 
-Local development:
+`PACERELLE_WS_URL` optionally overrides the websocket URL. Corresponding CLI
+flags are `--agent-id`, `--token`, `--base-url`, `--ws-url`, and `--store-root`.
+The default gateway is `https://api.pacerelle.com`. Keep E2EE enabled;
+`--no-e2ee` exists for local transport debugging only.
 
 ```bash
-npx -y @pacerelle/mcp-server \
-  --base-url "http://localhost:8080" \
-  --ws-url "ws://localhost:8080"
+npm run build --workspace sdk-js
+npm test --workspace mcp-server
 ```

package/dist/bridge.d.ts

@@ -3,36 +3,150 @@ export interface MessageSender {
     sendMessage(options: {
         conversationId: string;
         to: string;
+        toDeviceId?: string;
         text: string;
         replyToMessageId?: string;
     }): Promise<void>;
 }
+export interface InboxMessage {
+    id: string;
+    direction: "incoming";
+    sequence: number;
+    conversation_id: string;
+    from: string;
+    from_device_id?: string;
+    reply_target: string;
+    text: string;
+    encrypted: boolean;
+    reply_to_message_id: string | null;
+    attachments: AgentMessage["attachments"];
+    widget_response: AgentMessage["widgetResponse"] | null;
+    widget_update: AgentMessage["widgetUpdate"] | null;
+    recorded_at: string;
+    processed_at: string | null;
+    processing_note?: string;
+}
+interface ReplyRecord {
+    local_id: string;
+    direction: "outgoing";
+    conversation_id: string;
+    to: string;
+    text: string;
+    source_message_id?: string;
+    recorded_at: string;
+    delivery_status: "sending" | "submitted" | "unknown";
+}
+export interface BridgeState {
+    version: 1;
+    epoch: string;
+    nextSequence: number;
+    inbox: InboxMessage[];
+    replies: ReplyRecord[];
+    checkpoints: WorkCheckpoint[];
+}
+export interface WorkCheckpoint {
+    source_message_id: string;
+    conversation_id: string;
+    summary: string;
+    next_action: string;
+    host_session_label?: string;
+    status: "active" | "completed";
+    updated_at: string;
+}
+interface ReplyTarget {
+    sourceMessageId?: string;
+    conversationId?: string;
+    to?: string;
+}
+export interface WaitOptions {
+    conversationId?: string;
+    afterCursor?: string;
+    limit?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export type ConnectionState = "connecting" | "connected" | "reconnecting" | "disconnected" | "stopped";
+/** Reading/waiting never acknowledges application work. Persistence precedes visibility. */
 export declare class PacerelleMcpBridge {
     private readonly client;
     private readonly historyLimit;
-    private readonly messages;
-    private current;
-    private pendingWidget;
-    constructor(client: MessageSender, historyLimit?: number);
+    private readonly options;
+    private state;
+    private connection;
+    private readonly listeners;
+    constructor(client: MessageSender, historyLimit?: number, options?: {
+        state?: BridgeState;
+        onStateChange?: (state: BridgeState) => void;
+    });
     recordMessage(message: AgentMessage): void;
-    sendMessage(args: {
-        text: string;
+    setConnectionState(state: ConnectionState): void;
+    getStatus(): {
+        connection: ConnectionState;
+        pending_count: number;
+        cursor: string;
+        host_action: string;
+        uncertain_sends: ReplyRecord[];
+    };
+    waitForMessages(args?: WaitOptions): Promise<{
+        status: string;
+        messages: InboxMessage[];
+        cursor: string;
+        has_more: boolean;
+        connection: ConnectionState;
+    }>;
+    markProcessed(args: {
+        messageId: string;
+        note?: string;
+    }): {
+        ok: boolean;
+        message_id: string;
+        pending_count: number;
+    };
+    saveCheckpoint(args: {
+        sourceMessageId: string;
+        summary: string;
+        nextAction: string;
+        hostSessionLabel?: string;
+        status?: "active" | "completed";
+    }): WorkCheckpoint;
+    getCheckpoints(args?: {
         conversationId?: string;
-        to?: string;
+        includeCompleted?: boolean;
+    }): WorkCheckpoint[];
+    sendMessage(args: ReplyTarget & {
+        text: string;
         replyToMessageId?: string;
-    }): Promise<Record<string, unknown>>;
-    sendWidget(args: {
+    }): Promise<{
+        ok: boolean;
+        conversation_id: string;
+        to: string;
+        delivery_status: string;
+    }>;
+    sendWidget(args: ReplyTarget & {
         widgetJson: string | Record<string, unknown>;
-        conversationId?: string;
-        to?: string;
-    }): Promise<Record<string, unknown>>;
+    }): Promise<{
+        ok: boolean;
+        widget_id: unknown;
+        kind: unknown;
+        conversation_id: string;
+        to: string;
+        delivery_status: string;
+    }>;
     getHistory(args: {
         conversationId?: string;
         limit?: number;
-    }): Array<Record<string, unknown>>;
-    currentConversation(): Record<string, unknown>;
+    }): (InboxMessage | ReplyRecord)[];
+    currentConversation(): InboxMessage | {
+        status: string;
+    };
     pendingWidgetResponse(): Record<string, unknown>;
     attach(client: AgentGatewayClient): void;
-    private requireCurrent;
+    private commit;
+    private notify;
+    private cursor;
+    private parseCursor;
+    private resolveTarget;
+    private submitReply;
     private parseWidget;
 }
+export {};