fascicle 0.6.3 → 0.8.10

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.
@@ -0,0 +1,430 @@
1
+ import { J as TrajectoryLogger } from "./index-CEj6hY9z.js";
2
+ import { z } from "zod";
3
+
4
+ //#region src/engine/providers/claude_cli/types.d.ts
5
+ /**
6
+ * Public types for the claude_cli subprocess provider (spec §5.1, §5.3, §5.4).
7
+ *
8
+ * Value fields are snake_case; exported type aliases are PascalCase. These
9
+ * types are re-exported from packages/engine/src/index.ts so callers can
10
+ * narrow provider-scoped options and provider_reported values at their use
11
+ * site.
12
+ */
13
+ type AuthMode = 'auto' | 'oauth' | 'api_key';
14
+ type SandboxProviderConfig = {
15
+ readonly kind: 'bwrap';
16
+ readonly network_allowlist?: ReadonlyArray<string>;
17
+ readonly additional_write_paths?: ReadonlyArray<string>;
18
+ } | {
19
+ readonly kind: 'greywall';
20
+ readonly network_allowlist?: ReadonlyArray<string>;
21
+ readonly additional_write_paths?: ReadonlyArray<string>;
22
+ /**
23
+ * greywall 0.3+ takes filesystem/network policy from a JSON settings
24
+ * file. By default the adapter writes a temp settings file derived
25
+ * from `network_allowlist`/`additional_write_paths`. Set to forward
26
+ * a caller-managed settings file directly via `--settings` instead.
27
+ * The temp-file path is then skipped entirely.
28
+ */
29
+ readonly settings_path?: string;
30
+ };
31
+ type ClaudeCliProviderConfig = {
32
+ readonly binary?: string;
33
+ readonly auth_mode?: AuthMode;
34
+ readonly api_key?: string;
35
+ /**
36
+ * The subprocess env seeds the standard process-env keys
37
+ * (PATH/HOME/SHELL/USER/LOGNAME/LANG/TMPDIR) by default under every
38
+ * auth mode so the spawn target (sandbox wrapper or the claude binary)
39
+ * can be resolved on PATH. Under `auth_mode: 'oauth'` the *full*
40
+ * `process.env` is inherited so the CLI can reach the logged-in OAuth
41
+ * session. Set to `false` to opt out and start from an empty env.
42
+ */
43
+ readonly inherit_env?: boolean;
44
+ readonly default_cwd?: string;
45
+ readonly startup_timeout_ms?: number;
46
+ readonly stall_timeout_ms?: number;
47
+ readonly setting_sources?: ReadonlyArray<'user' | 'project' | 'local'>;
48
+ readonly plugin_dirs?: ReadonlyArray<string>;
49
+ readonly sandbox?: SandboxProviderConfig;
50
+ readonly skip_probe?: boolean;
51
+ };
52
+ //#endregion
53
+ //#region src/engine/types.d.ts
54
+ type EffortLevel = 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
55
+ type FinishReason = 'stop' | 'tool_calls' | 'length' | 'content_filter' | 'aborted' | 'max_steps';
56
+ type RetryFailureKind = 'rate_limit' | 'provider_5xx' | 'network' | 'timeout';
57
+ type RetryPolicy = {
58
+ max_attempts: number;
59
+ initial_delay_ms: number;
60
+ max_delay_ms: number;
61
+ retry_on: ReadonlyArray<RetryFailureKind>;
62
+ };
63
+ /**
64
+ * The resolved transport + model id a generate call dispatches to. `model_id`
65
+ * is passed verbatim to the provider; the engine does not interpret it.
66
+ */
67
+ type ResolvedModel = {
68
+ provider: string;
69
+ model_id: string;
70
+ };
71
+ type Pricing = {
72
+ input_per_million: number;
73
+ output_per_million: number;
74
+ cached_input_per_million?: number;
75
+ cache_write_per_million?: number;
76
+ reasoning_per_million?: number;
77
+ };
78
+ type PricingTable = Readonly<Record<string, Pricing>>;
79
+ type UsageTotals = {
80
+ input_tokens: number;
81
+ output_tokens: number;
82
+ reasoning_tokens?: number;
83
+ cached_input_tokens?: number;
84
+ cache_write_tokens?: number;
85
+ };
86
+ type CostBreakdown = {
87
+ total_usd: number;
88
+ input_usd: number;
89
+ output_usd: number;
90
+ cached_input_usd?: number;
91
+ cache_write_usd?: number;
92
+ reasoning_usd?: number;
93
+ currency: 'USD';
94
+ is_estimate: true;
95
+ };
96
+ type ToolCallRecord = {
97
+ id: string;
98
+ name: string;
99
+ input: unknown;
100
+ output?: unknown;
101
+ error?: {
102
+ message: string;
103
+ stack?: string;
104
+ };
105
+ duration_ms: number;
106
+ started_at: number;
107
+ };
108
+ type StepRecord = {
109
+ index: number;
110
+ text: string;
111
+ tool_calls: ToolCallRecord[];
112
+ usage: UsageTotals;
113
+ cost?: CostBreakdown;
114
+ finish_reason: FinishReason;
115
+ };
116
+ type UserContentPart = {
117
+ type: 'text';
118
+ text: string;
119
+ } | {
120
+ type: 'image';
121
+ image: Uint8Array | string;
122
+ media_type?: string;
123
+ };
124
+ type AssistantContentPart = {
125
+ type: 'text';
126
+ text: string;
127
+ } | {
128
+ type: 'tool_call';
129
+ id: string;
130
+ name: string;
131
+ input: unknown;
132
+ };
133
+ type Message = {
134
+ role: 'system';
135
+ content: string;
136
+ } | {
137
+ role: 'user';
138
+ content: string | UserContentPart[];
139
+ } | {
140
+ role: 'assistant';
141
+ content: string | AssistantContentPart[];
142
+ } | {
143
+ role: 'tool';
144
+ tool_call_id: string;
145
+ name: string;
146
+ content: string;
147
+ };
148
+ type ToolExecContext = {
149
+ abort: AbortSignal;
150
+ trajectory?: TrajectoryLogger;
151
+ tool_call_id: string;
152
+ step_index: number;
153
+ };
154
+ type Tool<i = unknown, o = unknown> = {
155
+ name: string;
156
+ description: string;
157
+ input_schema: z.ZodType<i>;
158
+ execute: (input: i, ctx: ToolExecContext) => Promise<o> | o;
159
+ needs_approval?: boolean | ((input: i) => boolean | Promise<boolean>);
160
+ };
161
+ type ToolApprovalRequest = {
162
+ tool_name: string;
163
+ input: unknown;
164
+ step_index: number;
165
+ abort: AbortSignal;
166
+ };
167
+ type ToolApprovalHandler = (request: ToolApprovalRequest) => boolean | Promise<boolean>;
168
+ type StreamChunk = {
169
+ kind: 'text';
170
+ text: string;
171
+ step_index: number;
172
+ } | {
173
+ kind: 'reasoning';
174
+ text: string;
175
+ step_index: number;
176
+ } | {
177
+ kind: 'tool_call_start';
178
+ id: string;
179
+ name: string;
180
+ step_index: number;
181
+ } | {
182
+ kind: 'tool_call_input_delta';
183
+ id: string;
184
+ delta: string;
185
+ step_index: number;
186
+ } | {
187
+ kind: 'tool_call_end';
188
+ id: string;
189
+ input: unknown;
190
+ step_index: number;
191
+ } | {
192
+ kind: 'tool_result';
193
+ id: string;
194
+ output?: unknown;
195
+ error?: {
196
+ message: string;
197
+ };
198
+ step_index: number;
199
+ } | {
200
+ kind: 'step_finish';
201
+ step_index: number;
202
+ finish_reason: FinishReason;
203
+ usage: UsageTotals;
204
+ } | {
205
+ kind: 'finish';
206
+ finish_reason: FinishReason;
207
+ usage: UsageTotals;
208
+ };
209
+ type GenerateOptions<t = string> = {
210
+ model?: string;
211
+ provider?: string;
212
+ prompt: string | Message[];
213
+ system?: string;
214
+ schema?: z.ZodType<t>;
215
+ tools?: Tool[];
216
+ effort?: EffortLevel;
217
+ temperature?: number;
218
+ max_tokens?: number;
219
+ top_p?: number;
220
+ max_steps?: number;
221
+ abort?: AbortSignal;
222
+ trajectory?: TrajectoryLogger;
223
+ on_chunk?: (chunk: StreamChunk) => void | Promise<void>;
224
+ retry?: RetryPolicy;
225
+ tool_error_policy?: 'feed_back' | 'throw';
226
+ schema_repair_attempts?: number;
227
+ on_tool_approval?: ToolApprovalHandler;
228
+ provider_options?: Record<string, unknown>;
229
+ };
230
+ type GenerateResult<t = string> = {
231
+ content: t;
232
+ tool_calls: ToolCallRecord[];
233
+ steps: StepRecord[];
234
+ usage: UsageTotals;
235
+ cost?: CostBreakdown;
236
+ finish_reason: FinishReason;
237
+ model_resolved: {
238
+ provider: string;
239
+ model_id: string;
240
+ };
241
+ provider_reported?: Record<string, unknown>;
242
+ };
243
+ type ProviderInit = {
244
+ api_key?: string;
245
+ base_url?: string;
246
+ [k: string]: unknown;
247
+ };
248
+ type ProviderConfigMap = {
249
+ anthropic?: {
250
+ api_key: string;
251
+ base_url?: string;
252
+ };
253
+ openai?: {
254
+ api_key: string;
255
+ base_url?: string;
256
+ organization?: string;
257
+ };
258
+ google?: {
259
+ api_key: string;
260
+ base_url?: string;
261
+ };
262
+ ollama?: {
263
+ base_url: string;
264
+ };
265
+ lmstudio?: {
266
+ base_url: string;
267
+ };
268
+ openrouter?: {
269
+ api_key: string;
270
+ base_url?: string;
271
+ http_referer?: string;
272
+ x_title?: string;
273
+ };
274
+ bedrock?: {
275
+ region: string;
276
+ api_key?: string;
277
+ access_key_id?: string;
278
+ secret_access_key?: string;
279
+ session_token?: string;
280
+ base_url?: string;
281
+ };
282
+ claude_cli?: ClaudeCliProviderConfig;
283
+ [custom: string]: ProviderInit | undefined;
284
+ };
285
+ /**
286
+ * Call-level defaults applied by the engine before dispatching to a provider.
287
+ *
288
+ * Per-call options from `generate(opts)` win over defaults using these rules:
289
+ *
290
+ * | Field | Rule |
291
+ * | --------------------------------------------------------------------- | ----------------------------------------- |
292
+ * | `model` | per-call wins; else default; else `sonnet` |
293
+ * | `provider` | per-call wins; else default; else sole configured provider; else `anthropic` |
294
+ * | `system`, `effort`, `max_steps`, `tool_error_policy`, `schema_repair_attempts` | per-call wins (nullish coalesce) |
295
+ * | `retry_policy` | per-call replaces wholesale |
296
+ * | `provider_options` | two-level: per-provider-key shallow merge |
297
+ * | `prompt`, `tools`, `schema`, `abort`, `trajectory`, `on_chunk` | not defaultable; always call-supplied |
298
+ */
299
+ type EngineDefaults = {
300
+ readonly model?: string;
301
+ readonly provider?: string;
302
+ readonly system?: string;
303
+ readonly effort?: EffortLevel;
304
+ readonly max_steps?: number;
305
+ readonly retry_policy?: RetryPolicy;
306
+ readonly tool_error_policy?: 'feed_back' | 'throw';
307
+ readonly schema_repair_attempts?: number;
308
+ readonly provider_options?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
309
+ };
310
+ type EngineConfig = {
311
+ providers: ProviderConfigMap;
312
+ pricing?: PricingTable;
313
+ default_retry?: RetryPolicy;
314
+ default_effort?: EffortLevel;
315
+ default_max_steps?: number;
316
+ defaults?: EngineDefaults;
317
+ };
318
+ type Engine = {
319
+ generate: <t = string>(opts: GenerateOptions<t>) => Promise<GenerateResult<t>>;
320
+ register_price: (provider: string, model_id: string, pricing: Pricing) => void;
321
+ resolve_price: (provider: string, model_id: string) => Pricing | undefined;
322
+ list_prices: () => PricingTable;
323
+ dispose: () => Promise<void>;
324
+ };
325
+ //#endregion
326
+ //#region src/engine/create_engine.d.ts
327
+ declare function create_engine(config: EngineConfig): Engine;
328
+ //#endregion
329
+ //#region src/engine/errors.d.ts
330
+ declare class rate_limit_error extends Error {
331
+ readonly kind: "rate_limit_error";
332
+ readonly retry_after_ms: number | undefined;
333
+ readonly attempts: number;
334
+ readonly status: number | undefined;
335
+ constructor(message: string, metadata?: {
336
+ retry_after_ms?: number;
337
+ attempts?: number;
338
+ status?: number;
339
+ });
340
+ }
341
+ declare class provider_error extends Error {
342
+ readonly kind: "provider_error";
343
+ readonly status: number | undefined;
344
+ readonly body: string | undefined;
345
+ readonly cause_kind: 'provider_5xx' | 'network' | 'unknown' | undefined;
346
+ constructor(message: string, metadata?: {
347
+ status?: number;
348
+ body?: string;
349
+ cause_kind?: 'provider_5xx' | 'network' | 'unknown';
350
+ });
351
+ }
352
+ declare class schema_validation_error extends Error {
353
+ readonly kind: "schema_validation_error";
354
+ readonly zod_error: unknown;
355
+ readonly raw_text: string;
356
+ constructor(message: string, zod_error: unknown, raw_text: string);
357
+ }
358
+ declare class tool_error extends Error {
359
+ readonly kind: "tool_error";
360
+ readonly tool_name: string;
361
+ readonly tool_call_id: string;
362
+ readonly cause: unknown;
363
+ constructor(message: string, metadata: {
364
+ tool_name: string;
365
+ tool_call_id: string;
366
+ cause: unknown;
367
+ });
368
+ }
369
+ declare class tool_approval_denied_error extends Error {
370
+ readonly kind: "tool_approval_denied_error";
371
+ readonly tool_name: string;
372
+ readonly step_index: number;
373
+ readonly tool_call_id: string;
374
+ constructor(message: string, metadata: {
375
+ tool_name: string;
376
+ step_index: number;
377
+ tool_call_id: string;
378
+ });
379
+ }
380
+ declare class model_required_error extends Error {
381
+ readonly kind: "model_required_error";
382
+ constructor(message?: string);
383
+ }
384
+ declare class provider_not_configured_error extends Error {
385
+ readonly kind: "provider_not_configured_error";
386
+ readonly provider: string;
387
+ constructor(provider: string);
388
+ }
389
+ declare class engine_config_error extends Error {
390
+ readonly kind: "engine_config_error";
391
+ readonly provider: string | undefined;
392
+ constructor(message: string, provider?: string);
393
+ }
394
+ declare class on_chunk_error extends Error {
395
+ readonly kind: "on_chunk_error";
396
+ readonly cause: unknown;
397
+ constructor(message: string, cause: unknown);
398
+ }
399
+ declare class provider_capability_error extends Error {
400
+ readonly kind: "provider_capability_error";
401
+ readonly provider: string;
402
+ readonly capability: string;
403
+ constructor(provider: string, capability: string, detail?: string);
404
+ }
405
+ declare class engine_disposed_error extends Error {
406
+ readonly kind: "engine_disposed_error";
407
+ constructor(message?: string);
408
+ }
409
+ type ClaudeCliErrorReason = 'binary_not_found' | 'auth_missing' | 'auth_expired' | 'api_key_missing' | 'startup_timeout' | 'stall_timeout' | 'no_result_event' | 'result_error' | 'subprocess_exit' | 'sandbox_unavailable' | 'engine_disposed' | 'parse_error';
410
+ declare class claude_cli_error extends Error {
411
+ readonly kind: "claude_cli_error";
412
+ readonly reason: ClaudeCliErrorReason;
413
+ readonly status: number | undefined;
414
+ readonly stderr_snippet: string | undefined;
415
+ constructor(reason: ClaudeCliErrorReason, message: string, metadata?: {
416
+ status?: number;
417
+ stderr_snippet?: string;
418
+ });
419
+ }
420
+ declare class provider_auth_error extends Error {
421
+ readonly kind: "provider_auth_error";
422
+ readonly provider: string;
423
+ readonly refresh_command: string | undefined;
424
+ constructor(provider: string, message: string, metadata?: {
425
+ refresh_command?: string;
426
+ });
427
+ }
428
+ //#endregion
429
+ export { RetryFailureKind as A, UserContentPart as B, GenerateResult as C, ProviderConfigMap as D, PricingTable as E, ToolApprovalHandler as F, ToolApprovalRequest as I, ToolCallRecord as L, StepRecord as M, StreamChunk as N, ProviderInit as O, Tool as P, ToolExecContext as R, GenerateOptions as S, Pricing as T, EffortLevel as _, on_chunk_error as a, EngineDefaults as b, provider_error as c, schema_validation_error as d, tool_approval_denied_error as f, CostBreakdown as g, AssistantContentPart as h, model_required_error as i, RetryPolicy as j, ResolvedModel as k, provider_not_configured_error as l, create_engine as m, engine_config_error as n, provider_auth_error as o, tool_error as p, engine_disposed_error as r, provider_capability_error as s, claude_cli_error as t, rate_limit_error as u, Engine as v, Message as w, FinishReason as x, EngineConfig as y, UsageTotals as z };
430
+ //# sourceMappingURL=index-Cy7EUeiP.d.ts.map