@ctxprotocol/sdk 0.8.3 → 0.8.5

package/dist/index.cjs

@@ -230,11 +230,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.
    *
@@ -263,42 +371,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
@@ -307,6 +398,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
@@ -322,9 +415,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;
    *   }
    * }
    * ```
@@ -341,7 +440,9 @@ var Query = class {
         modelId: opts.modelId,
         includeData: opts.includeData,
         includeDataUrl: opts.includeDataUrl,
+        includeDeveloperTrace: opts.includeDeveloperTrace,
         queryDepth: opts.queryDepth,
+        debugScoutDeepMode: opts.debugScoutDeepMode,
         stream: true
       })
     });
@@ -352,6 +453,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();
@@ -365,7 +508,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 {
             }
           }
@@ -375,7 +521,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 {
           }
         }
@@ -454,30 +603,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;
@@ -496,7 +649,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) {
@@ -504,7 +666,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;