@toon-protocol/client-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,965 @@
+import { NostrEvent } from 'nostr-tools/pure';
+import { SwapPair } from '@toon-protocol/core';
+import { ToonClientConfig } from '@toon-protocol/client';
+import { FastifyInstance } from 'fastify';
+
+/**
+ * Shared request/response contract for the `toon-clientd` localhost control
+ * plane. Both the daemon (server) and the MCP server / control-client (caller)
+ * import these types so the wire shape stays in lockstep.
+ *
+ * Every endpoint is plain JSON over HTTP on `127.0.0.1:<port>`. The daemon owns
+ * the long-lived BTP session + payment channels + relay subscription; callers
+ * are stateless and never see chain keys.
+ */
+
+/** The chain family a paid write settles on. */
+type SettlementChain = 'evm' | 'solana' | 'mina';
+/** Per-chain settlement readiness, mirrored from `ToonClient.getNetworkStatus()`. */
+interface ChainStatus {
+    chain: string;
+    /** Whether settlement is configured + the apex can verify inbound claims. */
+    ready: boolean;
+    detail?: string;
+}
+/** `GET /status` — daemon + connection health. */
+interface StatusResponse {
+    /** Daemon process uptime, ms. */
+    uptimeMs: number;
+    /**
+     * True while the managed anon proxy / BTP session / channel are still coming
+     * up. Tools should surface "bootstrapping — retry" rather than blocking.
+     */
+    bootstrapping: boolean;
+    /** True once the client has started and a channel is open (ready to publish). */
+    ready: boolean;
+    /** The active settlement chain for paid writes to the apex. */
+    settlementChain: SettlementChain;
+    identity: {
+        nostrPubkey: string;
+        evmAddress?: string;
+        solanaAddress?: string;
+        minaAddress?: string;
+    };
+    transport: {
+        type: 'direct' | 'socks5' | 'gateway';
+        socksProxy?: string;
+        btpUrl?: string;
+    };
+    relay: {
+        url: string;
+        connected: boolean;
+        /** Number of events currently held in the read buffer. */
+        buffered: number;
+        /** Active subscription ids. */
+        subscriptions: string[];
+        /**
+         * Error from the daemon-managed read proxy, if any. Set only in the
+         * btp-direct + relay-`.anyone` case where the daemon starts its own `anon`
+         * proxy for reads; a failure here means hidden-service reads are down while
+         * direct paid writes are unaffected.
+         */
+        proxyError?: string;
+    };
+    /** Per-chain settlement status when a named `network` tier is configured. */
+    network?: ChainStatus[];
+    /** Last error observed during bootstrap, if any (non-fatal). */
+    lastError?: string;
+}
+/** `POST /publish` — pay-to-write a single Nostr event. */
+interface PublishRequest {
+    /** A fully-signed Nostr event (id + sig present). */
+    event: NostrEvent;
+    /** ILP destination override (default: the configured apex/town address). */
+    destination?: string;
+    /** Fee override in base units. Defaults to the daemon's configured fee. */
+    fee?: string;
+    /**
+     * Which apex (BTP write target) to publish through. Defaults to the
+     * config-seeded apex. Writes always go through BTP — never to a relay
+     * directly — so this selects among the registered apexes, not relays.
+     */
+    btpUrl?: string;
+}
+interface PublishResponse {
+    eventId: string;
+    /** FULFILL response data (base64), e.g. an Arweave tx id from a DVM. */
+    data?: string;
+    /** Channel the claim was signed against. */
+    channelId: string;
+    /** Channel nonce after this publish (advances by one per paid write). */
+    nonce: number;
+}
+/** `POST /subscribe` — register a persistent free-read subscription. */
+interface SubscribeRequest {
+    /** NIP-01 filter(s). A single object or an array of OR-ed filters. */
+    filters: NostrFilter | NostrFilter[];
+    /** Optional caller-supplied subscription id (else one is generated). */
+    subId?: string;
+    /**
+     * Restrict the subscription to a single relay. Omit to FAN OUT across every
+     * registered relay (the same subId is registered on each); reads merge into
+     * one ordered stream.
+     */
+    relayUrl?: string;
+}
+interface SubscribeResponse {
+    subId: string;
+    /** The relays the subscription was registered on. */
+    relays: string[];
+}
+/** `GET /events` — drain buffered events for a subscription (free read). */
+interface EventsQuery {
+    /** Restrict to a single subscription id. */
+    subId?: string;
+    /** Cursor from a prior `EventsResponse.cursor`; returns only newer events. */
+    cursor?: number;
+    /** Max events to return (default 200). */
+    limit?: number;
+    /** Restrict the drain to events received from a single relay. */
+    relayUrl?: string;
+}
+interface EventsResponse {
+    events: NostrEvent[];
+    /** Opaque monotonic cursor; pass back to fetch only events after these. */
+    cursor: number;
+    /** Whether more events remain beyond `limit`. */
+    hasMore: boolean;
+}
+/** `POST /channels` — open (or return existing) a payment channel. */
+interface OpenChannelRequest {
+    /** ILP destination of the peer to open against (default: configured apex). */
+    destination?: string;
+}
+interface ChannelInfo {
+    channelId: string;
+    nonce: number;
+    cumulativeAmount: string;
+}
+/** `GET /channels` — list tracked channels with nonce watermarks. */
+interface ChannelsResponse {
+    channels: ChannelInfo[];
+}
+/**
+ * `POST /swap` — pay asset A to a mill peer, receive asset B + a signed
+ * target-chain claim. The daemon builds the NIP-59 gift-wrapped kind:20032 swap
+ * rumor and streams it via SDK `streamSwap`, signing the source-asset claim
+ * against the open apex channel (the mill peer must be routed via
+ * `apexChildPeers`).
+ */
+interface SwapRequest {
+    /** Mill peer ILP destination (e.g. `g.townhouse.mill`). */
+    destination: string;
+    /** Total source-asset amount to swap, in source micro-units. */
+    amount: string;
+    /** Mill's 64-char lowercase hex Nostr pubkey (NIP-59 gift-wrap recipient). */
+    millPubkey: string;
+    /**
+     * The swap pair to execute — from kind:10032 discovery, or operator-supplied
+     * when the mill announces pairs to a relay other than the town relay.
+     */
+    pair: SwapPair;
+    /**
+     * Sender's payout address on `pair.to.chain` (EVM 0x-hex / Solana or Mina
+     * base58). Echoed on every rumor as the `chain-recipient` tag.
+     */
+    chainRecipient: string;
+    /** Split the swap into N equal packets (default 1). */
+    packetCount?: number;
+    /**
+     * Which apex to settle the source-asset claim through (default: the
+     * config-seeded apex). The mill must be a child peer of this apex.
+     */
+    btpUrl?: string;
+}
+/** One accumulated, decrypted claim harvested from a single swap packet. */
+interface SwapClaim {
+    /** Source-asset amount sent for this packet (micro-units, decimal). */
+    sourceAmount: string;
+    /** Target-asset amount claimed (micro-units, decimal). */
+    targetAmount: string;
+    /** Decrypted signed target-chain claim bytes, base64. */
+    claim: string;
+    /** Target-chain channel id (real on-chain id, or a dev placeholder). */
+    channelId?: string;
+    /** Sender's payout address echoed by the mill. */
+    recipient?: string;
+    /** Mill's on-chain signer address. */
+    millSignerAddress?: string;
+    /** Mill-side claim id. */
+    claimId?: string;
+    /** Balance-proof nonce on the target channel (decimal). */
+    nonce?: string;
+    /** Cumulative transferred on the target channel (micro-units, decimal). */
+    cumulativeAmount?: string;
+}
+interface SwapResponse {
+    /** True when at least one packet FULFILLed with a usable claim. */
+    accepted: boolean;
+    /** Number of packets the mill FULFILLed. */
+    packetsAccepted: number;
+    /** Per-packet accumulated claims (settlement metadata + signed claim). */
+    claims: SwapClaim[];
+    /** Total source sent across accepted packets (micro-units, decimal). */
+    cumulativeSource: string;
+    /** Total target received across accepted packets (micro-units, decimal). */
+    cumulativeTarget: string;
+    /** Final stream state. */
+    state: 'completed' | 'failed' | 'stopped';
+    /** First rejection code from the mill, if any (e.g. `F99`). */
+    code?: string;
+    /** First rejection message, if any. */
+    message?: string;
+}
+/** `POST /relays` — add a relay READ target (fans into all fan-out reads). */
+interface AddRelayRequest {
+    /** Relay WS URL, e.g. `ws://host:7100` or a `.anyone` hidden service. */
+    relayUrl: string;
+}
+/** `DELETE /relays` — remove a relay read target. */
+interface RemoveRelayRequest {
+    relayUrl: string;
+}
+/**
+ * `POST /apex` — add an apex WRITE target. Settlement params are DISCOVERED by
+ * reading the apex's `kind:10032` announcement off a relay, so the caller never
+ * hand-supplies chain/settlement details.
+ */
+interface AddApexRequest {
+    /** ILP address of the apex to add (e.g. `g.townhouse.town`). */
+    ilpAddress: string;
+    /**
+     * Relay to discover the apex's `kind:10032` on. If it isn't already a read
+     * target it is added (and persisted) first.
+     */
+    relayUrl: string;
+    /** Optional apex Nostr pubkey to narrow the discovery filter (64-char hex). */
+    pubkey?: string;
+    /** Preferred settlement chain family; defaults to the apex's first chain. */
+    chain?: SettlementChain;
+    /** Child peers reached via this apex's channel (e.g. `["dvm","mill"]`). */
+    childPeers?: string[];
+    /** Per-write fee override (base units) for this apex. */
+    feePerEvent?: string;
+}
+interface AddApexResponse {
+    btpUrl: string;
+    destination: string;
+    chain: SettlementChain;
+    /** Whether the apex bootstrapped + opened a channel by the time we replied. */
+    ready: boolean;
+}
+/** `DELETE /apex` — remove an apex write target by its BTP URL. */
+interface RemoveApexRequest {
+    btpUrl: string;
+}
+/** Status of one registered relay read target. */
+interface RelayTargetStatus {
+    relayUrl: string;
+    connected: boolean;
+    buffered: number;
+    subscriptions: string[];
+    /** True for the permanent config-seeded relay (not removable). */
+    isDefault: boolean;
+}
+/** Status of one registered apex write target. */
+interface ApexTargetStatus {
+    btpUrl: string;
+    destination: string;
+    chain: SettlementChain;
+    ready: boolean;
+    bootstrapping: boolean;
+    channelId?: string;
+    lastError?: string;
+    /** True for the permanent config-seeded apex (not removable). */
+    isDefault: boolean;
+}
+/** `GET /targets` — list every registered relay + apex target. */
+interface TargetsResponse {
+    relays: RelayTargetStatus[];
+    apexes: ApexTargetStatus[];
+}
+/** Uniform error envelope returned with non-2xx responses. */
+interface ErrorResponse {
+    error: string;
+    detail?: string;
+    /** True when the caller should retry (e.g. still bootstrapping). */
+    retryable?: boolean;
+}
+/**
+ * NIP-01 subscription filter. Tag filters use `#<single-letter>` keys, e.g.
+ * `{ '#e': [...], '#p': [...] }`.
+ */
+interface NostrFilter {
+    ids?: string[];
+    authors?: string[];
+    kinds?: number[];
+    since?: number;
+    until?: number;
+    limit?: number;
+    search?: string;
+    [tag: `#${string}`]: string[] | undefined;
+}
+
+/**
+ * Thin HTTP client for the `toon-clientd` localhost control plane. Used by the
+ * MCP server (and any other caller) to drive the daemon without holding any
+ * chain keys or long-lived connections itself.
+ */
+
+/** Error thrown when the daemon returns a non-2xx response. */
+declare class ControlApiError extends Error {
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly detail?: string | undefined;
+    constructor(message: string, status: number, retryable: boolean, detail?: string | undefined);
+}
+/** Thrown when the daemon is unreachable (not running / wrong port). */
+declare class DaemonUnreachableError extends Error {
+    readonly baseUrl: string;
+    readonly causedBy?: unknown | undefined;
+    constructor(baseUrl: string, causedBy?: unknown | undefined);
+}
+interface ControlClientOptions {
+    /** Base URL of the daemon, e.g. `http://127.0.0.1:8787`. */
+    baseUrl: string;
+    /** Per-request timeout, ms. Default 35000 (publishes can wait on FULFILL). */
+    timeoutMs?: number;
+    /** Inject a fetch implementation (tests). Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+declare class ControlClient {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(opts: ControlClientOptions);
+    /** True if the daemon answers `GET /status` (used as a liveness probe). */
+    ping(): Promise<boolean>;
+    status(): Promise<StatusResponse>;
+    publish(body: PublishRequest): Promise<PublishResponse>;
+    subscribe(body: SubscribeRequest): Promise<SubscribeResponse>;
+    events(query?: EventsQuery): Promise<EventsResponse>;
+    openChannel(body?: OpenChannelRequest): Promise<{
+        channelId: string;
+    }>;
+    channels(): Promise<ChannelsResponse>;
+    swap(body: SwapRequest): Promise<SwapResponse>;
+    targets(): Promise<TargetsResponse>;
+    addRelay(body: AddRelayRequest): Promise<TargetsResponse>;
+    removeRelay(body: RemoveRelayRequest): Promise<TargetsResponse>;
+    addApex(body: AddApexRequest): Promise<AddApexResponse>;
+    removeApex(body: RemoveApexRequest): Promise<TargetsResponse>;
+    private request;
+}
+
+/**
+ * Persistent town-relay Nostr-WS subscription — the read half of the TOON
+ * client, which `@toon-protocol/client` does not provide (its bootstrap only
+ * issues one-shot WS queries and `DiscoveryTracker` is passive).
+ *
+ * Reads are FREE: this opens a long-lived NIP-01 connection to the town relay,
+ * keeps a bounded ring buffer of received events (de-duplicated by `event.id`),
+ * and lets callers drain new events via a monotonic cursor. It auto-reconnects
+ * with exponential backoff and re-issues every active REQ on reconnect.
+ *
+ * The WebSocket is injectable (`wsFactory`) so unit tests can drive the wire
+ * protocol without a real relay; the default factory uses the `ws` package and,
+ * when a `socks5h://` proxy is configured, routes through it so `.anyone`
+ * hidden-service relays are reachable.
+ */
+
+/** Minimal WebSocket surface this module depends on (subset of `ws`). */
+interface MinimalWebSocket {
+    send(data: string): void;
+    close(): void;
+    on(event: 'open' | 'close', cb: () => void): void;
+    on(event: 'message', cb: (data: unknown) => void): void;
+    on(event: 'error', cb: (err: unknown) => void): void;
+}
+type WebSocketFactory = (url: string) => MinimalWebSocket;
+interface RelaySubscriptionOptions {
+    /** Town relay WS URL, e.g. `wss://<host>.anyone/` or `ws://localhost:7100`. */
+    relayUrl: string;
+    /** Optional `socks5h://host:port` proxy for `.anyone` relays. */
+    socksProxy?: string;
+    /** Max events retained in the ring buffer (oldest evicted). Default 5000. */
+    bufferSize?: number;
+    /** Base reconnect delay, ms. Default 1000. */
+    reconnectBaseMs?: number;
+    /** Max reconnect delay, ms. Default 30000. */
+    reconnectMaxMs?: number;
+    /** Inject a WebSocket factory (tests / proxy customisation). */
+    wsFactory?: WebSocketFactory;
+    /**
+     * Decode an `EVENT` payload that arrived as a string. The TOON relay sends
+     * events TOON-encoded (key/value text) rather than as a JSON object, so the
+     * daemon injects a TOON decoder here. When the payload is already a JSON
+     * object it is used directly and this is not called.
+     */
+    decodeEvent?: (raw: string) => NostrEvent;
+    /**
+     * Invoked once per newly-buffered (de-duplicated) event. The daemon uses this
+     * to feed a runner-level MERGED buffer across many relays — so a fan-out read
+     * (`toon_read` with no relayUrl) draws from one ordered stream with a single
+     * scalar cursor. The relay still keeps its own buffer for `bufferedCount` /
+     * single-relay drains.
+     */
+    onEvent?: (subId: string, event: NostrEvent) => void;
+    /** Optional logger. */
+    logger?: (msg: string) => void;
+}
+/** Result of {@link RelaySubscription.getEvents}. */
+interface DrainResult {
+    events: NostrEvent[];
+    cursor: number;
+    hasMore: boolean;
+}
+declare class RelaySubscription {
+    private readonly relayUrl;
+    private readonly socksProxy?;
+    private readonly bufferSize;
+    private readonly reconnectBaseMs;
+    private readonly reconnectMaxMs;
+    private readonly log;
+    private readonly wsFactory;
+    private readonly decodeEvent?;
+    private readonly onEvent?;
+    /** Active subscriptions: subId -> filters (re-sent on every (re)connect). */
+    private readonly subscriptions;
+    /** Ring buffer of received events, ordered by ascending `seq`. */
+    private buffer;
+    /** De-dup index: event.id -> seq (kept in lockstep with the buffer). */
+    private readonly seen;
+    private seqCounter;
+    private subIdCounter;
+    private ws;
+    private connected;
+    private closing;
+    private reconnectAttempts;
+    private reconnectTimer;
+    constructor(opts: RelaySubscriptionOptions);
+    /** Whether the underlying socket is currently open. */
+    isConnected(): boolean;
+    /** Number of events currently held in the buffer. */
+    bufferedCount(): number;
+    /** Active subscription ids. */
+    activeSubscriptions(): string[];
+    /** Open the connection (idempotent). */
+    start(): void;
+    /**
+     * Register a persistent subscription and (if connected) send the REQ.
+     * Returns the subscription id (caller-supplied or generated).
+     */
+    subscribe(filters: NostrFilter | NostrFilter[], subId?: string): string;
+    /** Cancel a subscription and send CLOSE if connected. */
+    unsubscribe(subId: string): void;
+    /**
+     * Drain events newer than `cursor`. The cursor is the highest `seq` returned;
+     * pass it back to fetch only events received since. Filtering by `subId`
+     * restricts to one subscription.
+     */
+    getEvents(opts?: {
+        subId?: string;
+        cursor?: number;
+        limit?: number;
+    }): DrainResult;
+    /** Close the connection permanently and stop reconnecting. */
+    close(): void;
+    private open;
+    private scheduleReconnect;
+    private sendReq;
+    private sendRaw;
+    private handleMessage;
+    /**
+     * Normalise an `EVENT` payload to a NostrEvent. Standard relays send a JSON
+     * object; the TOON relay sends a TOON-encoded string, decoded via the injected
+     * `decodeEvent`. Returns undefined when it can't be parsed.
+     */
+    private parseEventPayload;
+    private bufferEvent;
+}
+
+/**
+ * Daemon configuration: resolved from a JSON config file and/or environment
+ * variables, then expanded into a `ToonClientConfig` (BTP + channels + signer)
+ * plus daemon-only settings (HTTP port, relay URL, apex negotiation).
+ *
+ * The mnemonic is sourced from (in precedence order):
+ *   1. `TOON_CLIENT_MNEMONIC` env var,
+ *   2. an encrypted keystore (#207) at `keystorePath`, decrypted with
+ *      `TOON_CLIENT_KEYSTORE_PASSWORD`,
+ *   3. the `mnemonic` field of the config file (discouraged — plaintext on disk).
+ */
+
+/** Apex/town settlement parameters injected as a peer negotiation. */
+interface ApexNegotiationConfig {
+    /** ILP destination address, e.g. `g.townhouse.town`. */
+    destination: string;
+    /** Peer id key used in the negotiation map (last ILP segment, e.g. `town`). */
+    peerId: string;
+    /** Settlement chain family. */
+    chain: SettlementChain;
+    /** Negotiated chain key, e.g. `evm:base:84532`. */
+    chainKey: string;
+    /** Numeric chain id (EVM only; 0 for solana/mina). */
+    chainId: number;
+    /** The apex's settlement (receive) address on `chain`. */
+    settlementAddress: string;
+    /** Token contract / mint / zkApp address. */
+    tokenAddress?: string;
+    /** EVM TokenNetwork / Solana programId / Mina zkApp address. */
+    tokenNetwork?: string;
+}
+interface DaemonConfigFile {
+    /** Named network tier (drives settlement presets, #209). */
+    network?: 'mainnet' | 'testnet' | 'devnet' | 'custom';
+    mnemonic?: string;
+    mnemonicAccountIndex?: number;
+    keystorePath?: string;
+    /**
+     * Set when the daemon auto-generated the keystore (#251 first-run onboarding).
+     * Such a keystore is encrypted with a default password so the identity reloads
+     * across restarts without `TOON_CLIENT_KEYSTORE_PASSWORD`. A user-imported
+     * keystore leaves this unset and still requires the env password.
+     */
+    keystoreAutoPassword?: boolean;
+    /** Human-facing onboarding notes written by first-run scaffolding (ignored at runtime). */
+    _help?: Record<string, string>;
+    /** BTP WebSocket URL of the apex/connector. */
+    btpUrl?: string;
+    /** Transport: `direct` or a `socks5h://` proxy for `.anyone` hosts. */
+    socksProxy?: string;
+    /** Auto-manage the anon proxy for `.anyone` BTP hosts. Default true for HS. */
+    managedAnonProxy?: boolean;
+    /** Loopback SOCKS port the managed anon proxy binds (also used for reads). Default 9050. */
+    managedAnonSocksPort?: number;
+    /** Town relay WS URL for FREE reads. */
+    relayUrl?: string;
+    /** Default ILP publish destination. Default `g.townhouse.town`. */
+    destination?: string;
+    /** Default fee per paid write, base units. Default `1`. */
+    feePerEvent?: string;
+    /** Channel nonce-watermark persistence file. Default `<dir>/channels.json`. */
+    channelStorePath?: string;
+    /** Localhost control-plane port. Default 8787. */
+    httpPort?: number;
+    /**
+     * Active settlement chain for paid writes to the apex. A single daemon settles
+     * to a given peer on ONE chain (the `ChannelManager` keys channels per peer +
+     * each `ToonClient` owns one BTP session). Default `evm`. Override with
+     * `TOON_CLIENT_CHAIN`. For simultaneous multi-chain, run one daemon per chain
+     * (distinct `httpPort` + `channelStorePath`).
+     */
+    chain?: SettlementChain;
+    /** Manual apex negotiation (HS / direct-apex mode where bootstrap finds 0 peers). */
+    apex?: ApexNegotiationConfig;
+    /**
+     * Per-chain apex negotiations. The entry for the active `chain` is used; the
+     * others are retained so switching chains needs only a `chain`/restart change.
+     */
+    apexChains?: Partial<Record<SettlementChain, ApexNegotiationConfig>>;
+    /**
+     * Additional apex CHILD peers (last ILP segment, e.g. `["dvm","mill"]`)
+     * reachable via the SAME apex channel — used when publishing/swapping to
+     * `g.townhouse.dvm` / `g.townhouse.mill`. The runner injects the apex
+     * negotiation under each and points it at the open apex channel (no extra
+     * on-chain channel). The apex `peerId` itself is always handled.
+     */
+    apexChildPeers?: string[];
+    /** Extra settlement overrides passed straight through to ToonClient. */
+    supportedChains?: string[];
+    settlementAddresses?: Record<string, string>;
+    preferredTokens?: Record<string, string>;
+    tokenNetworks?: Record<string, string>;
+    chainRpcUrls?: Record<string, string>;
+    /** Solana on-chain payment-channel params (required when `chain` is solana). */
+    solanaChannel?: ToonClientConfig['solanaChannel'];
+    /** Mina on-chain payment-channel params (required when `chain` is mina). */
+    minaChannel?: ToonClientConfig['minaChannel'];
+}
+interface ResolvedDaemonConfig {
+    httpPort: number;
+    relayUrl: string;
+    socksProxy?: string;
+    /**
+     * When true the daemon must start its OWN managed `anon` proxy for free reads
+     * — the btp-direct + relay-`.anyone` case the ToonClient does not cover (it
+     * only auto-starts a proxy for a `.anyone` btpUrl). `readProxySocksPort` is the
+     * loopback port to bind; `socksProxy` already points the relay at it.
+     */
+    manageReadProxy: boolean;
+    /** Loopback SOCKS port for the daemon-managed read proxy (when `manageReadProxy`). */
+    readProxySocksPort?: number;
+    destination: string;
+    feePerEvent: bigint;
+    apex?: ApexNegotiationConfig;
+    /** Apex child peers reached via the same apex channel (e.g. dvm, mill). */
+    apexChildPeers?: string[];
+    /** The active settlement chain for paid writes. */
+    chain: SettlementChain;
+    /** File mapping (destination, chain) → on-chain channelId for restart resume. */
+    apexChannelStorePath: string;
+    /** Fully-built config for the `ToonClient` constructor. */
+    toonClientConfig: ToonClientConfig;
+    network?: string;
+}
+/**
+ * Password used to encrypt an auto-generated keystore (#251 first-run
+ * onboarding) when `TOON_CLIENT_KEYSTORE_PASSWORD` is unset. At-rest
+ * obfuscation only — its purpose is letting the daemon reload the identity
+ * across restarts with no env var. Users wanting a real password re-import the
+ * keystore and set the env var.
+ */
+declare const DEFAULT_KEYSTORE_PASSWORD = "toon-client-default";
+/** Default config directory: `~/.toon-client`. Overridable via env. */
+declare function configDir(): string;
+/** Default config file path. */
+declare function defaultConfigPath(): string;
+/** Read + parse the JSON config file, returning `{}` when absent. */
+declare function readConfigFile(path: string): DaemonConfigFile;
+/** Resolve the mnemonic from env / keystore / config (in precedence order). */
+declare function resolveMnemonic(file: DaemonConfigFile): string;
+/**
+ * Build the full resolved daemon config (file overlaid with env, mnemonic
+ * resolved, ToonClientConfig assembled). Env overrides supported:
+ *   TOON_CLIENT_BTP_URL, TOON_CLIENT_RELAY_URL, TOON_CLIENT_SOCKS,
+ *   TOON_CLIENT_HTTP_PORT, TOON_CLIENT_NETWORK.
+ */
+declare function resolveConfig(file: DaemonConfigFile): ResolvedDaemonConfig;
+
+/**
+ * ClientRunner — the daemon's connection owner. The TOON client is 1-to-MANY:
+ * it can write through several apexes (each a `ToonClient` + BTP session +
+ * payment channel) and read from several relays (each a `RelaySubscription`).
+ *
+ * • Writes go through BTP, never to a relay directly — `publish`/`swap` select
+ *   an apex (default: the config-seeded one).
+ * • Reads FAN OUT — `subscribe`/`getEvents` apply across every relay and merge
+ *   into one ordered stream with a single scalar cursor (the runner owns the
+ *   merged buffer; each `RelaySubscription` mirrors new events into it).
+ *
+ * Targets are added at runtime (`addRelay`/`addApex`), persisted to
+ * `targets.json`, replayed on the next boot, and removable. The config-seeded
+ * relay + apex are the permanent DEFAULT targets and cannot be removed.
+ *
+ * Each apex bootstraps asynchronously and non-blocking: the connection comes up
+ * in the background (the managed anon proxy alone can take 30–90s). Until ready,
+ * writes against it report `bootstrapping` so tools surface "retry".
+ */
+
+/** The subset of `ToonClient` the runner depends on. */
+interface ToonClientLike {
+    start(): Promise<{
+        peersDiscovered: number;
+        mode: string;
+    }>;
+    stop(): Promise<void>;
+    getPublicKey(): string;
+    getEvmAddress(): string | undefined;
+    getSolanaAddress(): string | undefined;
+    getMinaAddress(): string | undefined;
+    getNetworkStatus(): {
+        evm: string;
+        solana: string;
+        mina: string;
+    } | undefined;
+    publishEvent(event: NostrEvent, options?: {
+        destination?: string;
+        claim?: unknown;
+        ilpAmount?: bigint;
+    }): Promise<{
+        success: boolean;
+        eventId?: string;
+        data?: string;
+        error?: string;
+    }>;
+    signBalanceProof(channelId: string, amount: bigint): Promise<unknown>;
+    openChannel(destination?: string): Promise<string>;
+    getTrackedChannels(): string[];
+    getChannelNonce(channelId: string): number;
+    getChannelCumulativeAmount(channelId: string): bigint;
+    sendSwapPacket(params: {
+        destination: string;
+        amount: bigint;
+        toonData: Uint8Array;
+        claim?: unknown;
+    }): Promise<{
+        accepted: boolean;
+        data?: string;
+        code?: string;
+        message?: string;
+    }>;
+}
+/** A started managed proxy: just the teardown handle the runner needs. */
+interface ManagedProxyHandle {
+    stop(): Promise<void>;
+}
+/** Starts a managed `anon` read proxy on a loopback SOCKS port. */
+type StartReadProxy = (opts: {
+    socksPort: number;
+    log?: (msg: string) => void;
+}) => Promise<ManagedProxyHandle>;
+/** Builds a `ToonClient` (or a fake) for a given resolved client config. */
+type CreateClient = (config: ToonClientConfig) => ToonClientLike;
+/** Builds a `RelaySubscription` for a given relay URL + optional read proxy. */
+type CreateRelay = (opts: {
+    relayUrl: string;
+    socksProxy?: string;
+    onEvent: (subId: string, event: NostrEvent) => void;
+    logger?: (msg: string) => void;
+}) => RelaySubscription;
+interface ClientRunnerDeps {
+    config: ResolvedDaemonConfig;
+    /** Factory producing the (real or fake) ToonClient for a client config. */
+    createClient: CreateClient;
+    /** Factory producing a relay subscription (defaults to the real one). */
+    createRelay?: CreateRelay;
+    /**
+     * Starts the daemon-managed read proxy (defaults to the real
+     * `startManagedAnonProxy`). Injected so tests avoid the anon download/spawn.
+     */
+    startReadProxy?: StartReadProxy;
+    logger?: (msg: string) => void;
+    /** Path to the dynamic-targets store (tests override). */
+    targetsPath?: string;
+}
+declare class ClientRunner {
+    private readonly config;
+    private readonly createClient;
+    private readonly createRelay;
+    private readonly startReadProxy;
+    private readonly log;
+    private readonly targetsPath?;
+    private readonly startedAt;
+    /** Apex write targets, keyed by btpUrl. */
+    private readonly apexes;
+    /** Relay read targets, keyed by relayUrl. */
+    private readonly relays;
+    /** Runner-level merged read buffer across all relays (de-duped by event.id). */
+    private merged;
+    private readonly mergedSeen;
+    private mergedSeq;
+    /**
+     * Fan-out subscriptions (no relayUrl restriction): replayed onto relays added
+     * later so a new relay immediately participates in existing reads.
+     */
+    private readonly fanoutSubs;
+    private subIdCounter;
+    private readonly defaultBtpUrl;
+    private readonly defaultRelayUrl;
+    /** Teardown for the daemon-managed read proxy (btp-direct + relay-`.anyone`). */
+    private stopReadProxy;
+    private readProxyError;
+    private stopped;
+    private started;
+    constructor(deps: ClientRunnerDeps);
+    /**
+     * Start the live connections: the shared read proxy, every relay socket, the
+     * default apex bootstrap (non-blocking), then replay persisted dynamic
+     * targets. Returns immediately; apexes become ready asynchronously.
+     */
+    start(): void;
+    /** Await the default apex's bootstrap (kicking it off if not already running). */
+    bootstrap(): Promise<void>;
+    /**
+     * Build + register a relay (idempotent by URL), wiring its events into the
+     * merged buffer and replaying active fan-out subscriptions. Does NOT start the
+     * socket — callers start it (so construction stays side-effect-free for tests).
+     */
+    private registerRelay;
+    /**
+     * Add a relay read target at runtime. `.anyone` relays reuse the managed read
+     * proxy (started here if needed). Persisted unless `persist` is false.
+     */
+    addRelay(relayUrl: string, persist?: boolean): Promise<void>;
+    /** Remove a relay read target. The config-seeded default cannot be removed. */
+    removeRelay(relayUrl: string): void;
+    /** Mirror a newly-buffered relay event into the merged cross-relay buffer. */
+    private pushMerged;
+    /**
+     * Register a free-read subscription. With no `relayUrl` it FANS OUT across
+     * every relay (and onto relays added later); with one it targets that relay.
+     */
+    subscribe(req: SubscribeRequest): SubscribeResponse;
+    /** Drain merged events newer than the cursor (free read), optionally scoped. */
+    getEvents(query: EventsQuery): EventsResponse;
+    private makeApex;
+    /**
+     * Bootstrap one apex (memoized): start, inject negotiation, open/resume the
+     * channel, route child peers. Concurrent callers await the same in-flight
+     * work rather than re-running it.
+     */
+    private bootstrapApex;
+    private doBootstrapApex;
+    /**
+     * Add an apex write target. Settlement params are discovered by reading the
+     * apex's kind:10032 off the given relay (added first if unknown). Persisted.
+     */
+    addApex(req: AddApexRequest): Promise<AddApexResponse>;
+    /** Build + register + bootstrap an apex from a (persisted) target record. */
+    private instantiateApex;
+    /** Remove an apex write target. The config-seeded default cannot be removed. */
+    removeApex(btpUrl: string): Promise<void>;
+    /** Derive a per-apex ToonClientConfig from the default (shared identity/transport). */
+    private deriveApexClientConfig;
+    private apexChannelStorePathFor;
+    private replayPersistedTargets;
+    private ensureReadProxy;
+    private bringUpReadProxy;
+    /** Open the apex channel — or, on a restart, RESUME the existing one. */
+    private openOrResumeApexChannel;
+    /** Inject the apex settlement negotiation directly into its ToonClient. */
+    private injectApexNegotiation;
+    /** Route apex CHILD peers (dvm/mill) through the SAME apex payment channel. */
+    private routeChildPeersThroughApexChannel;
+    private defaultApex;
+    /** Whether any apex has finished bootstrapping. */
+    isReady(): boolean;
+    isBootstrapping(): boolean;
+    getStatus(): StatusResponse;
+    /** Full registry of relay + apex targets with per-target status. */
+    getTargets(): TargetsResponse;
+    /** Pay-to-write a single event through the selected (or default) apex. */
+    publish(req: PublishRequest): Promise<PublishResponse>;
+    /** Open (or return) a payment channel on the selected (or default) apex. */
+    openChannel(destination?: string, btpUrl?: string): Promise<{
+        channelId: string;
+    }>;
+    /** List tracked channels across ALL apexes with nonce + cumulative amount. */
+    getChannels(): ChannelsResponse;
+    /** Swap source→target asset against a mill peer via the selected apex. */
+    swap(req: SwapRequest): Promise<SwapResponse>;
+    /** Graceful teardown: close every relay + stop every apex client + read proxy. */
+    stop(): Promise<void>;
+    private selectApex;
+    private assertApexReady;
+}
+/** Thrown by paid-write operations while the target apex is not yet ready. */
+declare class NotReadyError extends Error {
+    readonly retryable = true;
+    constructor(message: string);
+}
+/** Thrown when the relay/connector rejects a paid write. */
+declare class PublishRejectedError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * First-run onboarding for `toon-clientd`.
+ *
+ * A brand-new user (`npx`/plugin install) has no identity and no config file.
+ * Before the daemon resolves its config it calls {@link scaffoldFirstRun},
+ * which makes a fresh install start with zero manual setup:
+ *
+ *   1. **Identity** — if no mnemonic source is configured (no
+ *      `TOON_CLIENT_MNEMONIC`, no `keystorePath`, no `mnemonic`), generate a
+ *      fresh BIP-39 mnemonic, encrypt it to `~/.toon-client/keystore.json`, and
+ *      record `keystorePath` (+ `keystoreAutoPassword`) in `config.json`. The
+ *      keystore is encrypted with `TOON_CLIENT_KEYSTORE_PASSWORD` when set, else
+ *      a default password so the identity survives restarts with no env var.
+ *      The mnemonic + derived addresses are printed ONCE for backup.
+ *   2. **Transport scaffolding** — ensure `config.json` carries the transport
+ *      knobs (`btpUrl`/`relayUrl`/`managedAnonProxy`) plus a `_help` block
+ *      documenting direct-vs-`.anyone` selection, so the user can see what to
+ *      point at.
+ *
+ * This is all idempotent: on later runs an identity already exists, so nothing
+ * is regenerated and the config is left untouched.
+ */
+
+/** Default keystore path: `~/.toon-client/keystore.json`. */
+declare function defaultKeystorePath(): string;
+/**
+ * True when SOME mnemonic source is already configured: the env var, a keystore
+ * path, or an inline mnemonic. When false the daemon would otherwise hard-fail
+ * with "No mnemonic configured".
+ */
+declare function hasConfiguredIdentity(file: DaemonConfigFile): boolean;
+interface ScaffoldOptions {
+    /** Config file path (defaults to `TOON_CLIENT_CONFIG` / `~/.toon-client/config.json`). */
+    configPath?: string;
+    /** Log sink (defaults to stderr, since stdout may carry MCP/JSON). */
+    log?: (msg: string) => void;
+}
+/**
+ * Generate + persist an identity and/or scaffold transport config on first run.
+ * Safe to call on every startup — it only acts when something is missing.
+ */
+declare function scaffoldFirstRun(opts?: ScaffoldOptions): Promise<void>;
+
+/**
+ * Fastify route registration for the `toon-clientd` control plane. Each route
+ * is a thin adapter: parse/validate the request, call the `ClientRunner`, map
+ * errors to the uniform `ErrorResponse` envelope.
+ *
+ * Bound to loopback only by the daemon entry — there is no auth layer because
+ * the surface never leaves `127.0.0.1`.
+ */
+
+declare function registerRoutes(app: FastifyInstance, runner: ClientRunner): void;
+
+/** Whether a process with `pid` is currently alive. */
+declare function isProcessAlive(pid: number): boolean;
+/** Read the recorded daemon PID, or null when absent/invalid. */
+declare function readPid(path?: string): number | null;
+/**
+ * Acquire the single-instance lock for the current process. Throws if another
+ * live daemon already holds it. Reclaims a stale lock (dead PID).
+ */
+declare function acquireLock(path?: string): void;
+/** Release the lock if it belongs to this process. */
+declare function releaseLock(path?: string): void;
+/** Whether a daemon is currently running per the PID lock. */
+declare function isDaemonRunning(path?: string): boolean;
+interface SpawnDaemonOptions {
+    /** Path to the `toon-clientd` bin (defaults to this package's daemon entry). */
+    daemonEntry?: string;
+    /** Extra env for the spawned process. */
+    env?: NodeJS.ProcessEnv;
+    /** Directory for the detached stdout/stderr log. */
+    logDir?: string;
+}
+/**
+ * Spawn the daemon as a detached, fully background process (survives the
+ * parent — e.g. the ephemeral MCP/agent session — exiting). Returns the child
+ * PID. The caller should poll {@link waitForReady} before issuing requests.
+ */
+declare function spawnDaemonDetached(opts?: SpawnDaemonOptions): number;
+/**
+ * Poll the control plane until the daemon answers `GET /status`, up to
+ * `timeoutMs`. Resolves true once reachable (NOT necessarily done
+ * bootstrapping — anon can take 30–90s; callers surface `bootstrapping`).
+ */
+declare function waitForReady(baseUrl: string, timeoutMs?: number, intervalMs?: number): Promise<boolean>;
+
+/**
+ * MCP tool definitions + dispatch. The MCP server is a thin proxy: each tool
+ * maps to a `toon-clientd` control-plane call. This module is the testable core
+ * (no stdio / SDK transport) so the tool→HTTP mapping and the
+ * "bootstrapping — retry" handling can be unit-tested directly.
+ */
+
+/** A JSON-Schema-described MCP tool. */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+/** MCP tool-call result shape (subset of the SDK's CallToolResult). */
+interface ToolResult {
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+    isError?: boolean;
+}
+declare const TOOL_DEFINITIONS: ToolDefinition[];
+/**
+ * Dispatch an MCP tool call to the daemon control plane. Always resolves with a
+ * `ToolResult` (errors are encoded as `isError: true` text, not thrown, so the
+ * agent sees a readable message). A retryable error (daemon still
+ * bootstrapping) yields a clear "retry shortly" message.
+ */
+declare function dispatchTool(client: ControlClient, name: string, args: Record<string, unknown>): Promise<ToolResult>;
+
+export { type AddApexRequest, type AddApexResponse, type AddRelayRequest, type ApexNegotiationConfig, type ApexTargetStatus, type ChainStatus, type ChannelInfo, type ChannelsResponse, ClientRunner, type ClientRunnerDeps, ControlApiError, ControlClient, type ControlClientOptions, DEFAULT_KEYSTORE_PASSWORD, type DaemonConfigFile, DaemonUnreachableError, type DrainResult, type ErrorResponse, type EventsQuery, type EventsResponse, type MinimalWebSocket, type NostrFilter, NotReadyError, type OpenChannelRequest, PublishRejectedError, type PublishRequest, type PublishResponse, RelaySubscription, type RelaySubscriptionOptions, type RelayTargetStatus, type RemoveApexRequest, type RemoveRelayRequest, type ResolvedDaemonConfig, type SettlementChain, type StatusResponse, type SubscribeRequest, type SubscribeResponse, type SwapClaim, type SwapRequest, type SwapResponse, TOOL_DEFINITIONS, type TargetsResponse, type ToolDefinition, type ToolResult, type ToonClientLike, type WebSocketFactory, acquireLock, configDir, defaultConfigPath, defaultKeystorePath, dispatchTool, hasConfiguredIdentity, isDaemonRunning, isProcessAlive, readConfigFile, readPid, registerRoutes, releaseLock, resolveConfig, resolveMnemonic, scaffoldFirstRun, spawnDaemonDetached, waitForReady };