@ctxprotocol/sdk 0.8.2 → 0.8.4

package/dist/client/index.d.ts

@@ -9,9 +9,19 @@ interface ContextClientOptions {
     apiKey: string;
     /**
      * Base URL for the Context Protocol API
-     * @default "https://ctxprotocol.com"
+     * @default "https://www.ctxprotocol.com"
      */
     baseUrl?: string;
+    /**
+     * Request timeout for non-streaming API calls in milliseconds.
+     * @default 300000
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Request timeout for establishing streaming API calls in milliseconds.
+     * @default 600000
+     */
+    streamTimeoutMs?: number;
 }
 /**
  * An individual MCP tool exposed by a tool listing
@@ -287,6 +297,8 @@ interface ExecutionResult<T = unknown> {
     /** Execution duration in milliseconds */
     durationMs: number;
 }
+/** Supported orchestration depth modes for query execution. */
+type QueryDepth = "fast" | "auto" | "deep";
 /**
  * Options for the agentic query endpoint (pay-per-response).
  *
@@ -319,12 +331,80 @@ 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
+     * - `auto`: server decides between fast/deep
+     * - `deep`: full completeness-oriented path
+     */
+    queryDepth?: QueryDepth;
     /**
      * Optional idempotency key (UUID recommended).
      * Reuse the same key when retrying the same logical request.
      */
     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
  */
@@ -364,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
@@ -376,6 +458,7 @@ interface QueryApiSuccessResponse {
     durationMs: number;
     data?: unknown;
     dataUrl?: string;
+    developerTrace?: QueryDeveloperTrace;
 }
 /**
  * Raw API response from the query endpoint
@@ -395,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";
@@ -403,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
  */
@@ -515,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.
      *
@@ -554,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
@@ -569,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;
@@ -607,6 +703,8 @@ declare class Query {
 declare class ContextClient {
     private readonly apiKey;
     private readonly baseUrl;
+    private readonly requestTimeoutMs;
+    private readonly streamTimeoutMs;
     private _closed;
     /**
      * Discovery resource for searching tools
@@ -629,7 +727,9 @@ declare class ContextClient {
      *
      * @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: ContextClientOptions);
     /**
@@ -639,7 +739,7 @@ declare class ContextClient {
     close(): void;
     /**
      * 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
      */
@@ -647,10 +747,11 @@ declare class ContextClient {
     /**
      * 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
      */
     _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,8 @@ var Query = class {
           modelId: opts.modelId,
           includeData: opts.includeData,
           includeDataUrl: opts.includeDataUrl,
+          includeDeveloperTrace: opts.includeDeveloperTrace,
+          queryDepth: opts.queryDepth,
           stream: false
         })
       }
@@ -284,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");
@@ -302,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
@@ -317,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;
@@ -336,6 +455,8 @@ var Query = class {
         modelId: opts.modelId,
         includeData: opts.includeData,
         includeDataUrl: opts.includeDataUrl,
+        includeDeveloperTrace: opts.includeDeveloperTrace,
+        queryDepth: opts.queryDepth,
         stream: true
       })
     });
@@ -346,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();
@@ -359,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 {
             }
           }
@@ -369,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 {
           }
         }
@@ -381,9 +547,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
@@ -406,14 +577,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);
@@ -427,7 +610,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
    */
@@ -437,7 +620,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();
@@ -505,6 +688,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
    */
@@ -513,14 +697,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;