@ctxprotocol/sdk 0.8.1 → 0.8.3

package/README.md

@@ -28,13 +28,13 @@ We're funding the initial supply of MCP Tools for the Context Marketplace. **Bec
 - **🔌 One Interface, Everything:** Stop integrating APIs one by one. Use a single SDK to access any tool in the marketplace.
 - **🧠 Zero-Ops:** We're a gateway to the best MCP tools. Just send the JSON and get the result.
 - **⚡️ Agentic Discovery:** Your Agent can search the marketplace at runtime to find tools it didn't know it needed.
-- **💸 Pay-Per-Response:** The $500/year subscription? Now $0.01/response. No monthly fees, just results.
+- **💸 Dual-Surface Economics:** Use Query for pay-per-response intelligence or Execute for session-budgeted method calls.
 
 ## Who Is This SDK For?
 
 | Role | What You Use |
 |------|--------------|
-| **AI Agent Developer** | `@ctxprotocol/sdk` — Query marketplace, execute tools, handle payments |
+| **AI Agent Developer** | `@ctxprotocol/sdk` — Query curated answers or Execute with explicit method pricing + sessions |
 | **Tool Contributor (Data Broker)** | `@modelcontextprotocol/sdk` + `@ctxprotocol/sdk` — Standard MCP server + security middleware |
 
 **For AI Agent Developers:** Use this SDK to search the marketplace, execute tools, and handle micro-payments.
