@ctxprotocol/sdk 0.9.0 → 0.11.0

package/README.md

@@ -96,16 +96,19 @@ const result = await client.tools.execute({
 console.log(result.session); // methodPrice, spent, remaining, maxSpend, ...
 ```
 
-**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:
+**Query mode** gives you a managed librarian contract — the server runs a discovery-first planner contract (`discover/probe -> plan-from-evidence -> execute -> bounded fallback`) with model-aware context budgeting and can return plain answers or structured evidence packages 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
+  answerModelId: "glm-model", // optional: choose the final synthesis model
+  responseShape: "answer_with_evidence", // optional: answer | answer_with_evidence | evidence_only
   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.response);   // response text or summary
+console.log(answer.summary);    // short machine-friendly summary
+console.log(answer.evidence);   // structured evidence package
 console.log(answer.toolsUsed);  // Which tools were used
 console.log(answer.cost);       // Cost breakdown
 console.log(answer.dataUrl);    // Optional blob URL with full data
@@ -114,6 +117,16 @@ console.log(answer.developerTrace?.diagnostics?.selection); // lane + scout prob
 console.log(answer.orchestrationMetrics); // high-level first-pass / rediscovery metrics
 ```
 
+`responseShape` options:
+
+- `answer`: backward-compatible prose answer
+- `answer_with_evidence`: prose plus `summary`, `evidence`, `artifacts`, `freshness`, `confidence`, `usage`, `outcome`, and `controller`
+- `evidence_only`: machine-friendly summary plus the same evidence package for downstream agents
+
+Premium wedge answers can also expose `evidence.marketIntelligence`, `view.rows`, `view.columns`, and the top-level controller fields `stopReason`, `issueClass`, and `actionsTaken`.
+
+The first-party chat app uses the same Query contract and defaults to `answer_with_evidence`.
+
 > Mixed listings are first-class: one listing can expose methods to both surfaces. Methods without `_meta.pricing.executeUsd` remain query-only until priced.
 >
 > Compatibility: SDK/API payload fields such as `price` and `pricePerQuery` are retained for backward compatibility. In Query mode, they represent listing-level **price per response turn**.
@@ -128,8 +141,11 @@ const client = new ContextClient({
   apiKey: "sk_live_...",
 });
 
-// Pay-per-response: Ask a question, get a curated answer
-const answer = await client.query.run("What are the top whale movements on Base?");
+// Pay-per-response: Ask a question, get a managed answer package
+const answer = await client.query.run({
+  query: "What are the top whale movements on Base?",
+  responseShape: "answer_with_evidence",
+});
 console.log(answer.response);
 
 // Execute surface: require explicit execute pricing
@@ -402,7 +418,7 @@ const closed = await client.tools.closeSession("sess_123");
 
 #### `client.query.run(options)`
 
-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.
+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 the selected Query response contract (`answer`, `answer_with_evidence`, or `evidence_only`).
 
 `queryDepth` controls orchestration depth:
 - `fast`: lower-latency path for simple lookups.
@@ -422,14 +438,14 @@ const answer = await client.query.run("What are the top whale movements on Base?
 const answer = await client.query.run({
   query: "Analyze whale activity on Base",
   tools: ["tool-uuid-1", "tool-uuid-2"],  // optional — auto-discover if omitted
-  modelId: "kimi-model-thinking",          // optional
+  answerModelId: "kimi-model-thinking",    // optional final synthesis model
   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
+console.log(answer.response);     // response text or summary
 console.log(answer.toolsUsed);    // [{ id, name, skillCalls }]
 console.log(answer.cost);         // { modelCostUsd, toolCostUsd, totalCostUsd }
 console.log(answer.durationMs);   // Total time
@@ -564,7 +580,7 @@ interface ExecutionResult<T = unknown> {
 
 ```typescript
 interface QueryResult {
-  response: string;                    // AI-synthesized answer
+  response: string;                    // response text or summary
   toolsUsed: QueryToolUsage[];         // Tools used: { id, name, skillCalls }
   cost: QueryCost;                     // { modelCostUsd, toolCostUsd, totalCostUsd }
   durationMs: number;

package/dist/client/index.cjs

@@ -1,6 +1,18 @@
 'use strict';
 
 // src/client/types.ts
+var ALLOWED_TOOL_CATEGORIES = [
+  "Crypto & DeFi",
+  "Financial Markets",
+  "Business & Sales",
+  "Marketing & SEO",
+  "Legal & Regulatory",
+  "Real World",
+  "Developer Tools",
+  "Research & Academia",
+  "Utility",
+  "Other"
+];
 var ContextError = class _ContextError extends Error {
   constructor(message, code, statusCode, helpUrl) {
     super(message);
@@ -12,6 +24,57 @@ var ContextError = class _ContextError extends Error {
   }
 };
 
+// src/client/resources/developer.ts
+var Developer = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Update a tool listing's metadata (name, description, category).
+   *
+   * Requires an API key belonging to the tool's owner.
+   *
+   * @param toolId - The UUID of the tool to update
+   * @param updates - Fields to update (at least one required)
+   * @returns The updated tool metadata
+   *
+   * @throws {ContextError} If authentication fails or the caller does not own the tool
+   *
+   * @example
+   * ```typescript
+   * const updated = await client.developer.updateTool("tool-uuid", {
+   *   description: "Updated description with better showcase prompts",
+   *   category: "crypto",
+   * });
+   * console.log(updated.updatedAt);
+   * ```
+   */
+  async updateTool(toolId, updates) {
+    if (!toolId) {
+      throw new ContextError("toolId is required");
+    }
+    if (updates.name === void 0 && updates.description === void 0 && updates.category === void 0) {
+      throw new ContextError(
+        "At least one field required: name, description, or category"
+      );
+    }
+    if (updates.category !== void 0 && updates.category !== null && !ALLOWED_TOOL_CATEGORIES.includes(updates.category)) {
+      throw new ContextError(
+        `category must be one of: ${ALLOWED_TOOL_CATEGORIES.join(", ")}`
+      );
+    }
+    const encodedToolId = encodeURIComponent(toolId);
+    return this.client._fetch(
+      `/api/v1/tools/${encodedToolId}`,
+      {
+        method: "PATCH",
+        body: JSON.stringify(updates)
+      },
+      { retry: false }
+    );
+  }
+};
+
 // src/client/resources/discovery.ts
 var Discovery = class {
   constructor(client) {
@@ -236,6 +299,47 @@ var Query = class {
   constructor(client) {
     this.client = client;
   }
+  normalizeResult(result) {
+    const candidate = result;
+    if (candidate.outcomeType === "clarification_required" && "clarification" in candidate && candidate.clarification) {
+      return candidate;
+    }
+    if (candidate.outcomeType === "capability_miss" && "capabilityMiss" in candidate && candidate.capabilityMiss) {
+      return candidate;
+    }
+    return {
+      ...candidate,
+      outcomeType: "answer"
+    };
+  }
+  buildPolicyErrorEvent(params) {
+    if (params.clarificationPolicy !== "error") {
+      return;
+    }
+    if (params.result.outcomeType === "clarification_required") {
+      return {
+        type: "error",
+        error: params.result.response,
+        code: "clarification_required",
+        reasonCode: "clarification_required",
+        outcomeType: "clarification_required",
+        clarification: params.result.clarification,
+        querySession: params.result.querySession
+      };
+    }
+    if (params.result.outcomeType === "capability_miss") {
+      return {
+        type: "error",
+        error: params.result.response,
+        code: "capability_miss",
+        reasonCode: "capability_miss",
+        outcomeType: "capability_miss",
+        capabilityMiss: params.result.capabilityMiss,
+        querySession: params.result.querySession
+      };
+    }
+    return void 0;
+  }
   buildSyntheticTraceFromRunResult(params) {
     const timeline = params.toolsUsed.map((tool, index) => ({
       stepType: "tool-call",
@@ -378,6 +482,7 @@ var Query = class {
   async run(options) {
     const opts = typeof options === "string" ? { query: options } : options;
     let terminalError;
+    let finalResult;
     for await (const event of this.stream(opts)) {
       if (event.type === "error") {
         terminalError = {
@@ -389,9 +494,12 @@ var Query = class {
         continue;
       }
       if (event.type === "done") {
-        return event.result;
+        finalResult = event.result;
       }
     }
+    if (finalResult) {
+      return finalResult;
+    }
     if (terminalError) {
       throw new ContextError(terminalError.error, terminalError.code);
     }
@@ -443,7 +551,11 @@ var Query = class {
       body: JSON.stringify({
         query: opts.query,
         tools: opts.tools,
-        modelId: opts.modelId,
+        resumeFrom: opts.resumeFrom,
+        forkFrom: opts.forkFrom,
+        clarificationPolicy: opts.clarificationPolicy,
+        answerModelId: opts.answerModelId,
+        responseShape: opts.responseShape,
         includeData: opts.includeData,
         includeDataUrl: opts.includeDataUrl,
         includeDeveloperTrace: opts.includeDeveloperTrace,
@@ -481,22 +593,31 @@ var Query = class {
         return event;
       }
       if (event.type === "done") {
+        const normalizedResult = this.normalizeResult(event.result);
         let mergedTrace = this.mergeDeveloperTrace(
           aggregatedTrace,
-          event.result.developerTrace
+          normalizedResult.developerTrace
         );
         if (!mergedTrace && opts.includeDeveloperTrace) {
           mergedTrace = statusTimeline.length > 0 ? this.buildSyntheticTraceFromStreamStatus({
             statusTimeline,
-            toolsUsed: event.result.toolsUsed,
-            durationMs: event.result.durationMs
+            toolsUsed: normalizedResult.toolsUsed,
+            durationMs: normalizedResult.durationMs
           }) : this.buildSyntheticTraceFromRunResult({
-            toolsUsed: event.result.toolsUsed,
-            durationMs: event.result.durationMs
+            toolsUsed: normalizedResult.toolsUsed,
+            durationMs: normalizedResult.durationMs
           });
         }
         if (mergedTrace) {
-          event.result.developerTrace = mergedTrace;
+          normalizedResult.developerTrace = mergedTrace;
+        }
+        event.result = normalizedResult;
+        const policyErrorEvent = this.buildPolicyErrorEvent({
+          result: normalizedResult,
+          clarificationPolicy: opts.clarificationPolicy
+        });
+        if (policyErrorEvent) {
+          return policyErrorEvent;
         }
       }
       return event;
@@ -551,6 +672,10 @@ var ContextClient = class {
   requestTimeoutMs;
   streamTimeoutMs;
   _closed = false;
+  /**
+   * Developer resource for managing tool listings (contributor/developer concerns).
+   */
+  developer;
   /**
    * Discovery resource for searching tools
    */
@@ -592,6 +717,7 @@ var ContextClient = class {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.requestTimeoutMs = requestTimeoutMs;
     this.streamTimeoutMs = streamTimeoutMs;
+    this.developer = new Developer(this);
     this.discovery = new Discovery(this);
     this.tools = new Tools(this);
     this.query = new Query(this);
@@ -750,8 +876,10 @@ var ContextClient = class {
   }
 };
 
+exports.ALLOWED_TOOL_CATEGORIES = ALLOWED_TOOL_CATEGORIES;
 exports.ContextClient = ContextClient;
 exports.ContextError = ContextError;
+exports.Developer = Developer;
 exports.Discovery = Discovery;
 exports.Query = Query;
 exports.Tools = Tools;