@openvole/volenet-mcp 0.1.0 → 0.2.0

package/README.md

@@ -32,8 +32,10 @@ your behalf, not commands you type. Ask for them in your own words.
 > *"pair with the agent at http://10.0.0.5:9700"* → `volenet_connect`, which reports the
 > fingerprint first and pairs once you confirm it
 
-Add `--user` to register it in every project rather than the current one. If the `claude` CLI is
-not on PATH, the installer prints the one line to paste instead of guessing at its config.
+It registers for **every project**, because the identity it installs is per machine — one keypair
+in your home directory, shared by every session. Add `--local` to limit it to the current project.
+If the `claude` CLI is not on PATH, the installer prints the one line to paste instead of guessing
+at its config.
 
 ### Settings
 
@@ -52,6 +54,21 @@ Environment wins over stored settings, which win over defaults. None of it is re
 
 That directory **is** your identity: back it up, and anyone who has it is you.
 
+## Slash commands
+
+The server ships its flows as MCP prompts, so the client surfaces them as commands — you pick one
+rather than hoping a sentence matches the right tool.
+
+| command | what it does |
+|---|---|
+| `whoami` | this session's identity, and whether it can reach anything |
+| `peers` | who is reachable, and by which route |
+| `setup` | get onto the mesh — join a hub, or pair with an agent |
+| `pair` | pair with an agent, fingerprint checked, asking for brain access if wanted |
+| `rooms` | rooms this session is in, and how to say something to one |
+| `catch-up` | read what arrived while away and say what needs answering |
+| `reach` | message a peer and wait for the reply |
+
 ## Commands
 
 Alongside the tools, a few things are useful before a session exists, or without one. These touch
@@ -81,6 +98,7 @@ than a command, because it needs a running node and a conversation to happen in.
 | `volenet_ask` | Ask another **agent's** brain a question and wait for the answer. |
 | `volenet_requests` | Trust decisions waiting on you; accept or deny. |
 | `volenet_wait` | Wait for the next message instead of checking again later. |
+| `volenet_room` | Rooms: list, post, create, join, leave, invite. |
 | `volenet_hub` | Join a hub, leave one, or say which you are on. Remembered. |
 | `volenet_connect` | Pair with a node, or ask a hub member for consent to chat. |
 
@@ -109,6 +127,15 @@ things close most of that gap:
   called again. That is what makes a back-and-forth feel like a conversation instead of a
   mailbox: say something, wait, get the reply in the same turn.
 
+**The daemon notifies you when something arrives** — a desktop notification, which is the thing a
+chat client actually does. It is the only part of the machinery that is always running, so it is
+the only part that can. `VOLENET_MCP_NOTIFY=off` silences it; set it to a command name instead and
+that command is run with the title and body as its two arguments.
+
+**A message cannot answer itself.** MCP's only server-initiated model call is `sampling`, and
+Claude Code declares no capabilities at all — `volenet_whoami` reports which it is, so nobody waits
+for a reply that cannot come. What is left is making sure an arrived message is *seen* promptly.
+
 For catch-up at the start of a session, ask for the inbox — or have it arrive before you type
 anything, with a `SessionStart` hook in `.claude/settings.json`:
 
@@ -124,6 +151,43 @@ anything, with a `SessionStart` hook in `.claude/settings.json`:
 
 `--read` marks them seen, since the hook has just put them in front of you.
 