@@ -72,25 +72,36 @@ Before using the API, complete setup at [ctxprotocol.com](https://ctxprotocol.co
 
 The SDK offers two payment models to serve different use cases:
 
-| Mode | Method | Payment Model | Use Case |
-|------|--------|---------------|----------|
-| **Execute** | `client.tools.execute()` | Pay-per-request | Simple data fetches, predictable costs, building custom pipelines |
-| **Query** | `client.query.run()` | Pay-per-response | Complex questions, multi-tool synthesis, curated intelligence |
+| Mode | Method | Payment Model | Settlement Shape | Use Case |
+|------|--------|---------------|------------------|----------|
+| **Execute** | `client.tools.execute()` | Per execute call | Session accrual + deferred batch flush | Deterministic pipelines, raw outputs, explicit spend envelopes |
+| **Query** | `client.query.run()` | Pay-per-response | Deferred post-response | Complex questions, multi-tool synthesis, curated intelligence |
 
-**Execute mode** gives you raw data and full control — one tool, one call, one payment:
+**Execute mode** gives you raw data and full control with explicit method pricing and session budgets:
 ```typescript
+const session = await client.tools.startSession({ maxSpendUsd: "2.00" });
+const executeTools = await client.discovery.search({
+  query: "whale transactions",
+  mode: "execute",
+  surface: "execute",
+  requireExecutePricing: true,
+});
+
 const result = await client.tools.execute({
-  toolId: "tool-uuid",
-  toolName: "whale_transactions",
+  toolId: executeTools[0].id,
+  toolName: executeTools[0].mcpTools[0].name,
   args: { chain: "base", limit: 20 },
+  sessionId: session.session.sessionId ?? undefined,
 });
+console.log(result.session); // methodPrice, spent, remaining, maxSpend, ...
 ```
 
-**Query mode** gives you curated answers — the server handles tool discovery, multi-tool orchestration (up to 100 MCP calls per tool), self-healing retries, completeness checks, model-aware context budgeting, and AI synthesis for one flat fee:
+**Query mode** gives you curated answers — the server handles answer-safe tool discovery, multi-tool orchestration (up to 100 MCP calls per response turn), self-healing retries, completeness checks, model-aware context budgeting, and AI synthesis for one flat fee:
 ```typescript
 const answer = await client.query.run({
   query: "What are the top whale movements on Base?",
   modelId: "glm-model",      // optional: choose a supported model
+  queryDepth: "auto",        // optional: fast | auto | deep
   includeDataUrl: true,      // optional: persist full execution data to blob
 });
 console.log(answer.response);   // AI-synthesized answer
@@ -99,6 +110,11 @@ console.log(answer.cost);       // Cost breakdown
 console.log(answer.dataUrl);    // Optional blob URL with full data
 ```
 
+> Mixed listings are first-class: one listing can expose methods to both surfaces. Methods without `_meta.pricing.executeUsd` remain query-only until priced.
+>
+> Compatibility: SDK/API payload fields such as `price` and `pricePerQuery` are retained for backward compatibility. In Query mode, they represent listing-level **price per response turn**.
+> A future major release can add response-named aliases (for example, `pricePerResponse`) before deprecating legacy names.
+
 ## Quick Start
 
 ```typescript
@@ -112,16 +128,25 @@ const client = new ContextClient({
 const answer = await client.query.run("What are the top whale movements on Base?");
 console.log(answer.response);
 
-// Pay-per-request: Execute a specific tool for raw data
-const tools = await client.discovery.search("gas prices");
+// Execute surface: require explicit execute pricing
+const tools = await client.discovery.search({
+  query: "gas prices",
+  mode: "execute",
+  surface: "execute",
+  requireExecutePricing: true,
+});
+const session = await client.tools.startSession({ maxSpendUsd: "1.00" });
 const result = await client.tools.execute({
   toolId: tools[0].id,
   toolName: tools[0].mcpTools[0].name,
   args: { chainId: 1 },
+  sessionId: session.session.sessionId ?? undefined,
 });
 console.log(result.result);
 ```
 
+See the runnable dual-surface example in [`examples/client/src/index.ts`](./examples/client/src/index.ts).
+
 ---
 
 ## The Agentic Pattern: How to Build Autonomous Bots
@@ -274,10 +299,12 @@ If you can answer without a tool, just respond normally.`;
 
 ### Client Options
 
-| Option    | Type     | Required | Default                  | Description                    |
-| --------- | -------- | -------- | ------------------------ | ------------------------------ |
-| `apiKey`  | `string` | Yes      | —                        | Your Context Protocol API key  |
-| `baseUrl` | `string` | No       | `https://ctxprotocol.com`| API base URL (for development) |
+| Option             | Type     | Required | Default                        | Description                                   |
+| ------------------ | -------- | -------- | ------------------------------ | --------------------------------------------- |
+| `apiKey`           | `string` | Yes      | —                              | Your Context Protocol API key                 |
+| `baseUrl`          | `string` | No       | `https://www.ctxprotocol.com`  | API base URL (for development)                |
+| `requestTimeoutMs` | `number` | No       | `300000`                       | Timeout for non-streaming API calls           |
+| `streamTimeoutMs`  | `number` | No       | `600000`                       | Timeout for establishing streaming API calls  |
 
 ```typescript
 // Production
@@ -289,6 +316,8 @@ const client = new ContextClient({
 const client = new ContextClient({
   apiKey: "sk_test_...",
   baseUrl: "http://localhost:3000",
+  requestTimeoutMs: 420_000,
+  streamTimeoutMs: 840_000,
 });
 ```
 
@@ -297,40 +326,84 @@ const client = new ContextClient({
 ### Discovery
 
 #### `client.discovery.search(query, limit?)`
+#### `client.discovery.search(options)`
 
-Search for tools matching a query string.
+Search for tools with optional surface-aware filters.
 
 ```typescript
 const tools = await client.discovery.search("ethereum gas", 10);
+
+const executeTools = await client.discovery.search({
+  query: "ethereum gas",
+  mode: "execute",
+  surface: "execute",
+  requireExecutePricing: true,
+});
 ```
 
-#### `client.discovery.getFeatured(limit?)`
+#### `client.discovery.getFeatured(limit?, options?)`
 
 Get featured/popular tools.
 
 ```typescript
 const featured = await client.discovery.getFeatured(5);
+const featuredExecute = await client.discovery.getFeatured(5, {
+  mode: "execute",
+  requireExecutePricing: true,
+});
 ```
 
-### Tools (Pay-Per-Request)
+### Tools (Execute Surface)
+
+Session lifecycle helpers use the canonical execute-scoped API contract:
+`/api/v1/tools/execute/sessions...`
 
 #### `client.tools.execute(options)`
 
-Execute a single tool method. One call, one payment, raw result.
+Execute a single tool method. Execute calls can run inside session budgets.
 
 ```typescript
+const session = await client.tools.startSession({ maxSpendUsd: "2.50" });
+
 const result = await client.tools.execute({
   toolId: "uuid-of-tool",
   toolName: "get_gas_prices",
   args: { chainId: 1 },
+  sessionId: session.session.sessionId ?? undefined,
 });
+
+console.log(result.method.executePriceUsd);
+console.log(result.session);
+```
+
+#### `client.tools.startSession({ maxSpendUsd })`
+
+```typescript
+const started = await client.tools.startSession({ maxSpendUsd: "5.00" });
+```
+
+#### `client.tools.getSession(sessionId)`
+
+```typescript
+const status = await client.tools.getSession("sess_123");
+```
+
+#### `client.tools.closeSession(sessionId)`
+
+```typescript
+const closed = await client.tools.closeSession("sess_123");
 ```
 
 ### Query (Pay-Per-Response)
 
 #### `client.query.run(options)`
 
-Run an agentic query. The server discovers tools, executes the full pipeline (up to 100 MCP calls per tool), applies model-aware mediator/data budgeting, and returns an AI-synthesized answer.
+Run an agentic query. The server discovers answer-safe tools, executes the full pipeline (up to 100 MCP calls per response turn), applies model-aware mediator/data budgeting, and returns an AI-synthesized answer.
+
+`queryDepth` controls orchestration depth:
+- `fast`: lower-latency path for simple lookups.
+- `auto`: server routes to either `fast` or `deep` from query intent + selected tool complexity.
+- `deep`: completeness-oriented path (default when omitted).
 
 ```typescript
 // Simple string
@@ -341,6 +414,7 @@ const answer = await client.query.run({
   query: "Analyze whale activity on Base",
   tools: ["tool-uuid-1", "tool-uuid-2"],  // optional — auto-discover if omitted
   modelId: "kimi-model-thinking",          // optional
+  queryDepth: "auto",                      // optional: fast | auto | deep
   includeData: true,                       // optional: include execution data inline
   includeDataUrl: true,                    // optional: include blob URL for full data
 });
@@ -353,12 +427,17 @@ console.log(answer.data);         // Optional execution data (when includeData=t
 console.log(answer.dataUrl);      // Optional blob URL (when includeDataUrl=true)
 ```
 
+When retrieval-first synthesis rollout is enabled server-side, full-data or truncation-sensitive query requests can switch to retrieval-first context assembly using private stage artifacts and canonical execution data slices. `includeData` and `includeDataUrl` continue to reference the same canonical dataset used for synthesis.
+
 #### `client.query.stream(options)`
 
 Same as `run()` but streams events in real-time via SSE.
 
 ```typescript
-for await (const event of client.query.stream("What are the top whale movements?")) {
+for await (const event of client.query.stream({
+  query: "What are the top whale movements?",
+  queryDepth: "fast",
+})) {
   switch (event.type) {
     case "tool-status":
       console.log(`Tool ${event.tool.name}: ${event.status}`);
@@ -414,7 +493,7 @@ interface Tool {
   id: string;
   name: string;
   description: string;
-  price: string;
+  price: string; // listing-level response price metadata (legacy field name)
   category?: string;
   isVerified?: boolean;
   mcpTools?: McpTool[];
@@ -427,17 +506,35 @@ interface Tool {
 interface McpTool {
   name: string;
   description: string;
-  inputSchema?: Record<string, unknown>;  // JSON Schema for arguments
-  outputSchema?: Record<string, unknown>; // JSON Schema for response
+  inputSchema?: Record<string, unknown>;   // JSON Schema for arguments
+  outputSchema?: Record<string, unknown>;  // JSON Schema for response
+  _meta?: {
+    surface?: "answer" | "execute" | "both";
+    queryEligible?: boolean;
+    latencyClass?: "instant" | "fast" | "slow" | "streaming";
+    pricing?: { executeUsd?: string; queryUsd?: string };
+  };
+  executeEligible?: boolean;
+  executePriceUsd?: string | null;
 }
 ```
 
-### ExecutionResult (Pay-Per-Request)
+### ExecutionResult (Execute Surface)
 
 ```typescript
 interface ExecutionResult<T = unknown> {
+  mode: "execute";
   result: T;
   tool: { id: string; name: string };
+  method: { name: string; executePriceUsd: string };
+  session: {
+    sessionId: string | null;
+    methodPrice: string;
+    spent: string;
+    remaining: string | null;
+    maxSpend: string | null;
+    status?: "open" | "closed" | "expired";
+  };
   durationMs: number;
 }
 ```
@@ -832,13 +929,13 @@ pnpm add -D @types/express
 
 ## Payment Flow
 
-Context uses **deferred settlement** — tools execute first, and payment is settled in the background after the result is returned:
+Context uses surface-aware deferred settlement:
 
-1. Your USDC spending cap (ERC-20 allowance on ContextRouter) is verified
-2. Tool executes and returns results
-3. Payment is settled server-side via the operator wallet (no client-side transactions)
+1. **Query surface** settles after each response turn
+2. **Execute surface** accrues per-call spend into execute sessions, then flushes batches
+3. Your USDC spending cap (ERC-20 allowance on ContextRouter) is still the global ceiling
 4. **90%** goes to the tool developer, **10%** goes to the protocol
-5. If execution fails, tool fees are **waived** — you only pay for successful results
+5. Session responses expose `methodPrice`, `spent`, `remaining`, and `maxSpend` on each execute call
 
 ## Documentation
 

package/dist/client/index.cjs

@@ -17,27 +17,36 @@ var Discovery = class {
   constructor(client) {
     this.client = client;
   }
-  /**
-   * Search for tools matching a query string
-   *
-   * @param query - The search query (e.g., "gas prices", "nft metadata")
-   * @param limit - Maximum number of results (1-50, default 10)
-   * @returns Array of matching tools
-   *
-   * @example
-   * ```typescript
-   * const tools = await client.discovery.search("gas prices");
-   * console.log(tools[0].name); // "Gas Price Oracle"
-   * console.log(tools[0].mcpTools); // Available methods
-   * ```
-   */
-  async search(query, limit) {
+  async search(queryOrOptions, limit) {
+    const options = typeof queryOrOptions === "string" ? { query: queryOrOptions, limit } : queryOrOptions;
     const params = new URLSearchParams();
+    const query = options.query ?? "";
     if (query) {
       params.set("q", query);
     }
-    if (limit !== void 0) {
-      params.set("limit", String(limit));
+    if (options.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    if (options.mode) {
+      params.set("mode", options.mode);
+    }
+    if (options.surface) {
+      params.set("surface", options.surface);
+    }
+    if (options.queryEligible !== void 0) {
+      params.set("queryEligible", String(options.queryEligible));
+    }
+    if (options.requireExecutePricing !== void 0) {
+      params.set(
+        "requireExecutePricing",
+        String(options.requireExecutePricing)
+      );
+    }
+    if (options.excludeLatencyClasses && options.excludeLatencyClasses.length > 0) {
+      params.set("excludeLatency", options.excludeLatencyClasses.join(","));
+    }
+    if (options.excludeSlow !== void 0) {
+      params.set("excludeSlow", String(options.excludeSlow));
     }
     const queryString = params.toString();
     const endpoint = `/api/v1/tools/search${queryString ? `?${queryString}` : ""}`;
@@ -55,8 +64,12 @@ var Discovery = class {
    * const featured = await client.discovery.getFeatured(5);
    * ```
    */
-  async getFeatured(limit) {
-    return this.search("", limit);
+  async getFeatured(limit, options) {
+    return this.search({
+      ...options ?? {},
+      query: "",
+      ...limit !== void 0 ? { limit } : {}
+    });
   }
 };
 
@@ -97,14 +110,31 @@ var Tools = class {
    * ```
    */
   async execute(options) {
-    const { toolId, toolName, args, idempotencyKey } = options;
+    const {
+      toolId,
+      toolName,
+      args,
+      idempotencyKey,
+      mode,
+      sessionId,
+      maxSpendUsd,
+      closeSession
+    } = options;
     const headers = idempotencyKey ? { "Idempotency-Key": idempotencyKey } : void 0;
     const response = await this.client._fetch(
       "/api/v1/tools/execute",
       {
         method: "POST",
         headers,
-        body: JSON.stringify({ toolId, toolName, args })
+        body: JSON.stringify({
+          toolId,
+          toolName,
+          args,
+          mode: mode ?? "execute",
+          sessionId,
+          maxSpendUsd,
+          closeSession
+        })
       }
     );
     if ("error" in response) {
@@ -118,13 +148,79 @@ var Tools = class {
     }
     if (response.success) {
       return {
+        mode: response.mode,
         result: response.result,
         tool: response.tool,
+        method: response.method,
+        session: response.session,
         durationMs: response.durationMs
       };
     }
     throw new ContextError("Unexpected response format from API");
   }
+  /**
+   * Start an execute session with a max spend budget.
+   */
+  async startSession(options) {
+    const response = await this.client._fetch(
+      "/api/v1/tools/execute/sessions",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          mode: "execute",
+          maxSpendUsd: options.maxSpendUsd
+        })
+      }
+    );
+    return this.resolveSessionLifecycleResponse(response);
+  }
+  /**
+   * Fetch current execute session status by ID.
+   */
+  async getSession(sessionId) {
+    if (!sessionId) {
+      throw new ContextError("sessionId is required");
+    }
+    const encodedSessionId = encodeURIComponent(sessionId);
+    const response = await this.client._fetch(
+      `/api/v1/tools/execute/sessions/${encodedSessionId}`
+    );
+    return this.resolveSessionLifecycleResponse(response);
+  }
+  /**
+   * Close an execute session by ID.
+   */
+  async closeSession(sessionId) {
+    if (!sessionId) {
+      throw new ContextError("sessionId is required");
+    }
+    const encodedSessionId = encodeURIComponent(sessionId);
+    const response = await this.client._fetch(
+      `/api/v1/tools/execute/sessions/${encodedSessionId}/close`,
+      {
+        method: "POST",
+        body: JSON.stringify({ mode: "execute" })
+      }
+    );
+    return this.resolveSessionLifecycleResponse(response);
+  }
+  resolveSessionLifecycleResponse(response) {
+    if ("error" in response) {
+      throw new ContextError(
+        response.error,
+        response.code,
+        void 0,
+        response.helpUrl
+      );
+    }
+    if (response.success) {
+      return {
+        mode: response.mode,
+        session: response.session
+      };
+    }
+    throw new ContextError("Unexpected response format from API");
+  }
 };
 
 // src/client/resources/query.ts
@@ -177,6 +273,7 @@ var Query = class {
           modelId: opts.modelId,
           includeData: opts.includeData,
           includeDataUrl: opts.includeDataUrl,
+          queryDepth: opts.queryDepth,
           stream: false
         })
       }
@@ -242,6 +339,7 @@ var Query = class {
         modelId: opts.modelId,
         includeData: opts.includeData,
         includeDataUrl: opts.includeDataUrl,
+        queryDepth: opts.queryDepth,
         stream: true
       })
     });
@@ -287,9 +385,14 @@ var Query = class {
 };
 
 // src/client/client.ts
+var DEFAULT_BASE_URL = "https://www.ctxprotocol.com";
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e5;
+var DEFAULT_STREAM_TIMEOUT_MS = 6e5;
 var ContextClient = class {
   apiKey;
   baseUrl;
+  requestTimeoutMs;
+  streamTimeoutMs;
   _closed = false;
   /**
    * Discovery resource for searching tools
@@ -312,14 +415,26 @@ var ContextClient = class {
    *
    * @param options - Client configuration options
    * @param options.apiKey - Your Context Protocol API key (format: sk_live_...)
-   * @param options.baseUrl - Optional base URL override (defaults to https://ctxprotocol.com)
+   * @param options.baseUrl - Optional base URL override (defaults to https://www.ctxprotocol.com)
+   * @param options.requestTimeoutMs - Optional timeout for non-streaming requests (default 300000ms)
+   * @param options.streamTimeoutMs - Optional timeout for establishing stream requests (default 600000ms)
    */
   constructor(options) {
     if (!options.apiKey) {
       throw new ContextError("API key is required");
     }
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const streamTimeoutMs = options.streamTimeoutMs ?? DEFAULT_STREAM_TIMEOUT_MS;
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+      throw new ContextError("requestTimeoutMs must be a positive number");
+    }
+    if (!Number.isFinite(streamTimeoutMs) || streamTimeoutMs <= 0) {
+      throw new ContextError("streamTimeoutMs must be a positive number");
+    }
     this.apiKey = options.apiKey;
-    this.baseUrl = (options.baseUrl ?? "https://ctxprotocol.com").replace(/\/$/, "");
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.requestTimeoutMs = requestTimeoutMs;
+    this.streamTimeoutMs = streamTimeoutMs;
     this.discovery = new Discovery(this);
     this.tools = new Tools(this);
     this.query = new Query(this);
@@ -333,7 +448,7 @@ var ContextClient = class {
   }
   /**
    * Internal method for making authenticated HTTP requests
-   * Includes timeout (30s) and retry with exponential backoff for transient errors
+   * Includes timeout and retry with exponential backoff for transient errors
    *
    * @internal
    */
@@ -343,7 +458,7 @@ var ContextClient = class {
     }
     const url = `${this.baseUrl}${endpoint}`;
     const maxRetries = 3;
-    const timeoutMs = 3e4;
+    const timeoutMs = this.requestTimeoutMs;
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       const controller = new AbortController();
@@ -411,6 +526,7 @@ var ContextClient = class {
   /**
    * Internal method for making authenticated HTTP requests that returns
    * the raw Response object. Used for streaming endpoints (SSE).
+   * Includes a configurable timeout for stream setup.
    *
    * @internal
    */
@@ -419,14 +535,32 @@ var ContextClient = class {
       throw new ContextError("Client has been closed");
     }
     const url = `${this.baseUrl}${endpoint}`;
-    const response = await fetch(url, {
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-        ...options.headers
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.streamTimeoutMs);
+    let response;
+    try {
+      response = await fetch(url, {
+        ...options,
+        signal: controller.signal,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          ...options.headers
+        }
+      });
+    } catch (error) {
+      clearTimeout(timeout);
+      const lastError = error instanceof Error ? error : new Error(String(error));
+      if (lastError.name === "AbortError") {
+        throw new ContextError(
+          `Streaming request timed out after ${this.streamTimeoutMs / 1e3}s`,
+          void 0,
+          408
+        );
       }
-    });
+      throw new ContextError(lastError.message);
+    }
+    clearTimeout(timeout);
     if (!response.ok) {
       let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
       let errorCode;