zidane 1.7.0 → 1.8.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/dist/{agent-B__ISsOE.d.ts → agent-CWQ5XOw6.d.ts} +405 -5
- package/dist/{chunk-V4PBD7LE.js → chunk-2IB4XBQE.js} +162 -0
- package/dist/{chunk-T6MC3WP5.js → chunk-3RJOWJOJ.js} +1 -1
- package/dist/{chunk-O4QCBJQF.js → chunk-4N5ADW7A.js} +382 -73
- package/dist/{chunk-QCJKUQTQ.js → chunk-EC7IRWVS.js} +135 -4
- package/dist/chunk-FFFDQHMA.js +68 -0
- package/dist/{chunk-WDBO3JCO.js → chunk-TBC6MSVK.js} +118 -7
- package/dist/chunk-WQBKOZVI.js +641 -0
- package/dist/glob-j9gbk6xm.d.ts +5 -0
- package/dist/harnesses.d.ts +1 -1
- package/dist/harnesses.js +4 -3
- package/dist/index.d.ts +68 -4
- package/dist/index.js +152 -6
- package/dist/mcp.d.ts +1 -1
- package/dist/mcp.js +3 -1
- package/dist/providers.d.ts +1 -1
- package/dist/providers.js +16 -615
- package/dist/session.d.ts +1 -1
- package/dist/session.js +5 -2
- package/dist/{spawn-DRamirTu.d.ts → spawn-EEv1Johs.d.ts} +1 -1
- package/dist/tools.d.ts +3 -2
- package/dist/tools.js +5 -2
- package/dist/types.d.ts +2 -2
- package/dist/types.js +14 -0
- package/package.json +1 -1
|
@@ -3,6 +3,80 @@ import { b as ExecutionContext, c as ExecutionHandle } from './types-BpvTmawk.js
|
|
|
3
3
|
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
|
|
4
4
|
import { b as SkillsConfig, S as SkillConfig } from './types-CDI8Kmve.js';
|
|
5
5
|
|
|
6
|
+
/**
|
|
7
|
+
* Typed error classes for agent runs.
|
|
8
|
+
*
|
|
9
|
+
* Providers classify native errors into one of these so downstream consumers
|
|
10
|
+
* (e.g. harness adapters) can react without string-sniffing messages.
|
|
11
|
+
*
|
|
12
|
+
* Provider authors: implement `Provider.classifyError` to map native errors
|
|
13
|
+
* (SDK exceptions, HTTP responses) to a `ClassifiedError`. The loop wraps
|
|
14
|
+
* unclassified errors in `AgentProviderError` automatically.
|
|
15
|
+
*/
|
|
16
|
+
/** Kind of classified provider error */
|
|
17
|
+
type ClassifiedErrorKind = 'context_exceeded' | 'provider_error' | 'aborted';
|
|
18
|
+
/** Structured classification returned by `Provider.classifyError` */
|
|
19
|
+
interface ClassifiedError {
|
|
20
|
+
kind: ClassifiedErrorKind;
|
|
21
|
+
/** Upstream error code as surfaced by the provider (e.g. `context_length_exceeded`). Optional. */
|
|
22
|
+
providerCode?: string;
|
|
23
|
+
/** Optional human-readable message override. Falls back to the underlying error's message. */
|
|
24
|
+
message?: string;
|
|
25
|
+
}
|
|
26
|
+
interface TypedErrorOptions {
|
|
27
|
+
/** Provider name, always set (e.g. `anthropic`, `openrouter`) */
|
|
28
|
+
provider: string;
|
|
29
|
+
/** Optional upstream error code */
|
|
30
|
+
providerCode?: string;
|
|
31
|
+
/** Original error from the provider SDK/HTTP layer */
|
|
32
|
+
cause?: unknown;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Thrown when the model or provider signals that the context window was exceeded.
|
|
36
|
+
* Downstream consumers should catch this, prune history, and retry.
|
|
37
|
+
*/
|
|
38
|
+
declare class AgentContextExceededError extends Error {
|
|
39
|
+
readonly code: "context_exceeded";
|
|
40
|
+
readonly provider: string;
|
|
41
|
+
readonly providerCode?: string;
|
|
42
|
+
constructor(message: string, options: TypedErrorOptions);
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Thrown when the provider returns a non-context error (auth, rate limit, server error, etc.).
|
|
46
|
+
* Catch-all for unclassified provider failures.
|
|
47
|
+
*/
|
|
48
|
+
declare class AgentProviderError extends Error {
|
|
49
|
+
readonly code: "provider_error";
|
|
50
|
+
readonly provider: string;
|
|
51
|
+
readonly providerCode?: string;
|
|
52
|
+
constructor(message: string, options: TypedErrorOptions);
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Thrown when a run is aborted by the consumer via `agent.abort()` or an external `AbortSignal`.
|
|
56
|
+
*/
|
|
57
|
+
declare class AgentAbortedError extends Error {
|
|
58
|
+
readonly code: "aborted";
|
|
59
|
+
constructor(message?: string, options?: {
|
|
60
|
+
cause?: unknown;
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Regex patterns matching common "context window exceeded" messages across providers.
|
|
65
|
+
*
|
|
66
|
+
* Use {@link matchesContextExceeded} to test a free-form error message against them.
|
|
67
|
+
* Provider authors can also compose these into their own `classifyError` fallbacks.
|
|
68
|
+
*/
|
|
69
|
+
declare const CONTEXT_EXCEEDED_MESSAGE_PATTERNS: readonly RegExp[];
|
|
70
|
+
/**
|
|
71
|
+
* Return true when `message` matches any of the known "context window exceeded"
|
|
72
|
+
* phrasings. Safe for `''` / non-strings (returns false).
|
|
73
|
+
*/
|
|
74
|
+
declare function matchesContextExceeded(message: unknown): boolean;
|
|
75
|
+
/**
|
|
76
|
+
* Convert a `ClassifiedError` + underlying cause into the matching typed error instance.
|
|
77
|
+
*/
|
|
78
|
+
declare function toTypedError(classification: ClassifiedError, provider: string, cause: unknown): AgentContextExceededError | AgentProviderError | AgentAbortedError;
|
|
79
|
+
|
|
6
80
|
/**
|
|
7
81
|
* Shared types for the agent system.
|
|
8
82
|
*/
|
|
@@ -47,6 +121,41 @@ interface ImageContent {
|
|
|
47
121
|
data: string;
|
|
48
122
|
};
|
|
49
123
|
}
|
|
124
|
+
/**
|
|
125
|
+
* One block of a multimodal user prompt.
|
|
126
|
+
*
|
|
127
|
+
* `agent.run({ prompt })` accepts either a plain string (treated as a single
|
|
128
|
+
* text part) or an array of these parts for multimodal inputs.
|
|
129
|
+
*
|
|
130
|
+
* `document` parts are routed per provider: PDF-style mime types are sent as
|
|
131
|
+
* native document blocks when the provider supports them; text documents are
|
|
132
|
+
* inlined as text with an attachment header. Providers that cannot handle an
|
|
133
|
+
* image or document throw early.
|
|
134
|
+
*/
|
|
135
|
+
type PromptPart = PromptTextPart | PromptImagePart | PromptDocumentPart;
|
|
136
|
+
interface PromptTextPart {
|
|
137
|
+
type: 'text';
|
|
138
|
+
text: string;
|
|
139
|
+
}
|
|
140
|
+
interface PromptImagePart {
|
|
141
|
+
type: 'image';
|
|
142
|
+
/** IANA media type (e.g. `image/png`, `image/jpeg`) */
|
|
143
|
+
mediaType: string;
|
|
144
|
+
/** Base64-encoded payload */
|
|
145
|
+
data: string;
|
|
146
|
+
/** Optional display name */
|
|
147
|
+
name?: string;
|
|
148
|
+
}
|
|
149
|
+
interface PromptDocumentPart {
|
|
150
|
+
type: 'document';
|
|
151
|
+
/** IANA media type (e.g. `application/pdf`, `text/plain`) */
|
|
152
|
+
mediaType: string;
|
|
153
|
+
/** Either a base64-encoded payload (`encoding: 'base64'`) or raw text (`encoding: 'text'`) */
|
|
154
|
+
data: string;
|
|
155
|
+
encoding: 'base64' | 'text';
|
|
156
|
+
/** Optional display name used in attachment headers */
|
|
157
|
+
name?: string;
|
|
158
|
+
}
|
|
50
159
|
type SessionContentBlock = {
|
|
51
160
|
type: 'text';
|
|
52
161
|
text: string;
|
|
@@ -85,12 +194,27 @@ interface SessionTurn {
|
|
|
85
194
|
/** Unix timestamp (Date.now()) when the turn was created */
|
|
86
195
|
createdAt: number;
|
|
87
196
|
}
|
|
197
|
+
/**
|
|
198
|
+
* Per-run hook registrations. Each entry can be a single handler or an array of handlers.
|
|
199
|
+
* Keys are `AgentHooks` event names (loose-typed here to avoid a circular import; agent.ts
|
|
200
|
+
* narrows it to the strongly-typed map).
|
|
201
|
+
*/
|
|
202
|
+
type RunHookMap = Record<string, ((ctx: any) => unknown) | ((ctx: any) => unknown)[]>;
|
|
88
203
|
interface AgentRunOptions {
|
|
89
204
|
model?: string;
|
|
90
|
-
/**
|
|
91
|
-
|
|
205
|
+
/**
|
|
206
|
+
* User prompt. Optional when resuming a session with existing turns.
|
|
207
|
+
*
|
|
208
|
+
* Accepts either a plain string (single text part) or an array of `PromptPart`s for
|
|
209
|
+
* multimodal inputs (text, images, documents). See {@link PromptPart}.
|
|
210
|
+
*/
|
|
211
|
+
prompt?: string | PromptPart[];
|
|
92
212
|
system?: string;
|
|
93
213
|
thinking?: ThinkingLevel;
|
|
214
|
+
/**
|
|
215
|
+
* Legacy image attachments. When `prompt` is a string, these are appended as image
|
|
216
|
+
* parts after the text. Ignored when `prompt` is a `PromptPart[]`.
|
|
217
|
+
*/
|
|
94
218
|
images?: ImageContent[];
|
|
95
219
|
/** Abort signal — when triggered, the agent stops after the current turn */
|
|
96
220
|
signal?: AbortSignal;
|
|
@@ -98,7 +222,16 @@ interface AgentRunOptions {
|
|
|
98
222
|
behavior?: AgentBehavior;
|
|
99
223
|
/** Tool overrides for this run. Pass {} for no tools. Omit to use harness tools. */
|
|
100
224
|
tools?: Record<string, ToolDef>;
|
|
225
|
+
/**
|
|
226
|
+
* Per-run hook registrations. Each hook is attached before the run starts and
|
|
227
|
+
* detached in a finally block so handlers never leak across runs.
|
|
228
|
+
*
|
|
229
|
+
* Accepts either a single handler or an array (all handlers register).
|
|
230
|
+
*/
|
|
231
|
+
hooks?: RunHookMap;
|
|
101
232
|
}
|
|
233
|
+
/** Reason the provider gave for stopping the turn */
|
|
234
|
+
type TurnFinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'error' | 'other';
|
|
102
235
|
interface TurnUsage {
|
|
103
236
|
input: number;
|
|
104
237
|
output: number;
|
|
@@ -110,6 +243,16 @@ interface TurnUsage {
|
|
|
110
243
|
thinking?: number;
|
|
111
244
|
/** Cost in USD as reported by the provider (OpenRouter) */
|
|
112
245
|
cost?: number;
|
|
246
|
+
/**
|
|
247
|
+
* Why the model stopped this turn. Providers normalize native stop reasons to this union.
|
|
248
|
+
* Absent when the provider did not surface a reason (e.g. mock turns).
|
|
249
|
+
*/
|
|
250
|
+
finishReason?: TurnFinishReason;
|
|
251
|
+
/**
|
|
252
|
+
* The model ID the provider ultimately used. May differ from the requested model when the
|
|
253
|
+
* provider remaps aliases. Absent for providers that do not echo a model ID.
|
|
254
|
+
*/
|
|
255
|
+
modelId?: string;
|
|
113
256
|
}
|
|
114
257
|
interface AgentStats {
|
|
115
258
|
totalIn: number;
|
|
@@ -124,25 +267,58 @@ interface AgentStats {
|
|
|
124
267
|
children?: ChildRunStats[];
|
|
125
268
|
/** Structured output from schema enforcement (only present when behavior.schema is set) */
|
|
126
269
|
output?: Record<string, unknown>;
|
|
270
|
+
/**
|
|
271
|
+
* Milliseconds from the start of `agent.run()` to the first observable signal from the
|
|
272
|
+
* provider (first `stream:text`, `stream:thinking`, or `tool:before` event).
|
|
273
|
+
*
|
|
274
|
+
* Absent when the run produced no observable signals (e.g. aborted before any stream event).
|
|
275
|
+
*/
|
|
276
|
+
timeTillFirstTokenMs?: number;
|
|
127
277
|
}
|
|
128
278
|
interface ChildRunStats {
|
|
129
279
|
id: string;
|
|
130
280
|
task: string;
|
|
131
281
|
stats: AgentStats;
|
|
132
282
|
}
|
|
133
|
-
/**
|
|
283
|
+
/**
|
|
284
|
+
* Base context for tool execution hooks.
|
|
285
|
+
*
|
|
286
|
+
* `name` is the canonical tool identity — the spec name defined in the harness (or the
|
|
287
|
+
* `mcp_{server}_{tool}` name for MCP tools). Hooks should policy-match against `name`.
|
|
288
|
+
*
|
|
289
|
+
* `displayName` is the outward-facing name — the alias surfaced to the LLM when
|
|
290
|
+
* `HarnessConfig.toolAliases` maps the canonical name; otherwise equal to `name`.
|
|
291
|
+
* UI/telemetry adapters should emit `displayName`.
|
|
292
|
+
*
|
|
293
|
+
* Canonical vs. alias matters on session resume: `session.turns` persists canonical
|
|
294
|
+
* names only, so renaming an alias cannot desync history.
|
|
295
|
+
*/
|
|
134
296
|
interface ToolHookContext {
|
|
135
297
|
turnId: string;
|
|
136
298
|
callId: string;
|
|
299
|
+
/** Canonical tool name (harness spec name). Stable across alias-map changes. */
|
|
137
300
|
name: string;
|
|
301
|
+
/** Aliased (wire) name — equal to `name` when no alias is defined. */
|
|
302
|
+
displayName: string;
|
|
138
303
|
input: Record<string, unknown>;
|
|
139
304
|
}
|
|
140
|
-
/**
|
|
305
|
+
/**
|
|
306
|
+
* Base context for MCP tool hooks.
|
|
307
|
+
*
|
|
308
|
+
* `tool` is the native tool name on the MCP server. `server` is the configured server
|
|
309
|
+
* name. The canonical zidane-namespaced identity is `mcp_{server}_{tool}`.
|
|
310
|
+
*
|
|
311
|
+
* `displayName` equals the canonical namespaced name unless the harness has aliased
|
|
312
|
+
* this MCP tool via `HarnessConfig.toolAliases`; in which case `displayName` is the
|
|
313
|
+
* alias that the LLM sees.
|
|
314
|
+
*/
|
|
141
315
|
interface McpToolHookContext {
|
|
142
316
|
turnId: string;
|
|
143
317
|
callId: string;
|
|
144
318
|
server: string;
|
|
145
319
|
tool: string;
|
|
320
|
+
/** Aliased wire name for this MCP tool, or the canonical `mcp_{server}_{tool}` name. */
|
|
321
|
+
displayName: string;
|
|
146
322
|
input: Record<string, unknown>;
|
|
147
323
|
}
|
|
148
324
|
/** Base context for session hooks */
|
|
@@ -182,6 +358,12 @@ interface AnthropicParams {
|
|
|
182
358
|
refresh?: string;
|
|
183
359
|
expires?: number;
|
|
184
360
|
defaultModel?: string;
|
|
361
|
+
/**
|
|
362
|
+
* Optional override for the Anthropic SDK base URL. Honored end-to-end — headers and
|
|
363
|
+
* routing pass through to the forwarded host. Useful for proxies (e.g. corporate
|
|
364
|
+
* gateways, internal router).
|
|
365
|
+
*/
|
|
366
|
+
baseURL?: string;
|
|
185
367
|
}
|
|
186
368
|
declare function anthropic(anthropicParams?: AnthropicParams): Provider;
|
|
187
369
|
|
|
@@ -189,6 +371,12 @@ interface CerebrasParams {
|
|
|
189
371
|
apiKey?: string;
|
|
190
372
|
defaultModel?: string;
|
|
191
373
|
}
|
|
374
|
+
/**
|
|
375
|
+
* Cerebras provider.
|
|
376
|
+
*
|
|
377
|
+
* Thin wrapper around {@link openaiCompat} with Cerebras-specific defaults
|
|
378
|
+
* (base URL, default model).
|
|
379
|
+
*/
|
|
192
380
|
declare function cerebras(params?: CerebrasParams): Provider;
|
|
193
381
|
|
|
194
382
|
interface OpenAIParams {
|
|
@@ -204,10 +392,98 @@ interface OpenAIParams {
|
|
|
204
392
|
}
|
|
205
393
|
declare function openai(params?: OpenAIParams): Provider;
|
|
206
394
|
|
|
395
|
+
/**
|
|
396
|
+
* OpenAI-compatible provider factory + shared utilities.
|
|
397
|
+
*
|
|
398
|
+
* `openaiCompat(params)` returns a `Provider` that talks to any OpenAI-compatible
|
|
399
|
+
* HTTP endpoint (OpenRouter, Cerebras, Baseten, Fireworks, Groq, local LM servers, ...).
|
|
400
|
+
* Helpers (`consumeSSE`, `toOAIMessages`, ...) are shared by the bespoke `openrouter`
|
|
401
|
+
* and `cerebras` wrappers, which pin defaults on top of this factory.
|
|
402
|
+
*/
|
|
403
|
+
|
|
404
|
+
/**
|
|
405
|
+
* HTTP error thrown when an OpenAI-compatible endpoint returns a non-OK response.
|
|
406
|
+
*
|
|
407
|
+
* The body is best-effort JSON-parsed; `error.message` / `error.code` / `error.type`
|
|
408
|
+
* are extracted for clean downstream classification.
|
|
409
|
+
*/
|
|
410
|
+
declare class OpenAICompatHttpError extends Error {
|
|
411
|
+
readonly status: number;
|
|
412
|
+
readonly providerCode?: string;
|
|
413
|
+
readonly bodyText: string;
|
|
414
|
+
constructor(status: number, bodyText: string);
|
|
415
|
+
}
|
|
416
|
+
/**
|
|
417
|
+
* Classify an OpenAI-compatible error into `ClassifiedError`.
|
|
418
|
+
*
|
|
419
|
+
* Recognizes:
|
|
420
|
+
* - `AbortError` (from fetch) → `aborted`.
|
|
421
|
+
* - `OpenAICompatHttpError` with a context-exceeded code or message → `context_exceeded`.
|
|
422
|
+
* - Any other `OpenAICompatHttpError` → `provider_error`.
|
|
423
|
+
*
|
|
424
|
+
* Returns `null` for unrecognized error shapes (the loop falls back to `AgentProviderError`).
|
|
425
|
+
*/
|
|
426
|
+
declare function classifyOpenAICompatError(err: unknown): ClassifiedError | null;
|
|
427
|
+
/**
|
|
428
|
+
* Map an OpenAI-compatible `finish_reason` string to the zidane `TurnFinishReason` union.
|
|
429
|
+
*/
|
|
430
|
+
declare function mapOAIFinishReason(reason: string | null | undefined): TurnFinishReason | undefined;
|
|
431
|
+
/**
|
|
432
|
+
* Auth header config. `scheme` is prepended to the api key with a space, e.g.
|
|
433
|
+
* `{ name: 'Authorization', scheme: 'Bearer' }` → `Authorization: Bearer <key>`.
|
|
434
|
+
* Omit `scheme` for raw header values (e.g. `{ name: 'X-Api-Key' }` → `X-Api-Key: <key>`).
|
|
435
|
+
*
|
|
436
|
+
* Real-world examples:
|
|
437
|
+
* - Default OpenAI / OpenRouter / Cerebras: `{ name: 'Authorization', scheme: 'Bearer' }`.
|
|
438
|
+
* - Baseten: `{ name: 'Authorization', scheme: 'Api-Key' }`.
|
|
439
|
+
* - Some gateways: `{ name: 'X-Api-Key' }`.
|
|
440
|
+
*/
|
|
441
|
+
interface OpenAICompatAuthHeader {
|
|
442
|
+
name: string;
|
|
443
|
+
scheme?: string;
|
|
444
|
+
}
|
|
445
|
+
interface OpenAICompatParams {
|
|
446
|
+
/** Bearer-style API key. */
|
|
447
|
+
apiKey: string;
|
|
448
|
+
/** Base URL — `/chat/completions` is appended. */
|
|
449
|
+
baseURL: string;
|
|
450
|
+
/** Default model id when `run({ model })` is omitted. */
|
|
451
|
+
defaultModel?: string;
|
|
452
|
+
/** Provider name exposed as `Provider.name`. Defaults to `'openai-compat'`. */
|
|
453
|
+
name?: string;
|
|
454
|
+
/** Auth header shape. Defaults to `{ name: 'Authorization', scheme: 'Bearer' }`. */
|
|
455
|
+
authHeader?: OpenAICompatAuthHeader;
|
|
456
|
+
/** Extra headers sent with every request (e.g. referer, user-agent). */
|
|
457
|
+
extraHeaders?: Record<string, string>;
|
|
458
|
+
}
|
|
459
|
+
/**
|
|
460
|
+
* Factory for any OpenAI-compatible HTTP endpoint.
|
|
461
|
+
*
|
|
462
|
+
* Speaks the standard `POST /chat/completions` + `stream: true` + SSE dialect.
|
|
463
|
+
* Thin wrappers (`openrouter`, `cerebras`) call this with pinned defaults.
|
|
464
|
+
*
|
|
465
|
+
* @example Baseten (non-standard auth scheme)
|
|
466
|
+
* ```ts
|
|
467
|
+
* openaiCompat({
|
|
468
|
+
* name: 'baseten',
|
|
469
|
+
* apiKey: process.env.BASETEN_API_KEY!,
|
|
470
|
+
* baseURL: process.env.BASETEN_PROXY_URL!,
|
|
471
|
+
* authHeader: { name: 'Authorization', scheme: 'Api-Key' },
|
|
472
|
+
* })
|
|
473
|
+
* ```
|
|
474
|
+
*/
|
|
475
|
+
declare function openaiCompat(params: OpenAICompatParams): Provider;
|
|
476
|
+
|
|
207
477
|
interface OpenRouterParams {
|
|
208
478
|
apiKey?: string;
|
|
209
479
|
defaultModel?: string;
|
|
210
480
|
}
|
|
481
|
+
/**
|
|
482
|
+
* OpenRouter provider.
|
|
483
|
+
*
|
|
484
|
+
* Thin wrapper around {@link openaiCompat} with OpenRouter-specific defaults
|
|
485
|
+
* (base URL, default model) and required attribution headers.
|
|
486
|
+
*/
|
|
211
487
|
declare function openrouter(params?: OpenRouterParams): Provider;
|
|
212
488
|
|
|
213
489
|
interface ToolSpec {
|
|
@@ -273,6 +549,23 @@ interface Provider {
|
|
|
273
549
|
toolResultsMessage: (results: ToolResult[]) => SessionMessage;
|
|
274
550
|
/** Stream a turn, calling onText for each text delta */
|
|
275
551
|
stream: (options: StreamOptions, callbacks: StreamCallbacks) => Promise<TurnResult>;
|
|
552
|
+
/**
|
|
553
|
+
* Build a user `SessionMessage` from multimodal prompt parts.
|
|
554
|
+
*
|
|
555
|
+
* Providers that cannot handle a particular part type (e.g. document) should throw.
|
|
556
|
+
* The agent loop always canonicalizes the run-level prompt into parts before calling
|
|
557
|
+
* this method; providers may fall back to `userMessage` for the text-only path if
|
|
558
|
+
* they do not implement this.
|
|
559
|
+
*/
|
|
560
|
+
promptMessage?: (parts: PromptPart[]) => SessionMessage;
|
|
561
|
+
/**
|
|
562
|
+
* Classify a native provider error for downstream typed-error wrapping.
|
|
563
|
+
*
|
|
564
|
+
* Return `null` when the error is not recognized — the loop will wrap it in
|
|
565
|
+
* `AgentProviderError` with the provider's name. Return a `ClassifiedError` to
|
|
566
|
+
* route it to one of the typed error classes.
|
|
567
|
+
*/
|
|
568
|
+
classifyError?: (err: unknown) => ClassifiedError | null;
|
|
276
569
|
}
|
|
277
570
|
|
|
278
571
|
/** Core tools available in every basic harness (without spawn) */
|
|
@@ -324,6 +617,31 @@ interface HarnessConfig {
|
|
|
324
617
|
skills?: SkillsConfig;
|
|
325
618
|
/** Default behavior for agents using this harness */
|
|
326
619
|
behavior?: AgentBehavior;
|
|
620
|
+
/**
|
|
621
|
+
* Map canonical tool names to LLM-facing (aliased) names.
|
|
622
|
+
*
|
|
623
|
+
* Aliasing is **LLM-boundary-only**:
|
|
624
|
+
* - The alias is what the provider's tool spec carries, what the model calls it, and
|
|
625
|
+
* what appears in `ToolHookContext.displayName` / `McpToolHookContext.displayName`.
|
|
626
|
+
* - The canonical name is what lives in `session.turns`, `ToolHookContext.name`, and
|
|
627
|
+
* what the agent uses to look up the tool implementation. Alias changes never
|
|
628
|
+
* desync persisted history.
|
|
629
|
+
*
|
|
630
|
+
* Keys are canonical names from `tools` (or `mcp_{server}_{tool}` for MCP tools).
|
|
631
|
+
* Collisions between aliases are rejected by the loop.
|
|
632
|
+
*
|
|
633
|
+
* @example
|
|
634
|
+
* ```ts
|
|
635
|
+
* defineHarness({
|
|
636
|
+
* tools: { ...basicTools },
|
|
637
|
+
* toolAliases: { shell: 'Bash', read_file: 'Read', write_file: 'Write' },
|
|
638
|
+
* })
|
|
639
|
+
* ```
|
|
640
|
+
*
|
|
641
|
+
* @remarks Alias a tool only when the aliased name is semantically equivalent.
|
|
642
|
+
* `list_files` → `Glob` is NOT a valid alias because Glob is pattern-based.
|
|
643
|
+
*/
|
|
644
|
+
toolAliases?: Record<string, string>;
|
|
327
645
|
}
|
|
328
646
|
/**
|
|
329
647
|
* Define a harness with a name, optional system prompt, and tools.
|
|
@@ -347,6 +665,19 @@ interface McpConnection {
|
|
|
347
665
|
tools: Record<string, ToolDef>;
|
|
348
666
|
close: () => Promise<void>;
|
|
349
667
|
}
|
|
668
|
+
/**
|
|
669
|
+
* Normalize MCP server configs from any common shape to `McpServerConfig[]`.
|
|
670
|
+
*
|
|
671
|
+
* Accepts:
|
|
672
|
+
* - `McpServerConfig[]` — zidane native (pass-through).
|
|
673
|
+
* - `McpServerConfig` — a single config object (wrapped to a 1-element array).
|
|
674
|
+
* - `Record<string, RawShape>` — name-keyed map (common in host-SDK configs), where the key is the server name.
|
|
675
|
+
* - Mixed shapes with `type` vs `transport`, `httpUrl`/`sseUrl` vs `url`.
|
|
676
|
+
*
|
|
677
|
+
* Returns `[]` when `input` is nullish. Throws a descriptive error when the transport
|
|
678
|
+
* cannot be inferred from a given entry, or when the input shape is unsupported.
|
|
679
|
+
*/
|
|
680
|
+
declare function normalizeMcpServers(input: unknown): McpServerConfig[];
|
|
350
681
|
/**
|
|
351
682
|
* Convert MCP tool result content blocks to a single string.
|
|
352
683
|
* Text blocks are extracted; non-text blocks are JSON-stringified.
|
|
@@ -364,6 +695,68 @@ declare function resultToString(content: unknown[]): string;
|
|
|
364
695
|
*/
|
|
365
696
|
declare function connectMcpServers(configs: McpServerConfig[], _clientFactory?: () => Client, hooks?: Hookable<AgentHooks>): Promise<McpConnection>;
|
|
366
697
|
|
|
698
|
+
/**
|
|
699
|
+
* File-map session store.
|
|
700
|
+
*
|
|
701
|
+
* Wraps a narrow 3-method adapter (`get` / `save` / `delete`) that exchanges a flat
|
|
702
|
+
* map of filename → string content. Useful for embedding zidane sessions inside
|
|
703
|
+
* host-provided session backends that only speak in file maps (not zidane's native
|
|
704
|
+
* `SessionStore` shape).
|
|
705
|
+
*
|
|
706
|
+
* Serialization format:
|
|
707
|
+
* - `turns.jsonl` — one `SessionTurn` per line.
|
|
708
|
+
* - `meta.json` — session metadata (id, agentId, status, runs, metadata, timestamps).
|
|
709
|
+
*
|
|
710
|
+
* JSONL for turns keeps history inspectable with tools like `jq` and resilient to
|
|
711
|
+
* partial corruption — parse up to the first bad line and you still have a valid
|
|
712
|
+
* prefix. Metadata lives in its own file so large turn logs don't bloat the
|
|
713
|
+
* metadata path.
|
|
714
|
+
*
|
|
715
|
+
* Scope: each `createFileMapStore` handles a **single session** — the adapter's
|
|
716
|
+
* file map holds at most one zidane session at a time. This matches how host SDKs
|
|
717
|
+
* scope their session stores per conversation.
|
|
718
|
+
*
|
|
719
|
+
* Divergences from the built-in memory / sqlite stores:
|
|
720
|
+
* - `appendTurns` / `updateStatus` / `updateRun` auto-create a minimal `SessionData`
|
|
721
|
+
* record on first write, instead of silently no-oping when the session hasn't been
|
|
722
|
+
* explicitly `save()`-ed. This matches the host-SDK integration path where
|
|
723
|
+
* `createSession(...)` → `agent.run(...)` directly without an explicit `save()` call.
|
|
724
|
+
* - `updateRun` inserts the run if not found in the cached record (rather than
|
|
725
|
+
* silently dropping). Run records therefore always reach the adapter.
|
|
726
|
+
*/
|
|
727
|
+
|
|
728
|
+
/**
|
|
729
|
+
* Host-provided file-map adapter. Three methods exchanging `Record<string, string>`
|
|
730
|
+
* payloads — the whole persistence surface the wrapper needs.
|
|
731
|
+
*/
|
|
732
|
+
interface FileMapAdapter {
|
|
733
|
+
/** Load the current file map. Returns an empty `files` record when nothing is persisted. */
|
|
734
|
+
get: () => Promise<{
|
|
735
|
+
files: Record<string, string>;
|
|
736
|
+
}>;
|
|
737
|
+
/** Replace the persisted file map. Full-rewrite semantics. */
|
|
738
|
+
save: (files: Record<string, string>) => Promise<void>;
|
|
739
|
+
/** Delete all persisted state. */
|
|
740
|
+
delete: () => Promise<void>;
|
|
741
|
+
}
|
|
742
|
+
interface FileMapStoreOptions {
|
|
743
|
+
/** Filename for the JSONL turns log. Default: `turns.jsonl`. */
|
|
744
|
+
turnsFile?: string;
|
|
745
|
+
/** Filename for the metadata JSON. Default: `meta.json`. */
|
|
746
|
+
metaFile?: string;
|
|
747
|
+
}
|
|
748
|
+
/**
|
|
749
|
+
* Create a single-session `SessionStore` backed by a file-map adapter.
|
|
750
|
+
*
|
|
751
|
+
* @example
|
|
752
|
+
* ```ts
|
|
753
|
+
* const session = await createSession({
|
|
754
|
+
* store: createFileMapStore(hostSessionStore),
|
|
755
|
+
* })
|
|
756
|
+
* ```
|
|
757
|
+
*/
|
|
758
|
+
declare function createFileMapStore(adapter: FileMapAdapter, options?: FileMapStoreOptions): SessionStore;
|
|
759
|
+
|
|
367
760
|
/**
|
|
368
761
|
* In-memory session store.
|
|
369
762
|
* Useful for development and testing. Data is lost when the process exits.
|
|
@@ -495,6 +888,13 @@ interface Session {
|
|
|
495
888
|
readonly agentId?: string;
|
|
496
889
|
/** Current turn history */
|
|
497
890
|
readonly turns: SessionTurn[];
|
|
891
|
+
/**
|
|
892
|
+
* True when this session has no turns yet.
|
|
893
|
+
*
|
|
894
|
+
* Use this as a first-prompt signal when setting up a run — e.g. writing initial
|
|
895
|
+
* configuration only on fresh sessions. Equivalent to `turns.length === 0`.
|
|
896
|
+
*/
|
|
897
|
+
readonly isEmpty: boolean;
|
|
498
898
|
/** Top-level session status */
|
|
499
899
|
readonly status: SessionData['status'];
|
|
500
900
|
/** All runs in this session */
|
|
@@ -714,4 +1114,4 @@ interface Agent {
|
|
|
714
1114
|
}
|
|
715
1115
|
declare function createAgent({ harness: harnessOption, provider, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, _mcpConnector }: AgentOptions): Agent;
|
|
716
1116
|
|
|
717
|
-
export {
|
|
1117
|
+
export { type ToolResult as $, type Agent as A, type SessionEndStatus as B, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as C, type SessionHookContext as D, type SessionMessage as E, type SessionRun as F, type SessionStore as G, type Harness as H, type ImageContent as I, type SessionTurn as J, type SpawnHookContext as K, type SqliteStoreOptions as L, type McpConnection as M, type StreamCallbacks as N, type OAuthRefreshHookContext as O, type PromptDocumentPart as P, type StreamHookContext as Q, type RemoteStoreOptions as R, type Session as S, type StreamOptions as T, type ThinkingLevel as U, type ToolCall as V, type ToolContext as W, type ToolDef as X, type ToolExecutionMode as Y, type ToolHookContext as Z, type ToolMap as _, AgentAbortedError as a, type ToolSpec as a0, type TurnFinishReason as a1, type TurnResult as a2, type TurnUsage as a3, matchesContextExceeded as a4, type FileMapAdapter as a5, type FileMapStoreOptions as a6, type OpenAICompatAuthHeader as a7, OpenAICompatHttpError as a8, type OpenAICompatParams as a9, resultToString as aA, anthropic as aa, autoDetectAndConvert as ab, cerebras as ac, classifyOpenAICompatError as ad, connectMcpServers as ae, createAgent as af, createFileMapStore as ag, createMemoryStore as ah, createRemoteStore as ai, createSession as aj, createSqliteStore as ak, defineHarness as al, fromAnthropic as am, fromOpenAI as an, loadSession as ao, mapOAIFinishReason as ap, noTools as aq, normalizeMcpServers as ar, openai as as, openaiCompat as at, openrouter as au, toAnthropic as av, toOpenAI as aw, toTypedError as ax, _default as ay, basicTools as az, type AgentBehavior as b, AgentContextExceededError as c, type AgentHooks as d, type AgentOptions as e, AgentProviderError as f, type AgentRunOptions as g, type AgentStats as h, type AnthropicParams as i, type CerebrasParams as j, type ChildRunStats as k, type ClassifiedError as l, type ClassifiedErrorKind as m, type CreateSessionOptions as n, type HarnessConfig as o, type McpServerConfig as p, type McpToolHookContext as q, type OpenAIParams as r, type OpenRouterParams as s, type PromptImagePart as t, type PromptPart as u, type PromptTextPart as v, type Provider as w, type RunHookMap as x, type SessionContentBlock as y, type SessionData as z };
|