@toon-protocol/client-mcp 0.1.0 → 0.3.0

package/dist/{ed25519-2QVPINLS.js → ed25519-2LFQXLYS.js}

@@ -3,25 +3,29 @@ import {
   ED25519_TORSION_SUBGROUP,
   _map_to_curve_elligator2_curve25519,
   ed25519,
+  ed25519_FROST,
   ed25519_hasher,
   ed25519ctx,
   ed25519ph,
   ristretto255,
+  ristretto255_FROST,
   ristretto255_hasher,
   ristretto255_oprf,
   x25519
-} from "./chunk-FSS45ZX3.js";
+} from "./chunk-DLYE6U2Z.js";
 import "./chunk-F22GNSF6.js";
 export {
   ED25519_TORSION_SUBGROUP,
   _map_to_curve_elligator2_curve25519,
   ed25519,
+  ed25519_FROST,
   ed25519_hasher,
   ed25519ctx,
   ed25519ph,
   ristretto255,
+  ristretto255_FROST,
   ristretto255_hasher,
   ristretto255_oprf,
   x25519
 };
-//# sourceMappingURL=ed25519-2QVPINLS.js.map
+//# sourceMappingURL=ed25519-2LFQXLYS.js.map

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { NostrEvent } from 'nostr-tools/pure';
+import { NostrEvent, EventTemplate } from 'nostr-tools/pure';
 import { SwapPair } from '@toon-protocol/core';
 import { ToonClientConfig } from '@toon-protocol/client';
 import { FastifyInstance } from 'fastify';
+import { ViewSpec } from '@toon-protocol/views';
 
 /**
  * Shared request/response contract for the `toon-clientd` localhost control
@@ -27,8 +28,8 @@ interface StatusResponse {
     /** Daemon process uptime, ms. */
     uptimeMs: number;
     /**
-     * True while the managed anon proxy / BTP session / channel are still coming
-     * up. Tools should surface "bootstrapping — retry" rather than blocking.
+     * True while the BTP session / channel are still coming up. Tools should
+     * surface "bootstrapping — retry" rather than blocking.
      */
     bootstrapping: boolean;
     /** True once the client has started and a channel is open (ready to publish). */
