@ctxprotocol/sdk 0.9.0 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -9
- package/dist/client/index.cjs +66 -8
- package/dist/client/index.cjs.map +1 -1
- package/dist/client/index.d.cts +5 -635
- package/dist/client/index.d.ts +5 -635
- package/dist/client/index.js +66 -8
- package/dist/client/index.js.map +1 -1
- package/dist/contrib/search/index.cjs +703 -0
- package/dist/contrib/search/index.cjs.map +1 -0
- package/dist/contrib/search/index.d.cts +33 -0
- package/dist/contrib/search/index.d.ts +33 -0
- package/dist/contrib/search/index.js +690 -0
- package/dist/contrib/search/index.js.map +1 -0
- package/dist/index.cjs +66 -8
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +9 -1
- package/dist/index.d.ts +9 -1
- package/dist/index.js +66 -8
- package/dist/index.js.map +1 -1
- package/dist/types-Bgjq3OBR.d.cts +1071 -0
- package/dist/types-Bgjq3OBR.d.ts +1071 -0
- package/package.json +11 -1
package/dist/client/index.d.cts
CHANGED
|
@@ -1,637 +1,5 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
*/
|
|
4
|
-
interface ContextClientOptions {
|
|
5
|
-
/**
|
|
6
|
-
* Your Context Protocol API key
|
|
7
|
-
* @example "sk_live_abc123..."
|
|
8
|
-
*/
|
|
9
|
-
apiKey: string;
|
|
10
|
-
/**
|
|
11
|
-
* Base URL for the Context Protocol API
|
|
12
|
-
* @default "https://www.ctxprotocol.com"
|
|
13
|
-
*/
|
|
14
|
-
baseUrl?: string;
|
|
15
|
-
/**
|
|
16
|
-
* Request timeout for non-streaming API calls in milliseconds.
|
|
17
|
-
* @default 300000
|
|
18
|
-
*/
|
|
19
|
-
requestTimeoutMs?: number;
|
|
20
|
-
/**
|
|
21
|
-
* Request timeout for establishing streaming API calls in milliseconds.
|
|
22
|
-
* @default 600000
|
|
23
|
-
*/
|
|
24
|
-
streamTimeoutMs?: number;
|
|
25
|
-
}
|
|
26
|
-
/**
|
|
27
|
-
* An individual MCP tool exposed by a tool listing
|
|
28
|
-
*/
|
|
29
|
-
interface McpToolRateLimitHints {
|
|
30
|
-
/** Suggested request budget for this method */
|
|
31
|
-
maxRequestsPerMinute?: number;
|
|
32
|
-
/** Suggested parallel call ceiling for this method */
|
|
33
|
-
maxConcurrency?: number;
|
|
34
|
-
/** Suggested minimum delay between sequential calls */
|
|
35
|
-
cooldownMs?: number;
|
|
36
|
-
/** Whether this method already supports bulk/batch retrieval */
|
|
37
|
-
supportsBulk?: boolean;
|
|
38
|
-
/** Preferred batch-oriented methods to call instead of fan-out loops */
|
|
39
|
-
recommendedBatchTools?: string[];
|
|
40
|
-
/** Optional human-readable notes for planning */
|
|
41
|
-
notes?: string;
|
|
42
|
-
}
|
|
43
|
-
type DiscoveryMode = "query" | "execute";
|
|
44
|
-
type McpToolSurface = "answer" | "execute" | "both";
|
|
45
|
-
type McpToolLatencyClass = "instant" | "fast" | "slow" | "streaming";
|
|
46
|
-
interface McpToolPricingMeta {
|
|
47
|
-
executeUsd?: string;
|
|
48
|
-
queryUsd?: string;
|
|
49
|
-
[key: string]: unknown;
|
|
50
|
-
}
|
|
51
|
-
interface McpToolMeta {
|
|
52
|
-
/** Declared method surface */
|
|
53
|
-
surface?: McpToolSurface;
|
|
54
|
-
/** Whether this method can be selected in query mode */
|
|
55
|
-
queryEligible?: boolean;
|
|
56
|
-
/** Declared latency class for planner/runtime gating */
|
|
57
|
-
latencyClass?: McpToolLatencyClass;
|
|
58
|
-
/** Method-level pricing metadata */
|
|
59
|
-
pricing?: McpToolPricingMeta;
|
|
60
|
-
/** Derived discovery flag for execute eligibility */
|
|
61
|
-
executeEligible?: boolean;
|
|
62
|
-
/** Derived discovery field for explicit execute pricing visibility */
|
|
63
|
-
executePriceUsd?: string;
|
|
64
|
-
/** Context injection requirements handled by the Context runtime */
|
|
65
|
-
contextRequirements?: string[];
|
|
66
|
-
/**
|
|
67
|
-
* Optional planner/runtime pacing hints.
|
|
68
|
-
* Tool contributors can publish these to reduce rate-limit failures.
|
|
69
|
-
*/
|
|
70
|
-
rateLimit?: McpToolRateLimitHints;
|
|
71
|
-
rateLimitHints?: McpToolRateLimitHints;
|
|
72
|
-
/** Flat aliases accepted for convenience */
|
|
73
|
-
maxRequestsPerMinute?: number;
|
|
74
|
-
maxConcurrency?: number;
|
|
75
|
-
cooldownMs?: number;
|
|
76
|
-
supportsBulk?: boolean;
|
|
77
|
-
recommendedBatchTools?: string[];
|
|
78
|
-
notes?: string;
|
|
79
|
-
[key: string]: unknown;
|
|
80
|
-
}
|
|
81
|
-
interface StructuredMethodGuidanceHints {
|
|
82
|
-
/** Suggested call-order sequence extracted from method descriptions */
|
|
83
|
-
callOrderHints?: string[];
|
|
84
|
-
/** Parameter usage caveats extracted from method descriptions */
|
|
85
|
-
parameterCaveats?: string[];
|
|
86
|
-
/** Edge-case behavior notes extracted from method descriptions */
|
|
87
|
-
edgeCaseNotes?: string[];
|
|
88
|
-
}
|
|
89
|
-
interface McpTool {
|
|
90
|
-
/** Name of the MCP tool method */
|
|
91
|
-
name: string;
|
|
92
|
-
/** Description of what this method does */
|
|
93
|
-
description: string;
|
|
94
|
-
/**
|
|
95
|
-
* JSON Schema for the input arguments this tool accepts.
|
|
96
|
-
* Used by LLMs to generate correct arguments.
|
|
97
|
-
*/
|
|
98
|
-
inputSchema?: Record<string, unknown>;
|
|
99
|
-
/**
|
|
100
|
-
* JSON Schema for the output this tool returns.
|
|
101
|
-
* Used by LLMs to understand the response structure.
|
|
102
|
-
*/
|
|
103
|
-
outputSchema?: Record<string, unknown>;
|
|
104
|
-
/** MCP metadata extensions (context injection, rate-limit hints) */
|
|
105
|
-
_meta?: McpToolMeta;
|
|
106
|
-
/** Explicit execute eligibility in discovery responses */
|
|
107
|
-
executeEligible?: boolean;
|
|
108
|
-
/** Explicit execute price visibility in discovery responses */
|
|
109
|
-
executePriceUsd?: string | null;
|
|
110
|
-
/** Whether this method has normalized structured guidance hints */
|
|
111
|
-
hasStructuredGuidance?: boolean;
|
|
112
|
-
/** Optional structured guidance hints derived from the method description */
|
|
113
|
-
structuredGuidance?: StructuredMethodGuidanceHints;
|
|
114
|
-
}
|
|
115
|
-
/**
|
|
116
|
-
* Represents a tool available on the Context Protocol marketplace
|
|
117
|
-
*/
|
|
118
|
-
interface Tool {
|
|
119
|
-
/** Unique identifier for the tool (UUID) */
|
|
120
|
-
id: string;
|
|
121
|
-
/** Human-readable name of the tool */
|
|
122
|
-
name: string;
|
|
123
|
-
/** Description of what the tool does */
|
|
124
|
-
description: string;
|
|
125
|
-
/** Price per execution in USDC */
|
|
126
|
-
price: string;
|
|
127
|
-
/** Tool category (e.g., "defi", "nft") */
|
|
128
|
-
category?: string;
|
|
129
|
-
/** Whether the tool is verified by Context Protocol */
|
|
130
|
-
isVerified?: boolean;
|
|
131
|
-
/** Tool type - currently always "mcp" */
|
|
132
|
-
kind?: string;
|
|
133
|
-
/**
|
|
134
|
-
* Available MCP tool methods
|
|
135
|
-
* Use items from this array as `toolName` when executing
|
|
136
|
-
*/
|
|
137
|
-
mcpTools?: McpTool[];
|
|
138
|
-
/** Total number of queries processed */
|
|
139
|
-
totalQueries?: number;
|
|
140
|
-
/** Success rate percentage (0-100) */
|
|
141
|
-
successRate?: string;
|
|
142
|
-
/** Uptime percentage (0-100) */
|
|
143
|
-
uptimePercent?: string;
|
|
144
|
-
/** Total USDC staked by the developer */
|
|
145
|
-
totalStaked?: string;
|
|
146
|
-
/** Whether the tool has "Proven" status (100+ queries, >95% success, >98% uptime) */
|
|
147
|
-
isProven?: boolean;
|
|
148
|
-
}
|
|
149
|
-
/**
|
|
150
|
-
* Response from the tools search endpoint
|
|
151
|
-
*/
|
|
152
|
-
interface SearchResponse {
|
|
153
|
-
/** Array of matching tools */
|
|
154
|
-
tools: Tool[];
|
|
155
|
-
/** Discovery mode used by the server */
|
|
156
|
-
mode?: DiscoveryMode;
|
|
157
|
-
/** The search query that was used */
|
|
158
|
-
query: string;
|
|
159
|
-
/** Total number of results */
|
|
160
|
-
count: number;
|
|
161
|
-
}
|
|
162
|
-
/**
|
|
163
|
-
* Options for searching tools
|
|
164
|
-
*/
|
|
165
|
-
interface SearchOptions {
|
|
166
|
-
/** Search query (semantic search) */
|
|
167
|
-
query?: string;
|
|
168
|
-
/** Maximum number of results (1-50, default 10) */
|
|
169
|
-
limit?: number;
|
|
170
|
-
/** Discovery mode with billing semantics */
|
|
171
|
-
mode?: DiscoveryMode;
|
|
172
|
-
/** Optional explicit method surface filter */
|
|
173
|
-
surface?: McpToolSurface;
|
|
174
|
-
/** Require methods marked query eligible */
|
|
175
|
-
queryEligible?: boolean;
|
|
176
|
-
/** Require explicit method execute pricing */
|
|
177
|
-
requireExecutePricing?: boolean;
|
|
178
|
-
/** Exclude methods by latency class */
|
|
179
|
-
excludeLatencyClasses?: McpToolLatencyClass[];
|
|
180
|
-
/** Convenience switch to exclude slow methods in query mode */
|
|
181
|
-
excludeSlow?: boolean;
|
|
182
|
-
}
|
|
183
|
-
/**
|
|
184
|
-
* Options for executing a tool
|
|
185
|
-
*/
|
|
186
|
-
interface ExecuteOptions {
|
|
187
|
-
/** The UUID of the tool to execute (from search results) */
|
|
188
|
-
toolId: string;
|
|
189
|
-
/** The specific MCP tool name to call (from tool's mcpTools array) */
|
|
190
|
-
toolName: string;
|
|
191
|
-
/** Arguments to pass to the tool */
|
|
192
|
-
args?: Record<string, unknown>;
|
|
193
|
-
/**
|
|
194
|
-
* Optional idempotency key (UUID recommended).
|
|
195
|
-
* Reuse the same key when retrying the same logical request.
|
|
196
|
-
*/
|
|
197
|
-
idempotencyKey?: string;
|
|
198
|
-
/** Explicit execute mode label for request clarity */
|
|
199
|
-
mode?: "execute";
|
|
200
|
-
/** Optional execute session identifier */
|
|
201
|
-
sessionId?: string;
|
|
202
|
-
/** Optional per-session spend budget envelope (USD) */
|
|
203
|
-
maxSpendUsd?: string;
|
|
204
|
-
/** Request session closure after this execute call settles */
|
|
205
|
-
closeSession?: boolean;
|
|
206
|
-
}
|
|
207
|
-
type ExecuteSessionStatus = "open" | "closed" | "expired";
|
|
208
|
-
interface ExecuteSessionSpend {
|
|
209
|
-
mode: "execute";
|
|
210
|
-
sessionId: string | null;
|
|
211
|
-
methodPrice: string;
|
|
212
|
-
spent: string;
|
|
213
|
-
remaining: string | null;
|
|
214
|
-
maxSpend: string | null;
|
|
215
|
-
/** Optional lifecycle fields when the API returns session state */
|
|
216
|
-
status?: ExecuteSessionStatus;
|
|
217
|
-
expiresAt?: string;
|
|
218
|
-
closeRequested?: boolean;
|
|
219
|
-
pendingAccruedCount?: number;
|
|
220
|
-
pendingAccruedUsd?: string;
|
|
221
|
-
}
|
|
222
|
-
/**
|
|
223
|
-
* Successful execution response from the API
|
|
224
|
-
*/
|
|
225
|
-
interface ExecuteApiSuccessResponse {
|
|
226
|
-
success: true;
|
|
227
|
-
mode: "execute";
|
|
228
|
-
/** The result data from the tool execution */
|
|
229
|
-
result: unknown;
|
|
230
|
-
/** Information about the executed tool */
|
|
231
|
-
tool: {
|
|
232
|
-
id: string;
|
|
233
|
-
name: string;
|
|
234
|
-
};
|
|
235
|
-
/** Method-level execute pricing used for this call */
|
|
236
|
-
method: {
|
|
237
|
-
name: string;
|
|
238
|
-
executePriceUsd: string;
|
|
239
|
-
};
|
|
240
|
-
/** Spend envelope visibility for execute sessions */
|
|
241
|
-
session: ExecuteSessionSpend;
|
|
242
|
-
/** Execution duration in milliseconds */
|
|
243
|
-
durationMs: number;
|
|
244
|
-
}
|
|
245
|
-
/**
|
|
246
|
-
* Error response from the API
|
|
247
|
-
*/
|
|
248
|
-
interface ExecuteApiErrorResponse {
|
|
249
|
-
/** Human-readable error message */
|
|
250
|
-
error: string;
|
|
251
|
-
/** Explicit mode label for clarity */
|
|
252
|
-
mode?: "execute";
|
|
253
|
-
/** Error code for programmatic handling */
|
|
254
|
-
code?: ContextErrorCode;
|
|
255
|
-
/** URL to help resolve the issue */
|
|
256
|
-
helpUrl?: string;
|
|
257
|
-
/** Optional spend envelope context when available */
|
|
258
|
-
session?: ExecuteSessionSpend;
|
|
259
|
-
}
|
|
260
|
-
/**
|
|
261
|
-
* Raw API response from the execute endpoint
|
|
262
|
-
*/
|
|
263
|
-
type ExecuteApiResponse = ExecuteApiSuccessResponse | ExecuteApiErrorResponse;
|
|
264
|
-
interface ExecuteSessionStartOptions {
|
|
265
|
-
/** Maximum spend budget for the session (USD string) */
|
|
266
|
-
maxSpendUsd: string;
|
|
267
|
-
}
|
|
268
|
-
interface ExecuteSessionApiSuccessResponse {
|
|
269
|
-
success: true;
|
|
270
|
-
mode: "execute";
|
|
271
|
-
session: ExecuteSessionSpend;
|
|
272
|
-
}
|
|
273
|
-
type ExecuteSessionApiResponse = ExecuteSessionApiSuccessResponse | ExecuteApiErrorResponse;
|
|
274
|
-
interface ExecuteSessionResult {
|
|
275
|
-
mode: "execute";
|
|
276
|
-
session: ExecuteSessionSpend;
|
|
277
|
-
}
|
|
278
|
-
/**
|
|
279
|
-
* The resolved result returned to the user after SDK processing
|
|
280
|
-
*/
|
|
281
|
-
interface ExecutionResult<T = unknown> {
|
|
282
|
-
mode: "execute";
|
|
283
|
-
/** The data returned by the tool */
|
|
284
|
-
result: T;
|
|
285
|
-
/** Information about the executed tool */
|
|
286
|
-
tool: {
|
|
287
|
-
id: string;
|
|
288
|
-
name: string;
|
|
289
|
-
};
|
|
290
|
-
/** Method-level execute pricing used for this call */
|
|
291
|
-
method: {
|
|
292
|
-
name: string;
|
|
293
|
-
executePriceUsd: string;
|
|
294
|
-
};
|
|
295
|
-
/** Spend envelope visibility for execute calls */
|
|
296
|
-
session: ExecuteSessionSpend;
|
|
297
|
-
/** Execution duration in milliseconds */
|
|
298
|
-
durationMs: number;
|
|
299
|
-
}
|
|
300
|
-
/** Supported orchestration depth modes for query execution. */
|
|
301
|
-
type QueryDepth = "fast" | "auto" | "deep";
|
|
302
|
-
type QueryDeepMode = "deep-light" | "deep-heavy";
|
|
303
|
-
/**
|
|
304
|
-
* Options for the agentic query endpoint (pay-per-response).
|
|
305
|
-
*
|
|
306
|
-
* Unlike `execute()` which calls a single tool once, `query()` sends a
|
|
307
|
-
* natural-language question and lets the server handle discovery-first
|
|
308
|
-
* orchestration (`discover/probe -> plan-from-evidence -> execute ->
|
|
309
|
-
* bounded fallback`) plus synthesis.
|
|
310
|
-
* One flat fee covers up to 100 MCP skill calls per tool.
|
|
311
|
-
*/
|
|
312
|
-
interface QueryOptions {
|
|
313
|
-
/** The natural-language question to answer */
|
|
314
|
-
query: string;
|
|
315
|
-
/**
|
|
316
|
-
* Optional tool IDs to use. When omitted the server discovers tools
|
|
317
|
-
* automatically (Auto Mode). When provided, only these tools are used
|
|
318
|
-
* (Manual Mode).
|
|
319
|
-
*/
|
|
320
|
-
tools?: string[];
|
|
321
|
-
/**
|
|
322
|
-
* Optional model ID for query orchestration/synthesis.
|
|
323
|
-
* Supported IDs are published by the Context API.
|
|
324
|
-
*/
|
|
325
|
-
modelId?: string;
|
|
326
|
-
/**
|
|
327
|
-
* Include execution data inline in the query response.
|
|
328
|
-
* Useful for headless agents that need raw structured outputs.
|
|
329
|
-
*/
|
|
330
|
-
includeData?: boolean;
|
|
331
|
-
/**
|
|
332
|
-
* Persist execution data to Vercel Blob and return a download URL.
|
|
333
|
-
* Useful for large payload workflows where inline JSON is not ideal.
|
|
334
|
-
*/
|
|
335
|
-
includeDataUrl?: boolean;
|
|
336
|
-
/**
|
|
337
|
-
* Include machine-readable developer trace output for this query response.
|
|
338
|
-
* When enabled, the server may return summary counters plus diagnostics
|
|
339
|
-
* for lane selection, scout probe adequacy, and bounded fallback behavior.
|
|
340
|
-
*/
|
|
341
|
-
includeDeveloperTrace?: boolean;
|
|
342
|
-
/**
|
|
343
|
-
* Query orchestration depth mode:
|
|
344
|
-
* - `fast`: lower-latency path
|
|
345
|
-
* - `auto`: server decides between fast/deep
|
|
346
|
-
* - `deep`: full completeness-oriented path
|
|
347
|
-
*/
|
|
348
|
-
queryDepth?: QueryDepth;
|
|
349
|
-
/**
|
|
350
|
-
* Development/testing only: force the server's internal deep lane.
|
|
351
|
-
* Ignored by normal production usage and invalid when `queryDepth` is `fast`.
|
|
352
|
-
*/
|
|
353
|
-
debugScoutDeepMode?: QueryDeepMode;
|
|
354
|
-
/**
|
|
355
|
-
* Optional idempotency key (UUID recommended).
|
|
356
|
-
* Reuse the same key when retrying the same logical request.
|
|
357
|
-
*/
|
|
358
|
-
idempotencyKey?: string;
|
|
359
|
-
}
|
|
360
|
-
/**
|
|
361
|
-
* Tool reference attached to developer trace timeline steps.
|
|
362
|
-
*/
|
|
363
|
-
interface QueryDeveloperTraceToolRef {
|
|
364
|
-
id?: string;
|
|
365
|
-
name?: string;
|
|
366
|
-
method?: string;
|
|
367
|
-
[key: string]: unknown;
|
|
368
|
-
}
|
|
369
|
-
/**
|
|
370
|
-
* Loop metadata attached to developer trace timeline steps.
|
|
371
|
-
*/
|
|
372
|
-
interface QueryDeveloperTraceLoopInfo {
|
|
373
|
-
name?: string;
|
|
374
|
-
iteration?: number;
|
|
375
|
-
maxIterations?: number;
|
|
376
|
-
[key: string]: unknown;
|
|
377
|
-
}
|
|
378
|
-
/**
|
|
379
|
-
* Tool selection metadata attached to discovery/planning diagnostics.
|
|
380
|
-
*/
|
|
381
|
-
interface QueryDeveloperTraceToolSelection {
|
|
382
|
-
toolId: string;
|
|
383
|
-
toolName: string;
|
|
384
|
-
selectedMethodCount: number;
|
|
385
|
-
selectedMethods: string[];
|
|
386
|
-
omittedSelectedMethodCount: number;
|
|
387
|
-
priceUsd?: string;
|
|
388
|
-
}
|
|
389
|
-
/**
|
|
390
|
-
* Initial planner diagnostic details.
|
|
391
|
-
*/
|
|
392
|
-
interface QueryPlanningTraceDiagnostic {
|
|
393
|
-
plannerQuery: string;
|
|
394
|
-
scoutEvidenceAttached: boolean;
|
|
395
|
-
scoutEvidencePromptBlock: string | null;
|
|
396
|
-
allowedModules: string[];
|
|
397
|
-
}
|
|
398
|
-
/**
|
|
399
|
-
* Rediscovery/fallback diagnostic details.
|
|
400
|
-
*/
|
|
401
|
-
interface QueryRediscoveryTraceDiagnostic {
|
|
402
|
-
considered: boolean;
|
|
403
|
-
executed: boolean;
|
|
404
|
-
skipReason: string | null;
|
|
405
|
-
missingCapability: string | null;
|
|
406
|
-
rediscoveryQuery: string | null;
|
|
407
|
-
capabilityLooksLikeSearchNeed: boolean;
|
|
408
|
-
allowSearchFallbackOnElapsedCap: boolean;
|
|
409
|
-
searchFallbackUsed: boolean;
|
|
410
|
-
preRediscoveryBudgetReasonCode: string | null;
|
|
411
|
-
candidateSearchResults: QueryDeveloperTraceToolSelection[];
|
|
412
|
-
selectedAlternatives: QueryDeveloperTraceToolSelection[];
|
|
413
|
-
mergedTools: QueryDeveloperTraceToolSelection[];
|
|
414
|
-
usingPaidFallback: boolean;
|
|
415
|
-
branchPlan: QueryPlanningTraceDiagnostic | null;
|
|
416
|
-
}
|
|
417
|
-
/**
|
|
418
|
-
* Rich developer-trace diagnostics for discovery-first orchestration internals.
|
|
419
|
-
*/
|
|
420
|
-
interface QueryDeveloperTraceDiagnostics {
|
|
421
|
-
selection: {
|
|
422
|
-
selectedDepth: string;
|
|
423
|
-
deepMode: string | null;
|
|
424
|
-
debugScoutDeepMode: string | null;
|
|
425
|
-
plannerReasoningStage: string;
|
|
426
|
-
scoutEnabled: boolean;
|
|
427
|
-
preserveFastOneShot: boolean;
|
|
428
|
-
candidateMethodCount: number;
|
|
429
|
-
scoutProbeStatus: string;
|
|
430
|
-
scoutProbeAdequacy: string;
|
|
431
|
-
scoutProbeConfidence: number;
|
|
432
|
-
scoutMetadataConfidence: number;
|
|
433
|
-
scoutProbeShortlistedMethodCount: number;
|
|
434
|
-
scoutProbeMissingCapability: string | null;
|
|
435
|
-
scoutPrePlanProbeCalls: number;
|
|
436
|
-
scoutPrePlanProbeBudgetReasonCode: string | null;
|
|
437
|
-
scoutChangedInitialPlan: boolean;
|
|
438
|
-
scoutChangedPlannerReasoningStage: boolean;
|
|
439
|
-
scoutInitialSelectedDepth: string;
|
|
440
|
-
scoutInitialDeepMode: string | null;
|
|
441
|
-
scoutInitialPlannerReasoningStage: string;
|
|
442
|
-
scoutInitialReasonCode: string;
|
|
443
|
-
scoutFinalReasonCode: string;
|
|
444
|
-
scoutEvidenceAttachedToPlanning: boolean;
|
|
445
|
-
scoutLlmSelectionUsed: boolean;
|
|
446
|
-
scoutLlmSelectionFallback: boolean;
|
|
447
|
-
scoutLlmSelectionLatencyMs: number | null;
|
|
448
|
-
selectedTools: QueryDeveloperTraceToolSelection[];
|
|
449
|
-
};
|
|
450
|
-
planning: {
|
|
451
|
-
initial: QueryPlanningTraceDiagnostic;
|
|
452
|
-
};
|
|
453
|
-
cost?: {
|
|
454
|
-
planningCostUsd: number;
|
|
455
|
-
initialExecutionCostUsd: number;
|
|
456
|
-
rediscoveryAdditionalCostUsd: number;
|
|
457
|
-
synthesisCostUsd: number;
|
|
458
|
-
totalModelCostUsd: number;
|
|
459
|
-
toolCostUsd: number;
|
|
460
|
-
totalChargedUsd: number;
|
|
461
|
-
};
|
|
462
|
-
completeness: {
|
|
463
|
-
evaluations: unknown[];
|
|
464
|
-
triggerNeedsDifferentTools: boolean;
|
|
465
|
-
triggerMissingCapability: string | null;
|
|
466
|
-
};
|
|
467
|
-
rediscovery: QueryRediscoveryTraceDiagnostic | null;
|
|
468
|
-
[key: string]: unknown;
|
|
469
|
-
}
|
|
470
|
-
/**
|
|
471
|
-
* A single developer-trace timeline step.
|
|
472
|
-
*/
|
|
473
|
-
interface QueryDeveloperTraceStep {
|
|
474
|
-
stepType?: string;
|
|
475
|
-
event?: string;
|
|
476
|
-
status?: string;
|
|
477
|
-
message?: string;
|
|
478
|
-
timestampMs?: number;
|
|
479
|
-
tool?: QueryDeveloperTraceToolRef;
|
|
480
|
-
attempt?: number;
|
|
481
|
-
loop?: QueryDeveloperTraceLoopInfo;
|
|
482
|
-
metadata?: Record<string, unknown>;
|
|
483
|
-
[key: string]: unknown;
|
|
484
|
-
}
|
|
485
|
-
/**
|
|
486
|
-
* Aggregate counters that summarize developer-trace behavior.
|
|
487
|
-
*/
|
|
488
|
-
interface QueryDeveloperTraceSummary {
|
|
489
|
-
toolCalls?: number;
|
|
490
|
-
retryCount?: number;
|
|
491
|
-
selfHealCount?: number;
|
|
492
|
-
fallbackCount?: number;
|
|
493
|
-
failureCount?: number;
|
|
494
|
-
recoveryCount?: number;
|
|
495
|
-
completionChecks?: number;
|
|
496
|
-
loopCount?: number;
|
|
497
|
-
[key: string]: unknown;
|
|
498
|
-
}
|
|
499
|
-
/**
|
|
500
|
-
* Developer Mode trace payload returned per query response (opt-in).
|
|
501
|
-
*/
|
|
502
|
-
interface QueryDeveloperTrace {
|
|
503
|
-
summary?: QueryDeveloperTraceSummary;
|
|
504
|
-
timeline?: QueryDeveloperTraceStep[];
|
|
505
|
-
requestId?: string;
|
|
506
|
-
query?: string;
|
|
507
|
-
source?: string;
|
|
508
|
-
diagnostics?: QueryDeveloperTraceDiagnostics;
|
|
509
|
-
[key: string]: unknown;
|
|
510
|
-
}
|
|
511
|
-
/**
|
|
512
|
-
* Information about a tool that was used during a query response
|
|
513
|
-
*/
|
|
514
|
-
interface QueryToolUsage {
|
|
515
|
-
/** Tool ID */
|
|
516
|
-
id: string;
|
|
517
|
-
/** Tool name */
|
|
518
|
-
name: string;
|
|
519
|
-
/** Number of MCP skill calls made for this tool */
|
|
520
|
-
skillCalls: number;
|
|
521
|
-
}
|
|
522
|
-
/**
|
|
523
|
-
* Cost breakdown for a query response.
|
|
524
|
-
* All values are strings representing USD amounts.
|
|
525
|
-
*/
|
|
526
|
-
interface QueryCost {
|
|
527
|
-
/** AI model inference cost */
|
|
528
|
-
modelCostUsd: string;
|
|
529
|
-
/** Sum of all tool fees */
|
|
530
|
-
toolCostUsd: string;
|
|
531
|
-
/** Total cost (model + tools) */
|
|
532
|
-
totalCostUsd: string;
|
|
533
|
-
}
|
|
534
|
-
/**
|
|
535
|
-
* High-level orchestration outcome metrics returned by the query API.
|
|
536
|
-
*/
|
|
537
|
-
interface QueryOrchestrationMetrics {
|
|
538
|
-
parityStage: string;
|
|
539
|
-
orchestrationMode: string;
|
|
540
|
-
/** Whether the first plan path succeeded without fallback. */
|
|
541
|
-
firstPassSuccess: boolean;
|
|
542
|
-
/** Whether execution signaled a missing capability on first pass. */
|
|
543
|
-
capabilityMissSignaled: boolean;
|
|
544
|
-
/** Whether bounded rediscovery/fallback executed. */
|
|
545
|
-
rediscoveryExecuted: boolean;
|
|
546
|
-
}
|
|
547
|
-
/**
|
|
548
|
-
* The resolved result of a pay-per-response query
|
|
549
|
-
*/
|
|
550
|
-
interface QueryResult {
|
|
551
|
-
/** The AI-synthesized response text */
|
|
552
|
-
response: string;
|
|
553
|
-
/** Tools that were used to answer the query */
|
|
554
|
-
toolsUsed: QueryToolUsage[];
|
|
555
|
-
/** Cost breakdown */
|
|
556
|
-
cost: QueryCost;
|
|
557
|
-
/** Total duration in milliseconds */
|
|
558
|
-
durationMs: number;
|
|
559
|
-
/** Optional execution data from tools (when includeData=true) */
|
|
560
|
-
data?: unknown;
|
|
561
|
-
/** Optional blob URL for persisted execution data (when includeDataUrl=true) */
|
|
562
|
-
dataUrl?: string;
|
|
563
|
-
/** Optional machine-readable Developer Mode trace payload */
|
|
564
|
-
developerTrace?: QueryDeveloperTrace;
|
|
565
|
-
/** Optional orchestration outcome metrics for benchmarking and rollout analysis */
|
|
566
|
-
orchestrationMetrics?: QueryOrchestrationMetrics;
|
|
567
|
-
}
|
|
568
|
-
/**
|
|
569
|
-
* Successful response from the /api/v1/query endpoint
|
|
570
|
-
*/
|
|
571
|
-
interface QueryApiSuccessResponse {
|
|
572
|
-
success: true;
|
|
573
|
-
response: string;
|
|
574
|
-
toolsUsed: QueryToolUsage[];
|
|
575
|
-
cost: QueryCost;
|
|
576
|
-
durationMs: number;
|
|
577
|
-
data?: unknown;
|
|
578
|
-
dataUrl?: string;
|
|
579
|
-
developerTrace?: QueryDeveloperTrace;
|
|
580
|
-
orchestrationMetrics?: QueryOrchestrationMetrics;
|
|
581
|
-
}
|
|
582
|
-
/**
|
|
583
|
-
* Raw API response from the query endpoint
|
|
584
|
-
*/
|
|
585
|
-
type QueryApiResponse = QueryApiSuccessResponse | ExecuteApiErrorResponse;
|
|
586
|
-
/** Emitted when a tool starts or changes execution status */
|
|
587
|
-
interface QueryStreamToolStatusEvent {
|
|
588
|
-
type: "tool-status";
|
|
589
|
-
tool: {
|
|
590
|
-
id: string;
|
|
591
|
-
name: string;
|
|
592
|
-
};
|
|
593
|
-
status: string;
|
|
594
|
-
}
|
|
595
|
-
/** Emitted for each chunk of the AI response text */
|
|
596
|
-
interface QueryStreamTextDeltaEvent {
|
|
597
|
-
type: "text-delta";
|
|
598
|
-
delta: string;
|
|
599
|
-
}
|
|
600
|
-
/** Emitted when the server streams developer trace updates/chunks */
|
|
601
|
-
interface QueryStreamDeveloperTraceEvent {
|
|
602
|
-
type: "developer-trace";
|
|
603
|
-
trace: QueryDeveloperTrace;
|
|
604
|
-
}
|
|
605
|
-
/** Emitted when the full response is complete */
|
|
606
|
-
interface QueryStreamDoneEvent {
|
|
607
|
-
type: "done";
|
|
608
|
-
result: QueryResult;
|
|
609
|
-
}
|
|
610
|
-
/** Emitted when the server reports a recoverable or terminal query error */
|
|
611
|
-
interface QueryStreamErrorEvent {
|
|
612
|
-
type: "error";
|
|
613
|
-
error: string;
|
|
614
|
-
code?: ContextErrorCode | string;
|
|
615
|
-
scope?: string;
|
|
616
|
-
reasonCode?: string;
|
|
617
|
-
}
|
|
618
|
-
/**
|
|
619
|
-
* Union of all events emitted during a streaming query
|
|
620
|
-
*/
|
|
621
|
-
type QueryStreamEvent = QueryStreamToolStatusEvent | QueryStreamTextDeltaEvent | QueryStreamDeveloperTraceEvent | QueryStreamDoneEvent | QueryStreamErrorEvent;
|
|
622
|
-
/**
|
|
623
|
-
* Specific error codes returned by the Context Protocol API
|
|
624
|
-
*/
|
|
625
|
-
type ContextErrorCode = "unauthorized" | "no_wallet" | "insufficient_allowance" | "payment_failed" | "execution_failed" | "query_failed" | "invalid_tool_method" | "method_not_execute_eligible" | "invalid_max_spend" | "session_not_found" | "session_forbidden" | "session_closed" | "session_expired" | "max_spend_mismatch" | "session_budget_exceeded";
|
|
626
|
-
/**
|
|
627
|
-
* Error thrown by the Context Protocol client
|
|
628
|
-
*/
|
|
629
|
-
declare class ContextError extends Error {
|
|
630
|
-
readonly code?: (ContextErrorCode | string) | undefined;
|
|
631
|
-
readonly statusCode?: number | undefined;
|
|
632
|
-
readonly helpUrl?: string | undefined;
|
|
633
|
-
constructor(message: string, code?: (ContextErrorCode | string) | undefined, statusCode?: number | undefined, helpUrl?: string | undefined);
|
|
634
|
-
}
|
|
1
|
+
import { T as Tool, H as SearchOptions, I as ExecuteOptions, O as ExecutionResult, J as ExecuteSessionStartOptions, N as ExecuteSessionResult, a0 as QueryOptions, a1 as QueryResult, ad as QueryStreamEvent, D as ContextClientOptions } from '../types-Bgjq3OBR.cjs';
|
|
2
|
+
export { B as ContextError, aj as ContextErrorCode, U as ExecuteApiErrorResponse, V as ExecuteApiResponse, P as ExecuteApiSuccessResponse, X as ExecuteSessionApiResponse, W as ExecuteSessionApiSuccessResponse, L as ExecuteSessionSpend, K as ExecuteSessionStatus, M as McpTool, E as McpToolMeta, F as McpToolRateLimitHints, ac as QueryApiResponse, ab as QueryApiSuccessResponse, ao as QueryAssumptionMetadata, Z as QueryAttemptForkReason, _ as QueryAttemptReference, an as QueryCapabilityMissPayload, al as QueryClarificationOption, ak as QueryClarificationPayload, am as QueryClarificationPolicy, a5 as QueryCompletenessRepairEvent, a4 as QueryCost, Y as QueryDeepMode, Q as QueryDeveloperTrace, a6 as QueryDeveloperTraceDiagnostics, aa as QueryDeveloperTraceLoopInfo, a8 as QueryDeveloperTraceStep, a7 as QueryDeveloperTraceSummary, a9 as QueryDeveloperTraceToolRef, $ as QueryForkReference, ap as QueryOutcomeType, a2 as QuerySessionState, ag as QueryStreamDeveloperTraceEvent, ah as QueryStreamDoneEvent, ai as QueryStreamErrorEvent, af as QueryStreamTextDeltaEvent, ae as QueryStreamToolStatusEvent, a3 as QueryToolUsage, G as SearchResponse } from '../types-Bgjq3OBR.cjs';
|
|
635
3
|
|
|
636
4
|
/**
|
|
637
5
|
* Discovery resource for searching and finding tools on the Context Protocol marketplace
|
|
@@ -734,6 +102,8 @@ declare class Tools {
|
|
|
734
102
|
declare class Query {
|
|
735
103
|
private client;
|
|
736
104
|
constructor(client: ContextClient);
|
|
105
|
+
private normalizeResult;
|
|
106
|
+
private buildPolicyErrorEvent;
|
|
737
107
|
private buildSyntheticTraceFromRunResult;
|
|
738
108
|
private buildSyntheticTraceFromStreamStatus;
|
|
739
109
|
private mergeDeveloperTrace;
|
|
@@ -891,4 +261,4 @@ declare class ContextClient {
|
|
|
891
261
|
_fetchRaw(endpoint: string, options?: RequestInit): Promise<Response>;
|
|
892
262
|
}
|
|
893
263
|
|
|
894
|
-
export { ContextClient,
|
|
264
|
+
export { ContextClient, ContextClientOptions, Discovery, ExecuteOptions, ExecuteSessionResult, ExecuteSessionStartOptions, ExecutionResult, Query, QueryOptions, QueryResult, QueryStreamEvent, SearchOptions, Tool, Tools };
|