@ctxprotocol/sdk 0.8.2 → 0.8.4

package/README.md

@@ -101,12 +101,15 @@ console.log(result.session); // methodPrice, spent, remaining, maxSpend, ...
 const answer = await client.query.run({
   query: "What are the top whale movements on Base?",
   modelId: "glm-model",      // optional: choose a supported model
+  queryDepth: "deep",        // optional: fast | auto | deep
   includeDataUrl: true,      // optional: persist full execution data to blob
+  includeDeveloperTrace: true, // optional: include machine-readable runtime trace
 });
 console.log(answer.response);   // AI-synthesized answer
 console.log(answer.toolsUsed);  // Which tools were used
 console.log(answer.cost);       // Cost breakdown
 console.log(answer.dataUrl);    // Optional blob URL with full data
+console.log(answer.developerTrace?.summary); // retries/toolCalls/loops summary
 ```
 
 > Mixed listings are first-class: one listing can expose methods to both surfaces. Methods without `_meta.pricing.executeUsd` remain query-only until priced.
@@ -298,10 +301,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
@@ -313,6 +318,8 @@ const client = new ContextClient({
 const client = new ContextClient({
   apiKey: "sk_test_...",
   baseUrl: "http://localhost:3000",
+  requestTimeoutMs: 420_000,
+  streamTimeoutMs: 840_000,
 });
 ```
 
@@ -395,6 +402,11 @@ const closed = await client.tools.closeSession("sess_123");
 
 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
 const answer = await client.query.run("What are the top whale movements on Base?");
@@ -404,8 +416,10 @@ 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
+  includeDeveloperTrace: true,             // optional: include Developer Mode trace
 });
 
 console.log(answer.response);     // AI-synthesized text
@@ -414,14 +428,26 @@ console.log(answer.cost);         // { modelCostUsd, toolCostUsd, totalCostUsd }
 console.log(answer.durationMs);   // Total time
 console.log(answer.data);         // Optional execution data (when includeData=true)
 console.log(answer.dataUrl);      // Optional blob URL (when includeDataUrl=true)
+console.log(answer.developerTrace?.summary); // Optional trace summary (retries/toolCalls/loops)
 ```
 
+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.
 
+Event types:
+- `tool-status`
+- `text-delta`
+- `developer-trace` (when `includeDeveloperTrace=true`)
+- `done`
+
 ```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}`);
@@ -456,6 +482,7 @@ import type {
   // Query types (pay-per-response)
   QueryOptions,
   QueryResult,
+  QueryDeveloperTrace,
   QueryCost,
   QueryStreamEvent,
   ContextErrorCode,
@@ -533,6 +560,7 @@ interface QueryResult {
   durationMs: number;
   data?: unknown;                      // Optional execution data (includeData=true)
   dataUrl?: string;                    // Optional blob URL (includeDataUrl=true)
+  developerTrace?: QueryDeveloperTrace; // Optional machine-readable runtime trace
 }
 ```
 

package/dist/client/index.cjs

