@toon-protocol/client-mcp 0.10.8 → 0.11.0

package/dist/daemon.js

@@ -4,7 +4,7 @@ import {
   ClientRunner,
   registerRoutes,
   scaffoldFirstRun
-} from "./chunk-ADBNZA5O.js";
+} from "./chunk-KVK6OZVD.js";
 import {
   ControlClient,
   ToonClient,
@@ -17,7 +17,7 @@ import {
   resolveConfig,
   spawnDaemonDetached,
   waitForReady
-} from "./chunk-3ZBC2HUB.js";
+} from "./chunk-CMGJ3NFT.js";
 import "./chunk-32QD72IL.js";
 import "./chunk-DLYE6U2Z.js";
 import "./chunk-LR7W2ISE.js";

package/dist/daemon.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/daemon.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `toon-clientd` — the always-on, detached TOON client daemon. It owns the two\n * long-lived connections that cannot live in an ephemeral agent session:\n *   • a BTP session to the apex/connector (paid writes), and\n *   • a persistent town-relay Nostr-WS subscription (free reads),\n * plus the payment channels (with a persisted nonce watermark) and the signer.\n *\n * Subcommands:\n *   toon-clientd run      Run the daemon in the foreground (used internally by\n *                         the detached spawn; logs to stdout).\n *   toon-clientd start    Spawn the daemon detached and wait until reachable.\n *   toon-clientd stop     Stop a running daemon (SIGTERM the locked PID).\n *   toon-clientd status   Print the daemon status as JSON.\n */\n\nimport Fastify from 'fastify';\nimport { ToonClient } from '@toon-protocol/client';\nimport {\n  defaultConfigPath,\n  readConfigFile,\n  resolveConfig,\n  type ResolvedDaemonConfig,\n} from './daemon/config.js';\nimport { scaffoldFirstRun } from './daemon/first-run.js';\nimport { ClientRunner, type ToonClientLike } from './daemon/client-runner.js';\nimport { registerRoutes } from './daemon/routes.js';\nimport {\n  acquireLock,\n  isProcessAlive,\n  readPid,\n  releaseLock,\n  spawnDaemonDetached,\n  waitForReady,\n} from './daemon/lifecycle.js';\nimport { ControlClient } from './control-client.js';\n\nfunction baseUrl(config: ResolvedDaemonConfig): string {\n  return `http://127.0.0.1:${config.httpPort}`;\n}\n\nfunction loadResolvedConfig(): ResolvedDaemonConfig {\n  const path = process.env['TOON_CLIENT_CONFIG'] ?? defaultConfigPath();\n  return resolveConfig(readConfigFile(path));\n}\n\n/** Run the daemon in the foreground (the detached child's actual work). */\nasync function runForeground(): Promise<void> {\n  acquireLock();\n  const config = loadResolvedConfig();\n  const log = (msg: string): void => console.error(msg);\n\n  const runner = new ClientRunner({\n    config,\n    createClient: (clientConfig) =>\n      new ToonClient(clientConfig) as unknown as ToonClientLike,\n    logger: log,\n  });\n\n  const app = Fastify({\n    logger: false,\n    // Keep idle keep-alive sockets open longer than the MCP-side undici client\n    // would ever pool one (its keepAliveMaxTimeout default is 600s). The client\n    // calls this localhost control plane infrequently, so with Node's default\n    // 5s keep-alive the daemon was reaping sockets the client still held —\n    // causing the next request to fail with ECONNRESET (\"daemon not reachable\")\n    // until a retry opened a fresh socket (toon-client#186). Outliving the\n    // client's pool removes that race for non-retried (POST) requests too; the\n    // client-side retry covers the residual. Localhost-only listener, so a\n    // long-lived idle socket is harmless.\n    keepAliveTimeout: 650_000,\n  });\n  registerRoutes(app, runner);\n\n  // Begin bootstrap (non-blocking) before listening so /status is immediately\n  // reachable and reports `bootstrapping: true` while anon/BTP come up.\n  runner.start();\n\n  await app.listen({ host: '127.0.0.1', port: config.httpPort });\n  log(`[toon-clientd] listening on ${baseUrl(config)}`);\n\n  let shuttingDown = false;\n  const shutdown = async (signal: string): Promise<void> => {\n    if (shuttingDown) return;\n    shuttingDown = true;\n    log(`[toon-clientd] received ${signal}, shutting down`);\n    try {\n      await app.close();\n    } catch {\n      /* ignore */\n    }\n    await runner.stop();\n    releaseLock();\n    setTimeout(() => process.exit(0), 500).unref();\n  };\n  process.on('SIGTERM', () => void shutdown('SIGTERM'));\n  process.on('SIGINT', () => void shutdown('SIGINT'));\n}\n\n/** Spawn the daemon detached and wait until the control plane responds. */\nasync function start(): Promise<void> {\n  const config = loadResolvedConfig();\n  const url = baseUrl(config);\n  const existing = readPid();\n  if (existing !== null && isProcessAlive(existing)) {\n    console.log(`toon-clientd already running (pid ${existing}) at ${url}`);\n    return;\n  }\n  const pid = spawnDaemonDetached();\n  const ok = await waitForReady(url, 20_000);\n  if (ok) {\n    console.log(`toon-clientd started (pid ${pid}) at ${url}`);\n  } else {\n    console.error(\n      `toon-clientd spawned (pid ${pid}) but did not become reachable at ${url} in time. ` +\n        `Check the daemon log.`\n    );\n    process.exitCode = 1;\n  }\n}\n\n/** Stop a running daemon via SIGTERM on the locked PID. */\nasync function stop(): Promise<void> {\n  const pid = readPid();\n  if (pid === null || !isProcessAlive(pid)) {\n    console.log('toon-clientd is not running');\n    releaseLock();\n    return;\n  }\n  process.kill(pid, 'SIGTERM');\n  // Wait briefly for the process to exit.\n  for (let i = 0; i < 40; i++) {\n    if (!isProcessAlive(pid)) break;\n    await new Promise((r) => setTimeout(r, 100));\n  }\n  console.log(`toon-clientd stopped (pid ${pid})`);\n}\n\n/** Print the daemon status JSON. */\nasync function status(): Promise<void> {\n  const config = loadResolvedConfig();\n  const client = new ControlClient({ baseUrl: baseUrl(config) });\n  try {\n    const s = await client.status();\n    console.log(JSON.stringify(s, null, 2));\n  } catch {\n    console.log(JSON.stringify({ running: false }, null, 2));\n    process.exitCode = 1;\n  }\n}\n\nasync function main(): Promise<void> {\n  const cmd = process.argv[2] ?? 'run';\n  switch (cmd) {\n    case 'run':\n      // First-run onboarding (#251): mint + persist an identity and scaffold\n      // the transport config so a fresh install starts with no manual setup.\n      await scaffoldFirstRun();\n      await runForeground();\n      break;\n    case 'start':\n      await scaffoldFirstRun();\n      await start();\n      break;\n    case 'stop':\n      await stop();\n      break;\n    case 'status':\n      await status();\n      break;\n    default:\n      console.error(\n        `Unknown command \"${cmd}\". Usage: toon-clientd <run|start|stop|status>`\n      );\n      process.exitCode = 1;\n  }\n}\n\nmain().catch((err) => {\n  console.error(\n    err instanceof Error ? (err.stack ?? err.message) : String(err)\n  );\n  process.exitCode = 1;\n});\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/daemon.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * `toon-clientd` — the always-on, detached TOON client daemon. It owns the two\n * long-lived connections that cannot live in an ephemeral agent session:\n *   • a BTP session to the apex/connector (paid writes), and\n *   • a persistent relay Nostr-WS subscription (free reads),\n * plus the payment channels (with a persisted nonce watermark) and the signer.\n *\n * Subcommands:\n *   toon-clientd run      Run the daemon in the foreground (used internally by\n *                         the detached spawn; logs to stdout).\n *   toon-clientd start    Spawn the daemon detached and wait until reachable.\n *   toon-clientd stop     Stop a running daemon (SIGTERM the locked PID).\n *   toon-clientd status   Print the daemon status as JSON.\n */\n\nimport Fastify from 'fastify';\nimport { ToonClient } from '@toon-protocol/client';\nimport {\n  defaultConfigPath,\n  readConfigFile,\n  resolveConfig,\n  type ResolvedDaemonConfig,\n} from './daemon/config.js';\nimport { scaffoldFirstRun } from './daemon/first-run.js';\nimport { ClientRunner, type ToonClientLike } from './daemon/client-runner.js';\nimport { registerRoutes } from './daemon/routes.js';\nimport {\n  acquireLock,\n  isProcessAlive,\n  readPid,\n  releaseLock,\n  spawnDaemonDetached,\n  waitForReady,\n} from './daemon/lifecycle.js';\nimport { ControlClient } from './control-client.js';\n\nfunction baseUrl(config: ResolvedDaemonConfig): string {\n  return `http://127.0.0.1:${config.httpPort}`;\n}\n\nfunction loadResolvedConfig(): ResolvedDaemonConfig {\n  const path = process.env['TOON_CLIENT_CONFIG'] ?? defaultConfigPath();\n  return resolveConfig(readConfigFile(path));\n}\n\n/** Run the daemon in the foreground (the detached child's actual work). */\nasync function runForeground(): Promise<void> {\n  acquireLock();\n  const config = loadResolvedConfig();\n  const log = (msg: string): void => console.error(msg);\n\n  const runner = new ClientRunner({\n    config,\n    createClient: (clientConfig) =>\n      new ToonClient(clientConfig) as unknown as ToonClientLike,\n    logger: log,\n  });\n\n  const app = Fastify({\n    logger: false,\n    // Keep idle keep-alive sockets open longer than the MCP-side undici client\n    // would ever pool one (its keepAliveMaxTimeout default is 600s). The client\n    // calls this localhost control plane infrequently, so with Node's default\n    // 5s keep-alive the daemon was reaping sockets the client still held —\n    // causing the next request to fail with ECONNRESET (\"daemon not reachable\")\n    // until a retry opened a fresh socket (toon-client#186). Outliving the\n    // client's pool removes that race for non-retried (POST) requests too; the\n    // client-side retry covers the residual. Localhost-only listener, so a\n    // long-lived idle socket is harmless.\n    keepAliveTimeout: 650_000,\n  });\n  registerRoutes(app, runner);\n\n  // Begin bootstrap (non-blocking) before listening so /status is immediately\n  // reachable and reports `bootstrapping: true` while anon/BTP come up.\n  runner.start();\n\n  await app.listen({ host: '127.0.0.1', port: config.httpPort });\n  log(`[toon-clientd] listening on ${baseUrl(config)}`);\n\n  let shuttingDown = false;\n  const shutdown = async (signal: string): Promise<void> => {\n    if (shuttingDown) return;\n    shuttingDown = true;\n    log(`[toon-clientd] received ${signal}, shutting down`);\n    try {\n      await app.close();\n    } catch {\n      /* ignore */\n    }\n    await runner.stop();\n    releaseLock();\n    setTimeout(() => process.exit(0), 500).unref();\n  };\n  process.on('SIGTERM', () => void shutdown('SIGTERM'));\n  process.on('SIGINT', () => void shutdown('SIGINT'));\n}\n\n/** Spawn the daemon detached and wait until the control plane responds. */\nasync function start(): Promise<void> {\n  const config = loadResolvedConfig();\n  const url = baseUrl(config);\n  const existing = readPid();\n  if (existing !== null && isProcessAlive(existing)) {\n    console.log(`toon-clientd already running (pid ${existing}) at ${url}`);\n    return;\n  }\n  const pid = spawnDaemonDetached();\n  const ok = await waitForReady(url, 20_000);\n  if (ok) {\n    console.log(`toon-clientd started (pid ${pid}) at ${url}`);\n  } else {\n    console.error(\n      `toon-clientd spawned (pid ${pid}) but did not become reachable at ${url} in time. ` +\n        `Check the daemon log.`\n    );\n    process.exitCode = 1;\n  }\n}\n\n/** Stop a running daemon via SIGTERM on the locked PID. */\nasync function stop(): Promise<void> {\n  const pid = readPid();\n  if (pid === null || !isProcessAlive(pid)) {\n    console.log('toon-clientd is not running');\n    releaseLock();\n    return;\n  }\n  process.kill(pid, 'SIGTERM');\n  // Wait briefly for the process to exit.\n  for (let i = 0; i < 40; i++) {\n    if (!isProcessAlive(pid)) break;\n    await new Promise((r) => setTimeout(r, 100));\n  }\n  console.log(`toon-clientd stopped (pid ${pid})`);\n}\n\n/** Print the daemon status JSON. */\nasync function status(): Promise<void> {\n  const config = loadResolvedConfig();\n  const client = new ControlClient({ baseUrl: baseUrl(config) });\n  try {\n    const s = await client.status();\n    console.log(JSON.stringify(s, null, 2));\n  } catch {\n    console.log(JSON.stringify({ running: false }, null, 2));\n    process.exitCode = 1;\n  }\n}\n\nasync function main(): Promise<void> {\n  const cmd = process.argv[2] ?? 'run';\n  switch (cmd) {\n    case 'run':\n      // First-run onboarding (#251): mint + persist an identity and scaffold\n      // the transport config so a fresh install starts with no manual setup.\n      await scaffoldFirstRun();\n      await runForeground();\n      break;\n    case 'start':\n      await scaffoldFirstRun();\n      await start();\n      break;\n    case 'stop':\n      await stop();\n      break;\n    case 'status':\n      await status();\n      break;\n    default:\n      console.error(\n        `Unknown command \"${cmd}\". Usage: toon-clientd <run|start|stop|status>`\n      );\n      process.exitCode = 1;\n  }\n}\n\nmain().catch((err) => {\n  console.error(\n    err instanceof Error ? (err.stack ?? err.message) : String(err)\n  );\n  process.exitCode = 1;\n});\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { NostrEvent, EventTemplate } from 'nostr-tools/pure';
 import { SwapPair } from '@toon-protocol/core';
-import { ToonClientConfig } from '@toon-protocol/client';
+import { ToonClientConfig, FaucetChain } from '@toon-protocol/client';
 import { FastifyInstance } from 'fastify';
 import { ViewSpec } from '@toon-protocol/views';
 
@@ -67,7 +67,7 @@ interface StatusResponse {
 interface PublishRequest {
     /** A fully-signed Nostr event (id + sig present). */
     event: NostrEvent;
-    /** ILP destination override (default: the configured apex/town address). */
+    /** ILP destination override (default: the configured apex/relay address). */
     destination?: string;
     /** Fee override in base units. Defaults to the daemon's configured fee. */
     fee?: string;
@@ -100,7 +100,7 @@ interface PublishUnsignedRequest {
     content?: string;
     /** Event tags (array of string arrays). */
     tags?: string[][];
-    /** ILP destination override (default: the configured apex/town address). */
+    /** ILP destination override (default: the configured apex/relay address). */
     destination?: string;
     /** Fee override in base units. Defaults to the daemon's configured fee. */
     fee?: string;
@@ -288,7 +288,7 @@ interface SwapRequest {
     swapPubkey: string;
     /**
      * The swap pair to execute — from kind:10032 discovery, or operator-supplied
-     * when the swap peer announces pairs to a relay other than the town relay.
+     * when the swap peer announces pairs to a relay other than the default relay.
      */
     pair: SwapPair;
     /**
@@ -453,16 +453,42 @@ interface FundWalletRequest {
     /** Address to fund (default: this client's own address for `chain`). */
     address?: string;
 }
-/** `POST /fund-wallet` result. */
+/**
+ * `POST /fund-wallet` result — a snapshot of an ASYNC faucet drip job.
+ *
+ * The drip is non-blocking: `POST /fund-wallet` launches the faucet call in the
+ * daemon background and returns immediately with `status: 'pending'`. This avoids
+ * the MCP host's ~60s tool-call timeout surfacing a still-working Mina drip
+ * (which legitimately settles in ~75s, native MINA + USDC) as a misleading
+ * relay/apex timeout (#199-class). Poll `GET /fund-wallet/status` (or just
+ * re-read balances) to observe the terminal `'success'` / `'error'` state.
+ */
 interface FundWalletResponse {
-    /** The chain that was funded. */
+    /** The chain being funded. */
     chain: SettlementChain;
-    /** The address that was funded. */
+    /** The address being funded. */
     address: string;
     /** The faucet base URL the drip was requested from. */
     faucetUrl: string;
-    /** Raw parsed JSON body from the faucet (shape is faucet-defined). */
-    response: unknown;
+    /**
+     * Lifecycle of the background drip. `'timeout'` is distinct from `'error'`:
+     * the faucet client gave up but the on-chain drip MAY still have settled
+     * (observed on a loaded EVM faucet) — treat it as "uncertain, re-check
+     * balances", not a definitive failure, to avoid a misleading double-fund.
+     */
+    status: 'pending' | 'success' | 'error' | 'timeout';
+    /** Unix ms the drip was submitted. */
+    startedAt: number;
+    /** Unix ms the drip settled or failed (absent while `'pending'`). */
+    finishedAt?: number;
+    /** Raw parsed JSON body from the faucet on success (shape is faucet-defined). */
+    response?: unknown;
+    /** Error message on failure. */
+    error?: string;
+}
+/** `GET /fund-wallet/status` result — snapshots of tracked drip jobs. */
+interface FundStatusResponse {
+    jobs: FundWalletResponse[];
 }
 /** Uniform error envelope returned with non-2xx responses. */
 interface ErrorResponse {
@@ -543,6 +569,7 @@ declare class ControlClient {
     addApex(body: AddApexRequest): Promise<AddApexResponse>;
     removeApex(body: RemoveApexRequest): Promise<TargetsResponse>;
     fundWallet(body?: FundWalletRequest): Promise<FundWalletResponse>;
+    fundStatus(chain?: SettlementChain): Promise<FundStatusResponse>;
     /**
      * Whether an HTTP method is safe to transparently retry. Idempotent reads
      * (GET) and deletes can be replayed verbatim; a mutating POST cannot — the
@@ -555,11 +582,11 @@ declare class ControlClient {
 }
 
 /**
- * Persistent town-relay Nostr-WS subscription — the read half of the TOON
+ * Persistent 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,
+ * Reads are FREE: this opens a long-lived NIP-01 connection to the 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.
@@ -578,7 +605,7 @@ interface MinimalWebSocket {
 }
 type WebSocketFactory = (url: string) => MinimalWebSocket;
 interface RelaySubscriptionOptions {
-    /** Town relay WS URL, e.g. `ws://localhost:7100`. */
+    /** Relay WS URL, e.g. `ws://localhost:7100`. */
     relayUrl: string;
     /** Max events retained in the ring buffer (oldest evicted). Default 5000. */
     bufferSize?: number;
@@ -688,7 +715,7 @@ declare class RelaySubscription {
  *   3. the `mnemonic` field of the config file (discouraged — plaintext on disk).
  */
 
-/** Apex/town settlement parameters injected as a peer negotiation. */
+/** Apex/relay settlement parameters injected as a peer negotiation. */
 interface ApexNegotiationConfig {
     /** ILP destination address, e.g. `g.proxy`. */
     destination: string;
@@ -743,7 +770,7 @@ interface DaemonConfigFile {
      * mina faucet). Env override: `TOON_CLIENT_FAUCET_TIMEOUT_MS`.
      */
     faucetTimeoutMs?: number;
-    /** Town relay WS URL for FREE reads. */
+    /** Relay WS URL for FREE reads. */
     relayUrl?: string;
     /**
      * Apex CHANNEL ANCHOR (settlement peer). Defaults to the genesis seed apex's
@@ -1028,11 +1055,29 @@ declare class ClientRunner {
     private readonly createRelay;
     private readonly log;
     private readonly targetsPath?;
+    /**
+     * Identity-level chain-read client. Reading your OWN on-chain wallet balance is
+     * a pure (wallet keys + chain RPC) operation that has nothing to do with the
+     * ILP/payment peer, so it lives at the daemon level rather than inside an apex.
+     * Built once from the daemon's own `toonClientConfig` (the same keys + chain
+     * RPC config every apex shares) and REUSED as the default apex's client, so a
+     * funded apex's `start()` (which derives Solana/Mina keys) also benefits this
+     * reader. `getBalances` uses it directly, so balances work even with zero
+     * apexes registered (follow-up to #199/#200).
+     */
+    private readonly identityClient;
     private readonly startedAt;
     /** Apex write targets, keyed by btpUrl. */
     private readonly apexes;
     /** Relay read targets, keyed by relayUrl. */
     private readonly relays;
+    /**
+     * Async faucet drip jobs, keyed by chain. A drip is launched in the background
+     * (the Mina faucet legitimately takes ~75s — longer than the MCP host's ~60s
+     * tool-call budget) and its terminal state is observed via {@link getFundStatus}
+     * / re-reading balances rather than by blocking the caller.
+     */
+    private readonly fundJobs;
     /** Runner-level merged read buffer across all relays (de-duped by event.id). */
     private merged;
     private readonly mergedSeen;
@@ -1145,7 +1190,13 @@ declare class ClientRunner {
      * (the typical "fund me before I open a channel" flow). The daemon holds the
      * faucet URL + the keys, so the MCP caller never needs either.
      */
-    fundWallet(req?: FundWalletRequest): Promise<FundWalletResponse>;
+    fundWallet(req?: FundWalletRequest): FundWalletResponse;
+    /**
+     * Snapshots of tracked faucet drip jobs — all of them, or just the one for
+     * `chain`. Lets a caller poll for the terminal state of an async drip without
+     * re-dripping.
+     */
+    getFundStatus(chain?: FaucetChain): FundStatusResponse;
     /** Full registry of relay + apex targets with per-target status. */
     getTargets(): TargetsResponse;
     /** Pay-to-write a single event through the selected (or default) apex. */
@@ -1190,8 +1241,20 @@ declare class ClientRunner {
     getChannels(): ChannelsResponse;
     /**
      * On-chain wallet balances. The wallet is identity-level (same keys across
-     * apexes), so read from the first available apex's client; per-chain reads are
-     * best-effort inside the client (a failing chain is simply omitted).
+     * apexes), so this reads from the daemon's {@link identityClient} — NOT an apex
+     * — and therefore works even with zero apexes / no payment peer configured
+     * (reading your own balance is a pure wallet-keys + chain-RPC operation).
+     * Per-chain reads are best-effort inside the client (a failing chain is simply
+     * omitted).
+     *
+     * Each underlying read hits per-chain RPC providers that can stall
+     * indefinitely on devnet (a provider being `detail: "configured"` in
+     * toon_status means it is WIRED, not that its RPC is live). A stall here used
+     * to block the whole control request until the client aborted, surfacing as a
+     * misleading "relay/apex unreachable" timeout (#199). Bound each attempt well
+     * under the control-plane timeout and retry once so a single transient
+     * provider stall FAST-FAILS with an honest "balances handler / provider
+     * stalled" error instead of hanging.
      */
     getBalances(): Promise<BalancesResponse>;
     /**
@@ -1402,4 +1465,4 @@ interface JourneyResult {
  */
 declare function runJourney(plan: JourneyPlan, client: ControlClient): Promise<JourneyResult>;
 
-export { type AddApexRequest, type AddApexResponse, type AddRelayRequest, type ApexNegotiationConfig, type ApexTargetStatus, type BalanceInfo, type BalancesResponse, type ChainStatus, type ChannelDepositRequest, type ChannelDepositResponse, type ChannelInfo, type ChannelsResponse, ClientRunner, type ClientRunnerDeps, type CloseChannelRequest, type CloseChannelResponse, ControlApiError, ControlClient, type ControlClientOptions, DEFAULT_KEYSTORE_PASSWORD, type DaemonConfigFile, DaemonUnreachableError, type DrainResult, type ErrorResponse, type EventsQuery, type EventsResponse, type FundWalletRequest, type FundWalletResponse, type HttpFetchPaidRequest, type HttpFetchPaidResponse, type JourneyPlan, type JourneyResult, type JourneyState, type JourneyStep, type JourneyStepResult, type MinimalWebSocket, type NostrFilter, NotReadyError, type OpenChannelRequest, PublishRejectedError, type PublishRequest, type PublishResponse, type PublishUnsignedRequest, type QueryRequest, type QueryResponse, RelaySubscription, type RelaySubscriptionOptions, type RelayTargetStatus, type RemoveApexRequest, type RemoveRelayRequest, type ResolvedDaemonConfig, type SettleChannelRequest, type SettleChannelResponse, 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 UploadMediaRequest, type UploadMediaResponse, type WebSocketFactory, acquireLock, configDir, defaultConfigPath, defaultKeystorePath, dispatchTool, hasConfiguredIdentity, isDaemonRunning, isProcessAlive, readConfigFile, readPid, registerRoutes, releaseLock, resolveConfig, resolveMnemonic, runJourney, scaffoldFirstRun, spawnDaemonDetached, waitForReady };
+export { type AddApexRequest, type AddApexResponse, type AddRelayRequest, type ApexNegotiationConfig, type ApexTargetStatus, type BalanceInfo, type BalancesResponse, type ChainStatus, type ChannelDepositRequest, type ChannelDepositResponse, type ChannelInfo, type ChannelsResponse, ClientRunner, type ClientRunnerDeps, type CloseChannelRequest, type CloseChannelResponse, ControlApiError, ControlClient, type ControlClientOptions, DEFAULT_KEYSTORE_PASSWORD, type DaemonConfigFile, DaemonUnreachableError, type DrainResult, type ErrorResponse, type EventsQuery, type EventsResponse, type FundStatusResponse, type FundWalletRequest, type FundWalletResponse, type HttpFetchPaidRequest, type HttpFetchPaidResponse, type JourneyPlan, type JourneyResult, type JourneyState, type JourneyStep, type JourneyStepResult, type MinimalWebSocket, type NostrFilter, NotReadyError, type OpenChannelRequest, PublishRejectedError, type PublishRequest, type PublishResponse, type PublishUnsignedRequest, type QueryRequest, type QueryResponse, RelaySubscription, type RelaySubscriptionOptions, type RelayTargetStatus, type RemoveApexRequest, type RemoveRelayRequest, type ResolvedDaemonConfig, type SettleChannelRequest, type SettleChannelResponse, 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 UploadMediaRequest, type UploadMediaResponse, type WebSocketFactory, acquireLock, configDir, defaultConfigPath, defaultKeystorePath, dispatchTool, hasConfiguredIdentity, isDaemonRunning, isProcessAlive, readConfigFile, readPid, registerRoutes, releaseLock, resolveConfig, resolveMnemonic, runJourney, scaffoldFirstRun, spawnDaemonDetached, waitForReady };

package/dist/index.js

@@ -8,7 +8,7 @@ import {
   hasConfiguredIdentity,
   registerRoutes,
   scaffoldFirstRun
-} from "./chunk-ADBNZA5O.js";
+} from "./chunk-KVK6OZVD.js";
 import {
   PUBLISH_TOOL,
   TOOL_DEFINITIONS,
@@ -18,7 +18,7 @@ import {
   buildFollowListFilter,
   buildProfileFilter,
   dispatchTool
-} from "./chunk-XFRMAETF.js";
+} from "./chunk-JPQ4VCCF.js";
 import {
   ControlApiError,
   ControlClient,
@@ -36,7 +36,7 @@ import {
   resolveMnemonic,
   spawnDaemonDetached,
   waitForReady
-} from "./chunk-3ZBC2HUB.js";
+} from "./chunk-CMGJ3NFT.js";
 import "./chunk-32QD72IL.js";
 import "./chunk-DLYE6U2Z.js";
 import "./chunk-LR7W2ISE.js";

package/dist/mcp.js

@@ -4,7 +4,7 @@ import {
   APP_RESOURCE_URI,
   TOOL_DEFINITIONS,
   dispatchTool
-} from "./chunk-XFRMAETF.js";
+} from "./chunk-JPQ4VCCF.js";
 import {
   ARWEAVE_GATEWAYS,
   ControlClient,
@@ -13,7 +13,7 @@ import {
   readConfigFile,
   spawnDaemonDetached,
   waitForReady
-} from "./chunk-3ZBC2HUB.js";
+} from "./chunk-CMGJ3NFT.js";
 import "./chunk-32QD72IL.js";
 import "./chunk-DLYE6U2Z.js";
 import "./chunk-LR7W2ISE.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toon-protocol/client-mcp",
-  "version": "0.10.8",
+  "version": "0.11.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 swaps.",
   "license": "MIT",
   "author": "Jonathan Green",
@@ -49,8 +49,8 @@
     "typescript": "^5.3.0",
     "vitest": "^1.0.0",
     "@toon-protocol/arweave": "0.1.1",
-    "@toon-protocol/client": "0.14.8",
-    "@toon-protocol/views": "0.10.8"
+    "@toon-protocol/client": "0.14.10",
+    "@toon-protocol/views": "0.11.0"
   },
   "engines": {
     "node": ">=20"