@openvole/volenet 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1673 @@
+import * as crypto from 'node:crypto';
+import { KeyObject } from 'node:crypto';
+import * as http from 'node:http';
+
+/** What an outbox entry is. Consent traffic waits the same way chat does — a request that
+ * vanished because the other side was away was the first thing a phone user noticed. */
+type OutboxKind = 'chat' | 'connect-request' | 'connect-accept' | 'connect-deny';
+/** A message waiting on its recipient. `sentAt` is when it was written, which is what the recipient should see. */
+interface OutboxEntry {
+    ref: string;
+    to: string;
+    toName: string;
+    text: string;
+    sentAt: number;
+    attempts: number;
+    lastError?: string;
+    /** Absent on entries written before consent traffic was held: chat. */
+    kind?: OutboxKind;
+    /** connect-request only. */
+    note?: string;
+}
+/** What a hub tells a member on reconnect about one sender. */
+interface RelayNotice {
+    from: string;
+    fromName: string;
+    count: number;
+    first: number;
+    last: number;
+}
+declare const DEFAULT_OUTBOX_TTL_MS: number;
+declare const DEFAULT_NOTICE_TTL_MS: number;
+declare class ChatOutbox {
+    private readonly file;
+    private readonly ttlMs;
+    private entries;
+    constructor(file: string, ttlMs?: number);
+    load(now?: number): Promise<void>;
+    list(): OutboxEntry[];
+    forPeer(to: string): OutboxEntry[];
+    get size(): number;
+    add(entry: Omit<OutboxEntry, 'ref' | 'attempts'> & {
+        ref?: string;
+    }): Promise<OutboxEntry>;
+    remove(ref: string): Promise<boolean>;
+    noteAttempt(ref: string, error?: string): Promise<void>;
+    /** Drop entries older than the TTL. Returns what was dropped so the owner can say so. */
+    sweep(now?: number): Promise<OutboxEntry[]>;
+    private persist;
+}
+declare class RelayNotices {
+    private readonly file;
+    private readonly ttlMs;
+    /** to → (from → notice) */
+    private byMember;
+    constructor(file: string, ttlMs?: number);
+    load(now?: number): Promise<void>;
+    /** Remember that `from` tried to reach `to` just now. */
+    record(to: string, from: string, fromName: string, now?: number): Promise<void>;
+    /** Hand over everything waiting for `to`, and forget it. */
+    take(to: string, now?: number): Promise<RelayNotice[]>;
+    /** Put notices back that could not be handed over after all (the member dropped off again). */
+    restore(to: string, notices: RelayNotice[]): Promise<void>;
+    peek(to: string): RelayNotice[];
+    /** Members with something waiting. */
+    get size(): number;
+    sweep(now?: number): Promise<void>;
+    private persist;
+}
+
+/**
+ * VoleNet Protocol — message types, serialization, validation.
+ * All messages are signed with Ed25519 for integrity and authenticity.
+ */
+
+/**
+ * The local node's post-quantum (ML-DSA) signing key, set once at VoleNet start.
+ * Module-level because there is exactly one signing identity per process — this lets
+ */
+type VoleNetMessageType = 'ping' | 'pong' | 'discover' | 'discover:response' | 'auth:challenge' | 'auth:response' | 'auth:result' | 'task:delegate' | 'task:result' | 'task:status' | 'memory:sync' | 'memory:search' | 'memory:results' | 'session:sync' | 'tool:list' | 'tool:list:response' | 'tool:call' | 'tool:result' | 'leader:heartbeat' | 'leader:claim' | 'leader:ack' | 'chat:message' | 'sealed' | 'sealed:direct' | 'relay:deliver' | 'relay:error' | 'relay:ack' | 'relay:pending' | 'roster' | 'relay:connect-request' | 'relay:connect-accept' | 'relay:connect-deny' | 'file:offer' | 'file:accept' | 'file:reject' | 'file:relay-ready' | 'file:done' | 'file:error' | 'file:cancel' | 'relay:blob:create' | 'relay:blob:grant' | 'relay:blob:deny' | 'relay:blob:fetch' | 'relay:blob:done';
+interface VoleNetMessage {
+    version: number;
+    id: string;
+    type: VoleNetMessageType;
+    from: string;
+    to: string | '*';
+    timestamp: number;
+    signature: string;
+    sigPq?: string;
+    payload: unknown;
+}
+interface VoleNetInstance {
+    id: string;
+    name: string;
+    publicKey: string;
+    endpoint: string;
+    capabilities: string[];
+    role: 'coordinator' | 'worker' | 'peer';
+    load: number;
+    maxTasks: number;
+    lastSeen: number;
+    version: string;
+    /** X25519 public key (base64 SPKI) for sealed envelopes, when the peer announces one. */
+    xPublicKey?: string;
+    /** ML-KEM-768 public key (base64 SPKI) — the post-quantum half of the hybrid seal. */
+    mlkemPublicKey?: string;
+}
+interface RemoteToolInfo {
+    name: string;
+    description: string;
+    pawName: string;
+    instanceId: string;
+    instanceName: string;
+}
+/**
+ * Create a signed VoleNet message.
+ */
+declare function createMessage(type: VoleNetMessageType, from: string, to: string | '*', payload: unknown, privateKey: KeyObject, pqPrivateKey?: KeyObject): VoleNetMessage;
+/**
+ * Verify a received message's signature and freshness.
+ */
+declare function verifyMessage(message: VoleNetMessage, publicKey: KeyObject, pqPublicKey?: KeyObject): {
+    valid: boolean;
+    error?: string;
+};
+
+/**
+ * VoleNet Transport — HTTP server + WebSocket for peer communication.
+ *
+ * Two modes:
+ * - HTTP POST: for initial auth and one-shot messages (fallback)
+ * - WebSocket: for persistent bidirectional messaging (preferred)
+ *
+ * WebSocket enables NAT traversal — the peer behind NAT connects out,
+ * and the other side pushes through the open connection.
+ * Auto-reconnect with exponential backoff on disconnect.
+ */
+
+interface TransportConfig {
+    port: number;
+    tls?: {
+        cert: string;
+        key: string;
+    };
+    /** Max inbound messages per minute per source (IP / WS connection). Default 1200. */
+    maxMessagesPerMinute?: number;
+    /** Max concurrent inbound WebSocket connections (DoS). Default 1000. */
+    maxConnections?: number;
+    /** Close an inbound WS that doesn't send a verified message within this window, ms (DoS). Default 10000. */
+    authTimeoutMs?: number;
+    /** Global inbound message ceiling per second across all sources (load shed). Default 5000. */
+    maxMessagesPerSecond?: number;
+    /** Publish peer display names in /volenet/info (off by default — names are enumeration surface). */
+    publishNames?: boolean;
+    /** Liveness: ping every socket this often (ms) and drop one that misses a pong. Default 20000; 0 disables. */
+    pingIntervalMs?: number;
+}
+type MessageHandler = (message: VoleNetMessage, peerId: string) => void;
+type JoinHandler = (body: unknown, ip: string) => Promise<{
+    status: number;
+    json: unknown;
+}>;
+/**
+ * VoleNet Transport layer.
+ * HTTP server for initial connections + WebSocket for persistent messaging.
+ */
+declare class VoleNetTransport {
+    private server;
+    private wss;
+    private peers;
+    private messageHandlers;
+    /** Optional outbound transform — wraps a message in a sealed:direct envelope before sending. */
+    private sealer;
+    /** Resolves a full peerId to its announced display name (for /volenet/info when publishNames). */
+    private nameResolver;
+    private joinHandler;
+    private pairHandler;
+    private identityProvider;
+    /** VoleDrop data plane — handles /volenet/blob/* streamed requests. */
+    private blobHandler;
+    private msgWindow;
+    private wsConnSeq;
+    private config;
+    private started;
+    private wsConnections;
+    private globalWindow;
+    private verifyFn?;
+    private responder?;
+    private onConnectCbs;
+    private onDisconnectCbs;
+    private seenMsgs;
+    /** Every socket this transport owns, either direction — so stop() closes orphans too. */
+    private sockets;
+    private alive;
+    private pingTimer;
+    constructor(config: TransportConfig);
+    /** Register a handler for public self-join requests (HTTP POST /volenet/join). */
+    setJoinHandler(handler: JoinHandler): void;
+    /** Register a handler for consent-based pairing requests (HTTP POST /volenet/pair). */
+    setPairHandler(handler: JoinHandler): void;
+    /**
+     * Provide this node's own public identity for /volenet/info — the key `vole net pair`
+     * fetches (and fingerprints) before asking the operator here for consent. Public keys
+     * are announced to every peer anyway; exposing one here is not an enumeration surface.
+     */
+    setIdentityProvider(fn: () => {
+        publicKey: string;
+        name?: string;
+        instanceId?: string;
+    }): void;
+    /**
+     * Register the VoleDrop blob handler for /volenet/blob/* — the file-transfer data
+     * plane. Returns true when it handled the request. Auth (per-transfer tokens), byte
+     * budgets, and concurrency caps are the handler's responsibility: these routes carry
+     * large streamed bodies and deliberately bypass the JSON message pipeline.
+     */
+    setBlobHandler(fn: (req: http.IncomingMessage, res: http.ServerResponse, pathname: string) => boolean): void;
+    /**
+     * Inject a signature verifier. An inbound WebSocket is bound to a peer id ONLY after a
+     * message from it verifies — so an attacker can't claim a victim's id and hijack its
+     * downstream traffic.
+     */
+    setVerifier(fn: (message: VoleNetMessage) => boolean): void;
+    /**
+     * Inject a request responder for request/response messages (e.g. `discover` over HTTP).
+     * The returned message is delivered inline in the HTTP response body, so a peer behind NAT
+     * learns the responder's identity without the responder having to dial it back.
+     */
+    setResponder(fn: (message: VoleNetMessage) => VoleNetMessage | null): void;
+    /**
+     * Called when an outbound WebSocket to a peer opens. Lets the owner push a signed message
+     * immediately so the remote side binds this socket without waiting for the next heartbeat —
+     * which is what makes reverse delivery (hub→NAT'd-follower) consistent right after (re)connect.
+     */
+    setOnConnect(fn: (peerId: string) => void): void;
+    setOnDisconnect(fn: (peerId: string) => void): void;
+    /** Global sliding-window message ceiling across all sources (load shed). False when over. */
+    private globalRateAllow;
+    /**
+     * Central inbound gate. Every message must (a) verify — valid signature from an authorized
+     * peer — and (b) not be a replay of a recently-accepted (from,id), before it reaches ANY
+     * handler. Fails closed if no verifier is wired. This makes verification a single chokepoint
+     * so an individual handler can never forget to check.
+     */
+    private verifyAndAccept;
+    /** Sliding-window rate limit per source (IP or WS connection). Returns false when over. */
+    private rateAllow;
+    /**
+     * Start the transport server (HTTP + WebSocket).
+     */
+    start(): Promise<void>;
+    /** Bind the listening port, retrying briefly on EADDRINUSE (covers restart races). */
+    private listen;
+    /**
+     * Stop the transport.
+     */
+    stop(): Promise<void>;
+    onMessage(handler: MessageHandler): void;
+    /** Install the outbound seal transform (direct end-to-end encryption). */
+    setSealer(fn: (peerId: string, message: VoleNetMessage) => VoleNetMessage): void;
+    /** Install the display-name resolver used by /volenet/info when publishNames is enabled. */
+    setNameResolver(fn: (peerId: string) => string | undefined): void;
+    /**
+     * Feed a message into the normal receive pipeline as if it arrived over the wire. Used to
+     * re-dispatch the inner message recovered from a sealed:direct envelope, so every handler
+     * (tool calls, sync, chat) processes it — with full signature/replay/authorization checks —
+     * exactly as an unencrypted direct message.
+     */
+    injectMessage(message: VoleNetMessage): boolean;
+    /**
+     * Send a message to a peer.
+     * Prefers WebSocket (instant, bidirectional), falls back to HTTP POST.
+     */
+    sendToPeer(peerId: string, message: VoleNetMessage): Promise<boolean>;
+    broadcast(message: VoleNetMessage): Promise<number>;
+    /**
+     * Register a peer and initiate WebSocket connection.
+     */
+    addPeer(peerId: string, endpoint: string): void;
+    removePeer(peerId: string): void;
+    /**
+     * One socket per pair.
+     *
+     * Two nodes that can both dial end up with two sockets between them, and each side binds the
+     * OTHER's dial as the peer's socket while its own stays open, unreferenced. A stop() closes
+     * what it references and leaves the orphan; the far side then keeps believing the peer is
+     * connected, on a socket nothing will ever close, and forwards into it.
+     *
+     * When a second socket appears for a peer, the node with the smaller id counts as the dialer
+     * and both sides keep that one — so they agree — and close the other. Only a genuine double
+     * triggers this: a node that cannot be dialed keeps whatever socket it has. Without a known
+     * self id, the newest wins.
+     *
+     * @returns false when the new socket was the one let go.
+     */
+    private adopt;
+    /** Close a socket we are done with. Its close handler finds no peer referencing it and does nothing. */
+    private drop;
+    private track;
+    /**
+     * Liveness. A phone that walks out of Wi-Fi sends no close frame; without this its socket
+     * would stay OPEN here for as long as TCP takes to notice, and everything sent to it is lost.
+     * The ws library answers pings on its own, so the far side needs nothing.
+     */
+    private startPinging;
+    getPeers(): Array<{
+        peerId: string;
+        endpoint: string;
+        connected: boolean;
+        lastSeen: number;
+        transport: 'websocket' | 'http' | 'disconnected';
+    }>;
+    isPeerConnected(peerId: string): boolean;
+    pingPeer(endpoint: string): Promise<boolean>;
+    /**
+     * Connect to a peer via WebSocket.
+     */
+    private connectWebSocket;
+    /**
+     * Schedule WebSocket reconnect with exponential backoff.
+     */
+    private scheduleReconnect;
+}
+
+/**
+ * VoleNet Discovery — peer registry, capability announcement, health monitoring.
+ */
+
+interface DiscoveryConfig {
+    netDir: string;
+    instanceId: string;
+    instanceName: string;
+    role: 'coordinator' | 'worker' | 'peer';
+    endpoint: string;
+    capabilities: string[];
+    privateKey: KeyObject;
+    /** ML-DSA-65 signing key — hybrid signatures when present. */
+    pqPrivateKey?: KeyObject;
+    publicKeyString: string;
+    /** Peer URLs from vole.config.json — used only to warn when one goes stale (endpoint drift). */
+    configuredPeerUrls?: string[];
+    /** Our X25519 public key (base64 SPKI), announced so peers can seal envelopes to us. */
+    xPublicKeyB64?: string;
+    /** Our ML-KEM-768 public key (base64 SPKI), announced for post-quantum hybrid seals. */
+    mlkemPublicKeyB64?: string;
+}
+/**
+ * The configured URL that has gone stale for a peer, or null. A peer's advertised endpoint is
+ * what we actually reconnect to at runtime; if the config lists a DIFFERENT url on the SAME
+ * hostname (e.g. the old ":9710" after a hub moved behind a proxied "/mesh" path), the config
+ * entry silently stops working on the next restart — worth a loud hint now. Different-host
+ * advertisements (other mesh members, NAT'd guests) are none of the config's business.
+ */
+declare function findEndpointDrift(configuredUrls: string[] | undefined, advertised: string): string | null;
+declare class VoleNetDiscovery {
+    private instances;
+    private remoteTools;
+    private transport;
+    private config;
+    private healthTimer;
+    private authorizedPeers;
+    private onPeerChanged?;
+    /** Instances already warned about a stale configured URL — hint once, not every health cycle. */
+    private driftHinted;
+    constructor(transport: VoleNetTransport, config: DiscoveryConfig);
+    /**
+     * Start discovery — load authorized peers, announce self, begin health checks.
+     */
+    /** Set callback for when peers join/leave (triggers leader re-election) */
+    setOnPeerChanged(handler: () => void): void;
+    start(): Promise<void>;
+    /**
+     * Stop discovery — cleanup timers.
+     */
+    stop(): void;
+    /**
+     * Connect to a peer and perform authentication.
+     */
+    connectToPeer(endpoint: string): Promise<string | null>;
+    /**
+     * Handle incoming VoleNet messages.
+     */
+    private handleMessage;
+    /**
+     * Verify an inbound message is from an authorized peer (keystore + Ed25519 signature).
+     * Used by non-discovery handlers (e.g. peer chat) that receive raw transport messages.
+     */
+    verifyMessageFrom(message: VoleNetMessage): boolean;
+    /**
+     * Handle discovery announcement from a peer.
+     */
+    /**
+     * Build a signed discover:response for an inbound discover, with NO side effects.
+     * Wired as the transport's HTTP responder so a peer behind NAT receives our identity
+     * inline in its own request's response — it can't be reached by a dial-back. Returns
+     * null unless the discover is from an authorized peer with a valid signature.
+     */
+    buildDiscoverResponse(message: VoleNetMessage): VoleNetMessage | null;
+    private handleDiscover;
+    /**
+     * Handle discovery response.
+     */
+    private handleDiscoverResponse;
+    private handlePing;
+    private handlePong;
+    private handleToolList;
+    /**
+     * Health check — ping all peers, remove stale ones.
+     */
+    /** Send a signed ping to a peer — fired on WS connect for immediate binding, and by healthCheck. */
+    /** Warn (once per instance) when a configured peer URL no longer matches what it advertises. */
+    private hintEndpointDrift;
+    private sendPing;
+    private healthCheck;
+    /**
+     * Get all connected instances.
+     */
+    getInstances(): VoleNetInstance[];
+    /**
+     * Get all remote tools across all peers.
+     */
+    getRemoteTools(): RemoteToolInfo[];
+    /**
+     * Find which peer has a specific tool.
+     */
+    findToolOwner(toolName: string): {
+        instanceId: string;
+        instance: VoleNetInstance;
+    } | null;
+    /**
+     * Reload authorized peers from disk.
+     */
+    reloadAuthorized(): Promise<void>;
+}
+
+/**
+ * VoleNet Ed25519 key management.
+ * Each vole instance has a keypair for identity and message signing.
+ *
+ * Key format: "vole-ed25519 <base64-ed25519-public-key> <instance-name> [base64-ml-dsa-public-key]"
+ *   The 4th field (ML-DSA public key) is present when post-quantum support is available
+ *   — the identity is then a hybrid Ed25519 + ML-DSA keypair.
+ * Storage: .openvole/net/vole_key (private), vole_key.pub (public), vole_key.pq (ML-DSA private)
+ *          .openvole/net/authorized_voles (trusted peer public keys)
+ */
+
+interface VoleKeyPair {
+    publicKey: crypto.KeyObject;
+    privateKey: crypto.KeyObject;
+    publicKeyString: string;
+    instanceId: string;
+    /** Post-quantum (ML-DSA-65) keys — present when the runtime supports it (OpenSSL 3.5+ / Node 24+). */
+    pqPublicKey?: crypto.KeyObject;
+    pqPrivateKey?: crypto.KeyObject;
+    /** X25519 key-agreement keys for sealed (end-to-end encrypted) envelopes. */
+    xPublicKey?: crypto.KeyObject;
+    xPrivateKey?: crypto.KeyObject;
+    /** Base64 SPKI of xPublicKey — announced to peers via discovery. */
+    xPublicKeyB64?: string;
+    /** ML-KEM-768 keys — the post-quantum half of the hybrid seal (OpenSSL 3.5+ / Node 24+). */
+    mlkemPublicKey?: crypto.KeyObject;
+    mlkemPrivateKey?: crypto.KeyObject;
+    /** Base64 SPKI of mlkemPublicKey — announced to peers via discovery alongside xPublicKeyB64. */
+    mlkemPublicKeyB64?: string;
+}
+/**
+ * Generate a new Ed25519 keypair.
+ * Saves to .openvole/net/vole_key and vole_key.pub
+ */
+declare function generateKeyPair(netDir: string, instanceName: string): Promise<VoleKeyPair>;
+/**
+ * Load existing keypair from disk.
+ */
+declare function loadKeyPair(netDir: string): Promise<VoleKeyPair | null>;
+/**
+ * Parse a public key string ("vole-ed25519 <base64> <name>") into a KeyObject.
+ */
+declare function parsePublicKey(keyString: string): {
+    publicKey: crypto.KeyObject;
+    instanceId: string;
+    name: string;
+    pqPublicKey?: crypto.KeyObject;
+} | null;
+/**
+ * Load trusted peer public keys from authorized_voles file.
+ */
+declare function loadAuthorizedVoles(netDir: string): Promise<Map<string, {
+    publicKey: crypto.KeyObject;
+    name: string;
+    pqPublicKey?: crypto.KeyObject;
+}>>;
+/**
+ * Add a peer's public key to authorized_voles.
+ */
+declare function trustPeer(netDir: string, publicKeyString: string, opts?: {
+    allowUpgrade?: boolean;
+}): Promise<string>;
+/**
+ * Remove a peer's public key from authorized_voles.
+ */
+declare function revokePeer(netDir: string, instanceIdOrKey: string): Promise<boolean>;
+/**
+ * Relay consent store: peers whose relayed (hub-forwarded) chat this vole accepts. Distinct from
+ * authorized_voles — accepting relay contact from a peer does NOT grant it direct-connect trust
+ * (memory sync, tool sharing). Same on-disk line format so keys stay pinned to identities.
+ * Storage: .openvole/net/relay_accepts
+ */
+declare function loadRelayAccepts(netDir: string): Promise<Map<string, {
+    publicKey: crypto.KeyObject;
+    name: string;
+    pqPublicKey?: crypto.KeyObject;
+}>>;
+/** Record consent to receive relayed contact from a peer (append its pinned key line). */
+declare function addRelayAccept(netDir: string, publicKeyString: string): Promise<string>;
+/** Withdraw relay consent for a peer (remove its line from relay_accepts). */
+declare function removeRelayAccept(netDir: string, instanceIdOrKey: string): Promise<boolean>;
+
+interface VoleNetFilesConfig {
+    enabled?: boolean;
+    inboxDir?: string;
+    /**
+     * Largest file this node will accept over a direct transfer. Default 2 GiB; `0` means no
+     * limit. Transfers are chunked, resumable and streamed to disk, so size costs nothing but
+     * disk — which is exactly why a limit exists at all: it is the only thing standing between a
+     * peer (or a buggy sender) and a full disk. Relayed transfers are bounded separately by
+     * `relayMaxBytes`, because there the bytes land on somebody else's disk.
+     */
+    maxBytes?: number;
+    acceptFrom?: '*' | string[];
+    maxConcurrent?: number;
+    offerTtlMinutes?: number;
+    chunkBytes?: number;
+    /** Largest single blob this node will host when acting as a relay hub. Default 512 MiB. */
+    relayMaxBytes?: number;
+    relayQuotaBytes?: number;
+    relayTtlHours?: number;
+}
+type TransferState = 'offered' | 'pending' | 'accepted' | 'transferring' | 'verifying' | 'done' | 'rejected' | 'failed' | 'cancelled' | 'expired';
+interface TransferInfo {
+    transferId: string;
+    dir: 'send' | 'recv';
+    peerId: string;
+    peerName: string;
+    name: string;
+    size: number;
+    sha256: string;
+    state: TransferState;
+    mode?: 'pull' | 'push' | 'relay';
+    bytesDone: number;
+    error?: string;
+    note?: string;
+    savedPath?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+
+/**
+ * VoleNet Leader Election — ensures only one instance runs heartbeat/schedules.
+ *
+ * Algorithm: lowest instance ID wins (deterministic, no voting).
+ * Leader sends periodic heartbeat. If 3 heartbeats missed (30s), next-lowest takes over.
+ */
+
+interface LeaderState {
+    leaderId: string | null;
+    leaderName: string | null;
+    isLeader: boolean;
+    lastHeartbeat: number;
+    missedHeartbeats: number;
+}
+/**
+ * Manages leader election for heartbeat/schedule ownership.
+ */
+declare class VoleNetLeader {
+    private transport;
+    private discovery;
+    private instanceId;
+    private instanceName;
+    private privateKey;
+    private pqPrivateKey?;
+    private leaderId;
+    private leaderName;
+    private lastLeaderHeartbeat;
+    private missedHeartbeats;
+    private heartbeatTimer;
+    private monitorTimer;
+    private onBecomeLeader?;
+    private onLoseLeader?;
+    private forcedLeader?;
+    constructor(transport: VoleNetTransport, discovery: VoleNetDiscovery, instanceId: string, instanceName: string, privateKey: KeyObject, pqPrivateKey: KeyObject | undefined, forcedLeader?: string);
+    /**
+     * Start leader election.
+     */
+    start(onBecomeLeader?: () => void, onLoseLeader?: () => void): void;
+    /**
+     * Stop leader election.
+     */
+    stop(): void;
+    /**
+     * Get current leader state.
+     */
+    getState(): LeaderState;
+    /**
+     * Check if this instance is the leader.
+     */
+    isLeader(): boolean;
+    /** Trigger re-election (called when peers change) */
+    reelect(): void;
+    /**
+     * Elect leader.
+     * If forcedLeader is set, that instance name is always leader.
+     * Otherwise, lowest instance ID wins.
+     */
+    private electLeader;
+    /**
+     * Start sending leader heartbeats.
+     */
+    private startLeaderHeartbeat;
+    /**
+     * Stop sending leader heartbeats.
+     */
+    private stopLeaderHeartbeat;
+    /**
+     * Monitor leader liveness.
+     */
+    private monitor;
+    /**
+     * Handle incoming leader-related messages.
+     */
+    private handleMessage;
+}
+
+/**
+ * VoleNet Remote Task — delegate tasks to remote peers, execute remote tools.
+ * Transparent to the Brain — remote tools appear in the tool registry like local ones.
+ */
+
+interface RemoteTaskRequest {
+    taskId: string;
+    input: string;
+    maxIterations?: number;
+    agentProfile?: string;
+    context?: string;
+    /** Set by net_message — the sender's instance name. Marks this as a chat message
+     *  (framed as a peer message + run in a per-peer session) rather than a one-shot task. */
+    fromName?: string;
+}
+interface RemoteTaskResult {
+    taskId: string;
+    status: 'queued' | 'running' | 'completed' | 'failed' | 'timeout';
+    result?: string;
+    error?: string;
+    durationMs?: number;
+}
+interface RemoteToolCallRequest {
+    callId: string;
+    toolName: string;
+    params: unknown;
+}
+interface RemoteToolCallResult {
+    callId: string;
+    success: boolean;
+    output?: unknown;
+    error?: string;
+}
+/**
+ * Manages remote task delegation and tool execution across VoleNet peers.
+ */
+declare class RemoteTaskManager {
+    private transport;
+    private discovery;
+    private instanceId;
+    private privateKey;
+    private pqPrivateKey?;
+    private pendingTasks;
+    private pendingToolCalls;
+    private routing;
+    constructor(transport: VoleNetTransport, discovery: VoleNetDiscovery, instanceId: string, privateKey: KeyObject, pqPrivateKey: KeyObject | undefined, routing?: Record<string, string>);
+    /**
+     * Delegate a task to a remote peer.
+     * Returns when the remote task completes or times out.
+     */
+    delegateTask(targetInstanceId: string, request: RemoteTaskRequest, timeoutMs?: number): Promise<RemoteTaskResult>;
+    /**
+     * Execute a tool on a remote peer.
+     * Used by the tool registry when a tool is remote.
+     */
+    executeRemoteTool(targetInstanceId: string, toolName: string, params: unknown, timeoutMs?: number): Promise<RemoteToolCallResult>;
+    /**
+     * Resolve which peer should handle a tool call.
+     * Checks routing config first, then falls back to discovery.
+     */
+    resolveToolTarget(toolName: string): string | null;
+    /**
+     * Handle incoming messages related to tasks and tools.
+     */
+    private handleMessage;
+    private handleTaskResult;
+    private handleTaskStatus;
+    private handleToolResult;
+    /**
+     * Cleanup pending requests.
+     */
+    dispose(): void;
+}
+
+/**
+ * VoleNet Sync — memory and session synchronization across peers.
+ *
+ * Memory sync: write propagation + remote search + result merging.
+ * Session sync: transcript replication for cross-device continuity.
+ *
+ * Conflict resolution: last-write-wins with instance attribution.
+ * Consistency model: eventual (async propagation, no blocking).
+ */
+
+/** Memory write event for propagation */
+interface MemorySyncEntry {
+    file: string;
+    source: string;
+    content: string;
+    mode: 'overwrite' | 'append';
+    timestamp: number;
+    instanceId: string;
+    version: number;
+}
+/** Remote memory search request */
+interface MemorySearchRequest {
+    query: string;
+    source?: string;
+    limit?: number;
+    requestId: string;
+}
+/** Remote memory search result */
+interface MemorySearchResult {
+    requestId: string;
+    instanceId: string;
+    instanceName: string;
+    results: Array<{
+        file: string;
+        source: string;
+        score: number;
+        snippet: string;
+    }>;
+}
+/** Session sync entry */
+interface SessionSyncEntry {
+    sessionId: string;
+    role: string;
+    content: string;
+    timestamp: number;
+    instanceId: string;
+}
+interface SyncConfig {
+    memory: boolean;
+    session: boolean;
+}
+/**
+ * Manages memory and session synchronization across VoleNet peers.
+ */
+declare class VoleNetSync {
+    private transport;
+    private discovery;
+    private instanceId;
+    private instanceName;
+    private privateKey;
+    private pqPrivateKey?;
+    private config;
+    private onMemoryWrite?;
+    private onMemorySearch?;
+    private onSessionWrite?;
+    private pendingSearches;
+    private recentSyncs;
+    constructor(transport: VoleNetTransport, discovery: VoleNetDiscovery, instanceId: string, instanceName: string, privateKey: KeyObject, pqPrivateKey: KeyObject | undefined, config: SyncConfig);
+    /**
+     * Register callback for when a remote memory write arrives.
+     * The callback should apply the write to the local memory store.
+     */
+    setMemoryWriteHandler(handler: (entry: MemorySyncEntry) => Promise<void>): void;
+    /**
+     * Register callback for handling remote memory search requests.
+     * The callback should search the local store and return results.
+     */
+    setMemorySearchHandler(handler: (request: MemorySearchRequest) => Promise<MemorySearchResult['results']>): void;
+    /**
+     * Register callback for when a remote session write arrives.
+     */
+    setSessionWriteHandler(handler: (entry: SessionSyncEntry) => Promise<void>): void;
+    /**
+     * Propagate a local memory write to all peers.
+     * Called by paw-memory after a successful local write.
+     */
+    propagateMemoryWrite(entry: MemorySyncEntry): Promise<void>;
+    /**
+     * Search memory across all peers + local.
+     * Returns merged results from all sources, re-ranked by score.
+     */
+    searchRemoteMemory(query: string, options?: {
+        source?: string;
+        limit?: number;
+        timeoutMs?: number;
+    }): Promise<MemorySearchResult[]>;
+    /**
+     * Propagate a session message to peers.
+     */
+    propagateSessionWrite(entry: SessionSyncEntry): Promise<void>;
+    /**
+     * Handle incoming sync messages.
+     */
+    private handleMessage;
+    /**
+     * Handle incoming memory write from a peer.
+     */
+    private handleMemorySync;
+    /**
+     * Handle remote memory search request — search local store and reply.
+     */
+    private handleMemorySearchRequest;
+    /**
+     * Handle memory search results from a peer.
+     */
+    private handleMemorySearchResults;
+    /**
+     * Handle session sync from a peer.
+     */
+    private handleSessionSync;
+    /**
+     * Cleanup.
+     */
+    dispose(): void;
+}
+
+/**
+ * The only thing this library needs to know about an agent's tools.
+ *
+ * VoleNet can lend a node's tools to a peer it trusts, which means it has to be able to list them
+ * and run one. That is the whole contract — two methods and five fields — so it is stated here
+ * structurally rather than imported from the agent framework. Anything that satisfies this shape
+ * works, including a host with no notion of paws at all.
+ */
+/** One tool, as the network needs to see it. */
+interface SharedToolEntry {
+    name: string;
+    description: string;
+    /** Which plugin provides it. Used to decide what may be shared, so it is required. */
+    pawName: string;
+    /**
+     * The host's own context type is opaque here, and deliberately `any`: typed as `unknown` this
+     * contract would be satisfiable by nothing, since a function taking a specific context is not
+     * assignable to one taking anything at all.
+     */
+    execute: (params: unknown, ctx?: any) => Promise<unknown>;
+}
+/** A tool as the host defines it, when the network registers a peer's tools locally. */
+interface SharedToolDefinition {
+    name: string;
+    description: string;
+    /** The host's own parameter schema type (a Zod schema in OpenVole). Opaque here. */
+    parameters: unknown;
+    /**
+     * The host's own context type is opaque here, and deliberately `any`: typed as `unknown` this
+     * contract would be satisfiable by nothing, since a function taking a specific context is not
+     * assignable to one taking anything at all.
+     */
+    execute: (params: unknown, ctx?: any) => Promise<unknown>;
+}
+/** Whatever holds this node's tools. `ToolRegistry` in OpenVole; anything with this shape here. */
+interface ToolProvider {
+    get(toolName: string): SharedToolEntry | undefined;
+    list(): SharedToolEntry[];
+    /** Publish a peer's tools locally, so the host can call them as if they were its own. */
+    register(pawName: string, tools: SharedToolDefinition[], inProcess: boolean): void;
+}
+/**
+ * Plugins whose tools are backed by the host's control plane, and must never be shared over the
+ * mesh.
+ *
+ * They read as ordinary tools but execute against the local server — managing siblings, or
+ * speaking as this agent to one. A shared tool runs *on its owner*, so lending one of these lends
+ * the owner's authority with it: a peer that cannot manage agents itself could drive the owner's
+ * `agent_submit` and have every permission check pass, because by then the call really is the
+ * owner's. Excluded by **source** rather than by name — a name pattern would have to be kept in
+ * step with every tool ever added, and would quietly miss the first one somebody forgets.
+ *
+ * This lives with the network rather than with the tools because the network is what enforces it.
+ */
+declare const CONTROL_PLANE_PAWS: readonly ["__orchestrate__", "__agent_chat__"];
+declare function isControlPlanePaw(pawName: string): boolean;
+
+interface Logger {
+    error: (msg: string, ...args: unknown[]) => void;
+    warn: (msg: string, ...args: unknown[]) => void;
+    info: (msg: string, ...args: unknown[]) => void;
+    debug: (msg: string, ...args: unknown[]) => void;
+    trace: (msg: string, ...args: unknown[]) => void;
+}
+type LoggerFactory = (tag: string) => Logger;
+/**
+ * Hand this library the host's logger. Loggers created before this call are redirected too, so a
+ * host can inject at startup without caring which modules have already been imported.
+ */
+declare function setLoggerFactory(make: LoggerFactory): void;
+declare function createLogger(tag: string): Logger;
+/** Close the log file this library opened. A host that injected its own logger owns its stream. */
+declare function closeLogger(): void;
+
+/**
+ * Sealed envelopes — end-to-end encryption for VoleNet messages (relay and, opt-in, direct).
+ *
+ * Hybrid KEM: every seal mixes an X25519 ECDH shared secret with an ML-KEM-768 (post-quantum)
+ * shared secret — HKDF-SHA256 over the concatenation — so confidentiality holds unless BOTH the
+ * classical and the post-quantum KEM are broken. This closes the harvest-now-decrypt-later gap:
+ * an adversary recording ciphertext today cannot read it with a future quantum computer. The
+ * X25519 half uses a fresh ephemeral key per envelope (random nonces, no cross-envelope leakage);
+ * the ML-KEM half encapsulates to the recipient's static PQ key. The AAD binds the envelope to
+ * its routing (`from|to`), so a relay cannot re-address a ciphertext without breaking the tag.
+ *
+ * Backward-compatible: when the recipient announces no ML-KEM key (an older peer) or the runtime
+ * lacks ML-KEM, the seal falls back to X25519-only (the `v1` scheme, byte-identical to before).
+ * The scheme is bound into the KDF, so stripping the KEM ciphertext from a hybrid box yields the
+ * wrong key and fails the tag — a downgrade cannot silently weaken an envelope, only drop it.
+ *
+ * The plaintext is a full, signed VoleNet message: sealing wraps the existing protocol, it does
+ * not replace any of its checks — the recipient still verifies the inner signature, freshness,
+ * and sender identity after unsealing.
+ */
+
+interface SealedBox {
+    /** Ephemeral X25519 public key, base64 SPKI DER. */
+    epk: string;
+    /** ML-KEM-768 ciphertext, base64 — present only for hybrid (post-quantum) envelopes. */
+    kem?: string;
+    /** ChaCha20-Poly1305 nonce, base64 (12 bytes). */
+    n: string;
+    /** Ciphertext ‖ auth tag, base64. */
+    c: string;
+}
+/**
+ * Seal plaintext to a recipient. When `recipientMlkemPubB64` is supplied (and ML-KEM is available),
+ * produces a post-quantum hybrid envelope; otherwise an X25519-only one. Returns null on a bad key.
+ */
+declare function seal(recipientXPubB64: string, plaintext: Buffer, aad: string, recipientMlkemPubB64?: string): SealedBox | null;
+/**
+ * Unseal with our X25519 private key (and ML-KEM private key for hybrid envelopes). The scheme is
+ * chosen by whether the box carries a KEM ciphertext, so a stripped-KEM downgrade fails the tag
+ * rather than decrypting under a weaker key. Returns null on any tampering or mismatch.
+ */
+declare function unseal(xPrivateKey: crypto.KeyObject, box: SealedBox, aad: string, mlkemPrivateKey?: crypto.KeyObject): Buffer | null;
+
+/** One answer waiting on the peer that asked for it. */
+interface PendingResult {
+    /** Who asked. */
+    peerId: string;
+    /** Their id for the task — what the answer must carry to be recognised. */
+    taskId: string;
+    status: string;
+    result?: string;
+    error?: string;
+    /** When the answer was ready. */
+    at: number;
+    attempts: number;
+}
+declare const DEFAULT_RESULT_TTL_MS: number;
+/** Ceiling per peer, oldest dropped first, so one absent asker cannot fill the disk. */
+declare const MAX_RESULTS_PER_PEER = 50;
+declare class ResultOutbox {
+    private readonly file;
+    private readonly ttlMs;
+    private entries;
+    constructor(file: string, ttlMs?: number);
+    load(now?: number): Promise<void>;
+    list(): PendingResult[];
+    forPeer(peerId: string): PendingResult[];
+    has(peerId: string): boolean;
+    get size(): number;
+    /** Hold an answer. Re-asking the same task replaces the old answer rather than stacking. */
+    add(entry: Omit<PendingResult, 'attempts'>): Promise<PendingResult>;
+    remove(peerId: string, taskId: string): Promise<boolean>;
+    noteAttempt(peerId: string, taskId: string): Promise<void>;
+    /** Drop answers older than the TTL. Returns what was dropped so the owner can say so. */
+    sweep(now?: number): Promise<PendingResult[]>;
+    private persist;
+}
+
+/**
+ * VoleNet Manager — lifecycle management for the distributed networking layer.
+ * Initializes transport, discovery, and key management.
+ * Starts/stops with the engine.
+ */
+
+/**
+ * Message types NEVER wrapped in a sealed:direct envelope: the handshake/transport types that must
+ * be readable to bootstrap encryption (they carry no secrets — public keys, endpoints, liveness),
+ * the seal envelopes themselves, the relay envelopes (already end-to-end sealed to a third party),
+ * and high-frequency leader election (not confidential). Everything else is sealed when enabled.
+ */
+/**
+ * Anywhere this node's events can be published. Only `emit` is ever called, so any emitter shape
+ * satisfies it — OpenVole's mitt bus, an EventEmitter, or a few lines in a host that has neither.
+ */
+interface EventSink {
+    emit: (type: any, event?: any) => void;
+}
+/** An EventSink that can also be listened to, for a host that has no bus of its own. */
+interface EventBus extends EventSink {
+    on: (type: any, handler: (event?: any) => void) => void;
+    off: (type: any, handler?: (event?: any) => void) => void;
+}
+/**
+ * A minimal event bus, so a host without one can still hear what this node is doing. OpenVole
+ * passes its own typed bus instead; both satisfy EventSink.
+ */
+declare function createEventBus(): EventBus;
+/** Glob-ish tool-name match: exact, '*' wildcard, or 'prefix*'. */
+/**
+ * Display prefix for a peer's namespaced tools. Peer names are self-announced labels —
+ * identity is the key-derived instanceId — so when two peers share a name, the prefix
+ * is disambiguated with a short id suffix: alice~3f9c/tool.
+ */
+declare function peerPrefix(peerName: string, peerId: string, duplicateName: boolean): string;
+/** Whether a tool passes the share-level allowlist (empty/absent allows all). */
+declare function isSharedTool(name: string, toolAllow?: string[]): boolean;
+interface VoleNetConfig {
+    enabled?: boolean;
+    instanceName?: string;
+    role?: 'coordinator' | 'worker' | 'peer';
+    port?: number;
+    /**
+     * Hostname this instance advertises to peers (the host in its discovery endpoint).
+     * Defaults to the first non-internal IPv4 address. Set this to your public domain
+     * (e.g. "hub.example.com") when running with TLS so the advertised endpoint matches
+     * the certificate — otherwise peers connecting over wss/https hit a name mismatch.
+     * Overridable at runtime via the VOLE_NET_HOSTNAME env var.
+     */
+    hostname?: string;
+    /**
+     * Full endpoint advertised to peers INSTEAD of `<scheme>://<hostname>:<port>` — for running
+     * VoleNet behind a reverse proxy so the raw listen port never has to be exposed. Example:
+     * "https://club.example.com/mesh", with nginx proxying that path (WebSocket upgrade included)
+     * to the local VoleNet port. Peers join with this URL and are told to reconnect to it; the
+     * joining side needs nothing — all peer traffic is endpoint-relative and the WS upgrade is
+     * accepted on any path. Env override: VOLE_NET_PUBLIC_URL.
+     */
+    publicUrl?: string;
+    keyPath?: string;
+    /**
+     * Remember a peer learned at runtime — accepting a pair request, or joining a hub — so it
+     * survives a restart. The host owns its own config format; without this the entry is
+     * live-only, which is the right default for a library.
+     */
+    persistPeer?: (url: string) => Promise<void>;
+    peers?: Array<{
+        /**
+         * Where to reach this peer. Also how the entry is matched to a connected peer, by
+         * port or host. Omit it for a peer that has no address of its own — a phone, or
+         * anything behind NAT that can only dial us — and identify it with `id`/`name`.
+         */
+        url?: string;
+        /**
+         * Match by instance id instead of address (a full id, or a prefix of at least 8
+         * characters). This is the only way to name a peer that advertises no endpoint,
+         * and the only stable one for a peer whose address moves.
+         */
+        id?: string;
+        /** Match by announced instance name. Weaker than `id` — a name is not proof of identity. */
+        name?: string;
+        /** What this peer can do on OUR instance. Defaults to 'full' — set it for a guest. */
+        trust?: 'full' | 'tool' | 'read';
+        allowTools?: string[];
+        denyTools?: string[];
+        /** Allow this peer to use our Brain for their tasks (LLM cost on us) */
+        allowBrain?: boolean;
+    }>;
+    share?: {
+        tools?: boolean;
+        memory?: boolean;
+        session?: boolean;
+        /**
+         * Patterns limiting WHICH tools are shared (advertised + callable) to peers without
+         * an explicit per-peer allowTools entry — e.g. ["club_*"]. Empty/absent = all tools.
+         * Essential for public hubs: share one curated tool set with strangers.
+         */
+        toolAllow?: string[];
+    };
+    /** Retention for node-to-node chat sessions (volenet:<peer>). */
+    chatRetention?: {
+        /** Max messages kept per peer transcript (oldest trimmed). Default 1000. */
+        maxMessages?: number;
+        /** Clear chat sessions idle longer than this many days. Default 90; 0 disables. */
+        maxAgeDays?: number;
+    };
+    /**
+     * Brain source for brainless workers:
+     * - "local" (default): use local brain paw
+     * - "remote": delegate thinking to a peer that allows brain sharing
+     * - "<instanceName>": delegate to a specific peer's brain
+     */
+    brainSource?: 'local' | 'remote' | string;
+    tls?: {
+        cert: string;
+        key: string;
+    };
+    /** Max concurrent inbound VoleNet WebSocket connections (DoS). Default 1000. */
+    maxConnections?: number;
+    /** Close inbound WS that don't send a verified message within this many ms (DoS). Default 10000. */
+    authTimeoutMs?: number;
+    /** Global inbound message ceiling per second across all sources (load shed). Default 5000. */
+    maxMessagesPerSecond?: number;
+    discovery?: 'manual' | 'mdns';
+    routing?: Record<string, string>;
+    /**
+     * Leader selection mode:
+     * - "auto" (default): lowest instance ID wins, automatic failover
+     * - "<instanceName>": force a specific instance as leader
+     */
+    leader?: 'auto' | string;
+    /**
+     * Heartbeat mode:
+     * - "leader" (default): only the leader runs heartbeat/schedules
+     * - "independent": each instance runs its own heartbeat independently
+     */
+    heartbeatMode?: 'leader' | 'independent';
+    /**
+     * Brain load balancing:
+     * - "local" (default): each instance handles its own tasks
+     * - "loadbalance": route incoming tasks to the least-loaded brain across peers
+     */
+    brainMode?: 'local' | 'loadbalance';
+    /**
+     * Task overflow behavior when local queue is full:
+     * - "reject" (default): reject the task
+     * - "forward": forward to the least-loaded peer automatically
+     */
+    taskOverflow?: 'reject' | 'forward';
+    /** Max queued tasks before overflow triggers (default: 10) */
+    maxQueuedTasks?: number;
+    /**
+     * Public self-join — let unknown peers register over HTTP and join at a restricted
+     * "guest" trust level (for a public mesh hub). Off by default. Guests are NEVER 'full'.
+     */
+    publicJoin?: {
+        enabled?: boolean;
+        /** Trust granted to self-joined guests. Never 'full'. Default 'tool'. */
+        trustLevel?: 'read' | 'tool';
+        /** Let guests use OUR Brain (LLM cost on us). Default false. */
+        allowBrain?: boolean;
+        /** Max trusted peers before new joins are refused. Default 200. */
+        maxPeers?: number;
+        /** Join requests allowed per minute per IP. Default 5. */
+        ratePerMinute?: number;
+        /** Queue joins to pending_joins.jsonl for manual `vole net trust` instead of auto-trusting. */
+        requireApproval?: boolean;
+    };
+    /**
+     * Blind relay (hub side): forward sealed member↔member envelopes the hub cannot read.
+     * v1 carries end-to-end encrypted chat only — no tool calls or delegation ride the relay.
+     */
+    relay?: {
+        enabled?: boolean;
+        /** Forwards allowed per minute per (sender, recipient) pair. Default 30. */
+        maxPerMinutePerPair?: number;
+        /** Max sealed envelope size in bytes. Default 65536. */
+        maxBytes?: number;
+        /**
+         * Member side: who may reach ME over a relay. Sharing a hub is not consent — a member's
+         * relayed chat is dropped until I accept it. Default (unset): only peers I've explicitly
+         * approved (a connect-request) or already directly trust. '*' opens me to any hub member
+         * (community-hub behaviour). A list pre-authorises peers by name or instanceId prefix.
+         */
+        acceptFrom?: '*' | string[];
+        /**
+         * Hub side: how long a "somebody tried to reach you" notice is kept for a member who is
+         * away, in hours. Default 168 (a week). A notice is sender, count and times — the message
+         * itself is never held by the hub.
+         */
+        noticeTtlHours?: number;
+        /**
+         * Member side: how long an undelivered chat message waits in THIS node's own outbox for
+         * its recipient to reappear, in hours. Default 168 (a week).
+         */
+        outboxTtlHours?: number;
+    };
+    /**
+     * Direct end-to-end encryption. When true, post-handshake messages to a peer that supports it
+     * (announces an ML-KEM key) are sealed with the hybrid X25519 + ML-KEM-768 KEM before sending —
+     * confidentiality independent of TLS, and post-quantum. Opportunistic: peers that don't support
+     * it (older versions) still receive plaintext, so a mixed-version mesh keeps working. Default off.
+     */
+    encrypt?: boolean;
+    /**
+     * Publish peer display names (the live announced `instanceName`) in the public /volenet/info
+     * response. Off by default — names are an enumeration surface. Turn on for a public hub whose
+     * members are meant to be seen (e.g. a social wall), so external tooling can read live names
+     * without the authenticated dashboard.
+     */
+    publishNames?: boolean;
+    /**
+     * VoleDrop — E2E-encrypted file transfer (files stream over /volenet/blob/*; the per-transfer
+     * key is sealed with the PQ-hybrid seal). `acceptFrom` mirrors relay.acceptFrom: unset means
+     * every offer waits for an explicit accept; '*' or a name/id-prefix list auto-accepts (use for
+     * your own fleet). Hubs with relay enabled also store ciphertext blobs for NAT'd member pairs,
+     * bounded by relayQuotaBytes/relayTtlHours.
+     */
+    files?: VoleNetFilesConfig;
+}
+/** A hub-vouched mesh member, learned from a relay hub's roster broadcast. */
+interface RosterMember {
+    instanceId: string;
+    name: string;
+    publicKey: string;
+    xPublicKey?: string;
+    mlkemPublicKey?: string;
+    connected: boolean;
+}
+/** A single human-capable peer-chat message, stored per peer for the dashboard. */
+interface ChatEntry {
+    dir: 'in' | 'out';
+    text: string;
+    fromName: string;
+    timestamp: number;
+    messageId: string;
+    /** True when this message travelled through a relay hub as a sealed envelope. */
+    relayed?: boolean;
+}
+declare class VoleNetManager {
+    private keyPair;
+    private transport;
+    private discovery;
+    private remoteTaskMgr;
+    private sync;
+    private leader;
+    private toolProviders;
+    /** registered remote tool name → owning instanceId (identity-keyed routing; never by peer name) */
+    private remoteToolOwners;
+    private config;
+    private projectRoot;
+    private toolRegistry;
+    private started;
+    /** Per-IP join timestamps for public-join rate limiting. */
+    private joinTimestamps;
+    /** Relay: per-(from,to) forward windows (hub side). */
+    private relayWindows;
+    /** Relay: hub-vouched member rosters, keyed by hub instanceId. */
+    private hubRosters;
+    /** Relay: inner-message replay guard — the transport's outer guard can't see re-wraps. */
+    private seenSealed;
+    private rosterTimer;
+    /** Relay consent gate: instanceIds whose relayed chat I accept (persisted to relay_accepts). */
+    private relayAcceptIds;
+    private messageBus;
+    /** Sender side: chat the hub could not forward, waiting on its recipient. Own disk only. */
+    private chatOutbox;
+    /** Sender side: envelopes awaiting the hub's verdict, keyed by the ref on the outer envelope. */
+    private relayInflight;
+    private outboxFlushing;
+    /** Member side: who tried to reach me while I was away, as a hub told me on reconnect. */
+    private chatPending;
+    /** Member side: when I last received chat from each sender — a notice older than that is stale. */
+    private lastChatFrom;
+    /** Hub side: notices for members who are away. */
+    private relayNotices;
+    /** Brain answers whose asker had gone by the time they were ready — see result-outbox.ts. */
+    private resultOutbox;
+    /** Peers a flush is already running for, so a burst of pings does not send an answer twice. */
+    private flushingResults;
+    /** The polling timers waiting on delegated tasks, so stopping cancels them. */
+    private delegationTimers;
+    /** Relay: inbound connect-requests awaiting my approval (in-memory; keyed by requester id). */
+    private relayRequests;
+    /** Relay: connect-requests I sent that aren't confirmed yet (for the "awaiting" UI hint). */
+    private relayOutgoing;
+    /** Relay: peers that have accepted MY request (in-memory; distinguishes connected vs awaiting). */
+    private relayConfirmed;
+    /** Per-peer human chat logs (in-memory; keyed by peer instanceId). */
+    private chatLog;
+    /** Periodically re-attempts configured peers — self-heals start-order races + drops. */
+    private peerConnectTimer?;
+    /** Periodic chat-session retention prune. */
+    private chatPruneTimer?;
+    /** VoleDrop file transfer engine (net.files). */
+    private files;
+    /** Consent-based pairing: inbound requests awaiting the operator (persisted to pair_requests.json). */
+    private pairRequests;
+    /** Per-IP pair-request timestamps (rate limiting, same shape as publicJoin's). */
+    private pairTimestamps;
+    constructor(config: VoleNetConfig, projectRoot: string);
+    /**
+     * Start VoleNet — load keys, start transport, connect to peers.
+     */
+    start(toolRegistry?: ToolProvider, bus?: EventSink): Promise<void>;
+    /**
+     * Stop VoleNet — disconnect peers, stop transport.
+     */
+    /**
+     * Send one brain answer to the peer that asked for it, and keep it if that fails.
+     *
+     * Failure here is ordinary: thinking takes as long as it takes, and a peer that asked from
+     * a phone is very likely closed by the time there is something to say. Nobody else holds a
+     * copy — the asker has the question and we have the only answer — so it waits, and goes out
+     * the next time that peer speaks to us.
+     */
+    private deliverTaskResult;
+    /**
+     * A peer just spoke to us, so anything we were holding for it can go out now.
+     *
+     * Re-signed rather than replayed: a stored message carries the timestamp it was written
+     * with, and receivers enforce freshness.
+     */
+    private flushResultsFor;
+    stop(): Promise<void>;
+    /**
+     * Get connected instances.
+     */
+    getInstances(): VoleNetInstance[];
+    /** Send a file to a peer (direct or relay-rostered). Async — completion via bus events. */
+    sendFile(peerRef: string, filePath: string, note?: string): Promise<{
+        ok: boolean;
+        transferId?: string;
+        error?: string;
+    }>;
+    acceptFile(transferId: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    rejectFile(transferId: string, reason?: string): Promise<{
+        ok: boolean;
+    }>;
+    cancelFileTransfer(transferId: string): Promise<{
+        ok: boolean;
+    }>;
+    listFileTransfers(): TransferInfo[];
+    getFileTransfer(transferId: string): TransferInfo | undefined;
+    /** Session ID for a peer's human-chat transcript (persisted via paw-session). */
+    private chatSessionId;
+    /**
+     * Append a chat entry for a peer. Persists via paw-session's session_append tool
+     * when available; otherwise falls back to an in-memory log (capped at 200).
+     */
+    private appendChat;
+    /**
+     * Get the human-chat history with a peer. Reads from paw-session when available,
+     * otherwise the in-memory fallback.
+     */
+    getChatHistory(peerId: string): Promise<ChatEntry[]>;
+    /** Clear the human-chat history with a peer (paw-session or in-memory). */
+    clearChat(peerId: string): Promise<void>;
+    /** Clear chat sessions (volenet:*) idle longer than the retention age cap. */
+    private pruneChatSessions;
+    /**
+     * Send a human chat message to a peer. Does NOT invoke any brain.
+     * Resolves the peer by id or name, signs + sends a chat:message, and logs it locally.
+     */
+    sendChat(peerId: string, text: string): Promise<{
+        ok: boolean;
+        delivered?: boolean;
+        relayed?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Find a hub-rostered member by ref, seal an inner message to it, and forward via its hub.
+     * Shared by relayed chat and the consent handshake — the hub sees only ciphertext.
+     */
+    private sealToMemberViaRelay;
+    /**
+     * Seal a chat message to a hub-rostered member, send it via that hub, and wait for the hub's
+     * verdict. Forwarded, or held: when the member is away the message goes to this node's own
+     * outbox and leaves when the member reappears in a roster. A hub too old to give a verdict
+     * is treated the way it always was — the write to the hub counts as the delivery.
+     */
+    private sendChatViaRelay;
+    /**
+     * The hub's verdict on an envelope we sent: forwarded, held because the member is away,
+     * refused — or silence, from a hub too old to give one.
+     */
+    private awaitRelayVerdict;
+    /**
+     * Route a hub's relay:error to the envelope it is about. Older hubs echo no ref, so a verdict
+     * without one settles everything in flight to that member — in practice the one message.
+     */
+    private settleRelay;
+    /**
+     * Send what is waiting for anyone who is back. Runs on every roster update, so a member
+     * reappearing on a hub is what triggers delivery — nothing polls. One message at a time and
+     * in order, so a conversation arrives the way it was written.
+     */
+    private flushChatOutbox;
+    /**
+     * Outbound direct-seal transform. Wraps a message in a sealed:direct envelope when encryption is
+     * enabled and the target peer supports it (announces an ML-KEM key ⟹ 4.12.0+, can unwrap). The
+     * inner message is already signed; the recipient recovers and re-verifies it. Handshake, relay,
+     * and leader types pass through untouched. Never throws — falls back to plaintext on any issue.
+     */
+    private maybeSealDirect;
+    /** Resolve a relay-member ref (id / name / id-prefix) against every hub roster. */
+    private resolveRelayPeer;
+    /** Persist consent to a peer, pinning its roster-vouched key line in relay_accepts. */
+    private persistRelayAccept;
+    /**
+     * Ask a rostered member to accept relay contact. Initiating implies consent to receive its
+     * reply, so the peer is added to my accept list immediately (persisted).
+     */
+    requestRelayConnect(peerRef: string, note?: string): Promise<{
+        ok: boolean;
+        queued?: boolean;
+        error?: string;
+    }>;
+    /**
+     * Consent traffic goes through the same verdict-and-hold path as chat. It used to be
+     * fire-and-forget, so a request to a member who had just locked their phone simply vanished —
+     * and, on the older hub, so did the fact that anything had been sent.
+     */
+    private sendConsentViaRelay;
+    /** Approve an inbound connect-request: consent to the peer, persist it, and notify the peer. */
+    approveRelayConnect(peerRef: string): Promise<{
+        ok: boolean;
+        queued?: boolean;
+        error?: string;
+    }>;
+    /** Deny an inbound connect-request: clear it and (best-effort) tell the peer. */
+    denyRelayConnect(peerRef: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** Withdraw previously-granted relay consent for a peer (removes it from relay_accepts). */
+    revokeRelayConnect(peerRef: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Inbound relay connect-requests awaiting my approval (newest first). */
+    getRelayRequests(): Array<{
+        id: string;
+        name: string;
+        viaHub: string;
+        viaHubName: string;
+        note?: string;
+        ts: number;
+    }>;
+    /** Chat waiting on this node for recipients who are away. Own disk only, never a hub's. */
+    getChatOutbox(): OutboxEntry[];
+    /** Who tried to reach me while I was away, per the hub that told me. Cleared as their messages arrive. */
+    getChatPending(): Array<RelayNotice & {
+        viaHub: string;
+    }>;
+    /** Unseal, verify, and ingest an envelope addressed to us. Allowlist: chat, consent, files. */
+    private deliverSealed;
+    /** True when a relay sender may reach me: '*' policy, an acceptFrom match, or a prior approval. */
+    private isRelayAccepted;
+    /** Record (or refresh) an inbound relay connect-request awaiting my approval. */
+    private recordRelayRequest;
+    private rosterName;
+    private findRosterMember;
+    /** Hub: push the current member directory to every connected member. */
+    private broadcastRoster;
+    /** Hand a member that just reconnected everything the hub noted for it while it was away. */
+    private sendRelayNotices;
+    /** Rosters received from relay hubs (hub instanceId → member directory). */
+    getRosters(): Map<string, Map<string, RosterMember>>;
+    /**
+     * Relay-reachable members from all hub rosters, flattened for the dashboard.
+     * A member we ALSO connect to directly is omitted here — direct trumps relay, the same
+     * precedence sendChat() uses — so the UI never lists one peer in two places.
+     */
+    getRelayMembers(): Array<{
+        id: string;
+        name: string;
+        viaHub: string;
+        viaHubName: string;
+        connected: boolean;
+        /** I accept this member's relayed chat ('*'/acceptFrom match or an approval). */
+        accepted: boolean;
+        /** This member has an inbound connect-request awaiting my approval. */
+        incoming: boolean;
+        /** I've requested this member but it hasn't accepted yet. */
+        awaiting: boolean;
+    }>;
+    /**
+     * Get all remote tools.
+     */
+    getRemoteTools(): RemoteToolInfo[];
+    /**
+     * Find which peer owns a tool.
+     */
+    findToolOwner(toolName: string): {
+        instanceId: string;
+        instance: VoleNetInstance;
+    } | null;
+    /**
+     * Get the remote task manager.
+     */
+    getRemoteTaskManager(): RemoteTaskManager | null;
+    /**
+     * Get the sync manager (for memory/session propagation).
+     */
+    getSync(): VoleNetSync | null;
+    /**
+     * Get the leader election manager.
+     */
+    getLeader(): VoleNetLeader | null;
+    /**
+     * Check if this instance is the VoleNet leader.
+     */
+    isLeader(): boolean;
+    /**
+     * Check if this instance should run heartbeat.
+     * In "independent" mode, every instance runs heartbeat.
+     * In "leader" mode (default), only the leader runs it.
+     */
+    shouldRunHeartbeat(): boolean;
+    /**
+     * Find the best peer for load-balanced task routing.
+     * Returns null if local should handle it (or no peers available).
+     */
+    findLeastLoadedPeer(): VoleNetInstance | null;
+    /**
+     * Check if a task should be forwarded to a peer (overflow mode).
+     * Returns the target peer or null if local should handle it.
+     */
+    shouldForwardTask(currentQueueSize: number): VoleNetInstance | null;
+    /**
+     * Check if this instance should delegate thinking to a remote brain.
+     * Returns the target peer instance ID, or null if local brain should be used.
+     */
+    shouldDelegateBrain(): string | null;
+    /** Handle a public self-join request (HTTP POST /volenet/join). Returns status + JSON body. */
+    handlePublicJoin(body: unknown, ip: string): Promise<{
+        status: number;
+        json: unknown;
+    }>;
+    private pairRequestsPath;
+    private loadPairRequests;
+    private persistPairRequests;
+    /** Handle POST /volenet/pair — queue the introduction; trust NOTHING until acceptPair. */
+    handlePairRequest(body: unknown, ip: string, bus?: EventSink): Promise<{
+        status: number;
+        json: unknown;
+    }>;
+    listPairRequests(): Array<{
+        id: string;
+        name: string;
+        endpoint?: string;
+        note?: string;
+        ts: number;
+    }>;
+    /** Operator consent: trust the requester's pinned key, live-reload, dial back if possible. */
+    acceptPair(ref: string): Promise<{
+        ok: boolean;
+        name?: string;
+        error?: string;
+    }>;
+    denyPair(ref: string): Promise<{
+        ok: boolean;
+    }>;
+    /** Fetch a remote node's identity for the operator to fingerprint before pairing. */
+    probePair(url: string): Promise<{
+        ok: boolean;
+        name?: string;
+        fingerprint?: string;
+        publicKey?: string;
+        alreadyTrusted?: boolean;
+        error?: string;
+    }>;
+    /** Treat a URL as a configured peer and dial it now. The inverse of {@link forgetPeer}. */
+    addPeer(url: string): Promise<void>;
+    /**
+     * Stop treating a URL as a configured peer.
+     *
+     * The reconnect loop re-dials everything in `config.peers` every 15 seconds, so dropping the
+     * socket alone would have it back within a tick. Both halves belong together: forget the entry
+     * and close the connection. Trust is untouched — this says "do not dial", not "do not trust".
+     */
+    forgetPeer(url: string): boolean;
+    /** Record a peer URL in the live config, ask the host to remember it, then dial it. */
+    private addPeerEntry;
+    /**
+     * Dashboard-initiated pairing: trust the probed key (the operator confirmed the
+     * fingerprint client-side), persist + dial the peer, and file the pair request for
+     * the other operator. Fully live — no restart needed on this side.
+     */
+    initiatePair(url: string, publicKey: string, note?: string): Promise<{
+        ok: boolean;
+        pending?: boolean;
+        alreadyTrusted?: boolean;
+        error?: string;
+    }>;
+    /** Dashboard-initiated public-hub join (the vole net join flow, in-process and live). */
+    initiateJoin(url: string): Promise<{
+        ok: boolean;
+        pending?: boolean;
+        hubName?: string;
+        error?: string;
+    }>;
+    /**
+     * Check if a specific peer is allowed to use our brain.
+     */
+    isPeerAllowedBrain(peerId: string): boolean;
+    /**
+     * Whether this peer may call our tools at all — tool/full trust (from net.peers OR a
+     * publicJoin guest's granted trustLevel), or share.tools. Uses getPeerTrust, not
+     * matchPeerConfig, so a publicJoin guest's `trustLevel: "tool"` actually grants tool
+     * access — matching the documented behavior and how isPeerAllowedBrain already works.
+     * (Per-tool curation still applies via share.toolAllow in isPeerAllowedTool.)
+     */
+    private peerToolsEnabled;
+    /** Whether this peer may call a specific tool (honors per-peer allow/deny lists). */
+    isPeerAllowedTool(peerId: string, toolName: string): boolean;
+    /**
+     * Match a connected peer to its config entry.
+     * Matches by port (handles localhost vs real IP) or by instance name.
+     */
+    private matchPeerConfig;
+    /**
+     * Get trust level for a peer.
+     */
+    getPeerTrust(peerId: string): {
+        trust: string;
+        allowTools?: string[];
+        denyTools?: string[];
+        allowBrain?: boolean;
+    } | null;
+    /**
+     * Get the keypair (for CLI display).
+     */
+    /** Our instance name (for message framing). */
+    getInstanceName(): string;
+    getKeyPair(): VoleKeyPair | null;
+    /**
+     * Get the transport (for sending messages).
+     */
+    getTransport(): VoleNetTransport | null;
+    /**
+     * Get the discovery manager.
+     */
+    getDiscovery(): VoleNetDiscovery | null;
+    /**
+     * Check if VoleNet is active.
+     */
+    isActive(): boolean;
+    private getNetDir;
+    private getHostname;
+    private getCapabilities;
+}
+
+/**
+ * Merge the transport-verified caller identity into remote tool params.
+ * Always overwrites any incoming `__caller` — a peer cannot impersonate another instance.
+ * Tools that want attribution declare an optional `__caller` parameter; others ignore it.
+ */
+declare function withVerifiedCaller(params: unknown, instanceId: string, name?: string): Record<string, unknown>;
+/**
+ * The endpoint an instance advertises to peers. An explicit publicUrl wins outright —
+ * set it when VoleNet sits behind a reverse proxy so peers are told the proxy URL
+ * (e.g. "https://club.example.com/mesh") instead of a raw listen port that may be firewalled.
+ */
+declare function buildAdvertisedEndpoint(opts: {
+    publicUrl?: string;
+    tls?: boolean;
+    hostname: string;
+    port: number;
+}): string;
+type PeerEntry = {
+    url: string;
+    trust?: string;
+} & Record<string, unknown>;
+/**
+ * Add a peer URL to a config peers list, REPLACING any existing entry on the same hostname —
+ * re-joining a hub at a new endpoint (a proxied /mesh path instead of a raw :9710 port) must
+ * update the entry, not stack a dead duplicate beside it. The replaced entry's trust and
+ * per-peer settings carry over. Returns the new list plus the URL it replaced, if any.
+ */
+declare function upsertPeerUrl(peers: PeerEntry[], url: string): {
+    peers: PeerEntry[];
+    replaced?: string;
+};
+
+export { CONTROL_PLANE_PAWS, type ChatEntry, ChatOutbox, DEFAULT_NOTICE_TTL_MS, DEFAULT_OUTBOX_TTL_MS, DEFAULT_RESULT_TTL_MS, type EventBus, type EventSink, type LeaderState, type Logger, type LoggerFactory, MAX_RESULTS_PER_PEER, type MemorySearchRequest, type MemorySearchResult, type MemorySyncEntry, type OutboxEntry, type OutboxKind, type PendingResult, type RelayNotice, RelayNotices, RemoteTaskManager, type RemoteTaskRequest, type RemoteTaskResult, type RemoteToolCallRequest, type RemoteToolCallResult, type RemoteToolInfo, ResultOutbox, type RosterMember, type SealedBox, type SessionSyncEntry, type SharedToolDefinition, type SharedToolEntry, type ToolProvider, type VoleKeyPair, type VoleNetConfig, VoleNetDiscovery, type VoleNetInstance, VoleNetLeader, VoleNetManager, type VoleNetMessage, type VoleNetMessageType, VoleNetSync, VoleNetTransport, addRelayAccept, buildAdvertisedEndpoint, closeLogger, createEventBus, createLogger, createMessage, findEndpointDrift, generateKeyPair, isControlPlanePaw, isSharedTool, loadAuthorizedVoles, loadKeyPair, loadRelayAccepts, parsePublicKey, peerPrefix, removeRelayAccept, revokePeer, seal, setLoggerFactory, trustPeer, unseal, upsertPeerUrl, verifyMessage, withVerifiedCaller };