@@ -228,6 +228,114 @@ var Query = class {
   constructor(client) {
     this.client = client;
   }
+  buildSyntheticTraceFromRunResult(params) {
+    const timeline = params.toolsUsed.map((tool, index) => ({
+      stepType: "tool-call",
+      event: "tool-call",
+      status: "success",
+      timestampMs: index,
+      tool: {
+        id: tool.id,
+        name: tool.name
+      },
+      metadata: {
+        skillCalls: tool.skillCalls,
+        synthetic: true
+      }
+    }));
+    const toolCalls = params.toolsUsed.reduce(
+      (sum, tool) => sum + Math.max(tool.skillCalls, 0),
+      0
+    );
+    return {
+      summary: {
+        toolCalls,
+        retryCount: 0,
+        selfHealCount: 0,
+        fallbackCount: 0,
+        failureCount: 0,
+        recoveryCount: 0,
+        completionChecks: 0,
+        loopCount: 0
+      },
+      timeline,
+      source: "sdk-fallback",
+      synthetic: true,
+      reason: "backend_trace_missing",
+      durationMs: params.durationMs
+    };
+  }
+  buildSyntheticTraceFromStreamStatus(params) {
+    const timeline = params.statusTimeline.map((entry, index) => ({
+      stepType: "tool-status",
+      event: "tool-status",
+      status: entry.status,
+      timestampMs: index,
+      tool: entry.tool.name || entry.tool.id ? {
+        id: entry.tool.id || void 0,
+        name: entry.tool.name || void 0
+      } : void 0,
+      metadata: { synthetic: true }
+    }));
+    const toolCallsFromUsage = params.toolsUsed.reduce(
+      (sum, tool) => sum + Math.max(tool.skillCalls, 0),
+      0
+    );
+    const toolCallsFromStatus = params.statusTimeline.filter(
+      (entry) => entry.status === "tool-complete"
+    ).length;
+    const toolCalls = toolCallsFromUsage > 0 ? toolCallsFromUsage : toolCallsFromStatus;
+    const retryCount = params.statusTimeline.filter(
+      (entry) => /(retry|fix|reflect|recover)/i.test(entry.status)
+    ).length;
+    const completionChecks = params.statusTimeline.filter(
+      (entry) => /complet/i.test(entry.status)
+    ).length;
+    return {
+      summary: {
+        toolCalls,
+        retryCount,
+        selfHealCount: retryCount,
+        fallbackCount: 0,
+        failureCount: 0,
+        recoveryCount: 0,
+        completionChecks,
+        loopCount: retryCount
+      },
+      timeline,
+      source: "sdk-fallback",
+      synthetic: true,
+      reason: "backend_trace_missing",
+      durationMs: params.durationMs
+    };
+  }
+  mergeDeveloperTrace(first, second) {
+    if (!first) return second;
+    if (!second) return first;
+    const firstTimeline = Array.isArray(first.timeline) ? first.timeline : [];
+    const secondTimeline = Array.isArray(second.timeline) ? second.timeline : [];
+    const mergedTimeline = [...firstTimeline, ...secondTimeline];
+    return {
+      ...first,
+      ...second,
+      summary: {
+        ...typeof first.summary === "object" && first.summary ? first.summary : {},
+        ...typeof second.summary === "object" && second.summary ? second.summary : {}
+      },
+      ...mergedTimeline.length > 0 ? { timeline: mergedTimeline } : {}
+    };
+  }
+  parseStreamEvent(rawData) {
+    const parsed = JSON.parse(rawData);
+    if (!parsed || typeof parsed !== "object") {
+      return void 0;
+    }
+    const event = parsed;
+    if (typeof event.type !== "string") {
+      return void 0;
+    }
+    return event;
+  }
   /**
    * Run an agentic query and wait for the full response.
    *
@@ -273,6 +381,8 @@ var Query = class {
           modelId: opts.modelId,
           includeData: opts.includeData,
           includeDataUrl: opts.includeDataUrl,
+          includeDeveloperTrace: opts.includeDeveloperTrace,
+          queryDepth: opts.queryDepth,
           stream: false
         })
       }
@@ -286,13 +396,18 @@ var Query = class {
       );
     }
     if (response.success) {
+      const developerTrace = response.developerTrace ?? (opts.includeDeveloperTrace ? this.buildSyntheticTraceFromRunResult({
+        toolsUsed: response.toolsUsed,
+        durationMs: response.durationMs
+      }) : void 0);
       return {
         response: response.response,
         toolsUsed: response.toolsUsed,
         cost: response.cost,
         durationMs: response.durationMs,
         data: response.data,
-        dataUrl: response.dataUrl
+        dataUrl: response.dataUrl,
+        developerTrace
       };
     }
     throw new ContextError("Unexpected response format from query API");
@@ -304,6 +419,7 @@ var Query = class {
    * Event types:
    * - `tool-status` — A tool started executing or changed status
    * - `text-delta` — A chunk of the AI response text
+   * - `developer-trace` — Runtime trace metadata (when includeDeveloperTrace=true)
    * - `done` — The full response is complete (includes final `QueryResult`)
    *
    * @param options - Query options or a plain string question
@@ -319,6 +435,9 @@ var Query = class {
    *     case "text-delta":
    *       process.stdout.write(event.delta);
    *       break;
+   *     case "developer-trace":
+   *       console.log("Trace summary:", event.trace.summary);
+   *       break;
    *     case "done":
    *       console.log("\nCost:", event.result.cost.totalCostUsd);
    *       break;
@@ -338,6 +457,8 @@ var Query = class {
         modelId: opts.modelId,
         includeData: opts.includeData,
         includeDataUrl: opts.includeDataUrl,
+        includeDeveloperTrace: opts.includeDeveloperTrace,
+        queryDepth: opts.queryDepth,
         stream: true
       })
     });
@@ -348,6 +469,45 @@ var Query = class {
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = "";
+    let aggregatedTrace;
+    const statusTimeline = [];
+    const parseAndHydrateEvent = (rawData) => {
+      const event = this.parseStreamEvent(rawData);
+      if (!event) {
+        return void 0;
+      }
+      if (event.type === "developer-trace") {
+        aggregatedTrace = this.mergeDeveloperTrace(aggregatedTrace, event.trace);
+        return event;
+      }
+      if (event.type === "tool-status") {
+        statusTimeline.push({
+          status: event.status,
+          tool: {
+            id: event.tool.id,
+            name: event.tool.name
+          }
+        });
+        return event;
+      }
+      if (event.type === "done") {
+        let mergedTrace = this.mergeDeveloperTrace(
+          aggregatedTrace,
+          event.result.developerTrace
+        );
+        if (!mergedTrace && opts.includeDeveloperTrace) {
+          mergedTrace = this.buildSyntheticTraceFromStreamStatus({
+            statusTimeline,
+            toolsUsed: event.result.toolsUsed,
+            durationMs: event.result.durationMs
+          });
+        }
+        if (mergedTrace) {
+          event.result.developerTrace = mergedTrace;
+        }
+      }
+      return event;
+    };
     try {
       while (true) {
         const { done, value } = await reader.read();
@@ -361,7 +521,10 @@ var Query = class {
             const data = trimmed.slice(6);
             if (data === "[DONE]") return;
             try {
-              yield JSON.parse(data);
+              const event = parseAndHydrateEvent(data);
+              if (event) {
+                yield event;
+              }
             } catch {
             }
           }
@@ -371,7 +534,10 @@ var Query = class {
         const data = buffer.trim().slice(6);
         if (data !== "[DONE]") {
           try {
-            yield JSON.parse(data);
+            const event = parseAndHydrateEvent(data);
+            if (event) {
+              yield event;
+            }
           } catch {
           }
         }
@@ -383,9 +549,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
@@ -408,14 +579,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);
@@ -429,7 +612,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
    */
@@ -439,7 +622,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();
@@ -507,6 +690,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
    */
@@ -515,14 +699,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;