@@ -42,8 +43,7 @@ interface StatusResponse {
         minaAddress?: string;
     };
     transport: {
-        type: 'direct' | 'socks5' | 'gateway';
-        socksProxy?: string;
+        type: 'direct';
         btpUrl?: string;
     };
     relay: {
@@ -53,13 +53,6 @@ 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[];
@@ -90,6 +83,58 @@ interface PublishResponse {
     /** Channel nonce after this publish (advances by one per paid write). */
     nonce: number;
 }
+/**
+ * `POST /publish-unsigned` — build, SIGN (with the daemon-held key), and
+ * pay-to-write a Nostr event. The caller (a UI/agent) supplies only the event
+ * shell — it never holds the private key. For replaceable kinds (0 profile,
+ * 3 follow list) the daemon merges the latest known event's tags before signing.
+ */
+interface PublishUnsignedRequest {
+    /** Event kind to publish (integer, 0–65535). */
+    kind: number;
+    /** Event content (default ''). */
+    content?: string;
+    /** Event tags (array of string arrays). */
+    tags?: string[][];
+    /** ILP destination override (default: the configured apex/town address). */
+    destination?: string;
+    /** Fee override in base units. Defaults to the daemon's configured fee. */
+    fee?: string;
+    /** Which apex (BTP write target) to publish through (default: config-seeded). */
+    btpUrl?: string;
+}
+/**
+ * `POST /upload-media` — two-step spendy write: upload bytes to Arweave via the
+ * kind:5094 blob-storage DVM, then sign+publish a media event referencing the
+ * resulting Arweave URL. Single-packet only (large media is out of scope; see
+ * `requestBlobStorage`).
+ */
+interface UploadMediaRequest {
+    /** Base64-encoded media bytes. */
+    dataBase64: string;
+    /** MIME type (default 'application/octet-stream'). */
+    mime?: string;
+    /**
+     * Kind of the media event to publish referencing the upload. Default 1063
+     * (NIP-94 file metadata). 20 = NIP-68 picture, 21/22 = NIP-71 video, 1 = note
+     * with a NIP-92 `imeta` attachment.
+     */
+    kind?: number;
+    /** Caption / content for the published media event. */
+    caption?: string;
+    /** Extra tags merged into the published media event. */
+    tags?: string[][];
+    /** Fee override in base units (applies to the upload + the publish). */
+    fee?: string;
+    /** Which apex to publish through (default: config-seeded). */
+    btpUrl?: string;
+}
+interface UploadMediaResponse extends PublishResponse {
+    /** Arweave URL the media event references. */
+    url: string;
+    /** Arweave transaction id of the uploaded blob. */
+    txId: string;
+}
 /** `POST /subscribe` — register a persistent free-read subscription. */
 interface SubscribeRequest {
     /** NIP-01 filter(s). A single object or an array of OR-ed filters. */
@@ -108,6 +153,18 @@ interface SubscribeResponse {
     /** The relays the subscription was registered on. */
     relays: string[];
 }
+/**
+ * `POST /query` — one-shot free read: subscribe the filter(s), wait briefly, and
+ * return every buffered event matching them. Used by the apps `toon_query` tool.
+ */
+interface QueryRequest {
+    filters: NostrFilter | NostrFilter[];
+    /** Bounded wait for relay delivery, ms (default 1200). */
+    timeoutMs?: number;
+}
+interface QueryResponse {
+    events: NostrEvent[];
+}
 /** `GET /events` — drain buffered events for a subscription (free read). */
 interface EventsQuery {
     /** Restrict to a single subscription id. */
@@ -211,9 +268,39 @@ interface SwapResponse {
     /** First rejection message, if any. */
     message?: string;
 }
+/**
+ * `POST /http-fetch-paid` — payment-aware HTTP GET/POST. The daemon issues the
+ * request via `ToonClient.h402Fetch`; if the origin answers `402 Payment
+ * Required` the client transparently pays over TOON and retries, returning the
+ * settled resource. The caller never holds chain keys — settlement happens
+ * inside the daemon against the open apex channel.
+ */
+interface HttpFetchPaidRequest {
+    /** Absolute URL of the resource to fetch (the origin may gate it behind 402). */
+    url: string;
+    /** HTTP method (default GET). */
+    method?: string;
+    /** Request headers as a flat string→string map. */
+    headers?: Record<string, string>;
+    /** Request body (string; sent verbatim). Typically used with POST. */
+    body?: string;
+    /** Per-request timeout, ms (passed through to the client). */
+    timeout?: number;
+}
+interface HttpFetchPaidResponse {
+    /** Final HTTP status after any 402-pay-and-retry round trip. */
+    status: number;
+    /** Response headers as a flat string→string map. */
+    headers: Record<string, string>;
+    /**
+     * Response body decoded as text. Binary bodies are returned as their decoded
+     * text for v1 (acceptable; a base64 path can be added later if needed).
+     */
+    body: 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. */
+    /** Relay WS URL, e.g. `ws://host:7100`. */
     relayUrl: string;
 }
 /** `DELETE /relays` — remove a relay read target. */
@@ -337,13 +424,17 @@ declare class ControlClient {
     ping(): Promise<boolean>;
     status(): Promise<StatusResponse>;
     publish(body: PublishRequest): Promise<PublishResponse>;
+    publishUnsigned(body: PublishUnsignedRequest): Promise<PublishResponse>;
+    uploadMedia(body: UploadMediaRequest): Promise<UploadMediaResponse>;
     subscribe(body: SubscribeRequest): Promise<SubscribeResponse>;
+    query(body: QueryRequest): Promise<QueryResponse>;
     events(query?: EventsQuery): Promise<EventsResponse>;
     openChannel(body?: OpenChannelRequest): Promise<{
         channelId: string;
     }>;
     channels(): Promise<ChannelsResponse>;
     swap(body: SwapRequest): Promise<SwapResponse>;
+    httpFetchPaid(body: HttpFetchPaidRequest): Promise<HttpFetchPaidResponse>;
     targets(): Promise<TargetsResponse>;
     addRelay(body: AddRelayRequest): Promise<TargetsResponse>;
     removeRelay(body: RemoveRelayRequest): Promise<TargetsResponse>;
@@ -363,9 +454,7 @@ declare class ControlClient {
  * with exponential backoff and re-issues every active REQ on reconnect.
  *
  * The WebSocket is injectable (`wsFactory`) so unit tests can drive the wire
- * protocol without a real relay; the default factory uses the `ws` package and,
- * when a `socks5h://` proxy is configured, routes through it so `.anyone`
- * hidden-service relays are reachable.
+ * protocol without a real relay; the default factory uses the `ws` package.
  */
 
 /** Minimal WebSocket surface this module depends on (subset of `ws`). */
@@ -378,10 +467,8 @@ interface MinimalWebSocket {
 }
 type WebSocketFactory = (url: string) => MinimalWebSocket;
 interface RelaySubscriptionOptions {
-    /** Town relay WS URL, e.g. `wss://<host>.anyone/` or `ws://localhost:7100`. */
+    /** Town relay WS URL, e.g. `ws://localhost:7100`. */
     relayUrl: string;
-    /** Optional `socks5h://host:port` proxy for `.anyone` relays. */
-    socksProxy?: string;
     /** Max events retained in the ring buffer (oldest evicted). Default 5000. */
     bufferSize?: number;
     /** Base reconnect delay, ms. Default 1000. */
@@ -416,7 +503,6 @@ interface DrainResult {
 }
 declare class RelaySubscription {
     private readonly relayUrl;
-    private readonly socksProxy?;
     private readonly bufferSize;
     private readonly reconnectBaseMs;
     private readonly reconnectMaxMs;
@@ -527,12 +613,19 @@ interface DaemonConfigFile {
     _help?: Record<string, string>;
     /** BTP WebSocket URL of the apex/connector. */
     btpUrl?: string;
-    /** Transport: `direct` or a `socks5h://` proxy for `.anyone` hosts. */
-    socksProxy?: string;
-    /** Auto-manage the anon proxy for `.anyone` BTP hosts. Default true for HS. */
-    managedAnonProxy?: boolean;
-    /** Loopback SOCKS port the managed anon proxy binds (also used for reads). Default 9050. */
-    managedAnonSocksPort?: number;
+    /**
+     * Connector-PROXY base URL (devnet payment-proxy, e.g.
+     * `https://proxy.devnet.toonprotocol.dev`). When set, the daemon routes paid
+     * writes through the proxy's `POST /ilp` (ILP-over-HTTP) WITHOUT a BTP socket;
+     * `btpUrl` then becomes optional. Env override: `TOON_CLIENT_PROXY_URL`.
+     */
+    proxyUrl?: string;
+    /**
+     * Devnet faucet base URL (e.g. `https://faucet.devnet.toonprotocol.dev`),
+     * carried through to the ToonClient config for tooling/e2e funding. Env
+     * override: `TOON_CLIENT_FAUCET_URL`.
+     */
+    faucetUrl?: string;
     /** Town relay WS URL for FREE reads. */
     relayUrl?: string;
     /** Default ILP publish destination. Default `g.townhouse.town`. */
@@ -580,16 +673,17 @@ interface DaemonConfigFile {
 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.
+     * Whether a write uplink (proxy or BTP) is configured. FREE reads work
+     * without one; a write attempt with `hasUplink === false` is rejected at the
+     * control plane with a clear "configure an uplink" error (issue #69). Reads
+     * (`subscribe`/`query`/`getEvents`) never consult this.
      */
-    manageReadProxy: boolean;
-    /** Loopback SOCKS port for the daemon-managed read proxy (when `manageReadProxy`). */
-    readProxySocksPort?: number;
+    hasUplink: boolean;
+    /** Connector-proxy base URL (devnet payment-proxy), when configured. */
+    proxyUrl?: string;
+    /** Devnet faucet base URL, when configured. */
+    faucetUrl?: string;
     destination: string;
     feePerEvent: bigint;
     apex?: ApexNegotiationConfig;
@@ -622,8 +716,9 @@ declare function resolveMnemonic(file: DaemonConfigFile): string;
 /**
  * Build the full resolved daemon config (file overlaid with env, mnemonic
  * resolved, ToonClientConfig assembled). Env overrides supported:
- *   TOON_CLIENT_BTP_URL, TOON_CLIENT_RELAY_URL, TOON_CLIENT_SOCKS,
- *   TOON_CLIENT_HTTP_PORT, TOON_CLIENT_NETWORK.
+ *   TOON_CLIENT_BTP_URL, TOON_CLIENT_PROXY_URL, TOON_CLIENT_FAUCET_URL,
+ *   TOON_CLIENT_RELAY_URL, TOON_CLIENT_HTTP_PORT, TOON_CLIENT_NETWORK,
+ *   TOON_CLIENT_DESTINATION.
  */
 declare function resolveConfig(file: DaemonConfigFile): ResolvedDaemonConfig;
 
@@ -643,8 +738,8 @@ declare function resolveConfig(file: DaemonConfigFile): ResolvedDaemonConfig;
  * 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".
+ * in the background. Until ready, writes against it report `bootstrapping` so
+ * tools surface "retry".
  */
 
 /** The subset of `ToonClient` the runner depends on. */
@@ -674,6 +769,28 @@ interface ToonClientLike {
         error?: string;
     }>;
     signBalanceProof(channelId: string, amount: bigint): Promise<unknown>;
+    /**
+     * Sign an unsigned event template with the daemon-held Nostr key (the key
+     * never leaves the daemon). Backs the `publish-unsigned` / `upload-media`
+     * paths so a UI/agent supplies only the event shell.
+     */
+    signEvent(template: EventTemplate): NostrEvent | Promise<NostrEvent>;
+    /**
+     * Upload bytes to Arweave via the kind:5094 blob-storage DVM (single-packet),
+     * returning the Arweave tx id. Reuses the client's claim/channel plumbing.
+     */
+    uploadBlob(params: {
+        blobData: Uint8Array;
+        contentType?: string;
+        bid?: string;
+        destination?: string;
+        ilpAmount?: bigint;
+    }): Promise<{
+        success: boolean;
+        txId?: string;
+        eventId?: string;
+        error?: string;
+    }>;
     openChannel(destination?: string): Promise<string>;
     getTrackedChannels(): string[];
     getChannelNonce(channelId: string): number;
@@ -689,22 +806,25 @@ interface ToonClientLike {
         code?: string;
         message?: string;
     }>;
+    /**
+     * Payment-aware HTTP fetch: issue the request and, on a `402 Payment
+     * Required`, transparently pay over TOON and retry, returning the settled Web
+     * `Response`. Pinned to the `ToonClient.h402Fetch` shape (issue #50).
+     */
+    h402Fetch(url: string, opts?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string | Uint8Array;
+        timeout?: number;
+        destination?: string;
+    }): Promise<Response>;
 }
 /** 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. */
+/** Builds a `RelaySubscription` for a given relay URL. */
 type CreateRelay = (opts: {
     relayUrl: string;
-    socksProxy?: string;
     onEvent: (subId: string, event: NostrEvent) => void;
     logger?: (msg: string) => void;
 }) => RelaySubscription;
@@ -714,11 +834,6 @@ interface ClientRunnerDeps {
     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;
@@ -727,7 +842,6 @@ declare class ClientRunner {
     private readonly config;
     private readonly createClient;
     private readonly createRelay;
-    private readonly startReadProxy;
     private readonly log;
     private readonly targetsPath?;
     private readonly startedAt;
@@ -747,9 +861,6 @@ declare class ClientRunner {
     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);
@@ -768,8 +879,7 @@ declare class ClientRunner {
      */
     private registerRelay;
     /**
-     * Add a relay read target at runtime. `.anyone` relays reuse the managed read
-     * proxy (started here if needed). Persisted unless `persist` is false.
+     * Add a relay read target at runtime. Persisted unless `persist` is false.
      */
     addRelay(relayUrl: string, persist?: boolean): Promise<void>;
     /** Remove a relay read target. The config-seeded default cannot be removed. */
@@ -781,6 +891,16 @@ declare class ClientRunner {
      * every relay (and onto relays added later); with one it targets that relay.
      */
     subscribe(req: SubscribeRequest): SubscribeResponse;
+    /**
+     * One-shot free read: subscribe the given filter(s) across all relays, wait a
+     * bounded window for the relay(s) to deliver, then return every buffered event
+     * matching the filter (matched by content, not subId — so events already
+     * buffered by other subscriptions are included despite the global dedup).
+     *
+     * Backs the apps `toon_query` tool the generative-UI runtime calls to resolve
+     * a ViewSpec node's data bind.
+     */
+    query(filters: NostrFilter | NostrFilter[], timeoutMs?: number): Promise<NostrEvent[]>;
     /** Drain merged events newer than the cursor (free read), optionally scoped. */
     getEvents(query: EventsQuery): EventsResponse;
     private makeApex;
@@ -804,10 +924,27 @@ declare class ClientRunner {
     private deriveApexClientConfig;
     private apexChannelStorePathFor;
     private replayPersistedTargets;
-    private ensureReadProxy;
-    private bringUpReadProxy;
-    /** Open the apex channel — or, on a restart, RESUME the existing one. */
+    /**
+     * Open the apex channel — or, on a restart, RESUME the existing one.
+     *
+     * With `resumeOnly`, only a persisted channel is resumed (no on-chain open);
+     * returns undefined when none exists so the caller can defer the open to the
+     * first write (funded-after-start demo flow, #69).
+     */
     private openOrResumeApexChannel;
+    /**
+     * Persist a (lazily- or eagerly-) opened apex channel so a restart RESUMES it
+     * (tracked, no re-deposit) rather than opening a second on-chain channel.
+     * No-op when the apex carries no negotiation (nothing to key the store on).
+     */
+    private persistApexChannel;
+    /**
+     * Discover the apex's settlement negotiation from its kind:10032 on the
+     * default relay and attach it to the apex (proxy-mode fallback when no config
+     * negotiation was supplied, #69). Throws ApexDiscoveryError on timeout/missing
+     * settlement params so the apex's `lastError` reports exactly what is missing.
+     */
+    private discoverApexNegotiation;
     /** Inject the apex settlement negotiation directly into its ToonClient. */
     private injectApexNegotiation;
     /** Route apex CHILD peers (dvm/mill) through the SAME apex payment channel. */
@@ -821,6 +958,26 @@ declare class ClientRunner {
     getTargets(): TargetsResponse;
     /** Pay-to-write a single event through the selected (or default) apex. */
     publish(req: PublishRequest): Promise<PublishResponse>;
+    /**
+     * Build, sign (with the daemon-held key), and pay-to-write an event. The
+     * caller supplies only the event shell; the private key never leaves the
+     * daemon. Payloads are MODEL-AUTHORED → validated server-side here (the model
+     * is not a security boundary). Replaceable kinds (0/3) merge the latest known
+     * event's tags before signing.
+     */
+    publishUnsigned(req: PublishUnsignedRequest): Promise<PublishResponse>;
+    /**
+     * Upload media to Arweave (kind:5094 blob DVM, single-packet) then sign+publish
+     * a media event referencing the resulting URL. One spendy operation, two steps,
+     * entirely server-side.
+     */
+    uploadMedia(req: UploadMediaRequest): Promise<UploadMediaResponse>;
+    /** Validate + assemble a signable event template (with replaceable merge). */
+    private buildTemplate;
+    /** Latest self-authored event of `kind` currently in the merged read buffer. */
+    private latestSelfReplaceable;
+    /** Tags for a published media event referencing an Arweave URL. */
+    private buildMediaTags;
     /** Open (or return) a payment channel on the selected (or default) apex. */
     openChannel(destination?: string, btpUrl?: string): Promise<{
         channelId: string;
@@ -829,7 +986,13 @@ declare class ClientRunner {
     getChannels(): ChannelsResponse;
     /** Swap source→target asset against a mill peer via the selected apex. */
     swap(req: SwapRequest): Promise<SwapResponse>;
-    /** Graceful teardown: close every relay + stop every apex client + read proxy. */
+    /**
+     * Payment-aware HTTP fetch through an apex's client. The client issues the
+     * request and, on `402 Payment Required`, pays over TOON and retries; we
+     * translate the resulting Web `Response` into the wire envelope.
+     */
+    httpFetchPaid(req: HttpFetchPaidRequest): Promise<HttpFetchPaidResponse>;
+    /** Graceful teardown: close every relay + stop every apex client. */
     stop(): Promise<void>;
     private selectApex;
     private assertApexReady;
@@ -859,9 +1022,8 @@ declare class PublishRejectedError extends Error {
  *      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.
+ *      knobs (`btpUrl`/`relayUrl`) plus a `_help` block documenting them, 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.
@@ -928,7 +1090,8 @@ declare function spawnDaemonDetached(opts?: SpawnDaemonOptions): number;
 /**
  * Poll the control plane until the daemon answers `GET /status`, up to
  * `timeoutMs`. Resolves true once reachable (NOT necessarily done
- * bootstrapping — anon can take 30–90s; callers surface `bootstrapping`).
+ * bootstrapping — the BTP session can take a moment; callers surface
+ * `bootstrapping`).
  */
 declare function waitForReady(baseUrl: string, timeoutMs?: number, intervalMs?: number): Promise<boolean>;
 
@@ -944,6 +1107,8 @@ interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    /** MCP-apps metadata, e.g. `{ ui: { resourceUri } }` linking a UI resource. */
+    _meta?: Record<string, unknown>;
 }
 /** MCP tool-call result shape (subset of the SDK's CallToolResult). */
 interface ToolResult {
@@ -951,6 +1116,8 @@ interface ToolResult {
         type: 'text';
         text: string;
     }[];
+    /** Machine-readable payload the MCP-app iframe reads (events, ViewSpec, …). */
+    structuredContent?: Record<string, unknown>;
     isError?: boolean;
 }
 declare const TOOL_DEFINITIONS: ToolDefinition[];
@@ -962,4 +1129,51 @@ declare const TOOL_DEFINITIONS: ToolDefinition[];
  */
 declare function dispatchTool(client: ControlClient, name: string, args: Record<string, unknown>): Promise<ToolResult>;
 
-export { type AddApexRequest, type AddApexResponse, type AddRelayRequest, type ApexNegotiationConfig, type ApexTargetStatus, type ChainStatus, type ChannelInfo, type ChannelsResponse, ClientRunner, type ClientRunnerDeps, ControlApiError, ControlClient, type ControlClientOptions, DEFAULT_KEYSTORE_PASSWORD, type DaemonConfigFile, DaemonUnreachableError, type DrainResult, type ErrorResponse, type EventsQuery, type EventsResponse, type MinimalWebSocket, type NostrFilter, NotReadyError, type OpenChannelRequest, PublishRejectedError, type PublishRequest, type PublishResponse, RelaySubscription, type RelaySubscriptionOptions, type RelayTargetStatus, type RemoveApexRequest, type RemoveRelayRequest, type ResolvedDaemonConfig, type SettlementChain, type StatusResponse, type SubscribeRequest, type SubscribeResponse, type SwapClaim, type SwapRequest, type SwapResponse, TOOL_DEFINITIONS, type TargetsResponse, type ToolDefinition, type ToolResult, type ToonClientLike, type WebSocketFactory, acquireLock, configDir, defaultConfigPath, defaultKeystorePath, dispatchTool, hasConfiguredIdentity, isDaemonRunning, isProcessAlive, readConfigFile, readPid, registerRoutes, releaseLock, resolveConfig, resolveMnemonic, scaffoldFirstRun, spawnDaemonDetached, waitForReady };
+/** Accumulated per-step results keyed by step id. */
+type JourneyState = Record<string, unknown>;
+/** One step in a journey: a tool call with a ViewSpec renderer. */
+interface JourneyStep {
+    /** Unique identifier for this step within the plan. */
+    id: string;
+    /** MCP tool name to call (e.g. `toon_status`, `toon_publish_unsigned`). */
+    toolName: string;
+    /** Build the tool input from accumulated prior-step state. */
+    buildInput: (state: JourneyState) => Record<string, unknown>;
+    /** Render the step's result data as a ViewSpec panel. */
+    renderPanel: (data: unknown, state: JourneyState) => ViewSpec;
+}
+/** Ordered sequence of steps with plan metadata. */
+interface JourneyPlan {
+    id: string;
+    title: string;
+    steps: JourneyStep[];
+}
+/** Result for one executed step. */
+interface JourneyStepResult {
+    stepId: string;
+    /** Raw ToolResult from the tool call. */
+    toolResult: ToolResult;
+    /** ToolResult carrying the step's ViewSpec panel as structuredContent. */
+    panel: ToolResult;
+}
+/** Final result of a runJourney call. */
+interface JourneyResult {
+    /** True when all steps completed without error. */
+    completed: boolean;
+    /** Results for every step that ran (may be partial on error). */
+    steps: JourneyStepResult[];
+    /** Present when the run halted due to a tool error. */
+    error?: {
+        stepId: string;
+        message: string;
+    };
+}
+
+/**
+ * Run all steps in the plan sequentially against the given ControlClient.
+ * Each step's result is threaded forward into the next step's buildInput via
+ * JourneyState. Halts on the first tool error and returns a partial result.
+ */
+declare function runJourney(plan: JourneyPlan, client: ControlClient): Promise<JourneyResult>;
+
+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 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 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 };