@theokit/agents 16.0.0 → 16.1.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/CHANGELOG.md +26 -0
- package/README.md +47 -1
- package/dist/{agent-compiler-BMpuJFAI.d.ts → agent-compiler-JSYkHpa7.d.ts} +2 -2
- package/dist/{delegation-scoring-CURe4oSL.d.ts → agent-orchestrator-BFWg2URC.d.ts} +11 -426
- package/dist/agent-runner-BUJKNNuI.d.ts +364 -0
- package/dist/agent-sse-handler-BRp9vHrb.d.ts +348 -0
- package/dist/{bridge-entry-BxJWDpQP.d.ts → bridge-entry-BNWDrPzg.d.ts} +8 -422
- package/dist/bridge.d.ts +8 -5
- package/dist/bridge.js +19 -15
- package/dist/{chunk-4PHZ25JN.js → chunk-3TE4PJZL.js} +62 -1137
- package/dist/chunk-3TE4PJZL.js.map +1 -0
- package/dist/{chunk-FIGLHWR2.js → chunk-4SXVNI5O.js} +7 -7
- package/dist/chunk-A2UVVEB3.js +799 -0
- package/dist/chunk-A2UVVEB3.js.map +1 -0
- package/dist/chunk-Z5SYU6Z6.js +353 -0
- package/dist/chunk-Z5SYU6Z6.js.map +1 -0
- package/dist/delegation-scoring-Cn5eM4lQ.d.ts +79 -0
- package/dist/evals.d.ts +84 -0
- package/dist/evals.js +191 -0
- package/dist/evals.js.map +1 -0
- package/dist/handoff.d.ts +91 -0
- package/dist/handoff.js +268 -0
- package/dist/handoff.js.map +1 -0
- package/dist/index.d.ts +19 -369
- package/dist/index.js +36 -32
- package/dist/index.js.map +1 -1
- package/dist/mcp-health.d.ts +1 -1
- package/dist/sdk-adapter-DQnKx7bA.d.ts +435 -0
- package/dist/testing.d.ts +2 -2
- package/dist/tools.d.ts +5 -3
- package/dist/tools.js +10 -6
- package/dist/tools.js.map +1 -1
- package/dist/{types-DdltPCj2.d.ts → types-D5cHmSLi.d.ts} +1 -1
- package/docs/capability-map.md +31 -1
- package/package.json +12 -2
- package/dist/chunk-4PHZ25JN.js.map +0 -1
- /package/dist/{chunk-FIGLHWR2.js.map → chunk-4SXVNI5O.js.map} +0 -0
|
@@ -0,0 +1,364 @@
|
|
|
1
|
+
import { PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool } from '@theokit/sdk';
|
|
2
|
+
import { RetryOptions } from '@theokit/sdk/retry';
|
|
3
|
+
import { C as CompiledTool, a as CompiledAgentOptions } from './agent-compiler-JSYkHpa7.js';
|
|
4
|
+
import { S as StreamEvent } from './agent-sse-handler-BRp9vHrb.js';
|
|
5
|
+
import { R as RoundStreamFactory, L as LoopStrategy, b as ReflectionStrategy, D as DelegationResult } from './agent-orchestrator-BFWg2URC.js';
|
|
6
|
+
import { B as BudgetOptions, R as ReasoningEffort, M as MainLoopMeta } from './types-D5cHmSLi.js';
|
|
7
|
+
import { CompressibleMessage } from '@theokit/sdk/compaction';
|
|
8
|
+
import { z } from 'zod';
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* TranscriptCompactionStrategy — a named, callable transcript-compaction authoring layer
|
|
12
|
+
* (Strategy pattern, V4-F). Mirrors `ReflectionStrategy`/`LoopStrategy`: interface
|
|
13
|
+
* + zod config schema + a `'token-budget'` default + `resolveCompactionStrategy`.
|
|
14
|
+
*
|
|
15
|
+
* The `'token-budget'` strategy DELEGATES to the SDK's `compactTranscript` (ADR D2 /
|
|
16
|
+
* G2 / sdk-runtime.md — the SDK owns the algorithm; agents owns the named interface;
|
|
17
|
+
* no reimplementation). Per ADR D1 it is CALLABLE by the app (exposed as
|
|
18
|
+
* `AgentRunner.compaction`), NOT auto-invoked by the reflective loop — the SDK owns
|
|
19
|
+
* per-turn context, so the app decides WHEN to compact and supplies the `summarize`
|
|
20
|
+
* callback (its own LLM). EC-6: consumers whose transcript rows carry roles outside
|
|
21
|
+
* the SDK's `CompressibleMessage` union (e.g. `'tool'`) cast at the call site, exactly
|
|
22
|
+
* as the SDK's own type contract requires.
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
/** Token budget mirrored from theocode's proven `DEFAULT_KEEP_TOKENS` (server/lib/compaction.ts). */
|
|
26
|
+
declare const DEFAULT_KEEP_TOKENS = 8000;
|
|
27
|
+
/**
|
|
28
|
+
* App-supplied summarizer: collapse the older window into one turn (the app's LLM).
|
|
29
|
+
* Signature matches the SDK `compactTranscript` contract — receives the older window
|
|
30
|
+
* AND the (optionally overridden) summary template.
|
|
31
|
+
*/
|
|
32
|
+
type Summarize = (older: CompressibleMessage[], template: string) => Promise<CompressibleMessage>;
|
|
33
|
+
/**
|
|
34
|
+
* Per-call options for {@link TranscriptCompactionStrategy.compact} — a faithful
|
|
35
|
+
* pass-through of the SDK `CompactTranscriptOptions` knobs the app controls. Defaults
|
|
36
|
+
* are the SDK's, EXCEPT `failSafe` which defaults `true` here: a thrown `summarize`
|
|
37
|
+
* returns the ORIGINAL transcript + a structured warn instead of losing it — compaction
|
|
38
|
+
* is an optimization, never a cause of data loss (error-handling discipline). The app
|
|
39
|
+
* passes `failSafe: false` to opt into fail-fast propagation.
|
|
40
|
+
*/
|
|
41
|
+
interface CompactionCallOptions {
|
|
42
|
+
/** Override the strategy's configured `keepTokens` for this call. */
|
|
43
|
+
readonly keepTokens?: number;
|
|
44
|
+
/** Summarize the older window; if omitted, the SDK drops it (its documented contract). */
|
|
45
|
+
readonly summarize?: Summarize;
|
|
46
|
+
/** Checkpoint marker (SDK default when omitted). */
|
|
47
|
+
readonly marker?: string;
|
|
48
|
+
/** Summary template passed to `summarize` (SDK default when omitted). */
|
|
49
|
+
readonly summaryTemplate?: string;
|
|
50
|
+
/** When true (DEFAULT here), a thrown `summarize` returns the original transcript + a warn. */
|
|
51
|
+
readonly failSafe?: boolean;
|
|
52
|
+
}
|
|
53
|
+
/** A named, callable compaction strategy. Pure of I/O except the delegated SDK call. */
|
|
54
|
+
interface TranscriptCompactionStrategy {
|
|
55
|
+
/** Strategy identifier (e.g. `'token-budget'`). */
|
|
56
|
+
readonly name: string;
|
|
57
|
+
/** The configured token budget (from `@Compaction` / `.compaction()` / default). */
|
|
58
|
+
readonly keepTokens: number;
|
|
59
|
+
/**
|
|
60
|
+
* Compact `messages` to the (optionally overridden) token budget via the SDK's
|
|
61
|
+
* `compactTranscript`. Returns the compacted transcript; never mutates the input.
|
|
62
|
+
*/
|
|
63
|
+
compact(messages: CompressibleMessage[], options?: CompactionCallOptions): Promise<CompressibleMessage[]>;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* Serializable config for a TranscriptCompactionStrategy (SSoT per type-safety.md / G3).
|
|
67
|
+
* `keepTokens` is REQUIRED for `'token-budget'` (EC-2 / G10 — no silent degradation
|
|
68
|
+
* to the SDK's turn-count `keepRecent` default; the strategy is named for token budget).
|
|
69
|
+
*/
|
|
70
|
+
declare const compactionStrategyConfigSchema: z.ZodObject<{
|
|
71
|
+
name: z.ZodLiteral<"token-budget">;
|
|
72
|
+
keepTokens: z.ZodNumber;
|
|
73
|
+
}, z.core.$strip>;
|
|
74
|
+
type CompactionStrategyConfig = z.infer<typeof compactionStrategyConfigSchema>;
|
|
75
|
+
/**
|
|
76
|
+
* Resolve a `@Compaction` / `.compaction()` declaration to a concrete strategy.
|
|
77
|
+
* Throws (Zod) on an unknown name or a missing/invalid `keepTokens` (EC-2/EC-5 —
|
|
78
|
+
* fail-fast, mirrors `resolveLoopStrategy`). The returned strategy's `compact`
|
|
79
|
+
* delegates to `compactTranscript`, defaulting `keepTokens` to the configured value.
|
|
80
|
+
*/
|
|
81
|
+
declare function resolveCompactionStrategy(name: string, config: {
|
|
82
|
+
keepTokens?: number;
|
|
83
|
+
}): TranscriptCompactionStrategy;
|
|
84
|
+
/**
|
|
85
|
+
* The default `'token-budget'` strategy (what `@Compaction('token-budget')` without
|
|
86
|
+
* an explicit budget resolves to). Carries {@link DEFAULT_KEEP_TOKENS}; the app may
|
|
87
|
+
* override per call via `compact(messages, { keepTokens })`.
|
|
88
|
+
*/
|
|
89
|
+
declare const tokenBudgetCompactionStrategy: TranscriptCompactionStrategy;
|
|
90
|
+
|
|
91
|
+
/**
|
|
92
|
+
* AgentRunner — the imperative twin of `@MainLoop` (plan ADR D4, V4-B).
|
|
93
|
+
*
|
|
94
|
+
* `AgentRunner.fromSpec(spec).reflection().stream().build()` resolves the loop strategy from
|
|
95
|
+
* an already-compiled spec (the capability-authored agent). `delegate()` shares the same runtime.
|
|
96
|
+
* `build()` is the compile boundary (no I/O, no IoC — standalone, mirrors
|
|
97
|
+
* Spring's `ChatClient.builder(...).build()`); `stream()`/`run()` do the I/O via
|
|
98
|
+
* `runReflectiveLoopStream` (the SAME loop `delegate()` drains — DRY, ADR 0031).
|
|
99
|
+
* V4-D-stream: `stream()` yields events live (SSE-first); `run()` drains it to a result.
|
|
100
|
+
*/
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Resolves the credential at the start of the stream, instead of demanding the value ready before the call.
|
|
104
|
+
*
|
|
105
|
+
* M74 — the credential injection point was ALREADY per run; what blocked it was the type. With a
|
|
106
|
+
* `string`, the caller must hold the value beforehand, so the *moment* is per run but the *value* is
|
|
107
|
+
* frozen earlier — and a short-lived OAuth bearer crosses the whole run without being re-fetched. It
|
|
108
|
+
* was the structural cause of a silent turn in production.
|
|
109
|
+
*/
|
|
110
|
+
type CredentialResolver = () => string | Promise<string>;
|
|
111
|
+
/** Options for {@link AgentRunner.run}. */
|
|
112
|
+
interface AgentRunnerRunOptions {
|
|
113
|
+
/**
|
|
114
|
+
* The LLM API key, or a resolver called when the stream starts.
|
|
115
|
+
*
|
|
116
|
+
* `string` remains valid and is the path for anyone holding an API key — it does not expire, and
|
|
117
|
+
* demanding a resolver there would be ceremony with no gain. The resolver exists for credentials
|
|
118
|
+
* that EXPIRE.
|
|
119
|
+
*/
|
|
120
|
+
readonly apiKey: string | CredentialResolver;
|
|
121
|
+
/** Session id override (default: a fresh isolated id). */
|
|
122
|
+
readonly sessionId?: string;
|
|
123
|
+
/**
|
|
124
|
+
* The run's USD ceiling across rounds: a number, or `{ maxCostUsd }`. The first round always
|
|
125
|
+
* runs, because no earlier round exists to project its cost from; when that round alone passes
|
|
126
|
+
* the ceiling, the run then stops with `DelegationBudgetExceededError`. Every later round is
|
|
127
|
+
* projected at the last round's cost, and the run stops before a round the ceiling cannot cover.
|
|
128
|
+
* `window`, and a ceiling (either spelling) that is `NaN` or not a number, are refused at the
|
|
129
|
+
* call with a `DelegationError`; a ceiling of 0 or below throws `DelegationBudgetExceededError`
|
|
130
|
+
* at the call, before any round; `Infinity` is no ceiling.
|
|
131
|
+
*/
|
|
132
|
+
readonly budget?: number | BudgetOptions;
|
|
133
|
+
/** Cancellation — aborts stop the reflective loop from re-entering. */
|
|
134
|
+
readonly signal?: AbortSignal;
|
|
135
|
+
/**
|
|
136
|
+
* V4-J: per-run tool override. When provided, REPLACES the build-time
|
|
137
|
+
* `compiled.tools` for this call only (e.g. a consumer that selects tools by
|
|
138
|
+
* request mode/permission). Absent ⇒ the agent's compiled tools (unchanged).
|
|
139
|
+
*/
|
|
140
|
+
readonly tools?: readonly CompiledTool[];
|
|
141
|
+
/**
|
|
142
|
+
* V4-L.2 (Axis-A SWAP): per-run model override. Merge-over-compiled —
|
|
143
|
+
* `opts.model ?? compiled.model ?? default`. Absent ⇒ the compiled model.
|
|
144
|
+
*/
|
|
145
|
+
readonly model?: string;
|
|
146
|
+
/**
|
|
147
|
+
* M1 (Axis-A SWAP): per-run extended-thinking effort. Merge-over-compiled —
|
|
148
|
+
* `opts.reasoningEffort ?? compiled.reasoningEffort` (resolved in the adapter, single site).
|
|
149
|
+
* Mapped to the SDK `ModelSelection.params` so the provider reasons (surfaced as `thinking`
|
|
150
|
+
* StreamEvents). Absent ⇒ the compiled reasoning effort (or none).
|
|
151
|
+
*/
|
|
152
|
+
readonly reasoningEffort?: ReasoningEffort;
|
|
153
|
+
/**
|
|
154
|
+
* M2 (Axis-A SWAP): per-run opt-in to convert inline `<think>…</think>` text into `thinking`
|
|
155
|
+
* events. Merge-over-compiled (`opts.parseThinkTags ?? compiled.parseThinkTags ?? false`). For
|
|
156
|
+
* models that emit reasoning as inline tags (qwen/deepseek) instead of a native reasoning param.
|
|
157
|
+
*/
|
|
158
|
+
readonly parseThinkTags?: boolean;
|
|
159
|
+
/**
|
|
160
|
+
* theocode#32 (Axis-A SWAP): per-run opt-in to strip a leaked Hermes `<function=…></tool_call>`
|
|
161
|
+
* tool-call dialect out of the text stream. Merge-over-compiled
|
|
162
|
+
* (`opts.stripToolDialect ?? compiled.stripToolDialect ?? false`). For models (qwen/qwen3-coder)
|
|
163
|
+
* that leak tool calls as text instead of native `tool_calls`.
|
|
164
|
+
*/
|
|
165
|
+
readonly stripToolDialect?: boolean;
|
|
166
|
+
/**
|
|
167
|
+
* theokit#58 (Axis-A SWAP): per-run opt-in to RECOVER a leaked Hermes `<function=…></tool_call>`
|
|
168
|
+
* tool-call dialect so the call EXECUTES (enables the SDK route's `extractToolCallsFromContent`).
|
|
169
|
+
* Merge-over-compiled (`opts.recoverLeakedToolCalls ?? compiled.recoverLeakedToolCalls ?? false`).
|
|
170
|
+
* Sibling of {@link stripToolDialect} (display-only); typically enabled together. Has effect only
|
|
171
|
+
* when {@link providers} routes a provider.
|
|
172
|
+
*/
|
|
173
|
+
readonly recoverLeakedToolCalls?: boolean;
|
|
174
|
+
/**
|
|
175
|
+
* V4-L.2 (Axis-A SWAP): per-run working directory, forwarded into
|
|
176
|
+
* `Agent.create({ local: { cwd } })` so the SDK populates `SystemPromptContext.cwd`
|
|
177
|
+
* (read by a `SystemPromptResolver` / `@ProjectContext`). Absent ⇒ no `local.cwd`.
|
|
178
|
+
*/
|
|
179
|
+
readonly cwd?: string;
|
|
180
|
+
/**
|
|
181
|
+
* SDK 4.0 (SE40): per-run root of the native `.jsonl` session transcript, forwarded into
|
|
182
|
+
* `Agent.create({ local: { baseDir } })`. Absent ⇒ the SDK default (`~/.theokit`).
|
|
183
|
+
*/
|
|
184
|
+
readonly baseDir?: string;
|
|
185
|
+
/**
|
|
186
|
+
* V4-L.2 (Axis-A SWAP): per-run loop-ceiling override. When provided, the loop
|
|
187
|
+
* strategy is re-resolved with this ceiling for this call only (zod-validated —
|
|
188
|
+
* `< 1` throws, never a silent unbounded loop). Absent ⇒ the build-time ceiling.
|
|
189
|
+
*/
|
|
190
|
+
readonly maxIterations?: number;
|
|
191
|
+
/**
|
|
192
|
+
* V4-L.3 (Axis-A SWAP): per-run plugins (e.g. permission gate by request mode).
|
|
193
|
+
* Accepts EITHER named-plugin discovery settings (`{ enabled: [...] }`) OR an
|
|
194
|
+
* array of code `Plugin` objects (`[permissionPlugin, cachePlugin]`). Both are
|
|
195
|
+
* forwarded RAW through the duck-typed `Agent.create` bridge to the SDK runtime,
|
|
196
|
+
* which accepts either form (mirrors the @theokit/sdk `AgentOptions.plugins` widen).
|
|
197
|
+
*/
|
|
198
|
+
readonly plugins?: PluginsSettings | readonly Plugin[];
|
|
199
|
+
/** V4-L.3 (Axis-A SWAP): per-run provider routing. */
|
|
200
|
+
readonly providers?: ProviderRoutingSettings;
|
|
201
|
+
/** V4-L.3 (Axis-A SWAP): per-run sub-agent definitions (opts-only; @SubAgents stays deferred). */
|
|
202
|
+
readonly agents?: Record<string, AgentDefinition>;
|
|
203
|
+
/**
|
|
204
|
+
* V4-L.3 (Axis-A SWAP): per-run SDK budget tracker — caps the INNER SDK tool-loop per
|
|
205
|
+
* send. Distinct from {@link AgentRunnerRunOptions.budget} (the OUTER reflective-loop USD ceiling).
|
|
206
|
+
*/
|
|
207
|
+
readonly budgetTracker?: BudgetTracker;
|
|
208
|
+
/**
|
|
209
|
+
* V4-Q: pre-built SDK `CustomTool[]` forwarded RAW to `Agent.create.tools` (appended after the
|
|
210
|
+
* agent's compiled tools), bypassing `defineTool`. For an app whose tools come from imperative
|
|
211
|
+
* SDK factories (no `@Tool` compile path / no recoverable Zod schema). Distinct from `tools`
|
|
212
|
+
* (which REPLACES the compiled `CompiledTool[]`).
|
|
213
|
+
*/
|
|
214
|
+
readonly sdkTools?: readonly CustomTool[];
|
|
215
|
+
/**
|
|
216
|
+
* V4-R: inject the per-round stream factory, driving the reflective loop with a caller-provided
|
|
217
|
+
* stream INSTEAD of the SDK adapter (tests / custom transport). When set, the SDK-create options
|
|
218
|
+
* (`tools`/`sdkTools`/`model`/`cwd`/`plugins`/...) are NOT used for this call — the consumer owns
|
|
219
|
+
* the stream. Absent ⇒ `createSdkAgentStream` (the default runtime).
|
|
220
|
+
*/
|
|
221
|
+
readonly streamFactory?: RoundStreamFactory;
|
|
222
|
+
/**
|
|
223
|
+
* V4-P: per-round transient retry. When set, the START of each reflective round (factory
|
|
224
|
+
* creation + first event, before any event is yielded) is wrapped in the SDK `withRetry` —
|
|
225
|
+
* a 429/5xx/network blip is recovered without re-applying an edit. Absent ⇒ single attempt.
|
|
226
|
+
* Default `isRetryable` is the SDK `isTransientError`.
|
|
227
|
+
*/
|
|
228
|
+
readonly retry?: RetryOptions;
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* A built, runnable agent. Construct via {@link AgentRunner.fromSpec} — the
|
|
232
|
+
* constructor takes already-resolved state and is an internal detail.
|
|
233
|
+
*/
|
|
234
|
+
/** Already-resolved state handed to the {@link AgentRunner} constructor (internal). */
|
|
235
|
+
interface AgentRunnerState {
|
|
236
|
+
readonly compiled: CompiledAgentOptions;
|
|
237
|
+
readonly agentName: string;
|
|
238
|
+
/** The resolved terminal-decision strategy (parity with `delegate()`). */
|
|
239
|
+
readonly loopStrategy: LoopStrategy;
|
|
240
|
+
/**
|
|
241
|
+
* M54 — true when `loopStrategy` came from `.loopStrategy(custom)` rather than a built-in name.
|
|
242
|
+
* A custom must NOT be re-resolved by name (its name is outside the `z.enum`); a per-run
|
|
243
|
+
* `maxIterations` override applies to it as a runner ceiling instead (see `stream`). Optional and
|
|
244
|
+
* defaults to `false`: a state built directly (tests, `delegate()`) is a by-name built-in.
|
|
245
|
+
*/
|
|
246
|
+
readonly loopStrategyIsCustom?: boolean;
|
|
247
|
+
/** The resolved between-round reflection (default or `.reflection(custom)` override). */
|
|
248
|
+
readonly reflectionStrategy: ReflectionStrategy;
|
|
249
|
+
/** Recorded streaming preference (see {@link AgentRunner.streamEnabled}). */
|
|
250
|
+
readonly streamEnabled: boolean;
|
|
251
|
+
/** The resolved compaction strategy, or `undefined` when none is declared (EC-4). */
|
|
252
|
+
readonly compaction?: TranscriptCompactionStrategy;
|
|
253
|
+
}
|
|
254
|
+
declare class AgentRunner {
|
|
255
|
+
private readonly compiled;
|
|
256
|
+
private readonly agentName;
|
|
257
|
+
/** The resolved terminal-decision strategy (parity with `delegate()`). */
|
|
258
|
+
readonly loopStrategy: LoopStrategy;
|
|
259
|
+
/** M54 — whether {@link loopStrategy} is a caller-injected custom (see {@link AgentRunnerState}). */
|
|
260
|
+
private readonly loopStrategyIsCustom;
|
|
261
|
+
/** The resolved between-round reflection (default or `.reflection(custom)` override). */
|
|
262
|
+
readonly reflectionStrategy: ReflectionStrategy;
|
|
263
|
+
/**
|
|
264
|
+
* Recorded streaming preference. The reflective loop currently always streams via
|
|
265
|
+
* the SDK `Run.stream()`; a non-streaming collect mode is future work — the flag is
|
|
266
|
+
* captured + exposed here, not yet branched on (honest per G10: documented, not a
|
|
267
|
+
* silent no-op).
|
|
268
|
+
*/
|
|
269
|
+
readonly streamEnabled: boolean;
|
|
270
|
+
/**
|
|
271
|
+
* V4-F: the resolved compaction strategy (from `@Compaction` or `.compaction()`),
|
|
272
|
+
* or `undefined` when neither is declared — compaction is opt-in (EC-4). CALLABLE
|
|
273
|
+
* by the app (ADR D1: `runner.compaction?.compact(messages, { summarize })`); the
|
|
274
|
+
* reflective loop does NOT auto-invoke it (the SDK owns per-turn context).
|
|
275
|
+
*/
|
|
276
|
+
readonly compaction?: TranscriptCompactionStrategy;
|
|
277
|
+
constructor(state: AgentRunnerState);
|
|
278
|
+
/** Start a fluent builder from an already-compiled spec. */
|
|
279
|
+
static fromSpec(spec: AgentRunnerSpec): AgentRunnerBuilder;
|
|
280
|
+
/**
|
|
281
|
+
* V4-D-stream: stream the agent's events LIVE across the reflective loop, returning
|
|
282
|
+
* the aggregated {@link DelegationResult} as the generator's return value. This is the
|
|
283
|
+
* on-ramp for streaming-first apps (SSE) — `runReflectiveLoopStream` yields every
|
|
284
|
+
* round's events before the loop terminates. `streamEnabled` is honored: when the
|
|
285
|
+
* builder set `.stream(false)`, callers should use {@link run} instead.
|
|
286
|
+
*/
|
|
287
|
+
stream(message: string, opts: AgentRunnerRunOptions): AsyncGenerator<StreamEvent, DelegationResult>;
|
|
288
|
+
/** The core stream path, after input guardrails have run (M9). */
|
|
289
|
+
private streamUnguarded;
|
|
290
|
+
/** Run the agent to a terminal result via the shared reflective loop (collect mode). */
|
|
291
|
+
/**
|
|
292
|
+
* Apply a per-call `maxIterations` override (M54 D4). A custom strategy must NOT be re-resolved by
|
|
293
|
+
* name — its name is outside the `z.enum`, which would throw — and its `shouldContinue` closure
|
|
294
|
+
* must survive; since the runner enforces the ceiling via `round < loop.maxIterations` (T1.1),
|
|
295
|
+
* overriding just that field bounds a custom without touching its logic. A built-in keeps the
|
|
296
|
+
* by-name re-resolution (zod fail-loud on `< 1`) — unchanged, zero-behavior.
|
|
297
|
+
*/
|
|
298
|
+
private resolvePerRunLoop;
|
|
299
|
+
run(message: string, opts: AgentRunnerRunOptions): Promise<DelegationResult>;
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* M53 — what the runner actually needs in order to run: an already-compiled agent plus the two
|
|
303
|
+
* loop knobs. It used to derive all of this from `walkAgentMetadata`, which chained the runner to
|
|
304
|
+
* the decorator surface. `strategy` and `compaction` are the two non-waist channels ADR 0002 keeps
|
|
305
|
+
* (the builder's `.compaction()` already outranked the decorator; this just names the input).
|
|
306
|
+
*/
|
|
307
|
+
/**
|
|
308
|
+
* The already-compiled agent the runner executes. Field-compatible with `SubAgentSpec` on purpose —
|
|
309
|
+
* one spec drives both `AgentRunner.fromSpec` and `delegate`.
|
|
310
|
+
*/
|
|
311
|
+
interface AgentRunnerSpec {
|
|
312
|
+
readonly name: string;
|
|
313
|
+
readonly compiled: CompiledAgentOptions;
|
|
314
|
+
readonly strategy?: MainLoopMeta['strategy'];
|
|
315
|
+
readonly maxIterations?: number;
|
|
316
|
+
readonly compaction?: {
|
|
317
|
+
name: string;
|
|
318
|
+
keepTokens?: number;
|
|
319
|
+
};
|
|
320
|
+
}
|
|
321
|
+
/** Fluent builder — accumulates config; `build()` is the compile boundary. */
|
|
322
|
+
declare class AgentRunnerBuilder {
|
|
323
|
+
private readonly spec;
|
|
324
|
+
private reflectionOverride?;
|
|
325
|
+
private streamEnabled;
|
|
326
|
+
private compactionOverride?;
|
|
327
|
+
private loopStrategyOverride?;
|
|
328
|
+
constructor(spec: AgentRunnerSpec);
|
|
329
|
+
/** Override the default reflection strategy (OCP — plan Drawback #2). No arg ⇒ keep default. */
|
|
330
|
+
reflection(strategy?: ReflectionStrategy): this;
|
|
331
|
+
/**
|
|
332
|
+
* M54 — inject a custom terminal-decision strategy (the fourth OCP axis, alongside
|
|
333
|
+
* `.reflection()`/`.compaction()`/`streamFactory`). WINS over the strategy the spec's name would
|
|
334
|
+
* resolve to, exactly as `.compaction()` outranks the spec. The runner caps ANY strategy at
|
|
335
|
+
* `custom.maxIterations` (T1.1), so a `shouldContinue: () => true` still terminates — never an
|
|
336
|
+
* infinite loop.
|
|
337
|
+
*
|
|
338
|
+
* @example
|
|
339
|
+
* ```ts
|
|
340
|
+
* // Stop as soon as the confidence in the last round crosses 0.9, else run to the ceiling.
|
|
341
|
+
* const stopWhenConfident: LoopStrategy = {
|
|
342
|
+
* name: 'confident',
|
|
343
|
+
* maxIterations: 8,
|
|
344
|
+
* shouldContinue: (o) => !o.responseText.includes('confidence: high'),
|
|
345
|
+
* }
|
|
346
|
+
* AgentRunner.fromSpec(spec).loopStrategy(stopWhenConfident).build()
|
|
347
|
+
* ```
|
|
348
|
+
*/
|
|
349
|
+
loopStrategy(custom: LoopStrategy): this;
|
|
350
|
+
/** Record the streaming preference (see {@link AgentRunner.streamEnabled}). */
|
|
351
|
+
stream(enabled?: boolean): this;
|
|
352
|
+
/**
|
|
353
|
+
* V4-F: declare the compaction strategy (e.g. `.compaction('token-budget', { keepTokens: 8000 })`).
|
|
354
|
+
* Resolved + validated at {@link build} (EC-5 — fail-fast there, not here). This builder
|
|
355
|
+
* call WINS over a `@Compaction` decorator on the same agent (EC-1 — explicit override).
|
|
356
|
+
*/
|
|
357
|
+
compaction(name: string, options?: {
|
|
358
|
+
keepTokens?: number;
|
|
359
|
+
}): this;
|
|
360
|
+
/** Resolve strategies from the spec — the compile→execute boundary (no I/O). */
|
|
361
|
+
build(): AgentRunner;
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
export { type AgentRunnerRunOptions as A, type CompactionCallOptions as C, DEFAULT_KEEP_TOKENS as D, type Summarize as S, type TranscriptCompactionStrategy as T, AgentRunner as a, AgentRunnerBuilder as b, type CompactionStrategyConfig as c, compactionStrategyConfigSchema as d, resolveCompactionStrategy as r, tokenBudgetCompactionStrategy as t };
|