@ctxprotocol/sdk 0.8.3 → 0.8.5

package/README.md

@@ -96,18 +96,22 @@ const result = await client.tools.execute({
 console.log(result.session); // methodPrice, spent, remaining, maxSpend, ...
 ```
 
-**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:
+**Query mode** gives you curated answers — the server runs a discovery-first planner contract (`discover/probe -> plan-from-evidence -> execute -> bounded fallback`) with 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
+  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/fallbacks/loops summary
+console.log(answer.developerTrace?.diagnostics?.selection); // lane + scout probe diagnostics
+console.log(answer.orchestrationMetrics); // high-level first-pass / rediscovery metrics
 ```
 
 > Mixed listings are first-class: one listing can expose methods to both surfaces. Methods without `_meta.pricing.executeUsd` remain query-only until priced.
@@ -398,13 +402,18 @@ const closed = await client.tools.closeSession("sess_123");
 
 #### `client.query.run(options)`
 
-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.
+Run an agentic query. The server applies discovery-first orchestration (`discover/probe -> plan-from-evidence -> execute -> bounded fallback`) with up to 100 MCP calls per response turn, then 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).
 
+`includeDeveloperTrace` and `orchestrationMetrics` expose optional rollout diagnostics.
+`developerTrace.summary` reports aggregate retry/fallback counters, while
+`developerTrace.diagnostics.selection` exposes runtime lane and scout probe signals
+used by discovery-first planning.
+
 ```typescript
 // Simple string
 const answer = await client.query.run("What are the top whale movements on Base?");
@@ -417,6 +426,7 @@ const answer = await client.query.run({
   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
@@ -425,6 +435,9 @@ 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/fallbacks/loops)
+console.log(answer.developerTrace?.diagnostics?.selection?.deepMode); // Optional deep lane trace
+console.log(answer.orchestrationMetrics); // Optional high-level first-pass metrics
 ```
 
 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.
@@ -433,6 +446,12 @@ When retrieval-first synthesis rollout is enabled server-side, full-data or trun
 
 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({
   query: "What are the top whale movements?",
@@ -472,6 +491,8 @@ import type {
   // Query types (pay-per-response)
   QueryOptions,
   QueryResult,
+  QueryDeveloperTrace,
+  QueryOrchestrationMetrics,
   QueryCost,
   QueryStreamEvent,
   ContextErrorCode,
@@ -549,6 +570,8 @@ interface QueryResult {
   durationMs: number;
   data?: unknown;                      // Optional execution data (includeData=true)
   dataUrl?: string;                    // Optional blob URL (includeDataUrl=true)
+  developerTrace?: QueryDeveloperTrace; // Optional runtime trace + diagnostics
+  orchestrationMetrics?: QueryOrchestrationMetrics; // Optional first-pass outcome metrics
 }
 ```
 

package/dist/client/index.cjs

@@ -228,11 +228,119 @@ 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.
    *
    * The server discovers relevant tools (or uses the ones you specify),
-   * executes the full agentic pipeline (up to 100 MCP calls per tool),
+   * executes the discovery-first pipeline (up to 100 MCP calls per tool),
    * and returns an AI-synthesized answer. Payment is settled after
    * successful execution via deferred settlement.
    *
@@ -261,42 +369,25 @@ var Query = class {
    */
   async run(options) {
     const opts = typeof options === "string" ? { query: options } : options;
-    const headers = opts.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : void 0;
-    const response = await this.client._fetch(
-      "/api/v1/query",
-      {
-        method: "POST",
-        headers,
-        body: JSON.stringify({
-          query: opts.query,
-          tools: opts.tools,
-          modelId: opts.modelId,
-          includeData: opts.includeData,
-          includeDataUrl: opts.includeDataUrl,
-          queryDepth: opts.queryDepth,
-          stream: false
-        })
+    let terminalError;
+    for await (const event of this.stream(opts)) {
+      if (event.type === "error") {
+        terminalError = {
+          error: event.error,
+          ...event.code ? { code: event.code } : {},
+          ...event.scope ? { scope: event.scope } : {},
+          ...event.reasonCode ? { reasonCode: event.reasonCode } : {}
+        };
+        continue;
+      }
+      if (event.type === "done") {
+        return event.result;
       }
-    );
-    if ("error" in response) {
-      throw new ContextError(
-        response.error,
-        response.code,
-        void 0,
-        response.helpUrl
-      );
     }
-    if (response.success) {
-      return {
-        response: response.response,
-        toolsUsed: response.toolsUsed,
-        cost: response.cost,
-        durationMs: response.durationMs,
-        data: response.data,
-        dataUrl: response.dataUrl
-      };
+    if (terminalError) {
+      throw new ContextError(terminalError.error, terminalError.code);
     }
-    throw new ContextError("Unexpected response format from query API");
+    throw new ContextError("Streaming query ended before done event");
   }
   /**
    * Run an agentic query with streaming. Returns an async iterable that
@@ -305,6 +396,8 @@ 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)
+   * - `error` — A structured query/runtime error emitted before stream completion
    * - `done` — The full response is complete (includes final `QueryResult`)
    *
    * @param options - Query options or a plain string question
@@ -320,9 +413,15 @@ 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;
+   *     case "error":
+   *       console.error("Stream error:", event.error);
+   *       break;
    *   }
    * }
    * ```
@@ -339,7 +438,9 @@ var Query = class {
         modelId: opts.modelId,
         includeData: opts.includeData,
         includeDataUrl: opts.includeDataUrl,
+        includeDeveloperTrace: opts.includeDeveloperTrace,
         queryDepth: opts.queryDepth,
+        debugScoutDeepMode: opts.debugScoutDeepMode,
         stream: true
       })
     });
@@ -350,6 +451,48 @@ 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 = statusTimeline.length > 0 ? this.buildSyntheticTraceFromStreamStatus({
+            statusTimeline,
+            toolsUsed: event.result.toolsUsed,
+            durationMs: event.result.durationMs
+          }) : this.buildSyntheticTraceFromRunResult({
+            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();
@@ -363,7 +506,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 {
             }
           }
@@ -373,7 +519,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 {
           }
         }
@@ -452,30 +601,34 @@ var ContextClient = class {
    *
    * @internal
    */
-  async _fetch(endpoint, options = {}) {
+  async _fetch(endpoint, options = {}, fetchOptions) {
     if (this._closed) {
       throw new ContextError("Client has been closed");
     }
     const url = `${this.baseUrl}${endpoint}`;
     const maxRetries = 3;
     const timeoutMs = this.requestTimeoutMs;
+    const method = (options.method ?? "GET").toUpperCase();
+    const requestHeaders = new Headers(options.headers);
+    const canRetryRequest = fetchOptions?.retry === false ? false : method === "GET" || method === "HEAD" || method === "OPTIONS" || requestHeaders.has("Idempotency-Key");
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), timeoutMs);
+      const mergedHeaders = new Headers(requestHeaders);
+      if (!mergedHeaders.has("Content-Type")) {
+        mergedHeaders.set("Content-Type", "application/json");
+      }
+      mergedHeaders.set("Authorization", `Bearer ${this.apiKey}`);
       try {
         const response = await fetch(url, {
           ...options,
           signal: controller.signal,
-          headers: {
-            "Content-Type": "application/json",
-            Authorization: `Bearer ${this.apiKey}`,
-            ...options.headers
-          }
+          headers: mergedHeaders
         });
         clearTimeout(timeout);
         if (!response.ok) {
-          if (response.status >= 500 && attempt < maxRetries) {
+          if (response.status >= 500 && canRetryRequest && attempt < maxRetries) {
             const delay = Math.min(1e3 * 2 ** attempt, 1e4);
             await new Promise((resolve) => setTimeout(resolve, delay));
             continue;
@@ -494,7 +647,16 @@ var ContextClient = class {
           }
           throw new ContextError(errorMessage, errorCode, response.status, helpUrl);
         }
-        return response.json();
+        try {
+          return await response.json();
+        } catch (error) {
+          const parseError = error instanceof Error ? error : new Error(String(error));
+          throw new ContextError(
+            `Failed to parse JSON response: ${parseError.message}`,
+            void 0,
+            response.status
+          );
+        }
       } catch (error) {
         clearTimeout(timeout);
         if (error instanceof ContextError) {
@@ -502,7 +664,7 @@ var ContextClient = class {
         }
         lastError = error instanceof Error ? error : new Error(String(error));
         const isRetryable = lastError.name === "AbortError" || lastError.message.includes("fetch failed") || lastError.message.includes("ECONNRESET") || lastError.message.includes("ETIMEDOUT");
-        if (isRetryable && attempt < maxRetries) {
+        if (isRetryable && canRetryRequest && attempt < maxRetries) {
           const delay = Math.min(1e3 * 2 ** attempt, 1e4);
           await new Promise((resolve) => setTimeout(resolve, delay));
           continue;