@toon-protocol/client-mcp 0.31.1 → 0.32.0

package/dist/index.d.ts

@@ -53,6 +53,13 @@ interface StatusResponse {
         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[];
@@ -67,6 +74,12 @@ interface PublishRequest {
     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;
@@ -83,9 +96,17 @@ interface SubscribeRequest {
     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 {
@@ -95,6 +116,8 @@ interface EventsQuery {
     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[];
@@ -143,6 +166,11 @@ interface SwapRequest {
     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 {
@@ -183,6 +211,74 @@ interface SwapResponse {
     /** 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;
@@ -248,6 +344,11 @@ declare class ControlClient {
     }>;
     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;
 }
 
@@ -296,6 +397,14 @@ interface RelaySubscriptionOptions {
      * 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;
 }
@@ -314,6 +423,7 @@ declare class RelaySubscription {
     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`. */
@@ -406,6 +516,15 @@ interface DaemonConfigFile {
     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. */
@@ -462,6 +581,15 @@ 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;
@@ -475,6 +603,14 @@ interface ResolvedDaemonConfig {
     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. */
@@ -492,18 +628,23 @@ declare function resolveMnemonic(file: DaemonConfigFile): string;
 declare function resolveConfig(file: DaemonConfigFile): ResolvedDaemonConfig;
 
 /**
- * ClientRunner — the daemon's connection owner. Wraps a single `ToonClient`
- * (BTP session + payment channels + signer) plus a persistent
- * `RelaySubscription` (free reads), and exposes the high-level operations the
- * HTTP routes map onto.
+ * 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`).
  *
- * Bootstrap is asynchronous and non-blocking: `start()` returns immediately and
- * the connection comes up in the background (the managed anon proxy alone can
- * take 30–90s). Until it is ready, write operations report `bootstrapping` so
- * tools surface "retry" rather than hang.
+ * • 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).
  *
- * The `ToonClient` is injected via `ToonClientLike` so unit tests can drive the
- * runner with a fake — no BTP/anon/on-chain dependency.
+ * 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. */
@@ -549,98 +690,151 @@ interface ToonClientLike {
         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. */
-    createClient: () => ToonClientLike;
-    /** Factory producing the relay subscription (defaults to the real one). */
-    createRelay?: () => RelaySubscription;
+    /** 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 client;
-    private readonly relay;
+    private readonly createClient;
+    private readonly createRelay;
+    private readonly startReadProxy;
     private readonly log;
+    private readonly targetsPath?;
     private readonly startedAt;
-    private bootstrapping;
-    private ready;
-    private lastError;
-    /** Channel opened against the default apex destination. */
-    private apexChannelId;
+    /** 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);
     /**
-     * Begin bootstrapping in the background. Resolves once kicked off; the
-     * connection becomes ready asynchronously. Awaitable for tests via the
-     * returned promise of the underlying work.
+     * 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;
-    /** The background bootstrap routine (exposed for awaiting in tests). */
+    /** Await the default apex's bootstrap (kicking it off if not already running). */
     bootstrap(): Promise<void>;
     /**
-     * Open the apex channel — or, on a restart, RESUME the existing one.
-     *
-     * `ChannelManager` persists the nonce watermark (by channelId) but not the
-     * peer→channelId mapping, so a naive `openChannel()` after restart re-deposits
-     * into a fresh channel and reverts on-chain. We persist the channelId here and,
-     * when present, `trackChannel()` the live channel (which rehydrates the nonce
-     * from the channel store) — no on-chain write, watermark continues.
+     * 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 openOrResumeApexChannel;
+    private registerRelay;
     /**
-     * Inject the apex settlement negotiation directly into the ToonClient when
-     * configured. Required for HS / direct-apex mode where bootstrap discovers 0
-     * peers (no relay-based discovery). Mirrors the docker entrypoint's approach.
+     * Add a relay read target at runtime. `.anyone` relays reuse the managed read
+     * proxy (started here if needed). Persisted unless `persist` is false.
      */
-    private injectApexNegotiation;
+    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;
     /**
-     * Route additional apex CHILD peers (e.g. `dvm`, `mill`) through the SAME
-     * apex payment channel. In the parent→child apex model the client holds ONE
-     * channel with the apex (g.townhouse) and pays via it regardless of which
-     * child the ILP destination addresses; but `ToonClient.resolvePeerId` keys off
-     * the destination's last segment (`town`/`dvm`/`mill`), so without this each
-     * child would (a) fail the "no negotiation for peer" guard and (b) try to open
-     * a SECOND on-chain channel to the same apex receive (which reverts —
-     * channel-exists). So: inject the same apex negotiation under each child peer
-     * AND pre-map its peer→channel to the already-open apex channel so
-     * `ensureChannel` reuses it (no second open; one shared nonce sequence).
+     * 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;
-    /** Pay-to-write a single event. Throws NOT_READY while bootstrapping. */
+    /** 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>;
-    /** Register a free-read subscription (does not require the paid path). */
-    subscribe(req: SubscribeRequest): SubscribeResponse;
-    /** Drain buffered events newer than the cursor (free read). */
-    getEvents(query: EventsQuery): EventsResponse;
-    /** Open (or return) a payment channel for a destination. */
-    openChannel(destination?: string): Promise<{
+    /** Open (or return) a payment channel on the selected (or default) apex. */
+    openChannel(destination?: string, btpUrl?: string): Promise<{
         channelId: string;
     }>;
-    /** List tracked channels with their nonce watermark + cumulative amount. */
+    /** List tracked channels across ALL apexes with nonce + cumulative amount. */
     getChannels(): ChannelsResponse;
-    /**
-     * Swap source asset → target asset against a mill peer.
-     *
-     * Uses SDK `streamSwap`, which builds a NIP-59 gift-wrapped kind:20032 swap
-     * rumor per packet and sends it over the open BTP session. The source-asset
-     * balance proof is signed by the ToonClient's ChannelManager against the apex
-     * channel — so the mill peer MUST be routed via `apexChildPeers` (otherwise
-     * there is no channel to sign against and the mill rejects with F99).
-     *
-     * A fresh ephemeral gift-wrap key is generated per swap (used for sealing the
-     * rumor AND decrypting the FULFILL claims) — independent of the daemon's
-     * settlement identity, so callers never need to expose a key.
-     */
+    /** Swap source→target asset against a mill peer via the selected apex. */
     swap(req: SwapRequest): Promise<SwapResponse>;
-    /** Graceful teardown of the relay subscription + ToonClient. */
+    /** Graceful teardown: close every relay + stop every apex client + read proxy. */
     stop(): Promise<void>;
-    private assertReady;
+    private selectApex;
+    private assertApexReady;
 }
-/** Thrown by paid-write operations while the daemon is not yet ready. */
+/** Thrown by paid-write operations while the target apex is not yet ready. */
 declare class NotReadyError extends Error {
     readonly retryable = true;
     constructor(message: string);
@@ -650,6 +844,49 @@ 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
@@ -725,4 +962,4 @@ declare const TOOL_DEFINITIONS: ToolDefinition[];
  */
 declare function dispatchTool(client: ControlClient, name: string, args: Record<string, unknown>): Promise<ToolResult>;
 
-export { type ApexNegotiationConfig, type ChainStatus, type ChannelInfo, type ChannelsResponse, ClientRunner, type ClientRunnerDeps, ControlApiError, ControlClient, type ControlClientOptions, 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 ResolvedDaemonConfig, type SettlementChain, type StatusResponse, type SubscribeRequest, type SubscribeResponse, type SwapClaim, type SwapRequest, type SwapResponse, TOOL_DEFINITIONS, type ToolDefinition, type ToolResult, type ToonClientLike, type WebSocketFactory, acquireLock, configDir, defaultConfigPath, dispatchTool, isDaemonRunning, isProcessAlive, readConfigFile, readPid, registerRoutes, releaseLock, resolveConfig, resolveMnemonic, spawnDaemonDetached, waitForReady };
+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 };

package/dist/index.js

@@ -4,15 +4,19 @@ import {
   NotReadyError,
   PublishRejectedError,
   RelaySubscription,
-  registerRoutes
-} from "./chunk-SECSBCDA.js";
+  defaultKeystorePath,
+  hasConfiguredIdentity,
+  registerRoutes,
+  scaffoldFirstRun
+} from "./chunk-AYZWVPNQ.js";
 import {
   TOOL_DEFINITIONS,
   dispatchTool
-} from "./chunk-JOGMX4IT.js";
+} from "./chunk-CPVOJ7FE.js";
 import {
   ControlApiError,
   ControlClient,
+  DEFAULT_KEYSTORE_PASSWORD,
   DaemonUnreachableError,
   acquireLock,
   configDir,
@@ -26,7 +30,7 @@ import {
   resolveMnemonic,
   spawnDaemonDetached,
   waitForReady
-} from "./chunk-MI2IWKHX.js";
+} from "./chunk-ALMTQYYJ.js";
 import "./chunk-32QD72IL.js";
 import "./chunk-QTDCFXPF.js";
 import "./chunk-LR7W2ISE.js";
@@ -37,6 +41,7 @@ export {
   ClientRunner,
   ControlApiError,
   ControlClient,
+  DEFAULT_KEYSTORE_PASSWORD,
   DaemonUnreachableError,
   NotReadyError,
   PublishRejectedError,
@@ -45,7 +50,9 @@ export {
   acquireLock,
   configDir,
   defaultConfigPath,
+  defaultKeystorePath,
   dispatchTool,
+  hasConfiguredIdentity,
   isDaemonRunning,
   isProcessAlive,
   readConfigFile,
@@ -54,6 +61,7 @@ export {
   releaseLock,
   resolveConfig,
   resolveMnemonic,
+  scaffoldFirstRun,
   spawnDaemonDetached,
   waitForReady
 };

package/dist/mcp.js

@@ -3,7 +3,7 @@ import { createRequire as __cr } from 'module'; const require = __cr(import.meta
 import {
   TOOL_DEFINITIONS,
   dispatchTool
-} from "./chunk-JOGMX4IT.js";
+} from "./chunk-CPVOJ7FE.js";
 import {
   ControlClient,
   defaultConfigPath,
@@ -11,7 +11,7 @@ import {
   readConfigFile,
   spawnDaemonDetached,
   waitForReady
-} from "./chunk-MI2IWKHX.js";
+} from "./chunk-ALMTQYYJ.js";
 import "./chunk-32QD72IL.js";
 import "./chunk-QTDCFXPF.js";
 import "./chunk-LR7W2ISE.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toon-protocol/client-mcp",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "Always-on local daemon + MCP server letting a Claude agent (Desktop or Code) act as a TOON Protocol client: pay-to-write publishing, free reads, channel/balance management, and mill swaps.",
   "license": "MIT",
   "author": "Jonathan Green",
@@ -45,8 +45,8 @@
     "typescript": "^5.3.0",
     "vitest": "^1.0.0",
     "@toon-protocol/client": "0.9.1",
-    "@toon-protocol/sdk": "0.5.0",
-    "@toon-protocol/core": "1.4.1"
+    "@toon-protocol/core": "1.4.1",
+    "@toon-protocol/sdk": "0.5.0"
   },
   "engines": {
     "node": ">=20"

package/dist/chunk-JOGMX4IT.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/mcp-tools.ts"],"sourcesContent":["/**\n * MCP tool definitions + dispatch. The MCP server is a thin proxy: each tool\n * maps to a `toon-clientd` control-plane call. This module is the testable core\n * (no stdio / SDK transport) so the tool→HTTP mapping and the\n * \"bootstrapping — retry\" handling can be unit-tested directly.\n */\n\nimport { ControlApiError, DaemonUnreachableError } from './control-client.js';\nimport type { ControlClient } from './control-client.js';\nimport type {\n  NostrFilter,\n  PublishRequest,\n  SwapRequest,\n} from './control-api.js';\n\n/** A JSON-Schema-described MCP tool. */\nexport interface ToolDefinition {\n  name: string;\n  description: string;\n  inputSchema: Record<string, unknown>;\n}\n\n/** MCP tool-call result shape (subset of the SDK's CallToolResult). */\nexport interface ToolResult {\n  content: { type: 'text'; text: string }[];\n  isError?: boolean;\n}\n\nexport const TOOL_DEFINITIONS: ToolDefinition[] = [\n  {\n    name: 'toon_status',\n    description:\n      'Report TOON client daemon health: bootstrapping/ready state, transport, ' +\n      'relay connection, buffered-event count, and per-chain settlement status.',\n    inputSchema: {\n      type: 'object',\n      properties: {},\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'toon_identity',\n    description:\n      \"Return this client's public identity (Nostr pubkey + EVM/Solana/Mina \" +\n      'addresses). Never returns private keys.',\n    inputSchema: {\n      type: 'object',\n      properties: {},\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'toon_publish',\n    description:\n      'Pay-to-write: publish a fully-signed Nostr event to the TOON network. ' +\n      'Signs an off-chain payment-channel claim and forwards it over BTP. ' +\n      'Returns the event id, channel id, and the advanced channel nonce.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        event: {\n          type: 'object',\n          description:\n            'A fully-signed Nostr event (must include id, pubkey, sig, kind, ' +\n            'created_at, tags, content).',\n        },\n        destination: {\n          type: 'string',\n          description:\n            'Optional ILP destination override (default: the apex/town).',\n        },\n        fee: {\n          type: 'string',\n          description:\n            'Optional fee override in base units (default: daemon config).',\n        },\n      },\n      required: ['event'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'toon_subscribe',\n    description:\n      'Free read: register a persistent town-relay subscription with NIP-01 ' +\n      'filter(s). Returns a subscription id to drain with toon_read.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        filters: {\n          description: 'A NIP-01 filter object or an array of OR-ed filters.',\n        },\n        subId: { type: 'string', description: 'Optional caller-supplied id.' },\n      },\n      required: ['filters'],\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'toon_read',\n    description:\n      'Free read: drain buffered events newer than a cursor. Pass back the ' +\n      'returned cursor to fetch only events received since the last read.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        subId: { type: 'string', description: 'Restrict to one subscription.' },\n        cursor: {\n          type: 'number',\n          description: 'Cursor from a prior toon_read.',\n        },\n        limit: {\n          type: 'number',\n          description: 'Max events to return (default 200).',\n        },\n      },\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'toon_open_channel',\n    description:\n      'Open (or return the existing) payment channel for a destination. ' +\n      'Channels open lazily on first publish; use this to pre-open.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        destination: {\n          type: 'string',\n          description: 'ILP destination (default: apex).',\n        },\n      },\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'toon_channels',\n    description:\n      'List tracked payment channels with their nonce watermark and cumulative ' +\n      'transferred amount.',\n    inputSchema: {\n      type: 'object',\n      properties: {},\n      additionalProperties: false,\n    },\n  },\n  {\n    name: 'toon_swap',\n    description:\n      'Pay a mill peer (asset A) to receive asset B plus a signed target-chain ' +\n      'claim. Builds the NIP-59 gift-wrapped kind:20032 swap rumor and streams ' +\n      'it; the source-asset claim is signed against the open apex channel (the ' +\n      'mill must be routed via apexChildPeers). Returns the accumulated, ' +\n      'decrypted target-chain claim(s) and settlement metadata.',\n    inputSchema: {\n      type: 'object',\n      properties: {\n        destination: {\n          type: 'string',\n          description: 'Mill peer ILP destination (e.g. g.townhouse.mill).',\n        },\n        amount: {\n          type: 'string',\n          description: 'Total source-asset amount to swap, source micro-units.',\n        },\n        millPubkey: {\n          type: 'string',\n          description:\n            \"Mill's 64-char lowercase hex Nostr pubkey (gift-wrap recipient).\",\n        },\n        pair: {\n          type: 'object',\n          description:\n            'The swap pair (from kind:10032 discovery or operator-supplied): ' +\n            '{ from:{assetCode,assetScale,chain}, to:{...}, rate, minAmount?, maxAmount? }.',\n        },\n        chainRecipient: {\n          type: 'string',\n          description:\n            \"Sender's payout address on pair.to.chain (EVM 0x-hex / Solana / Mina base58).\",\n        },\n        packetCount: {\n          type: 'number',\n          description: 'Split the swap into N equal packets (default 1).',\n        },\n      },\n      required: [\n        'destination',\n        'amount',\n        'millPubkey',\n        'pair',\n        'chainRecipient',\n      ],\n      additionalProperties: false,\n    },\n  },\n];\n\n/**\n * Dispatch an MCP tool call to the daemon control plane. Always resolves with a\n * `ToolResult` (errors are encoded as `isError: true` text, not thrown, so the\n * agent sees a readable message). A retryable error (daemon still\n * bootstrapping) yields a clear \"retry shortly\" message.\n */\nexport async function dispatchTool(\n  client: ControlClient,\n  name: string,\n  args: Record<string, unknown>\n): Promise<ToolResult> {\n  try {\n    switch (name) {\n      case 'toon_status':\n        return ok(await client.status());\n      case 'toon_identity': {\n        const s = await client.status();\n        return ok({\n          identity: s.identity,\n          ready: s.ready,\n          bootstrapping: s.bootstrapping,\n        });\n      }\n      case 'toon_publish':\n        return ok(await client.publish(args as unknown as PublishRequest));\n      case 'toon_subscribe':\n        return ok(\n          await client.subscribe({\n            filters: args['filters'] as NostrFilter | NostrFilter[],\n            ...(typeof args['subId'] === 'string'\n              ? { subId: args['subId'] }\n              : {}),\n          })\n        );\n      case 'toon_read':\n        return ok(\n          await client.events({\n            ...(typeof args['subId'] === 'string'\n              ? { subId: args['subId'] }\n              : {}),\n            ...(typeof args['cursor'] === 'number'\n              ? { cursor: args['cursor'] }\n              : {}),\n            ...(typeof args['limit'] === 'number'\n              ? { limit: args['limit'] }\n              : {}),\n          })\n        );\n      case 'toon_open_channel':\n        return ok(\n          await client.openChannel(\n            typeof args['destination'] === 'string'\n              ? { destination: args['destination'] }\n              : {}\n          )\n        );\n      case 'toon_channels':\n        return ok(await client.channels());\n      case 'toon_swap':\n        return ok(\n          await client.swap({\n            destination: String(args['destination']),\n            amount: String(args['amount']),\n            millPubkey: String(args['millPubkey']),\n            pair: args['pair'] as SwapRequest['pair'],\n            chainRecipient: String(args['chainRecipient']),\n            ...(typeof args['packetCount'] === 'number'\n              ? { packetCount: args['packetCount'] }\n              : {}),\n          })\n        );\n      default:\n        return err(`Unknown tool: ${name}`);\n    }\n  } catch (e) {\n    if (e instanceof ControlApiError && e.retryable) {\n      return err(\n        `TOON client is still bootstrapping (the anon proxy / BTP session can take ` +\n          `30–90s) — retry shortly. (${e.message})`\n      );\n    }\n    if (e instanceof DaemonUnreachableError) {\n      return err(\n        `TOON client daemon is not reachable at ${e.baseUrl}. It may have failed ` +\n          `to start — check ~/.toon-client/daemon.log.`\n      );\n    }\n    if (e instanceof ControlApiError) {\n      return err(`${e.message}${e.detail ? `: ${e.detail}` : ''}`);\n    }\n    return err(e instanceof Error ? e.message : String(e));\n  }\n}\n\nfunction ok(data: unknown): ToolResult {\n  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };\n}\n\nfunction err(message: string): ToolResult {\n  return { content: [{ type: 'text', text: message }], isError: true };\n}\n"],"mappings":";;;;;;;AA4BO,IAAM,mBAAqC;AAAA,EAChD;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IAEF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY,CAAC;AAAA,MACb,sBAAsB;AAAA,IACxB;AAAA,EACF;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IAEF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY,CAAC;AAAA,MACb,sBAAsB;AAAA,IACxB;AAAA,EACF;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IAGF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY;AAAA,QACV,OAAO;AAAA,UACL,MAAM;AAAA,UACN,aACE;AAAA,QAEJ;AAAA,QACA,aAAa;AAAA,UACX,MAAM;AAAA,UACN,aACE;AAAA,QACJ;AAAA,QACA,KAAK;AAAA,UACH,MAAM;AAAA,UACN,aACE;AAAA,QACJ;AAAA,MACF;AAAA,MACA,UAAU,CAAC,OAAO;AAAA,MAClB,sBAAsB;AAAA,IACxB;AAAA,EACF;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IAEF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY;AAAA,QACV,SAAS;AAAA,UACP,aAAa;AAAA,QACf;AAAA,QACA,OAAO,EAAE,MAAM,UAAU,aAAa,+BAA+B;AAAA,MACvE;AAAA,MACA,UAAU,CAAC,SAAS;AAAA,MACpB,sBAAsB;AAAA,IACxB;AAAA,EACF;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IAEF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY;AAAA,QACV,OAAO,EAAE,MAAM,UAAU,aAAa,gCAAgC;AAAA,QACtE,QAAQ;AAAA,UACN,MAAM;AAAA,UACN,aAAa;AAAA,QACf;AAAA,QACA,OAAO;AAAA,UACL,MAAM;AAAA,UACN,aAAa;AAAA,QACf;AAAA,MACF;AAAA,MACA,sBAAsB;AAAA,IACxB;AAAA,EACF;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IAEF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY;AAAA,QACV,aAAa;AAAA,UACX,MAAM;AAAA,UACN,aAAa;AAAA,QACf;AAAA,MACF;AAAA,MACA,sBAAsB;AAAA,IACxB;AAAA,EACF;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IAEF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY,CAAC;AAAA,MACb,sBAAsB;AAAA,IACxB;AAAA,EACF;AAAA,EACA;AAAA,IACE,MAAM;AAAA,IACN,aACE;AAAA,IAKF,aAAa;AAAA,MACX,MAAM;AAAA,MACN,YAAY;AAAA,QACV,aAAa;AAAA,UACX,MAAM;AAAA,UACN,aAAa;AAAA,QACf;AAAA,QACA,QAAQ;AAAA,UACN,MAAM;AAAA,UACN,aAAa;AAAA,QACf;AAAA,QACA,YAAY;AAAA,UACV,MAAM;AAAA,UACN,aACE;AAAA,QACJ;AAAA,QACA,MAAM;AAAA,UACJ,MAAM;AAAA,UACN,aACE;AAAA,QAEJ;AAAA,QACA,gBAAgB;AAAA,UACd,MAAM;AAAA,UACN,aACE;AAAA,QACJ;AAAA,QACA,aAAa;AAAA,UACX,MAAM;AAAA,UACN,aAAa;AAAA,QACf;AAAA,MACF;AAAA,MACA,UAAU;AAAA,QACR;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,MACA,sBAAsB;AAAA,IACxB;AAAA,EACF;AACF;AAQA,eAAsB,aACpB,QACA,MACA,MACqB;AACrB,MAAI;AACF,YAAQ,MAAM;AAAA,MACZ,KAAK;AACH,eAAO,GAAG,MAAM,OAAO,OAAO,CAAC;AAAA,MACjC,KAAK,iBAAiB;AACpB,cAAM,IAAI,MAAM,OAAO,OAAO;AAC9B,eAAO,GAAG;AAAA,UACR,UAAU,EAAE;AAAA,UACZ,OAAO,EAAE;AAAA,UACT,eAAe,EAAE;AAAA,QACnB,CAAC;AAAA,MACH;AAAA,MACA,KAAK;AACH,eAAO,GAAG,MAAM,OAAO,QAAQ,IAAiC,CAAC;AAAA,MACnE,KAAK;AACH,eAAO;AAAA,UACL,MAAM,OAAO,UAAU;AAAA,YACrB,SAAS,KAAK,SAAS;AAAA,YACvB,GAAI,OAAO,KAAK,OAAO,MAAM,WACzB,EAAE,OAAO,KAAK,OAAO,EAAE,IACvB,CAAC;AAAA,UACP,CAAC;AAAA,QACH;AAAA,MACF,KAAK;AACH,eAAO;AAAA,UACL,MAAM,OAAO,OAAO;AAAA,YAClB,GAAI,OAAO,KAAK,OAAO,MAAM,WACzB,EAAE,OAAO,KAAK,OAAO,EAAE,IACvB,CAAC;AAAA,YACL,GAAI,OAAO,KAAK,QAAQ,MAAM,WAC1B,EAAE,QAAQ,KAAK,QAAQ,EAAE,IACzB,CAAC;AAAA,YACL,GAAI,OAAO,KAAK,OAAO,MAAM,WACzB,EAAE,OAAO,KAAK,OAAO,EAAE,IACvB,CAAC;AAAA,UACP,CAAC;AAAA,QACH;AAAA,MACF,KAAK;AACH,eAAO;AAAA,UACL,MAAM,OAAO;AAAA,YACX,OAAO,KAAK,aAAa,MAAM,WAC3B,EAAE,aAAa,KAAK,aAAa,EAAE,IACnC,CAAC;AAAA,UACP;AAAA,QACF;AAAA,MACF,KAAK;AACH,eAAO,GAAG,MAAM,OAAO,SAAS,CAAC;AAAA,MACnC,KAAK;AACH,eAAO;AAAA,UACL,MAAM,OAAO,KAAK;AAAA,YAChB,aAAa,OAAO,KAAK,aAAa,CAAC;AAAA,YACvC,QAAQ,OAAO,KAAK,QAAQ,CAAC;AAAA,YAC7B,YAAY,OAAO,KAAK,YAAY,CAAC;AAAA,YACrC,MAAM,KAAK,MAAM;AAAA,YACjB,gBAAgB,OAAO,KAAK,gBAAgB,CAAC;AAAA,YAC7C,GAAI,OAAO,KAAK,aAAa,MAAM,WAC/B,EAAE,aAAa,KAAK,aAAa,EAAE,IACnC,CAAC;AAAA,UACP,CAAC;AAAA,QACH;AAAA,MACF;AACE,eAAO,IAAI,iBAAiB,IAAI,EAAE;AAAA,IACtC;AAAA,EACF,SAAS,GAAG;AACV,QAAI,aAAa,mBAAmB,EAAE,WAAW;AAC/C,aAAO;AAAA,QACL,iHAC+B,EAAE,OAAO;AAAA,MAC1C;AAAA,IACF;AACA,QAAI,aAAa,wBAAwB;AACvC,aAAO;AAAA,QACL,0CAA0C,EAAE,OAAO;AAAA,MAErD;AAAA,IACF;AACA,QAAI,aAAa,iBAAiB;AAChC,aAAO,IAAI,GAAG,EAAE,OAAO,GAAG,EAAE,SAAS,KAAK,EAAE,MAAM,KAAK,EAAE,EAAE;AAAA,IAC7D;AACA,WAAO,IAAI,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC,CAAC;AAAA,EACvD;AACF;AAEA,SAAS,GAAG,MAA2B;AACrC,SAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAQ,MAAM,KAAK,UAAU,MAAM,MAAM,CAAC,EAAE,CAAC,EAAE;AAC5E;AAEA,SAAS,IAAI,SAA6B;AACxC,SAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAQ,MAAM,QAAQ,CAAC,GAAG,SAAS,KAAK;AACrE;","names":[]}