@wrongstack/core 0.1.1 → 0.1.3
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/defaults/index.d.ts +738 -138
- package/dist/defaults/index.js +2507 -975
- package/dist/defaults/index.js.map +1 -1
- package/dist/index.d.ts +28 -9
- package/dist/index.js +3272 -1058
- package/dist/index.js.map +1 -1
- package/dist/kernel/index.d.ts +5 -3
- package/dist/kernel/index.js +89 -11
- package/dist/kernel/index.js.map +1 -1
- package/dist/provider-DovtyuM8.d.ts +813 -0
- package/dist/{secret-scrubber-Dax_Ou_o.d.ts → secret-scrubber-qU3AwEiI.d.ts} +126 -457
- package/dist/{tool-executor-DjnMELMV.d.ts → session-reader-DR4u3bu9.d.ts} +445 -59
- package/dist/{system-prompt-BG3nks8P.d.ts → system-prompt--mzZnenv.d.ts} +1 -1
- package/dist/types/index.d.ts +4 -3
- package/dist/types/index.js +153 -5
- package/dist/types/index.js.map +1 -1
- package/dist/utils/index.d.ts +42 -1
- package/dist/utils/index.js +122 -3
- package/dist/utils/index.js.map +1 -1
- package/package.json +5 -4
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { c as ContentBlock, a0 as Context, v as Tool, B as ToolResultBlock, F as ToolUseBlock, h as Provider, R as Request, k as Response, T as TextBlock, a5 as RunOptions, W as WrongStackError, J as JSONSchema, U as Usage, n as SessionEvent, o as SessionMetadata, p as SessionStore } from './provider-DovtyuM8.js';
|
|
2
|
+
import { p as PermissionPolicy, S as SecretScrubber, R as Renderer, B as EventBus, W as WireFamily, t as ProviderConfig, A as Container, X as Pipeline, _ as ReadonlyPipeline, b as Config, g as Logger, D as EventName, G as Listener } from './secret-scrubber-qU3AwEiI.js';
|
|
2
3
|
|
|
3
4
|
type AttachmentKind = 'text' | 'image' | 'file';
|
|
4
5
|
interface AttachmentMeta {
|
|
@@ -85,6 +86,13 @@ interface SlashCommand {
|
|
|
85
86
|
/** Short aliases — also prefixed automatically: `pluginName:alias`. */
|
|
86
87
|
aliases?: string[];
|
|
87
88
|
description: string;
|
|
89
|
+
/**
|
|
90
|
+
* Optional detailed help shown by `/help <name>`. Use this for usage,
|
|
91
|
+
* arguments, examples, side-effects — anything that doesn't fit in
|
|
92
|
+
* `description`. Renders verbatim, so format with line breaks.
|
|
93
|
+
* If absent, `/help <name>` falls back to `description`.
|
|
94
|
+
*/
|
|
95
|
+
help?: string;
|
|
88
96
|
/**
|
|
89
97
|
* Execute the command.
|
|
90
98
|
* @param args Everything after the command name (trimmed by dispatch).
|
|
@@ -100,6 +108,12 @@ interface SlashCommand {
|
|
|
100
108
|
declare class ToolRegistry {
|
|
101
109
|
private readonly tools;
|
|
102
110
|
register(tool: Tool, owner?: string): void;
|
|
111
|
+
/**
|
|
112
|
+
* Attempt to register a tool. Returns true if successful, false if a tool
|
|
113
|
+
* with the same name is already registered. Useful in multi-agent or plugin
|
|
114
|
+
* scenarios where duplicate registration may be intentional.
|
|
115
|
+
*/
|
|
116
|
+
tryRegister(tool: Tool, owner?: string): boolean;
|
|
103
117
|
/**
|
|
104
118
|
* Register a tool as a default. If the tool name is already registered,
|
|
105
119
|
* this is a no-op — the existing registration (from core or another
|
|
@@ -122,6 +136,145 @@ declare class ToolRegistry {
|
|
|
122
136
|
clear(): void;
|
|
123
137
|
}
|
|
124
138
|
|
|
139
|
+
/**
|
|
140
|
+
* Observability primitives — metrics, tracing, health. Implementations live in
|
|
141
|
+
* `defaults/observability/`. Consumers depend on these interfaces so a noop
|
|
142
|
+
* sink can be swapped for an OTel/Prometheus adapter without touching call
|
|
143
|
+
* sites.
|
|
144
|
+
*/
|
|
145
|
+
type MetricLabels = Record<string, string>;
|
|
146
|
+
interface MetricsSink {
|
|
147
|
+
/** Monotonically-increasing counter (e.g. total tool calls). */
|
|
148
|
+
counter(name: string, value?: number, labels?: MetricLabels): void;
|
|
149
|
+
/** Latency / size distribution (e.g. tool duration). */
|
|
150
|
+
histogram(name: string, value: number, labels?: MetricLabels): void;
|
|
151
|
+
/** Current value (e.g. active subagents, pending tasks). */
|
|
152
|
+
gauge(name: string, value: number, labels?: MetricLabels): void;
|
|
153
|
+
/** Point-in-time export — for /metrics scrape, debug dumps, tests. */
|
|
154
|
+
snapshot(): MetricsSnapshot;
|
|
155
|
+
/** Reset all metrics. Useful for tests; production code should rarely use. */
|
|
156
|
+
reset(): void;
|
|
157
|
+
}
|
|
158
|
+
interface MetricSeries {
|
|
159
|
+
name: string;
|
|
160
|
+
type: 'counter' | 'histogram' | 'gauge';
|
|
161
|
+
labels: MetricLabels;
|
|
162
|
+
/** Counter/gauge: latest value. Histogram: count, sum, min, max, p50, p95, p99. */
|
|
163
|
+
values: Record<string, number>;
|
|
164
|
+
}
|
|
165
|
+
interface MetricsSnapshot {
|
|
166
|
+
timestamp: number;
|
|
167
|
+
series: MetricSeries[];
|
|
168
|
+
}
|
|
169
|
+
type HealthStatus = 'healthy' | 'degraded' | 'unhealthy';
|
|
170
|
+
interface HealthCheckResult {
|
|
171
|
+
status: HealthStatus;
|
|
172
|
+
detail?: string;
|
|
173
|
+
/** Optional structured data (e.g. latency, version) for dashboards. */
|
|
174
|
+
data?: Record<string, unknown>;
|
|
175
|
+
}
|
|
176
|
+
interface HealthCheck {
|
|
177
|
+
readonly name: string;
|
|
178
|
+
check(): Promise<HealthCheckResult>;
|
|
179
|
+
}
|
|
180
|
+
interface AggregateHealth {
|
|
181
|
+
status: HealthStatus;
|
|
182
|
+
timestamp: number;
|
|
183
|
+
checks: (HealthCheckResult & {
|
|
184
|
+
name: string;
|
|
185
|
+
})[];
|
|
186
|
+
}
|
|
187
|
+
interface HealthRegistry {
|
|
188
|
+
register(check: HealthCheck): void;
|
|
189
|
+
unregister(name: string): void;
|
|
190
|
+
run(): Promise<AggregateHealth>;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* Minimal OTel-compatible Span. The default implementation is a noop; wire an
|
|
194
|
+
* OpenTelemetry adapter in production to get distributed tracing for free.
|
|
195
|
+
*/
|
|
196
|
+
interface Span {
|
|
197
|
+
setAttribute(key: string, value: string | number | boolean): void;
|
|
198
|
+
recordError(err: Error): void;
|
|
199
|
+
end(): void;
|
|
200
|
+
}
|
|
201
|
+
interface Tracer {
|
|
202
|
+
startSpan(name: string, attrs?: Record<string, string | number | boolean>): Span;
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
/**
|
|
206
|
+
* Input for a single tool execution, scoped to a single iteration's budget.
|
|
207
|
+
*/
|
|
208
|
+
interface ToolExecution {
|
|
209
|
+
toolUse: ToolUseBlock;
|
|
210
|
+
result: ToolResultBlock;
|
|
211
|
+
/** True if the tool was not found in the registry. */
|
|
212
|
+
unknownTool?: boolean;
|
|
213
|
+
/** True if the tool execution threw an exception. */
|
|
214
|
+
threw?: boolean;
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* Output from a single tool execution.
|
|
218
|
+
*/
|
|
219
|
+
interface ToolExecutionOutput {
|
|
220
|
+
result: ToolResultBlock | ToolConfirmPendingResult;
|
|
221
|
+
tool?: Tool;
|
|
222
|
+
durationMs: number;
|
|
223
|
+
}
|
|
224
|
+
/**
|
|
225
|
+
* Result of running a batch of tools for a single agent iteration.
|
|
226
|
+
*/
|
|
227
|
+
interface ToolBatchResult {
|
|
228
|
+
outputs: ToolExecutionOutput[];
|
|
229
|
+
remainingBudget: number;
|
|
230
|
+
}
|
|
231
|
+
type ConfirmAwaiter = (tool: Tool, input: unknown, toolUseId: string, suggestedPattern: string) => Promise<'yes' | 'no' | 'always' | 'deny'>;
|
|
232
|
+
interface ToolExecutorOptions {
|
|
233
|
+
permissionPolicy: PermissionPolicy;
|
|
234
|
+
secretScrubber: SecretScrubber;
|
|
235
|
+
renderer?: Renderer | undefined;
|
|
236
|
+
/**
|
|
237
|
+
* Optional event bus. When provided, the executor emits `tool.started`
|
|
238
|
+
* before invoking each tool's `execute()`. Closes the observability gap
|
|
239
|
+
* between "model decided to call tool" and "tool finished".
|
|
240
|
+
*/
|
|
241
|
+
events?: EventBus | undefined;
|
|
242
|
+
/**
|
|
243
|
+
* Optional tracer. When provided, every tool execution opens a
|
|
244
|
+
* `tool.<name>` span with attributes for tool name, permission decision,
|
|
245
|
+
* input size, output size, and outcome. Spans are no-op by default.
|
|
246
|
+
*/
|
|
247
|
+
tracer?: Tracer | undefined;
|
|
248
|
+
/**
|
|
249
|
+
* Async callback invoked when a tool needs user confirmation.
|
|
250
|
+
* When omitted and confirmation is required, the executor returns a
|
|
251
|
+
* failure result immediately (TUI path). When provided (CLI path),
|
|
252
|
+
* the callback handles the interactive prompt and returns a decision.
|
|
253
|
+
*/
|
|
254
|
+
confirmAwaiter?: ConfirmAwaiter | undefined;
|
|
255
|
+
iterationTimeoutMs?: number;
|
|
256
|
+
perIterationOutputCapBytes?: number;
|
|
257
|
+
}
|
|
258
|
+
interface ToolExecutorInit {
|
|
259
|
+
registry: ToolRegistry;
|
|
260
|
+
options: ToolExecutorOptions;
|
|
261
|
+
}
|
|
262
|
+
/**
|
|
263
|
+
* Result returned by executeBatch when a tool needs confirmation and
|
|
264
|
+
* no confirmAwaiter is available. The TUI catches this and surfaces a
|
|
265
|
+
* confirmation dialog; once resolved the tool is re-executed.
|
|
266
|
+
* The string tag identifies it as a "pending confirm" result so callers
|
|
267
|
+
* can distinguish it from an error without inspecting content strings.
|
|
268
|
+
*/
|
|
269
|
+
interface ToolConfirmPendingResult {
|
|
270
|
+
type: 'tool_confirm_pending';
|
|
271
|
+
toolUseId: string;
|
|
272
|
+
toolName: string;
|
|
273
|
+
input: unknown;
|
|
274
|
+
suggestedPattern: string;
|
|
275
|
+
}
|
|
276
|
+
type ToolExecutorStrategy = 'parallel' | 'sequential' | 'smart';
|
|
277
|
+
|
|
125
278
|
/**
|
|
126
279
|
* Factory for constructing a Provider instance. The `family` field
|
|
127
280
|
* declares the wire protocol so callers can route without inspecting
|
|
@@ -144,7 +297,18 @@ interface ProviderFactory$1 {
|
|
|
144
297
|
}
|
|
145
298
|
declare class ProviderRegistry {
|
|
146
299
|
private readonly factories;
|
|
300
|
+
/**
|
|
301
|
+
* Register a provider factory. If a factory with the same type already
|
|
302
|
+
* exists, it is replaced. Use this for both initial registration and
|
|
303
|
+
* runtime overrides (e.g. from plugins or CLI flags).
|
|
304
|
+
*/
|
|
147
305
|
register(f: ProviderFactory$1): void;
|
|
306
|
+
/**
|
|
307
|
+
* Override an existing factory. Throws if no factory is registered
|
|
308
|
+
* for the given type. Use this to safely replace a provider at runtime
|
|
309
|
+
* (e.g. in tests or when a plugin provides a custom implementation).
|
|
310
|
+
*/
|
|
311
|
+
override(type: string, f: ProviderFactory$1): void;
|
|
148
312
|
has(type: string): boolean;
|
|
149
313
|
create(cfg: ProviderConfig): Provider;
|
|
150
314
|
list(): string[];
|
|
@@ -154,7 +318,14 @@ declare class ProviderRegistry {
|
|
|
154
318
|
declare const DEFAULT_MAX_ITERATIONS = 100;
|
|
155
319
|
interface RunResult {
|
|
156
320
|
status: 'done' | 'failed' | 'max_iterations' | 'aborted';
|
|
157
|
-
|
|
321
|
+
/**
|
|
322
|
+
* Set when `status === 'failed'` (always) or `'aborted'` (when the abort
|
|
323
|
+
* carried an error context). Always a `WrongStackError` so callers can
|
|
324
|
+
* branch on `code`, `severity`, and `recoverable` without parsing strings.
|
|
325
|
+
* Raw throws are wrapped into an `AgentError` with code `AGENT_RUN_FAILED`
|
|
326
|
+
* by `Agent.run` before they reach this field.
|
|
327
|
+
*/
|
|
328
|
+
error?: WrongStackError;
|
|
158
329
|
finalText?: string;
|
|
159
330
|
iterations: number;
|
|
160
331
|
}
|
|
@@ -175,6 +346,20 @@ interface AgentInit {
|
|
|
175
346
|
* emit `iteration.limit_reached` and wait for a listener to grant/deny.
|
|
176
347
|
*/
|
|
177
348
|
autoExtendLimit?: boolean;
|
|
349
|
+
/**
|
|
350
|
+
* Optional confirm handler. When set, the executor calls it synchronously
|
|
351
|
+
* when a tool needs user confirmation (CLI path). When omitted, the
|
|
352
|
+
* executor returns a `ToolConfirmPendingResult` and the agent emits
|
|
353
|
+
* `tool.confirm_needed` for the TUI to resolve.
|
|
354
|
+
*/
|
|
355
|
+
confirmAwaiter?: ConfirmAwaiter | undefined;
|
|
356
|
+
/**
|
|
357
|
+
* Optional tracer. When provided, `Agent.run` opens an `agent.run` span,
|
|
358
|
+
* per-iteration `agent.iteration` spans, and `provider.complete` spans
|
|
359
|
+
* inside the retry loop. Tool spans are opened by the ToolExecutor.
|
|
360
|
+
* Default is `NoopTracer` (zero overhead).
|
|
361
|
+
*/
|
|
362
|
+
tracer?: Tracer | undefined;
|
|
178
363
|
}
|
|
179
364
|
interface AgentPipelines {
|
|
180
365
|
request: Pipeline<Request>;
|
|
@@ -213,6 +398,7 @@ declare class Agent {
|
|
|
213
398
|
private readonly plugins;
|
|
214
399
|
private readonly toolExecutor;
|
|
215
400
|
private readonly autoExtendLimit;
|
|
401
|
+
private readonly tracer;
|
|
216
402
|
constructor(init: AgentInit);
|
|
217
403
|
private get logger();
|
|
218
404
|
private get retry();
|
|
@@ -226,20 +412,39 @@ declare class Agent {
|
|
|
226
412
|
run(userInput: AgentInput, opts?: RunOptions): Promise<RunResult>;
|
|
227
413
|
private runInner;
|
|
228
414
|
/**
|
|
229
|
-
*
|
|
230
|
-
|
|
231
|
-
|
|
415
|
+
* Normalize user input and emit through userInput pipeline + session append.
|
|
416
|
+
*/
|
|
417
|
+
private normalizeAndEmitUserInput;
|
|
418
|
+
/**
|
|
419
|
+
* Check if iteration limit has been reached and request extension if needed.
|
|
420
|
+
* Returns the new effective limit (possibly extended) and a RunResult if
|
|
421
|
+
* the loop should exit. Returns `{ limit }` with no result when the
|
|
422
|
+
* iteration may proceed.
|
|
423
|
+
*/
|
|
424
|
+
private checkIterationLimit;
|
|
425
|
+
/**
|
|
426
|
+
* Build request and run through request pipeline.
|
|
427
|
+
*/
|
|
428
|
+
private buildAndRunRequestPipeline;
|
|
429
|
+
/**
|
|
430
|
+
* Process the provider response: run response pipeline, emit events,
|
|
431
|
+
* update session, render text, handle abort.
|
|
232
432
|
*/
|
|
233
|
-
private
|
|
433
|
+
private processResponse;
|
|
234
434
|
/**
|
|
235
|
-
*
|
|
236
|
-
*
|
|
237
|
-
*
|
|
238
|
-
*
|
|
435
|
+
* Execute tools and append tool results to context.
|
|
436
|
+
* When a tool returns `tool_confirm_pending` (no confirmAwaiter set),
|
|
437
|
+
* we pause and emit `tool.confirm_needed`. The run is blocked until
|
|
438
|
+
* the event listener resolves the confirmation, then we re-run the
|
|
439
|
+
* single tool.
|
|
239
440
|
*/
|
|
240
|
-
private streamProviderToResponse;
|
|
241
|
-
private callProviderWithRetry;
|
|
242
441
|
private executeTools;
|
|
442
|
+
private waitForConfirm;
|
|
443
|
+
private executeSingleWithDecision;
|
|
444
|
+
/**
|
|
445
|
+
* Run context window pipeline if compactor is present.
|
|
446
|
+
*/
|
|
447
|
+
private compactContextIfNeeded;
|
|
243
448
|
}
|
|
244
449
|
|
|
245
450
|
interface ToolRegistryView {
|
|
@@ -306,14 +511,68 @@ interface PluginAPI {
|
|
|
306
511
|
*/
|
|
307
512
|
onEvent<K extends EventName>(event: K, handler: Listener<K>): () => void;
|
|
308
513
|
}
|
|
514
|
+
/**
|
|
515
|
+
* Capability declaration — informs the host which subsystems a plugin
|
|
516
|
+
* intends to touch. Used for diagnostics and per-plugin enable/disable UX
|
|
517
|
+
* (e.g. "this plugin registers tools — disable to remove them"). Not
|
|
518
|
+
* enforced at runtime: a plugin that declares `tools: false` can still
|
|
519
|
+
* call `api.tools.register()`, but the host can flag the discrepancy.
|
|
520
|
+
*/
|
|
521
|
+
interface PluginCapabilities {
|
|
522
|
+
/** Will register tools via `api.tools.register()`. */
|
|
523
|
+
tools?: boolean;
|
|
524
|
+
/** Will register provider factories via `api.providers.register()`. */
|
|
525
|
+
providers?: boolean;
|
|
526
|
+
/**
|
|
527
|
+
* Pipelines the plugin hooks into. Use the standard names
|
|
528
|
+
* (`request | response | toolCall | userInput | assistantOutput | contextWindow`)
|
|
529
|
+
* or custom pipeline names exposed by other plugins.
|
|
530
|
+
*/
|
|
531
|
+
pipelines?: string[];
|
|
532
|
+
/** Will register slash commands via `api.slashCommands.register()`. */
|
|
533
|
+
slashCommands?: boolean;
|
|
534
|
+
/** Will start MCP servers via `api.mcp.start()`. */
|
|
535
|
+
mcp?: boolean;
|
|
536
|
+
}
|
|
537
|
+
/**
|
|
538
|
+
* Structured dependency declaration. The string form (`dependsOn: ['foo']`)
|
|
539
|
+
* is shorthand for `[{ name: 'foo' }]` — both work. Use the structured form
|
|
540
|
+
* when you need a version constraint:
|
|
541
|
+
*
|
|
542
|
+
* dependsOn: [{ name: 'wstack-auth', version: '^1.2.0' }]
|
|
543
|
+
*/
|
|
544
|
+
interface PluginDependency {
|
|
545
|
+
name: string;
|
|
546
|
+
/** npm-style semver range. Supports `^`, `~`, exact, and unprefixed. */
|
|
547
|
+
version?: string;
|
|
548
|
+
}
|
|
309
549
|
interface Plugin {
|
|
310
550
|
name: string;
|
|
311
551
|
version?: string;
|
|
552
|
+
/** One-line summary for `wstack plugins list` and error messages. */
|
|
553
|
+
description?: string;
|
|
554
|
+
/** Semver range against the kernel API version (KERNEL_API_VERSION). */
|
|
312
555
|
apiVersion: string;
|
|
313
|
-
/**
|
|
314
|
-
|
|
556
|
+
/**
|
|
557
|
+
* Capability hints — what subsystems the plugin will register against.
|
|
558
|
+
* Optional; provided for diagnostics and UX. The loader does not enforce
|
|
559
|
+
* these, but mismatch is surfaced via logger at warn level.
|
|
560
|
+
*/
|
|
561
|
+
capabilities?: PluginCapabilities;
|
|
562
|
+
/**
|
|
563
|
+
* JSON Schema for the options under `Config.plugins[<name>].options`.
|
|
564
|
+
* When present, the loader validates that section before calling `setup`
|
|
565
|
+
* and rejects the plugin with a clear error path on failure.
|
|
566
|
+
*/
|
|
567
|
+
configSchema?: JSONSchema;
|
|
568
|
+
/**
|
|
569
|
+
* Mandatory plugin dependencies — loading fails if any are absent or
|
|
570
|
+
* version-incompatible. Accepts both the legacy string-array form and
|
|
571
|
+
* the structured form with version constraints.
|
|
572
|
+
*/
|
|
573
|
+
dependsOn?: (string | PluginDependency)[];
|
|
315
574
|
/** Optional plugin dependencies — silently skipped if absent. */
|
|
316
|
-
optionalDeps?: string[];
|
|
575
|
+
optionalDeps?: (string | PluginDependency)[];
|
|
317
576
|
conflictsWith?: string[];
|
|
318
577
|
setup(api: PluginAPI): void | Promise<void>;
|
|
319
578
|
teardown?(api: PluginAPI): void | Promise<void>;
|
|
@@ -376,13 +635,75 @@ interface BridgeTransport {
|
|
|
376
635
|
close(agentId: string): Promise<void>;
|
|
377
636
|
}
|
|
378
637
|
|
|
638
|
+
type BudgetKind = 'tool_calls' | 'iterations' | 'tokens' | 'timeout' | 'cost';
|
|
639
|
+
declare class BudgetExceededError extends Error {
|
|
640
|
+
readonly kind: BudgetKind;
|
|
641
|
+
readonly limit: number;
|
|
642
|
+
readonly observed: number;
|
|
643
|
+
constructor(kind: BudgetKind, limit: number, observed: number);
|
|
644
|
+
}
|
|
645
|
+
interface BudgetLimits {
|
|
646
|
+
maxIterations?: number;
|
|
647
|
+
maxToolCalls?: number;
|
|
648
|
+
maxTokens?: number;
|
|
649
|
+
/** Estimated USD cost ceiling. */
|
|
650
|
+
maxCostUsd?: number;
|
|
651
|
+
/** Wall-clock timeout from start() to checkTimeout(). */
|
|
652
|
+
timeoutMs?: number;
|
|
653
|
+
}
|
|
654
|
+
interface BudgetUsage {
|
|
655
|
+
iterations: number;
|
|
656
|
+
toolCalls: number;
|
|
657
|
+
tokens: {
|
|
658
|
+
input: number;
|
|
659
|
+
output: number;
|
|
660
|
+
total: number;
|
|
661
|
+
};
|
|
662
|
+
costUsd: number;
|
|
663
|
+
elapsedMs: number;
|
|
664
|
+
}
|
|
665
|
+
/**
|
|
666
|
+
* Per-subagent budget enforcement. Each subagent gets its own instance so a
|
|
667
|
+
* runaway agent can't drain the cost ceiling of its siblings. All record/check
|
|
668
|
+
* methods are O(1) and safe to call from hot paths.
|
|
669
|
+
*
|
|
670
|
+
* Behavior: `record*` methods throw `BudgetExceededError` synchronously the
|
|
671
|
+
* moment a limit is crossed. The caller (runner/coordinator) catches this and
|
|
672
|
+
* marks the task as 'failed' with the budget kind, so the operator can see
|
|
673
|
+
* exactly which ceiling tripped.
|
|
674
|
+
*/
|
|
675
|
+
declare class SubagentBudget {
|
|
676
|
+
readonly limits: Readonly<BudgetLimits>;
|
|
677
|
+
private iterations;
|
|
678
|
+
private toolCalls;
|
|
679
|
+
private tokenInput;
|
|
680
|
+
private tokenOutput;
|
|
681
|
+
private costUsd;
|
|
682
|
+
private startTime;
|
|
683
|
+
constructor(limits?: BudgetLimits);
|
|
684
|
+
start(): void;
|
|
685
|
+
recordIteration(): void;
|
|
686
|
+
recordToolCall(): void;
|
|
687
|
+
recordUsage(usage: Usage, costUsd?: number): void;
|
|
688
|
+
/**
|
|
689
|
+
* Throws if the wall-clock budget is exhausted. Call this from the iteration
|
|
690
|
+
* loop so a hung tool can't keep a subagent running past its deadline.
|
|
691
|
+
*/
|
|
692
|
+
checkTimeout(): void;
|
|
693
|
+
/** Returns true if a timeout has occurred without throwing. Useful for races. */
|
|
694
|
+
isTimedOut(): boolean;
|
|
695
|
+
usage(): BudgetUsage;
|
|
696
|
+
}
|
|
697
|
+
|
|
379
698
|
interface SubagentConfig {
|
|
380
|
-
id
|
|
699
|
+
id?: string;
|
|
381
700
|
name: string;
|
|
382
|
-
role
|
|
701
|
+
role?: string;
|
|
383
702
|
prompt?: string;
|
|
384
703
|
maxIterations?: number;
|
|
385
704
|
maxToolCalls?: number;
|
|
705
|
+
maxTokens?: number;
|
|
706
|
+
maxCostUsd?: number;
|
|
386
707
|
timeoutMs?: number;
|
|
387
708
|
tools?: string[];
|
|
388
709
|
model?: string;
|
|
@@ -421,6 +742,18 @@ interface MultiAgentConfig {
|
|
|
421
742
|
maxConcurrent?: number;
|
|
422
743
|
doneCondition: DoneCondition;
|
|
423
744
|
timeoutMs?: number;
|
|
745
|
+
/**
|
|
746
|
+
* Optional default budget applied to every spawned subagent. Per-subagent
|
|
747
|
+
* fields in `SubagentConfig` override these. Coordinator enforces them by
|
|
748
|
+
* constructing a `SubagentBudget` per spawn — see `SubagentRunContext.budget`.
|
|
749
|
+
*/
|
|
750
|
+
defaultBudget?: {
|
|
751
|
+
maxIterations?: number;
|
|
752
|
+
maxToolCalls?: number;
|
|
753
|
+
maxTokens?: number;
|
|
754
|
+
maxCostUsd?: number;
|
|
755
|
+
timeoutMs?: number;
|
|
756
|
+
};
|
|
424
757
|
}
|
|
425
758
|
interface SpawnResult {
|
|
426
759
|
subagentId: string;
|
|
@@ -461,6 +794,28 @@ interface MultiAgentCoordinator {
|
|
|
461
794
|
stopAll(): Promise<void>;
|
|
462
795
|
getStatus(): CoordinatorStatus;
|
|
463
796
|
}
|
|
797
|
+
/**
|
|
798
|
+
* Caller-supplied runner that actually executes a task. The coordinator
|
|
799
|
+
* provides isolated state (own budget, own AbortSignal, own bridge handle)
|
|
800
|
+
* and enforces concurrency limits — the runner just runs the task and reports
|
|
801
|
+
* the outcome. This is the injection seam that decouples the coordinator
|
|
802
|
+
* from `Agent` so it can be tested with mocks and reused for non-Agent
|
|
803
|
+
* subagents (workers, MCP-driven subagents, etc.).
|
|
804
|
+
*/
|
|
805
|
+
type SubagentRunner = (task: TaskSpec, ctx: SubagentRunContext) => Promise<SubagentRunOutcome>;
|
|
806
|
+
interface SubagentRunContext {
|
|
807
|
+
subagentId: string;
|
|
808
|
+
config: SubagentConfig;
|
|
809
|
+
budget: SubagentBudget;
|
|
810
|
+
signal: AbortSignal;
|
|
811
|
+
/** Null until `setSubagentBridge` is called for this subagent. */
|
|
812
|
+
bridge: AgentBridge | null;
|
|
813
|
+
}
|
|
814
|
+
interface SubagentRunOutcome {
|
|
815
|
+
result?: unknown;
|
|
816
|
+
iterations: number;
|
|
817
|
+
toolCalls: number;
|
|
818
|
+
}
|
|
464
819
|
interface CoordinatorStatus {
|
|
465
820
|
coordinatorId: string;
|
|
466
821
|
subagents: {
|
|
@@ -642,48 +997,79 @@ declare function findCriticalPath(graph: TaskGraph): CriticalPathResult;
|
|
|
642
997
|
declare function topologicalSort(graph: TaskGraph): string[];
|
|
643
998
|
|
|
644
999
|
/**
|
|
645
|
-
*
|
|
646
|
-
|
|
647
|
-
interface
|
|
648
|
-
|
|
649
|
-
result: ToolResultBlock;
|
|
650
|
-
/** True if the tool was not found in the registry. */
|
|
651
|
-
unknownTool?: boolean;
|
|
652
|
-
/** True if the tool execution threw an exception. */
|
|
653
|
-
threw?: boolean;
|
|
654
|
-
}
|
|
655
|
-
/**
|
|
656
|
-
* Output from a single tool execution.
|
|
657
|
-
*/
|
|
658
|
-
interface ToolExecutionOutput {
|
|
659
|
-
result: ToolResultBlock;
|
|
660
|
-
tool?: Tool;
|
|
661
|
-
durationMs: number;
|
|
662
|
-
}
|
|
663
|
-
/**
|
|
664
|
-
* Result of running a batch of tools for a single agent iteration.
|
|
1000
|
+
* L2-A: SessionReader — query, replay, search, export over a `SessionStore`.
|
|
1001
|
+
*
|
|
1002
|
+
* Keeps a clean read-only interface (no `append`, no `delete`) so analytics
|
|
1003
|
+
* code can be wired against a store without granting it the writer surface.
|
|
665
1004
|
*/
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
/**
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
}
|
|
683
|
-
interface
|
|
684
|
-
|
|
685
|
-
|
|
1005
|
+
type SessionEventType = SessionEvent['type'];
|
|
1006
|
+
interface SessionQuery {
|
|
1007
|
+
/** Filter by start timestamp (ISO). Sessions started before this are excluded. */
|
|
1008
|
+
since?: string;
|
|
1009
|
+
/** Filter by start timestamp (ISO). Sessions started after this are excluded. */
|
|
1010
|
+
until?: string;
|
|
1011
|
+
/** Substring match against title (case-insensitive). */
|
|
1012
|
+
titleContains?: string;
|
|
1013
|
+
/** Filter by provider id. */
|
|
1014
|
+
provider?: string;
|
|
1015
|
+
/** Filter by model id. */
|
|
1016
|
+
model?: string;
|
|
1017
|
+
/** Minimum total tokens (input+output) to keep. */
|
|
1018
|
+
minTokens?: number;
|
|
1019
|
+
/** Limit result count. Defaults to no limit. */
|
|
1020
|
+
limit?: number;
|
|
1021
|
+
}
|
|
1022
|
+
interface SessionSearchHit {
|
|
1023
|
+
sessionId: string;
|
|
1024
|
+
eventIndex: number;
|
|
1025
|
+
ts: string;
|
|
1026
|
+
type: SessionEventType;
|
|
1027
|
+
/** Short snippet of the matched text — null for events without text content. */
|
|
1028
|
+
snippet: string | null;
|
|
1029
|
+
}
|
|
1030
|
+
interface SessionSearchQuery {
|
|
1031
|
+
/** Plain text or regex pattern. */
|
|
1032
|
+
query: string;
|
|
1033
|
+
/** Treat `query` as a regex. Defaults to false (literal substring). */
|
|
1034
|
+
regex?: boolean;
|
|
1035
|
+
/** Case-insensitive match. Defaults to true. */
|
|
1036
|
+
caseInsensitive?: boolean;
|
|
1037
|
+
/** Limit only to these event types. Defaults to all event types. */
|
|
1038
|
+
types?: SessionEventType[];
|
|
1039
|
+
/** Limit hit count. Defaults to 100. */
|
|
1040
|
+
limit?: number;
|
|
1041
|
+
}
|
|
1042
|
+
interface SessionExportOptions {
|
|
1043
|
+
/** "markdown" produces a human-readable chat log; "json" passes through raw events. */
|
|
1044
|
+
format: 'markdown' | 'json' | 'text';
|
|
1045
|
+
/** Include tool_use/tool_result blocks. Defaults to true. */
|
|
1046
|
+
includeTools?: boolean;
|
|
1047
|
+
/** Include system/diagnostic events (errors, compaction). Defaults to true. */
|
|
1048
|
+
includeDiagnostics?: boolean;
|
|
1049
|
+
}
|
|
1050
|
+
interface SessionSummaryLite {
|
|
1051
|
+
id: string;
|
|
1052
|
+
title: string;
|
|
1053
|
+
startedAt: string;
|
|
1054
|
+
endedAt?: string;
|
|
1055
|
+
provider: string;
|
|
1056
|
+
model: string;
|
|
1057
|
+
tokenTotal: number;
|
|
1058
|
+
}
|
|
1059
|
+
interface SessionReader {
|
|
1060
|
+
/** List sessions matching the query. Uses the underlying store's summary cache. */
|
|
1061
|
+
query(q?: SessionQuery): Promise<SessionSummaryLite[]>;
|
|
1062
|
+
/** Yield events for `sessionId` in chronological order. */
|
|
1063
|
+
replay(sessionId: string): AsyncIterable<SessionEvent>;
|
|
1064
|
+
/** Full-text/regex search across one or all sessions. */
|
|
1065
|
+
search(q: SessionSearchQuery, sessionId?: string): Promise<SessionSearchHit[]>;
|
|
1066
|
+
/** Render a session for human or downstream-tool consumption. */
|
|
1067
|
+
export(sessionId: string, opts: SessionExportOptions): Promise<string>;
|
|
1068
|
+
/** Read the metadata header without loading the full event stream. */
|
|
1069
|
+
metadata(sessionId: string): Promise<SessionMetadata>;
|
|
1070
|
+
}
|
|
1071
|
+
interface DefaultSessionReaderOptions {
|
|
1072
|
+
store: SessionStore;
|
|
686
1073
|
}
|
|
687
|
-
type ToolExecutorStrategy = 'parallel' | 'sequential' | 'smart';
|
|
688
1074
|
|
|
689
|
-
export { type
|
|
1075
|
+
export { type Span as $, type AddAttachmentInput as A, type BridgeMessage as B, type ConfirmAwaiter as C, DEFAULT_MODES as D, ENCRYPTED_PREFIX as E, type ModeStore as F, type MultiAgentConfig as G, type HealthCheck as H, type MultiAgentCoordinator as I, type PluginAPI as J, type PluginCapabilities as K, type PluginDependency as L, type MCPRegistryView as M, type PluginPipelines as N, type ProviderFactory as O, type Plugin as P, type ProviderRegistryView as Q, type SessionEventType as R, type SecretVault as S, type SessionExportOptions as T, type SessionQuery as U, type SessionReader as V, type SessionSearchHit as W, type SessionSearchQuery as X, type SessionSummaryLite as Y, type SlashCommand as Z, type SlashCommandRegistryView as _, type AgentBridge as a, type SpawnResult as a0, type SpecAnalysis as a1, type SpecApiEndpoint as a2, type SpecRequirement as a3, type SpecSection as a4, type SpecSectionType as a5, type SpecStatus as a6, type SpecTemplate as a7, type SpecValidationResult as a8, type Specification as a9, type ToolRegistryView as aA, type Tracer as aB, computeTaskProgress as aC, findCriticalPath as aD, topologicalSort as aE, ToolRegistry as aF, ProviderRegistry as aG, Agent as aH, type AgentInit as aI, type AgentInput as aJ, type AgentPipelines as aK, BudgetExceededError as aL, type BudgetKind as aM, type BudgetLimits as aN, type BudgetUsage as aO, DEFAULT_MAX_ITERATIONS as aP, type ProviderFactory$1 as aQ, type RunResult as aR, SubagentBudget as aS, type UserInputPayload as aT, createDefaultPipelines as aU, type SubagentConfig as aa, type SubagentContext as ab, type SubagentRunContext as ac, type SubagentRunOutcome as ad, type SubagentRunner as ae, type TaskAssignment as af, type TaskDelegation as ag, type TaskDependency as ah, type TaskEdge as ai, type TaskFilter as aj, type TaskGraph as ak, type TaskNode as al, type TaskPriority as am, type TaskProgress as an, type TaskResult as ao, type TaskSort as ap, type TaskSpec as aq, type TaskStatus as ar, type TaskType as as, type ToolBatchResult as at, type ToolConfirmPendingResult as au, type ToolExecution as av, type ToolExecutionOutput as aw, type ToolExecutorInit as ax, type ToolExecutorOptions as ay, type ToolExecutorStrategy as az, type AgentBridgeConfig as b, type AggregateHealth as c, type Attachment as d, type AttachmentKind as e, type AttachmentMeta as f, type AttachmentRef as g, type AttachmentStore as h, type BridgeMessageType as i, type BridgeTransport as j, type CoordinatorEvents as k, type CoordinatorStatus as l, type CriticalPathResult as m, DEFAULT_SPEC_TEMPLATE as n, type DefaultSessionReaderOptions as o, type DoneCondition as p, type HealthCheckResult as q, type HealthRegistry as r, type HealthStatus as s, type MetricLabels as t, type MetricSeries as u, type MetricsSink as v, type MetricsSnapshot as w, type Mode as x, type ModeConfig as y, type ModeManifest as z };
|
package/dist/types/index.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
-
export { C as CacheStats, a as Capabilities, b as
|
|
2
|
-
export {
|
|
3
|
-
export { B as
|
|
1
|
+
export { A as AgentError, C as CacheStats, a as Capabilities, b as ConfigError, c as ContentBlock, E as ErrorCode, d as ErrorSeverity, e as ErrorSubsystem, I as ImageBlock, J as JSONSchema, M as Message, f as MessageRole, P as Permission, g as PluginError, h as Provider, i as ProviderError, j as ProviderErrorBody, R as Request, k as Response, l as ResumedSession, S as SessionData, m as SessionError, n as SessionEvent, o as SessionMetadata, p as SessionStore, q as SessionSummary, r as SessionWriter, s as StopReason, t as StreamEvent, T as TextBlock, u as TokenCounter, v as Tool, w as ToolCallContext, x as ToolError, y as ToolFinalEvent, z as ToolProgressEvent, B as ToolResultBlock, D as ToolStreamEvent, F as ToolUseBlock, U as Usage, W as WrongStackError, G as asBlocks, H as asText, K as isAgentError, L as isConfigError, N as isImageBlock, O as isPluginError, Q as isSessionError, V as isTextBlock, X as isToolError, Y as isToolResultBlock, Z as isToolUseBlock, _ as isWrongStackError, $ as toWrongStackError } from '../provider-DovtyuM8.js';
|
|
2
|
+
export { C as CompactReport, a as Compactor, b as Config, c as ConfigLoader, d as ConfigStore, e as ContextConfig, E as ErrorHandler, F as FeaturesConfig, I as InputReader, L as LogConfig, f as LogLevel, g as Logger, M as MCPServerConfig, h as MemoryEntry, i as MemoryScope, j as MemoryStore, k as ModelsDevModel, l as ModelsDevPayload, m as ModelsDevProvider, n as ModelsRegistry, P as PathResolver, o as PermissionDecision, p as PermissionPolicy, q as PluginConfig, r as PromptOption, s as ProviderApiKey, t as ProviderConfig, R as Renderer, u as ResolvedModel, v as ResolvedProvider, w as RetryPolicy, S as SecretScrubber, x as SkillLoader, y as SkillManifest, T as ToolsConfig, z as TrustPolicy, W as WireFamily } from '../secret-scrubber-qU3AwEiI.js';
|
|
3
|
+
export { A as AddAttachmentInput, a as AgentBridge, b as AgentBridgeConfig, c as AggregateHealth, d as Attachment, e as AttachmentKind, f as AttachmentMeta, g as AttachmentRef, h as AttachmentStore, B as BridgeMessage, i as BridgeMessageType, j as BridgeTransport, C as ConfirmAwaiter, k as CoordinatorEvents, l as CoordinatorStatus, m as CriticalPathResult, D as DEFAULT_MODES, n as DEFAULT_SPEC_TEMPLATE, o as DefaultSessionReaderOptions, p as DoneCondition, E as ENCRYPTED_PREFIX, H as HealthCheck, q as HealthCheckResult, r as HealthRegistry, s as HealthStatus, M as MCPRegistryView, t as MetricLabels, u as MetricSeries, v as MetricsSink, w as MetricsSnapshot, x as Mode, y as ModeConfig, z as ModeManifest, F as ModeStore, G as MultiAgentConfig, I as MultiAgentCoordinator, P as Plugin, J as PluginAPI, K as PluginCapabilities, L as PluginDependency, N as PluginPipelines, O as ProviderFactory, Q as ProviderRegistryView, S as SecretVault, R as SessionEventType, T as SessionExportOptions, U as SessionQuery, V as SessionReader, W as SessionSearchHit, X as SessionSearchQuery, Y as SessionSummaryLite, Z as SlashCommand, _ as SlashCommandRegistryView, $ as Span, a0 as SpawnResult, a1 as SpecAnalysis, a2 as SpecApiEndpoint, a3 as SpecRequirement, a4 as SpecSection, a5 as SpecSectionType, a6 as SpecStatus, a7 as SpecTemplate, a8 as SpecValidationResult, a9 as Specification, aa as SubagentConfig, ab as SubagentContext, ac as SubagentRunContext, ad as SubagentRunOutcome, ae as SubagentRunner, af as TaskAssignment, ag as TaskDelegation, ah as TaskDependency, ai as TaskEdge, aj as TaskFilter, ak as TaskGraph, al as TaskNode, am as TaskPriority, an as TaskProgress, ao as TaskResult, ap as TaskSort, aq as TaskSpec, ar as TaskStatus, as as TaskType, at as ToolBatchResult, au as ToolConfirmPendingResult, av as ToolExecution, aw as ToolExecutionOutput, ax as ToolExecutorInit, ay as ToolExecutorOptions, az as ToolExecutorStrategy, aA as ToolRegistryView, aB as Tracer, aC as computeTaskProgress, aD as findCriticalPath, aE as topologicalSort } from '../session-reader-DR4u3bu9.js';
|
|
4
|
+
export { B as BuildContext, S as SystemPromptBuilder } from '../system-prompt--mzZnenv.js';
|