@ctxprotocol/sdk 0.11.1 → 0.13.0

package/dist/{types-DRbq-FA6.d.cts → types-DPxI353c.d.cts}

@@ -221,7 +221,7 @@ interface McpToolRateLimitHints {
     supportsBulk?: boolean;
     /** Preferred batch-oriented methods to call instead of fan-out loops */
     recommendedBatchTools?: string[];
-    /** Optional human-readable notes for planning */
+    /** Optional human-readable notes for execution behavior */
     notes?: string;
 }
 type DiscoveryMode = "query" | "execute";
@@ -237,7 +237,7 @@ interface McpToolMeta {
     surface?: McpToolSurface;
     /** Whether this method can be selected in query mode */
     queryEligible?: boolean;
-    /** Declared latency class for planner/runtime gating */
+    /** Declared latency class for metadata-scout/runtime gating */
     latencyClass?: McpToolLatencyClass;
     /** Method-level pricing metadata */
     pricing?: McpToolPricingMeta;
@@ -248,7 +248,7 @@ interface McpToolMeta {
     /** Context injection requirements handled by the Context runtime */
     contextRequirements?: string[];
     /**
-     * Optional planner/runtime pacing hints.
+     * Optional metadata-scout/runtime pacing hints.
      * Tool contributors can publish these to reduce rate-limit failures.
      */
     rateLimit?: McpToolRateLimitHints;
@@ -363,6 +363,13 @@ interface SearchOptions {
     excludeLatencyClasses?: McpToolLatencyClass[];
     /** Convenience switch to exclude slow methods in query mode */
     excludeSlow?: boolean;
+    /**
+     * Restrict discovery to the caller's favorite tools.
+     * - `true`: force favorites-only discovery for this request
+     * - `false`: force unrestricted discovery for this request
+     * - omitted: use the account-level default from Context settings
+     */
+    favoritesOnly?: boolean;
 }
 /**
  * Options for updating a tool listing via `client.developer.updateTool()`.
@@ -505,8 +512,6 @@ interface ExecutionResult<T = unknown> {
     /** Execution duration in milliseconds */
     durationMs: number;
 }
-/** Supported orchestration depth modes for query execution. */
-type QueryDepth = "fast" | "auto" | "deep";
 type QueryDeepMode = "deep" | "deep-light" | "deep-heavy";
 type QueryClarificationPolicy = "return" | "auto" | "error";
 type QueryOutcomeType = "answer" | "clarification_required" | "capability_miss";
@@ -602,19 +607,22 @@ interface QueryClarificationDiagnostics {
  * Options for the agentic query endpoint (pay-per-response).
  *
  * Unlike `execute()` which calls a single tool once, `query()` sends a
- * natural-language question and lets the server handle discovery-first
- * orchestration (`discover/probe -> plan-from-evidence -> execute ->
- * bounded fallback`) plus synthesis.
+ * natural-language question and lets the server handle the live librarian
+ * pipeline (`discover -> select -> metadata scout -> clarify if needed ->
+ * iterative execute -> synthesize -> settle`).
  * One flat fee covers up to 100 MCP skill calls per tool.
  */
 interface QueryOptions {
     /** The natural-language question to answer */
     query: string;
     /**
-     * How the SDK should handle clarification-required pre-plan situations:
+     * How the SDK should handle clarification-required situations:
      * - `return`: surface a structured clarification result to the caller
      * - `auto`: enable clarification auto-select and continue with the server's deterministic recommended option
      * - `error`: turn structured clarification/capability outcomes into terminal errors
+     *
+     * Default behavior is surface-dependent: headless SDK and MCP callers default
+     * to `auto`, while first-party chat defaults to `return`.
      */
     clarificationPolicy?: QueryClarificationPolicy;
     /**
@@ -623,6 +631,14 @@ interface QueryOptions {
      * (Manual Mode).
      */
     tools?: string[];
+    /**
+     * Restrict auto-discovery to the caller's favorite tools.
+     * Ignored when `tools` is provided because manual tool selection wins.
+     * - `true`: force favorites-only discovery for this request
+     * - `false`: force unrestricted discovery for this request
+     * - omitted: use the account-level default from Context settings
+     */
+    favoritesOnly?: boolean;
     /**
      * Resume a prior durable query attempt from its latest checkpoint.
      * Cannot be combined with `tools` or `forkFrom`.
@@ -662,23 +678,10 @@ interface QueryOptions {
     /**
      * Include machine-readable developer trace output for this query response.
      * When enabled, the server may return summary counters plus diagnostics
-     * for lane selection, scout probe adequacy, and bounded fallback behavior.
+     * for lane selection, metadata scout adequacy, clarification, and iterative
+     * execution behavior.
      */
     includeDeveloperTrace?: boolean;
-    /**
-     * Query orchestration depth mode:
-     * - `fast`: lower-latency path
-     * - `auto`: server decides between fast/deep
-     * - `deep`: full completeness-oriented path
-     */
-    queryDepth?: QueryDepth;
-    /**
-     * Development/testing only: force the server's internal deep lane.
-     * `deep` is the canonical value. Legacy `deep-light` / `deep-heavy`
-     * aliases are still accepted temporarily for compatibility and normalize
-     * to the same runtime lane. Invalid when `queryDepth` is `fast`.
-     */
-    debugScoutDeepMode?: QueryDeepMode;
     /**
      * Optional idempotency key (UUID recommended).
      * Reuse the same key when retrying the same logical request.
@@ -704,7 +707,7 @@ interface QueryDeveloperTraceLoopInfo {
     [key: string]: unknown;
 }
 /**
- * Tool selection metadata attached to discovery/planning diagnostics.
+ * Tool selection metadata attached to discovery and metadata-scout diagnostics.
  */
 interface QueryDeveloperTraceToolSelection {
     toolId: string;
@@ -715,7 +718,7 @@ interface QueryDeveloperTraceToolSelection {
     priceUsd?: string;
 }
 /**
- * Initial planner diagnostic details.
+ * Execution-contract details handed to the iterative runtime.
  */
 interface QueryPlanningTraceDiagnostic {
     plannerQuery: string;
@@ -723,25 +726,6 @@ interface QueryPlanningTraceDiagnostic {
     scoutEvidencePromptBlock: string | null;
     allowedModules: string[];
 }
-/**
- * Rediscovery/fallback diagnostic details.
- */
-interface QueryRediscoveryTraceDiagnostic {
-    considered: boolean;
-    executed: boolean;
-    skipReason: string | null;
-    missingCapability: string | null;
-    rediscoveryQuery: string | null;
-    capabilityLooksLikeSearchNeed: boolean;
-    allowSearchFallbackOnElapsedCap: boolean;
-    searchFallbackUsed: boolean;
-    preRediscoveryBudgetReasonCode: string | null;
-    candidateSearchResults: QueryDeveloperTraceToolSelection[];
-    selectedAlternatives: QueryDeveloperTraceToolSelection[];
-    mergedTools: QueryDeveloperTraceToolSelection[];
-    usingPaidFallback: boolean;
-    branchPlan: QueryPlanningTraceDiagnostic | null;
-}
 interface QueryCompletenessRepairEvent {
     attempt: number;
     outcome: "attempted" | "skipped_by_guardrail" | "skipped_no_retry_budget" | "skipped_needs_different_tools" | "skipped_no_retry_path" | "patch_failed" | "replan_failed" | "patched" | "replanned";
@@ -762,16 +746,15 @@ interface QueryCompletenessRepairEvent {
     }>;
 }
 /**
- * Rich developer-trace diagnostics for discovery-first orchestration internals.
+ * Rich developer-trace diagnostics for managed query-runtime internals.
  */
 interface QueryDeveloperTraceDiagnostics {
     selection: {
-        selectedDepth: string;
-        deepMode: string | null;
+        selectedPolicy: string;
         debugScoutDeepMode: string | null;
         plannerReasoningStage: string;
         scoutEnabled: boolean;
-        preserveFastOneShot: boolean;
+        oneShotBias: boolean;
         candidateMethodCount: number;
         scoutProbeStatus: string;
         scoutProbeAdequacy: string;
@@ -786,8 +769,7 @@ interface QueryDeveloperTraceDiagnostics {
         scoutPrePlanProbeBudgetReasonCode: string | null;
         scoutChangedInitialPlan: boolean;
         scoutChangedPlannerReasoningStage: boolean;
-        scoutInitialSelectedDepth: string;
-        scoutInitialDeepMode: string | null;
+        scoutInitialSelectedPolicy: string;
         scoutInitialPlannerReasoningStage: string;
         scoutInitialReasonCode: string;
         scoutFinalReasonCode: string;
@@ -797,9 +779,7 @@ interface QueryDeveloperTraceDiagnostics {
         scoutLlmSelectionLatencyMs: number | null;
         selectedTools: QueryDeveloperTraceToolSelection[];
     };
-    planning: {
-        initial: QueryPlanningTraceDiagnostic;
-    };
+    executionContract?: QueryPlanningTraceDiagnostic;
     cost?: {
         planningCostUsd: number;
         initialExecutionCostUsd: number;
@@ -809,13 +789,20 @@ interface QueryDeveloperTraceDiagnostics {
         toolCostUsd: number;
         totalChargedUsd: number;
     };
-    completeness: {
+    verification: {
         evaluations: unknown[];
         repairEvents: QueryCompletenessRepairEvent[];
         triggerNeedsDifferentTools: boolean;
         triggerMissingCapability: string | null;
     };
-    rediscovery: QueryRediscoveryTraceDiagnostic | null;
+    execution?: {
+        reasoningEnabled: boolean;
+        receivedReasoning: boolean;
+        reasoningChars: number;
+        scoutEvidenceInjected: boolean;
+        stepBudget: number;
+        completedStepCount: number;
+    };
     clarification?: QueryClarificationDiagnostics;
     contributorSearches?: ContributorSearchTraceRecord[];
     [key: string]: unknown;
@@ -849,6 +836,25 @@ interface QueryDeveloperTraceSummary {
     loopCount?: number;
     [key: string]: unknown;
 }
+/**
+ * Full tool call record (untruncated) for debugging.
+ */
+interface QueryDeveloperTraceToolCall {
+    toolId?: string;
+    toolName: string;
+    args?: unknown;
+    result: unknown;
+}
+/**
+ * MCP method schema exposed in the developer trace.
+ */
+interface QueryDeveloperTraceToolSchema {
+    serverName: string;
+    toolName: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
 /**
  * Developer Mode trace payload returned per query response (opt-in).
  */
@@ -859,6 +865,15 @@ interface QueryDeveloperTrace {
     query?: string;
     source?: string;
     diagnostics?: QueryDeveloperTraceDiagnostics;
+    initialCode?: string;
+    finalCode?: string;
+    executionTrace?: unknown[];
+    executionProgram?: unknown;
+    attemptCount?: number;
+    executionSuccess?: boolean;
+    executionResult?: unknown;
+    toolCallHistory?: QueryDeveloperTraceToolCall[];
+    toolSchemas?: QueryDeveloperTraceToolSchema[];
     [key: string]: unknown;
 }
 /**

package/dist/{types-DRbq-FA6.d.ts → types-DPxI353c.d.ts}

@@ -221,7 +221,7 @@ interface McpToolRateLimitHints {
     supportsBulk?: boolean;
     /** Preferred batch-oriented methods to call instead of fan-out loops */
     recommendedBatchTools?: string[];
-    /** Optional human-readable notes for planning */
+    /** Optional human-readable notes for execution behavior */
     notes?: string;
 }
 type DiscoveryMode = "query" | "execute";
@@ -237,7 +237,7 @@ interface McpToolMeta {
     surface?: McpToolSurface;
     /** Whether this method can be selected in query mode */
     queryEligible?: boolean;
-    /** Declared latency class for planner/runtime gating */
+    /** Declared latency class for metadata-scout/runtime gating */
     latencyClass?: McpToolLatencyClass;
     /** Method-level pricing metadata */
     pricing?: McpToolPricingMeta;
@@ -248,7 +248,7 @@ interface McpToolMeta {
     /** Context injection requirements handled by the Context runtime */
     contextRequirements?: string[];
     /**
-     * Optional planner/runtime pacing hints.
+     * Optional metadata-scout/runtime pacing hints.
      * Tool contributors can publish these to reduce rate-limit failures.
      */
     rateLimit?: McpToolRateLimitHints;
@@ -363,6 +363,13 @@ interface SearchOptions {
     excludeLatencyClasses?: McpToolLatencyClass[];
     /** Convenience switch to exclude slow methods in query mode */
     excludeSlow?: boolean;
+    /**
+     * Restrict discovery to the caller's favorite tools.
+     * - `true`: force favorites-only discovery for this request
+     * - `false`: force unrestricted discovery for this request
+     * - omitted: use the account-level default from Context settings
+     */
+    favoritesOnly?: boolean;
 }
 /**
  * Options for updating a tool listing via `client.developer.updateTool()`.
@@ -505,8 +512,6 @@ interface ExecutionResult<T = unknown> {
     /** Execution duration in milliseconds */
     durationMs: number;
 }
-/** Supported orchestration depth modes for query execution. */
-type QueryDepth = "fast" | "auto" | "deep";
 type QueryDeepMode = "deep" | "deep-light" | "deep-heavy";
 type QueryClarificationPolicy = "return" | "auto" | "error";
 type QueryOutcomeType = "answer" | "clarification_required" | "capability_miss";
@@ -602,19 +607,22 @@ interface QueryClarificationDiagnostics {
  * Options for the agentic query endpoint (pay-per-response).
  *
  * Unlike `execute()` which calls a single tool once, `query()` sends a
- * natural-language question and lets the server handle discovery-first
- * orchestration (`discover/probe -> plan-from-evidence -> execute ->
- * bounded fallback`) plus synthesis.
+ * natural-language question and lets the server handle the live librarian
+ * pipeline (`discover -> select -> metadata scout -> clarify if needed ->
+ * iterative execute -> synthesize -> settle`).
  * One flat fee covers up to 100 MCP skill calls per tool.
  */
 interface QueryOptions {
     /** The natural-language question to answer */
     query: string;
     /**
-     * How the SDK should handle clarification-required pre-plan situations:
+     * How the SDK should handle clarification-required situations:
      * - `return`: surface a structured clarification result to the caller
      * - `auto`: enable clarification auto-select and continue with the server's deterministic recommended option
      * - `error`: turn structured clarification/capability outcomes into terminal errors
+     *
+     * Default behavior is surface-dependent: headless SDK and MCP callers default
+     * to `auto`, while first-party chat defaults to `return`.
      */
     clarificationPolicy?: QueryClarificationPolicy;
     /**
@@ -623,6 +631,14 @@ interface QueryOptions {
      * (Manual Mode).
      */
     tools?: string[];
+    /**
+     * Restrict auto-discovery to the caller's favorite tools.
+     * Ignored when `tools` is provided because manual tool selection wins.
+     * - `true`: force favorites-only discovery for this request
+     * - `false`: force unrestricted discovery for this request
+     * - omitted: use the account-level default from Context settings
+     */
+    favoritesOnly?: boolean;
     /**
      * Resume a prior durable query attempt from its latest checkpoint.
      * Cannot be combined with `tools` or `forkFrom`.
@@ -662,23 +678,10 @@ interface QueryOptions {
     /**
      * Include machine-readable developer trace output for this query response.
      * When enabled, the server may return summary counters plus diagnostics
-     * for lane selection, scout probe adequacy, and bounded fallback behavior.
+     * for lane selection, metadata scout adequacy, clarification, and iterative
+     * execution behavior.
      */
     includeDeveloperTrace?: boolean;
-    /**
-     * Query orchestration depth mode:
-     * - `fast`: lower-latency path
-     * - `auto`: server decides between fast/deep
-     * - `deep`: full completeness-oriented path
-     */
-    queryDepth?: QueryDepth;
-    /**
-     * Development/testing only: force the server's internal deep lane.
-     * `deep` is the canonical value. Legacy `deep-light` / `deep-heavy`
-     * aliases are still accepted temporarily for compatibility and normalize
-     * to the same runtime lane. Invalid when `queryDepth` is `fast`.
-     */
-    debugScoutDeepMode?: QueryDeepMode;
     /**
      * Optional idempotency key (UUID recommended).
      * Reuse the same key when retrying the same logical request.
@@ -704,7 +707,7 @@ interface QueryDeveloperTraceLoopInfo {
     [key: string]: unknown;
 }
 /**
- * Tool selection metadata attached to discovery/planning diagnostics.
+ * Tool selection metadata attached to discovery and metadata-scout diagnostics.
  */
 interface QueryDeveloperTraceToolSelection {
     toolId: string;
@@ -715,7 +718,7 @@ interface QueryDeveloperTraceToolSelection {
     priceUsd?: string;
 }
 /**
- * Initial planner diagnostic details.
+ * Execution-contract details handed to the iterative runtime.
  */
 interface QueryPlanningTraceDiagnostic {
     plannerQuery: string;
@@ -723,25 +726,6 @@ interface QueryPlanningTraceDiagnostic {
     scoutEvidencePromptBlock: string | null;
     allowedModules: string[];
 }
-/**
- * Rediscovery/fallback diagnostic details.
- */
-interface QueryRediscoveryTraceDiagnostic {
-    considered: boolean;
-    executed: boolean;
-    skipReason: string | null;
-    missingCapability: string | null;
-    rediscoveryQuery: string | null;
-    capabilityLooksLikeSearchNeed: boolean;
-    allowSearchFallbackOnElapsedCap: boolean;
-    searchFallbackUsed: boolean;
-    preRediscoveryBudgetReasonCode: string | null;
-    candidateSearchResults: QueryDeveloperTraceToolSelection[];
-    selectedAlternatives: QueryDeveloperTraceToolSelection[];
-    mergedTools: QueryDeveloperTraceToolSelection[];
-    usingPaidFallback: boolean;
-    branchPlan: QueryPlanningTraceDiagnostic | null;
-}
 interface QueryCompletenessRepairEvent {
     attempt: number;
     outcome: "attempted" | "skipped_by_guardrail" | "skipped_no_retry_budget" | "skipped_needs_different_tools" | "skipped_no_retry_path" | "patch_failed" | "replan_failed" | "patched" | "replanned";
@@ -762,16 +746,15 @@ interface QueryCompletenessRepairEvent {
     }>;
 }
 /**
- * Rich developer-trace diagnostics for discovery-first orchestration internals.
+ * Rich developer-trace diagnostics for managed query-runtime internals.
  */
 interface QueryDeveloperTraceDiagnostics {
     selection: {
-        selectedDepth: string;
-        deepMode: string | null;
+        selectedPolicy: string;
         debugScoutDeepMode: string | null;
         plannerReasoningStage: string;
         scoutEnabled: boolean;
-        preserveFastOneShot: boolean;
+        oneShotBias: boolean;
         candidateMethodCount: number;
         scoutProbeStatus: string;
         scoutProbeAdequacy: string;
@@ -786,8 +769,7 @@ interface QueryDeveloperTraceDiagnostics {
         scoutPrePlanProbeBudgetReasonCode: string | null;
         scoutChangedInitialPlan: boolean;
         scoutChangedPlannerReasoningStage: boolean;
-        scoutInitialSelectedDepth: string;
-        scoutInitialDeepMode: string | null;
+        scoutInitialSelectedPolicy: string;
         scoutInitialPlannerReasoningStage: string;
         scoutInitialReasonCode: string;
         scoutFinalReasonCode: string;
@@ -797,9 +779,7 @@ interface QueryDeveloperTraceDiagnostics {
         scoutLlmSelectionLatencyMs: number | null;
         selectedTools: QueryDeveloperTraceToolSelection[];
     };
-    planning: {
-        initial: QueryPlanningTraceDiagnostic;
-    };
+    executionContract?: QueryPlanningTraceDiagnostic;
     cost?: {
         planningCostUsd: number;
         initialExecutionCostUsd: number;
@@ -809,13 +789,20 @@ interface QueryDeveloperTraceDiagnostics {
         toolCostUsd: number;
         totalChargedUsd: number;
     };
-    completeness: {
+    verification: {
         evaluations: unknown[];
         repairEvents: QueryCompletenessRepairEvent[];
         triggerNeedsDifferentTools: boolean;
         triggerMissingCapability: string | null;
     };
-    rediscovery: QueryRediscoveryTraceDiagnostic | null;
+    execution?: {
+        reasoningEnabled: boolean;
+        receivedReasoning: boolean;
+        reasoningChars: number;
+        scoutEvidenceInjected: boolean;
+        stepBudget: number;
+        completedStepCount: number;
+    };
     clarification?: QueryClarificationDiagnostics;
     contributorSearches?: ContributorSearchTraceRecord[];
     [key: string]: unknown;
@@ -849,6 +836,25 @@ interface QueryDeveloperTraceSummary {
     loopCount?: number;
     [key: string]: unknown;
 }
+/**
+ * Full tool call record (untruncated) for debugging.
+ */
+interface QueryDeveloperTraceToolCall {
+    toolId?: string;
+    toolName: string;
+    args?: unknown;
+    result: unknown;
+}
+/**
+ * MCP method schema exposed in the developer trace.
+ */
+interface QueryDeveloperTraceToolSchema {
+    serverName: string;
+    toolName: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
 /**
  * Developer Mode trace payload returned per query response (opt-in).
  */
@@ -859,6 +865,15 @@ interface QueryDeveloperTrace {
     query?: string;
     source?: string;
     diagnostics?: QueryDeveloperTraceDiagnostics;
+    initialCode?: string;
+    finalCode?: string;
+    executionTrace?: unknown[];
+    executionProgram?: unknown;
+    attemptCount?: number;
+    executionSuccess?: boolean;
+    executionResult?: unknown;
+    toolCallHistory?: QueryDeveloperTraceToolCall[];
+    toolSchemas?: QueryDeveloperTraceToolSchema[];
     [key: string]: unknown;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctxprotocol/sdk",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Official TypeScript SDK for the Context Protocol - Discover and execute AI tools programmatically",
   "type": "module",
   "main": "./dist/index.cjs",