@ctxprotocol/sdk 0.8.3 → 0.8.4

package/dist/client/index.d.cts

@@ -331,6 +331,12 @@ interface QueryOptions {
      * Useful for large payload workflows where inline JSON is not ideal.
      */
     includeDataUrl?: boolean;
+    /**
+     * Include machine-readable developer trace output for this query response.
+     * When enabled, the server may return timeline data describing retries,
+     * fallbacks, loop checks, and intermediate recovery behavior.
+     */
+    includeDeveloperTrace?: boolean;
     /**
      * Query orchestration depth mode:
      * - `fast`: lower-latency path
@@ -344,6 +350,61 @@ interface QueryOptions {
      */
     idempotencyKey?: string;
 }
+/**
+ * Tool reference attached to developer trace timeline steps.
+ */
+interface QueryDeveloperTraceToolRef {
+    id?: string;
+    name?: string;
+    method?: string;
+    [key: string]: unknown;
+}
+/**
+ * Loop metadata attached to developer trace timeline steps.
+ */
+interface QueryDeveloperTraceLoopInfo {
+    name?: string;
+    iteration?: number;
+    maxIterations?: number;
+    [key: string]: unknown;
+}
+/**
+ * A single developer-trace timeline step.
+ */
+interface QueryDeveloperTraceStep {
+    stepType?: string;
+    event?: string;
+    status?: string;
+    message?: string;
+    timestampMs?: number;
+    tool?: QueryDeveloperTraceToolRef;
+    attempt?: number;
+    loop?: QueryDeveloperTraceLoopInfo;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Aggregate counters that summarize developer-trace behavior.
+ */
+interface QueryDeveloperTraceSummary {
+    toolCalls?: number;
+    retryCount?: number;
+    selfHealCount?: number;
+    fallbackCount?: number;
+    failureCount?: number;
+    recoveryCount?: number;
+    completionChecks?: number;
+    loopCount?: number;
+    [key: string]: unknown;
+}
+/**
+ * Developer Mode trace payload returned per query response (opt-in).
+ */
+interface QueryDeveloperTrace {
+    summary?: QueryDeveloperTraceSummary;
+    timeline?: QueryDeveloperTraceStep[];
+    [key: string]: unknown;
+}
 /**
  * Information about a tool that was used during a query response
  */
@@ -383,6 +444,8 @@ interface QueryResult {
     data?: unknown;
     /** Optional blob URL for persisted execution data (when includeDataUrl=true) */
     dataUrl?: string;
+    /** Optional machine-readable Developer Mode trace payload */
+    developerTrace?: QueryDeveloperTrace;
 }
 /**
  * Successful response from the /api/v1/query endpoint
@@ -395,6 +458,7 @@ interface QueryApiSuccessResponse {
     durationMs: number;
     data?: unknown;
     dataUrl?: string;
+    developerTrace?: QueryDeveloperTrace;
 }
 /**
  * Raw API response from the query endpoint
@@ -414,6 +478,11 @@ interface QueryStreamTextDeltaEvent {
     type: "text-delta";
     delta: string;
 }
+/** Emitted when the server streams developer trace updates/chunks */
+interface QueryStreamDeveloperTraceEvent {
+    type: "developer-trace";
+    trace: QueryDeveloperTrace;
+}
 /** Emitted when the full response is complete */
 interface QueryStreamDoneEvent {
     type: "done";
@@ -422,7 +491,7 @@ interface QueryStreamDoneEvent {
 /**
  * Union of all events emitted during a streaming query
  */
-type QueryStreamEvent = QueryStreamToolStatusEvent | QueryStreamTextDeltaEvent | QueryStreamDoneEvent;
+type QueryStreamEvent = QueryStreamToolStatusEvent | QueryStreamTextDeltaEvent | QueryStreamDeveloperTraceEvent | QueryStreamDoneEvent;
 /**
  * Specific error codes returned by the Context Protocol API
  */
@@ -534,6 +603,10 @@ declare class Tools {
 declare class Query {
     private client;
     constructor(client: ContextClient);
+    private buildSyntheticTraceFromRunResult;
+    private buildSyntheticTraceFromStreamStatus;
+    private mergeDeveloperTrace;
+    private parseStreamEvent;
     /**
      * Run an agentic query and wait for the full response.
      *
@@ -573,6 +646,7 @@ declare class Query {
      * 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
@@ -588,6 +662,9 @@ declare class Query {
      *     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;
@@ -677,4 +754,4 @@ declare class ContextClient {
     _fetchRaw(endpoint: string, options?: RequestInit): Promise<Response>;
 }
 
-export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecuteSessionApiResponse, type ExecuteSessionApiSuccessResponse, type ExecuteSessionResult, type ExecuteSessionSpend, type ExecuteSessionStartOptions, type ExecuteSessionStatus, type ExecutionResult, type McpTool, type McpToolMeta, type McpToolRateLimitHints, Query, type QueryApiResponse, type QueryApiSuccessResponse, type QueryCost, type QueryOptions, type QueryResult, type QueryStreamDoneEvent, type QueryStreamEvent, type QueryStreamTextDeltaEvent, type QueryStreamToolStatusEvent, type QueryToolUsage, type SearchOptions, type SearchResponse, type Tool, Tools };
+export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecuteSessionApiResponse, type ExecuteSessionApiSuccessResponse, type ExecuteSessionResult, type ExecuteSessionSpend, type ExecuteSessionStartOptions, type ExecuteSessionStatus, type ExecutionResult, type McpTool, type McpToolMeta, type McpToolRateLimitHints, Query, type QueryApiResponse, type QueryApiSuccessResponse, type QueryCost, type QueryDeveloperTrace, type QueryDeveloperTraceLoopInfo, type QueryDeveloperTraceStep, type QueryDeveloperTraceSummary, type QueryDeveloperTraceToolRef, type QueryOptions, type QueryResult, type QueryStreamDeveloperTraceEvent, type QueryStreamDoneEvent, type QueryStreamEvent, type QueryStreamTextDeltaEvent, type QueryStreamToolStatusEvent, type QueryToolUsage, type SearchOptions, type SearchResponse, type Tool, Tools };

package/dist/client/index.d.ts

@@ -331,6 +331,12 @@ interface QueryOptions {
      * Useful for large payload workflows where inline JSON is not ideal.
      */
     includeDataUrl?: boolean;
+    /**
+     * Include machine-readable developer trace output for this query response.
+     * When enabled, the server may return timeline data describing retries,
+     * fallbacks, loop checks, and intermediate recovery behavior.
+     */
+    includeDeveloperTrace?: boolean;
     /**
      * Query orchestration depth mode:
      * - `fast`: lower-latency path
@@ -344,6 +350,61 @@ interface QueryOptions {
      */
     idempotencyKey?: string;
 }
+/**
+ * Tool reference attached to developer trace timeline steps.
+ */
+interface QueryDeveloperTraceToolRef {
+    id?: string;
+    name?: string;
+    method?: string;
+    [key: string]: unknown;
+}
+/**
+ * Loop metadata attached to developer trace timeline steps.
+ */
+interface QueryDeveloperTraceLoopInfo {
+    name?: string;
+    iteration?: number;
+    maxIterations?: number;
+    [key: string]: unknown;
+}
+/**
+ * A single developer-trace timeline step.
+ */
+interface QueryDeveloperTraceStep {
+    stepType?: string;
+    event?: string;
+    status?: string;
+    message?: string;
+    timestampMs?: number;
+    tool?: QueryDeveloperTraceToolRef;
+    attempt?: number;
+    loop?: QueryDeveloperTraceLoopInfo;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Aggregate counters that summarize developer-trace behavior.
+ */
+interface QueryDeveloperTraceSummary {
+    toolCalls?: number;
+    retryCount?: number;
+    selfHealCount?: number;
+    fallbackCount?: number;
+    failureCount?: number;
+    recoveryCount?: number;
+    completionChecks?: number;
+    loopCount?: number;
+    [key: string]: unknown;
+}
+/**
+ * Developer Mode trace payload returned per query response (opt-in).
+ */
+interface QueryDeveloperTrace {
+    summary?: QueryDeveloperTraceSummary;
+    timeline?: QueryDeveloperTraceStep[];
+    [key: string]: unknown;
+}
 /**
  * Information about a tool that was used during a query response
  */
@@ -383,6 +444,8 @@ interface QueryResult {
     data?: unknown;
     /** Optional blob URL for persisted execution data (when includeDataUrl=true) */
     dataUrl?: string;
+    /** Optional machine-readable Developer Mode trace payload */
+    developerTrace?: QueryDeveloperTrace;
 }
 /**
  * Successful response from the /api/v1/query endpoint
@@ -395,6 +458,7 @@ interface QueryApiSuccessResponse {
     durationMs: number;
     data?: unknown;
     dataUrl?: string;
+    developerTrace?: QueryDeveloperTrace;
 }
 /**
  * Raw API response from the query endpoint
@@ -414,6 +478,11 @@ interface QueryStreamTextDeltaEvent {
     type: "text-delta";
     delta: string;
 }
+/** Emitted when the server streams developer trace updates/chunks */
+interface QueryStreamDeveloperTraceEvent {
+    type: "developer-trace";
+    trace: QueryDeveloperTrace;
+}
 /** Emitted when the full response is complete */
 interface QueryStreamDoneEvent {
     type: "done";
@@ -422,7 +491,7 @@ interface QueryStreamDoneEvent {
 /**
  * Union of all events emitted during a streaming query
  */
-type QueryStreamEvent = QueryStreamToolStatusEvent | QueryStreamTextDeltaEvent | QueryStreamDoneEvent;
+type QueryStreamEvent = QueryStreamToolStatusEvent | QueryStreamTextDeltaEvent | QueryStreamDeveloperTraceEvent | QueryStreamDoneEvent;
 /**
  * Specific error codes returned by the Context Protocol API
  */
@@ -534,6 +603,10 @@ declare class Tools {
 declare class Query {
     private client;
     constructor(client: ContextClient);
+    private buildSyntheticTraceFromRunResult;
+    private buildSyntheticTraceFromStreamStatus;
+    private mergeDeveloperTrace;
+    private parseStreamEvent;
     /**
      * Run an agentic query and wait for the full response.
      *
@@ -573,6 +646,7 @@ declare class Query {
      * 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
@@ -588,6 +662,9 @@ declare class Query {
      *     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;
@@ -677,4 +754,4 @@ declare class ContextClient {
     _fetchRaw(endpoint: string, options?: RequestInit): Promise<Response>;
 }
 
-export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecuteSessionApiResponse, type ExecuteSessionApiSuccessResponse, type ExecuteSessionResult, type ExecuteSessionSpend, type ExecuteSessionStartOptions, type ExecuteSessionStatus, type ExecutionResult, type McpTool, type McpToolMeta, type McpToolRateLimitHints, Query, type QueryApiResponse, type QueryApiSuccessResponse, type QueryCost, type QueryOptions, type QueryResult, type QueryStreamDoneEvent, type QueryStreamEvent, type QueryStreamTextDeltaEvent, type QueryStreamToolStatusEvent, type QueryToolUsage, type SearchOptions, type SearchResponse, type Tool, Tools };
+export { ContextClient, type ContextClientOptions, ContextError, type ContextErrorCode, Discovery, type ExecuteApiErrorResponse, type ExecuteApiResponse, type ExecuteApiSuccessResponse, type ExecuteOptions, type ExecuteSessionApiResponse, type ExecuteSessionApiSuccessResponse, type ExecuteSessionResult, type ExecuteSessionSpend, type ExecuteSessionStartOptions, type ExecuteSessionStatus, type ExecutionResult, type McpTool, type McpToolMeta, type McpToolRateLimitHints, Query, type QueryApiResponse, type QueryApiSuccessResponse, type QueryCost, type QueryDeveloperTrace, type QueryDeveloperTraceLoopInfo, type QueryDeveloperTraceStep, type QueryDeveloperTraceSummary, type QueryDeveloperTraceToolRef, type QueryOptions, type QueryResult, type QueryStreamDeveloperTraceEvent, type QueryStreamDoneEvent, type QueryStreamEvent, type QueryStreamTextDeltaEvent, type QueryStreamToolStatusEvent, type QueryToolUsage, type SearchOptions, type SearchResponse, type Tool, Tools };

package/dist/client/index.js

@@ -226,6 +226,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.
    *
@@ -271,6 +379,7 @@ var Query = class {
           modelId: opts.modelId,
           includeData: opts.includeData,
           includeDataUrl: opts.includeDataUrl,
+          includeDeveloperTrace: opts.includeDeveloperTrace,
           queryDepth: opts.queryDepth,
           stream: false
         })
@@ -285,13 +394,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");
@@ -303,6 +417,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
@@ -318,6 +433,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;
@@ -337,6 +455,7 @@ var Query = class {
         modelId: opts.modelId,
         includeData: opts.includeData,
         includeDataUrl: opts.includeDataUrl,
+        includeDeveloperTrace: opts.includeDeveloperTrace,
         queryDepth: opts.queryDepth,
         stream: true
       })
@@ -348,6 +467,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 +519,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 +532,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 {
           }
         }