+Swap `SessionStart` for `UserPromptSubmit` and waiting messages arrive on every turn you take,
+which is as close to unprompted as this client allows.
+
+## The node runs in a daemon
+
+An identity that exists only while an editor is open is offline most of the time: senders hold what
+they cannot deliver, hubs record that somebody tried, and nothing arrives until you come back. So
+the node lives in a small daemon — one per identity, started the first time a session wants it,
+outliving every session. You are reachable whether or not anything is open.
+
+It also settles what two open editors would otherwise do to each other: two nodes on one identity
+means a hub binds one socket and the other goes deaf. One node, many sessions attached, no race.
+
+```bash
+volenet-mcp daemon    # run it in the foreground; normally it is started for you
+```
+
+Reading does not go through it. Messages are an append-only file, so a session reads them directly
+and keeps its own cursor — the protocol covers acting, not looking, and your history is still there
+if the daemon is gone. `VOLENET_MCP_NO_DAEMON=1` keeps the node in the session, which is the
+fallback where spawning is not allowed.
+
+## One identity, several sessions
+
+The identity is per machine — one keypair in `~/.openvole/volenet-mcp/`, shared by every session,
+because pairing once is the whole point of having one. Being *caught up* is not shared: messages
+are an append-only log, and each session keeps its own read cursor, keyed by the directory it was
+started in.
+
+So a session opening its inbox does not mark those messages seen for the others; a session
+reopened in the same project is the same reader and does not replay what it has already been
+shown; and two projects open at once are two readers of one log. Appending rather than rewriting
+is what makes that safe without a lock or a daemon.
+
+`VOLENET_MCP_SESSION` names the reader explicitly, if you want two sessions in one directory kept
+apart.
+
 ## Session lifetime
 
 The node lives as long as the editor session. That is a supported shape, not a degraded one: a

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { VoleNetManager } from '@openvole/volenet';
 
 interface StoredConfig {
     name?: string;
@@ -11,6 +10,8 @@ interface Settings {
     hub?: string;
     dir: string;
     port: number;
+    /** Which read state in the shared inbox is this session's. See {@link sessionKey}. */
+    session: string;
 }
 declare function defaultDir(): string;
 /** A name that says what this is without needing to be chosen. Identity is the key, not this. */
@@ -32,20 +33,31 @@ interface Message {
     id: string;
 }
 declare class Inbox {
-    private readonly file;
+    private readonly dir;
+    private readonly session;
     private messages;
-    /** Per peer, the timestamp up to which the session has been shown its messages. */
+    /** Per peer, the timestamp up to which *this* session has been shown its messages. */
     private readAt;
     private writing;
-    constructor(file: string);
+    /**
+     * @param dir   where the shared log and the cursors live
+     * @param session  which read state is ours. Sessions in different projects are different
+     *                 readers; the same project reopened is the same reader, so restarting does
+     *                 not replay everything already seen.
+     */
+    constructor(dir: string, session?: string);
+    private get log();
+    private get cursor();
     load(): Promise<void>;
+    /** Re-read what other sessions have appended since we loaded. */
+    refresh(): Promise<void>;
     /** Record a message. Returns false when this id was already recorded. */
     add(m: Message): Promise<boolean>;
     /** Everything with one peer, oldest first. */
     history(peerId: string, limit?: number): Message[];
-    /** Inbound messages the session has not been shown yet, oldest first. */
+    /** Inbound messages this session has not been shown yet, oldest first. */
     unread(): Message[];
-    /** Mark everything currently unread as seen. */
+    /** Mark everything currently unread as seen — for this session, and nobody else. */
     markRead(): Promise<void>;
     /** Every peer we have said anything to or heard anything from, most recent first. */
     peers(): Array<{
@@ -55,8 +67,145 @@ declare class Inbox {
         unread: number;
     }>;
     get size(): number;
-    /** Serialised: two messages arriving together must not race each other's rewrite. */
-    private persist;
+    /** One line, one write — an append no other session can lose. */
+    private append;
+    /** Rewrite the log with the newest MAX_MESSAGES. Rare, and atomic via rename. */
+    private compact;
+    private persistCursor;
+    /**
+     * Carry over messages written before the log existed.
+     *
+     * Earlier versions kept one `inbox.json` holding both the messages and a single read state. The
+     * messages are still someone's; dropping them on upgrade would lose real conversations. The old
+     * read state is deliberately *not* carried over — it was one cursor for every session, so honouring
+     * it would mark messages seen for sessions that never saw them. Unread is the safe direction.
+     */
+    private adoptLegacy;
+}
+
+/**
+ * Everything the tools need from a node, as a flat surface.
+ *
+ * The tools used to reach into `VoleNetManager` directly, including through the objects it hands
+ * back — `getTransport()?.getPeers()`, `getRemoteTaskManager().delegateTask()`. That is fine while
+ * the node lives in the same process, and impossible once it does not: a socket cannot return a
+ * transport. Flattening it to plain calls with plain values is what lets the same tools run
+ * against a node here or a node in a daemon, which is what being *present* while no session is
+ * open requires.
+ */
+
+interface PeerInfo {
+    id: string;
+    name: string;
+    connected: boolean;
+}
+interface RelayMemberInfo {
+    id: string;
+    name: string;
+    viaHubName: string;
+    connected: boolean;
+    accepted: boolean;
+    incoming: boolean;
+    awaiting: boolean;
+}
+interface PairRequestInfo {
+    id: string;
+    name: string;
+    note?: string;
+    wants?: string[];
+}
+interface PairGrantInput {
+    trust?: 'full' | 'tool' | 'read';
+    allowBrain?: boolean;
+}
+interface SendResult {
+    ok: boolean;
+    delivered?: boolean;
+    relayed?: boolean;
+    error?: string;
+}
+interface AskResult {
+    status: string;
+    result?: string;
+    error?: string;
+}
+interface Identity {
+    instanceId: string;
+    publicKeyString: string;
+}
+interface RoomView {
+    room: string;
+    name: string;
+    topic?: string;
+    members: Array<{
+        instanceId: string;
+        name: string;
+    }>;
+}
+/** A node, wherever it happens to be running. */
+interface NetLike {
+    identity(): Promise<Identity | null>;
+    /** Peers this node holds a direct link with, and whether the socket is live. */
+    instances(): Promise<PeerInfo[]>;
+    relayMembers(): Promise<RelayMemberInfo[]>;
+    sendChat(to: string, text: string): Promise<SendResult>;
+    askBrain(to: string, input: string, fromName: string, timeoutMs: number): Promise<AskResult>;
+    joinHub(url: string): Promise<{
+        ok: boolean;
+        pending?: boolean;
+        hubName?: string;
+        error?: string;
+    }>;
+    addPeer(url: string): Promise<void>;
+    forgetPeer(url: string): Promise<boolean>;
+    probePair(url: string): Promise<{
+        ok: boolean;
+        name?: string;
+        fingerprint?: string;
+        publicKey?: string;
+        alreadyTrusted?: boolean;
+        error?: string;
+    }>;
+    initiatePair(url: string, publicKey: string, note?: string, wants?: string[]): Promise<{
+        ok: boolean;
+        pending?: boolean;
+        error?: string;
+    }>;
+    requestRelayConnect(ref: string, note?: string): Promise<{
+        ok: boolean;
+        queued?: boolean;
+        error?: string;
+    }>;
+    approveRelayConnect(ref: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    denyRelayConnect(ref: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Rooms this node is in, as its hub last described them (PROTOCOL.md §7c). */
+    rooms(): Promise<RoomView[]>;
+    roomCommand(hub: string, type: 'room:create' | 'room:join' | 'room:leave' | 'room:invite' | 'room:list', payload: Record<string, unknown>): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Post to a room: one sealed copy per member, so there is no key and no rotation. */
+    postToRoom(room: string, text: string): Promise<{
+        ok: boolean;
+        sent: number;
+        held: number;
+        skipped: number;
+        error?: string;
+    }>;
+    listPairRequests(): Promise<PairRequestInfo[]>;
+    acceptPair(ref: string, grant?: PairGrantInput): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    denyPair(ref: string): Promise<{
+        ok: boolean;
+    }>;
 }
 
 /** What a node needs to start. Resolved from stored settings, env and defaults. */
@@ -76,28 +225,63 @@ interface Notice {
     last: number;
 }
 interface Node {
-    net: VoleNetManager;
+    net: NetLike;
     inbox: Inbox;
-    /** What happened when we tried to join the configured hub, for whoami to report honestly. */
-    hubStatus: string;
     /** Trust decisions waiting on the person, newest last. */
     requests: PendingRequest[];
     /** Who tried to reach us while we were away, as the hub reports on reconnect. */
     notices: Notice[];
     options: NodeOptions;
+    /** What happened when the node last tried to join the configured hub. */
+    hubStatus: string;
     /**
-     * Be told when a message lands. MCP cannot push, so a session that wants to *wait* for a reply
-     * — rather than poll for one — needs somewhere to hang a promise. Returns an unsubscribe.
+     * Whether the client will run a model when the server asks — MCP's `sampling` capability, and
+     * the only way an arriving message could ever answer itself. Set once the client has connected.
      */
+    canSample: boolean;
+    /** Where this node is running, which decides whether it is there when nothing is open. */
+    where: 'daemon' | 'in-process';
+    /** Be told when a message lands, so a session can wait for a reply rather than poll for one. */
     onMessage: (fn: (m: Message) => void) => () => void;
     stop: () => Promise<void>;
 }
+/**
+ * Attach to this identity's daemon, starting one if none is running.
+ *
+ * Falls back to a node in this process when a daemon cannot be had — a sandbox that forbids
+ * spawning, say. Everything still works; it is simply only present while this session is.
+ */
 declare function startNode(options: NodeOptions): Promise<Node>;
 
 declare function run(argv: string[], out?: NodeJS.WriteStream & {
     fd: 1;
 }): Promise<number>;
 
+/**
+ * Guided flows, shipped with the server.
+ *
+ * A tool list tells a session what it *can* do, not what to do first, in what order, or what the
+ * words mean. In a fresh session "pair with my agent at <url>" only works if the model happens to
+ * match the sentence to `volenet_connect` — which it usually will, and shouldn't have to. Prompts
+ * surface in the client as commands, so the flow is chosen rather than guessed.
+ *
+ * They ship in this package rather than as files written into someone's editor config, so
+ * installing is all it takes and they cannot drift from the tools they describe.
+ */
+interface PromptArgument {
+    name: string;
+    description: string;
+    required?: boolean;
+}
+interface PromptDef {
+    name: string;
+    description: string;
+    arguments?: PromptArgument[];
+    /** The instruction handed to the session, with any arguments already filled in. */
+    render: (args: Record<string, string>) => string;
+}
+declare const PROMPTS: PromptDef[];
+
 interface ToolDef {
     name: string;
     description: string;
@@ -133,5 +317,7 @@ declare const TOOLS: ToolDef[];
 declare function unreadFooter(node: Node, toolName: string): string;
 /** Wire the tools to an MCP server. Separated so a test can drive it without a transport. */
 declare function createServer(node: Node): Server;
+/** Remember what the client can do, so a later session can say so without asking again. */
+declare function recordClientCapabilities(dir: string, caps: unknown): Promise<void>;
 
-export { Inbox, type Node, type NodeOptions, type Settings, TOOLS, type ToolDef, createServer, defaultDir, defaultName, loadStored, resolveSettings, run as runCli, saveStored, startNode, unreadFooter };
+export { Inbox, type Node, type NodeOptions, PROMPTS, type PromptDef, type Settings, TOOLS, type ToolDef, createServer, defaultDir, defaultName, loadStored, recordClientCapabilities, resolveSettings, run as runCli, saveStored, startNode, unreadFooter };