@toon-protocol/client-mcp 0.10.9 → 0.11.0

package/dist/daemon.js

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

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';
 
@@ -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
@@ -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-CS4B3GET.js";
+} from "./chunk-KVK6OZVD.js";
 import {
   PUBLISH_TOOL,
   TOOL_DEFINITIONS,
@@ -18,7 +18,7 @@ import {
   buildFollowListFilter,
   buildProfileFilter,
   dispatchTool
-} from "./chunk-X4GKWZQP.js";
+} from "./chunk-JPQ4VCCF.js";
 import {
   ControlApiError,
   ControlClient,
@@ -36,7 +36,7 @@ import {
   resolveMnemonic,
   spawnDaemonDetached,
   waitForReady
-} from "./chunk-UHITXU5V.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-X4GKWZQP.js";
+} from "./chunk-JPQ4VCCF.js";
 import {
   ARWEAVE_GATEWAYS,
   ControlClient,
@@ -13,7 +13,7 @@ import {
   readConfigFile,
   spawnDaemonDetached,
   waitForReady
-} from "./chunk-UHITXU5V.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.9",
+  "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.9",
-    "@toon-protocol/views": "0.10.9"
+    "@toon-protocol/client": "0.14.10",
+    "@toon-protocol/views": "0.11.0"
   },
   "engines": {
     "node": ">=20"