@toon-protocol/client-mcp 0.31.1 → 0.31.2

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[];
@@ -406,6 +413,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 +478,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 +500,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. */
@@ -549,18 +582,33 @@ 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>;
 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;
+    /**
+     * 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;
 }
 declare class ClientRunner {
     private readonly config;
     private readonly client;
     private readonly relay;
+    private readonly startReadProxy;
     private readonly log;
     private readonly startedAt;
     private bootstrapping;
@@ -568,6 +616,10 @@ declare class ClientRunner {
     private lastError;
     /** Channel opened against the default apex destination. */
     private apexChannelId;
+    /** Teardown for a daemon-managed read proxy (btp-direct + relay-`.anyone`). */
+    private stopReadProxy;
+    /** Error from the read proxy (kept separate from the paid-path `lastError`). */
+    private readProxyError;
     private stopped;
     constructor(deps: ClientRunnerDeps);
     /**
@@ -576,6 +628,8 @@ declare class ClientRunner {
      * returned promise of the underlying work.
      */
     start(): void;
+    /** Start the daemon-managed `anon` read proxy (best-effort; logs on failure). */
+    private bringUpReadProxy;
     /** The background bootstrap routine (exposed for awaiting in tests). */
     bootstrap(): Promise<void>;
     /**
@@ -650,6 +704,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 +822,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 ApexNegotiationConfig, 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 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, 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-PRFPAEGG.js";
 import {
   TOOL_DEFINITIONS,
   dispatchTool
-} from "./chunk-JOGMX4IT.js";
+} from "./chunk-I5L5CB4N.js";
 import {
   ControlApiError,
   ControlClient,
+  DEFAULT_KEYSTORE_PASSWORD,
   DaemonUnreachableError,
   acquireLock,
   configDir,
@@ -26,7 +30,7 @@ import {
   resolveMnemonic,
   spawnDaemonDetached,
   waitForReady
-} from "./chunk-MI2IWKHX.js";
+} from "./chunk-ARFPM2PT.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-I5L5CB4N.js";
 import {
   ControlClient,
   defaultConfigPath,
@@ -11,7 +11,7 @@ import {
   readConfigFile,
   spawnDaemonDetached,
   waitForReady
-} from "./chunk-MI2IWKHX.js";
+} from "./chunk-ARFPM2PT.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.31.2",
   "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"