@tangle-network/agent-runtime 0.16.0 → 0.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +0 -17
- package/dist/agent.d.ts +1 -1
- package/dist/index.d.ts +30 -346
- package/dist/index.js +7 -521
- package/dist/index.js.map +1 -1
- package/dist/{types-DmhXdAhu.d.ts → types-ByIhNRFk.d.ts} +1 -21
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -23,7 +23,6 @@ pnpm add @tangle-network/agent-runtime @tangle-network/agent-eval
|
|
|
23
23
|
| `startRuntimeRun` | Canonical production-run row + cost ledger |
|
|
24
24
|
| `defineAgent` | Declarative per-vertical agent manifest — surfaces, knowledge, rubric, run fn |
|
|
25
25
|
| `resolveChatModel` / `validateChatModelId` / `getModels` | Router catalog fetch + fail-closed admission + precedence resolver |
|
|
26
|
-
| `createTraceBridge` | Map `RuntimeStreamEvent` → `agent-eval` `TraceEvent` |
|
|
27
26
|
| `decideKnowledgeReadiness` | `ready` / `blocked` / `caveat` branch for routes / UI |
|
|
28
27
|
| `createOpenAICompatibleBackend` | OpenAI-compatible streaming backend (TCloud / cli-bridge) |
|
|
29
28
|
| `createSandboxPromptBackend` | Sandbox / sidecar `streamPrompt` clients |
|
|
@@ -174,22 +173,6 @@ await run.persist({ runtimeEvents: telemetry.events })
|
|
|
174
173
|
|
|
175
174
|
Full runnable: [`examples/runtime-run/`](./examples/runtime-run/).
|
|
176
175
|
|
|
177
|
-
## agent-eval trace bridge
|
|
178
|
-
|
|
179
|
-
If you persist traces in agent-eval's `TraceStore`, the bridge maps
|
|
180
|
-
runtime stream events to `TraceEvent` so consumer repos don't hand-roll
|
|
181
|
-
the adapter.
|
|
182
|
-
|
|
183
|
-
```ts
|
|
184
|
-
import { createTraceBridge } from '@tangle-network/agent-runtime'
|
|
185
|
-
|
|
186
|
-
const bridge = createTraceBridge({ runId, spanId })
|
|
187
|
-
for await (const event of runAgentTaskStream({ task, backend, input })) {
|
|
188
|
-
const trace = bridge.toTraceEvent(event)
|
|
189
|
-
if (trace) await traceStore.appendEvent(trace)
|
|
190
|
-
}
|
|
191
|
-
```
|
|
192
|
-
|
|
193
176
|
## Error taxonomy
|
|
194
177
|
|
|
195
178
|
| Error | When |
|
package/dist/agent.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import * as _tangle_network_agent_eval from '@tangle-network/agent-eval';
|
|
2
2
|
import { FindingSubject, TraceAnalystKindSpec, AnalystFinding, TraceStore, RunCompleteHook, FeedbackLabel, FeedbackTrajectoryStore } from '@tangle-network/agent-eval';
|
|
3
|
-
import { R as RuntimeStreamEvent } from './types-
|
|
3
|
+
import { R as RuntimeStreamEvent } from './types-ByIhNRFk.js';
|
|
4
4
|
import { I as ImprovementAdapter, K as KnowledgeAdapter, a as RunAnalystLoopResult } from './types-D_MXrmJP.js';
|
|
5
5
|
|
|
6
6
|
/**
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,7 @@
|
|
|
1
|
-
import { AgentEvalError, KnowledgeReadinessReport, ControlEvalResult, KnowledgeRequirement
|
|
2
|
-
export { AgentEvalError, AgentEvalErrorCode,
|
|
3
|
-
import { A as AgentBackendInput, a as AgentExecutionBackend, b as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, c as RunAgentTaskOptions, d as AgentTaskRunResult, e as RunAgentTaskStreamOptions, f as
|
|
4
|
-
export {
|
|
5
|
-
import { AgentProfilePrompt, AgentProfileResources, AgentSubagentProfile, AgentProfile, SandboxInstance } from '@tangle-network/sandbox';
|
|
1
|
+
import { AgentEvalError, KnowledgeReadinessReport, ControlEvalResult, KnowledgeRequirement } from '@tangle-network/agent-eval';
|
|
2
|
+
export { AgentEvalError, AgentEvalErrorCode, ConfigError, ControlBudget, ControlDecision, ControlEvalResult, ControlRunResult, ControlStep, DataAcquisitionPlan, JudgeError, KnowledgeReadinessReport, KnowledgeRequirement, NotFoundError, RunRecord, ValidationError } from '@tangle-network/agent-eval';
|
|
3
|
+
import { A as AgentBackendInput, a as AgentExecutionBackend, b as AgentBackendContext, R as RuntimeStreamEvent, K as KnowledgeReadinessDecision, c as RunAgentTaskOptions, d as AgentTaskRunResult, e as RunAgentTaskStreamOptions, f as AgentTaskSpec, g as AgentRuntimeEvent, h as AgentTaskStatus, i as RuntimeSessionStore, j as RuntimeSession } from './types-ByIhNRFk.js';
|
|
4
|
+
export { k as AgentAdapter, l as AgentKnowledgeProvider, m as AgentRuntimeEventSink, n as AgentTaskContext } from './types-ByIhNRFk.js';
|
|
6
5
|
|
|
7
6
|
/**
|
|
8
7
|
* @stable
|
|
@@ -77,130 +76,6 @@ declare function createOpenAICompatibleBackend<TInput extends AgentBackendInput
|
|
|
77
76
|
retry?: BackendRetryPolicy;
|
|
78
77
|
}): AgentExecutionBackend<TInput>;
|
|
79
78
|
|
|
80
|
-
/**
|
|
81
|
-
* Send an AgentProfile to a sandbox runtime for one chat turn. Composes
|
|
82
|
-
* the per-turn overlay (user message, prior history, knowledge flags)
|
|
83
|
-
* via `mergeAgentProfiles`, POSTs the full profile to the runtime's
|
|
84
|
-
* `/runtime/agents/run/stream` endpoint, and yields `RuntimeStreamEvent`s
|
|
85
|
-
* from the SSE response. The full profile — subagents, MCP servers,
|
|
86
|
-
* permissions, file mounts — reaches the sandbox by construction.
|
|
87
|
-
*/
|
|
88
|
-
|
|
89
|
-
/** A message in the chat turn's prior context. Provider-neutral. */
|
|
90
|
-
interface ChatTurnMessage {
|
|
91
|
-
role: 'user' | 'assistant' | 'system';
|
|
92
|
-
content: string;
|
|
93
|
-
/** Optional metadata the consumer wants threaded through (timestamps, msg id, etc). */
|
|
94
|
-
metadata?: Record<string, unknown>;
|
|
95
|
-
}
|
|
96
|
-
/**
|
|
97
|
-
* Per-turn profile overlay. The caller's profile is the durable contract;
|
|
98
|
-
* the overlay carries volatile per-turn context (workspace facts, dynamic-
|
|
99
|
-
* advisor instructions, RAG hits) that the runtime should see but that
|
|
100
|
-
* doesn't belong in the canonical profile. Composed via `mergeAgentProfiles`.
|
|
101
|
-
*/
|
|
102
|
-
interface ChatTurnOverlay {
|
|
103
|
-
/** Volatile prompt additions: dynamic-advisor context, intake gate output, RAG citations. */
|
|
104
|
-
promptOverlay?: AgentProfilePrompt;
|
|
105
|
-
/** Per-turn additional file mounts (vault docs, recent uploads). */
|
|
106
|
-
resourcesOverlay?: AgentProfileResources;
|
|
107
|
-
/** Override or augment the subagent map for this turn (rare). */
|
|
108
|
-
subagentsOverlay?: Record<string, AgentSubagentProfile>;
|
|
109
|
-
/** Free-form metadata threaded into the runtime call. */
|
|
110
|
-
metadata?: Record<string, unknown>;
|
|
111
|
-
}
|
|
112
|
-
/**
|
|
113
|
-
* Sandbox runtime contract — the subset of `SandboxInstance` `runChatTurn`
|
|
114
|
-
* actually invokes. Defined as an interface so consumers can inject a
|
|
115
|
-
* stub in tests without standing up a real sandbox.
|
|
116
|
-
*/
|
|
117
|
-
interface ChatTurnSandbox {
|
|
118
|
-
/** Sandbox identifier used in the runtime URL. */
|
|
119
|
-
readonly id: string;
|
|
120
|
-
/** Base URL of the sandbox runtime, e.g. `https://sandbox.tangle.tools/v1/sandboxes/<id>`. */
|
|
121
|
-
readonly runtimeUrl: string;
|
|
122
|
-
/** Optional bearer for the runtime call (sidecar auth). */
|
|
123
|
-
readonly authHeader?: {
|
|
124
|
-
name: string;
|
|
125
|
-
value: string;
|
|
126
|
-
};
|
|
127
|
-
}
|
|
128
|
-
interface RunChatTurnOptions {
|
|
129
|
-
/** Canonical agent profile — the durable contract. */
|
|
130
|
-
profile: AgentProfile;
|
|
131
|
-
/** Volatile per-turn additions. */
|
|
132
|
-
overlay?: ChatTurnOverlay;
|
|
133
|
-
/** Current user message. */
|
|
134
|
-
message: string;
|
|
135
|
-
/** Prior conversation. */
|
|
136
|
-
priorMessages: readonly ChatTurnMessage[];
|
|
137
|
-
/** Sandbox the turn should run inside. */
|
|
138
|
-
sandbox: ChatTurnSandbox;
|
|
139
|
-
/** Override model for this turn (otherwise profile.model.default is used). */
|
|
140
|
-
modelOverride?: string;
|
|
141
|
-
/** AbortSignal for cancellation (timeouts, client disconnect, etc). */
|
|
142
|
-
signal?: AbortSignal;
|
|
143
|
-
/** Override fetch (for tests). */
|
|
144
|
-
fetch?: typeof fetch;
|
|
145
|
-
}
|
|
146
|
-
/**
|
|
147
|
-
* Compose the per-turn profile via `mergeAgentProfiles(profile, overlay)`,
|
|
148
|
-
* POST the FULL composed profile to the sandbox's runtime streaming endpoint,
|
|
149
|
-
* and yield parsed `RuntimeStreamEvent`s. The runtime resolves prompt,
|
|
150
|
-
* subagents, MCP servers, and permissions from the profile — callers do not
|
|
151
|
-
* hand-craft a `backend.profile` shape.
|
|
152
|
-
*
|
|
153
|
-
* for await (const event of runChatTurn({ profile, overlay, message, priorMessages, sandbox })) {
|
|
154
|
-
* // event.type === 'message' / 'tool_call' / 'task_complete' / etc.
|
|
155
|
-
* }
|
|
156
|
-
*/
|
|
157
|
-
declare function runChatTurn(options: RunChatTurnOptions): AsyncIterable<RuntimeStreamEvent>;
|
|
158
|
-
/**
|
|
159
|
-
* Compose the per-turn AgentProfile. Public-and-pure so consumers can
|
|
160
|
-
* preview/log/persist the composed shape without firing a runtime call.
|
|
161
|
-
*/
|
|
162
|
-
declare function composeTurnProfile(base: AgentProfile, overlay: ChatTurnOverlay): AgentProfile;
|
|
163
|
-
declare class ChatTurnError extends Error {
|
|
164
|
-
readonly status?: number | undefined;
|
|
165
|
-
constructor(message: string, status?: number | undefined);
|
|
166
|
-
}
|
|
167
|
-
/**
|
|
168
|
-
* Convenience: build a `ChatTurnSandbox` from a full `SandboxInstance`. Most
|
|
169
|
-
* callers already have one of these from `client.create()`. The runtime URL
|
|
170
|
-
* is derived from the instance's transport configuration.
|
|
171
|
-
*/
|
|
172
|
-
declare function sandboxAsChatTurnTarget(instance: SandboxInstance, opts?: {
|
|
173
|
-
authHeader?: {
|
|
174
|
-
name: string;
|
|
175
|
-
value: string;
|
|
176
|
-
};
|
|
177
|
-
}): ChatTurnSandbox;
|
|
178
|
-
|
|
179
|
-
/**
|
|
180
|
-
* Derive a stable executionId from the run identity. The same
|
|
181
|
-
* `(projectId, sessionId, turnIndex)` tuple yields the same id — so a
|
|
182
|
-
* client retry of the same turn lands on the same substrate execution
|
|
183
|
-
* and the orchestrator's buffer replays instead of starting a second
|
|
184
|
-
* prompt.
|
|
185
|
-
*
|
|
186
|
-
* Format is readable, not hashed: operators grepping orchestrator logs
|
|
187
|
-
* for `gtm-agent:thread-abc:3` find the run without translating an
|
|
188
|
-
* opaque id. Substrate executionIds are not a secrecy boundary.
|
|
189
|
-
*
|
|
190
|
-
* Wire integration:
|
|
191
|
-
* - `@tangle-network/sandbox@0.1.x` PromptOptions does not yet expose
|
|
192
|
-
* `executionId`. The SDK auto-reconnects in-call by extracting it
|
|
193
|
-
* from the response `execution.started` event; products do nothing.
|
|
194
|
-
* - For cross-process reconnect today, bypass the SDK and POST to the
|
|
195
|
-
* orchestrator's `/agents/run/stream` directly with this id in the
|
|
196
|
-
* `X-Execution-ID` header (see tax-agent's `sessions.ts`).
|
|
197
|
-
*/
|
|
198
|
-
declare function deriveExecutionId(input: {
|
|
199
|
-
projectId: string;
|
|
200
|
-
sessionId: string;
|
|
201
|
-
turnIndex: number;
|
|
202
|
-
}): string;
|
|
203
|
-
|
|
204
79
|
/**
|
|
205
80
|
* `handleChatTurn` — framework-neutral chat-turn HTTP orchestrator.
|
|
206
81
|
* Owns the NDJSON `ChatStreamEvent` line protocol, the `session.run.*`
|
|
@@ -300,6 +175,31 @@ interface ChatTurnResult {
|
|
|
300
175
|
*/
|
|
301
176
|
declare function handleChatTurn(input: RunChatTurnInput): ChatTurnResult;
|
|
302
177
|
|
|
178
|
+
/**
|
|
179
|
+
* Derive a stable executionId from the run identity. The same
|
|
180
|
+
* `(projectId, sessionId, turnIndex)` tuple yields the same id — so a
|
|
181
|
+
* client retry of the same turn lands on the same substrate execution
|
|
182
|
+
* and the orchestrator's buffer replays instead of starting a second
|
|
183
|
+
* prompt.
|
|
184
|
+
*
|
|
185
|
+
* Format is readable, not hashed: operators grepping orchestrator logs
|
|
186
|
+
* for `gtm-agent:thread-abc:3` find the run without translating an
|
|
187
|
+
* opaque id. Substrate executionIds are not a secrecy boundary.
|
|
188
|
+
*
|
|
189
|
+
* Wire integration:
|
|
190
|
+
* - `@tangle-network/sandbox@0.1.x` PromptOptions does not yet expose
|
|
191
|
+
* `executionId`. The SDK auto-reconnects in-call by extracting it
|
|
192
|
+
* from the response `execution.started` event; products do nothing.
|
|
193
|
+
* - For cross-process reconnect today, bypass the SDK and POST to the
|
|
194
|
+
* orchestrator's `/agents/run/stream` directly with this id in the
|
|
195
|
+
* `X-Execution-ID` header (see tax-agent's `sessions.ts`).
|
|
196
|
+
*/
|
|
197
|
+
declare function deriveExecutionId(input: {
|
|
198
|
+
projectId: string;
|
|
199
|
+
sessionId: string;
|
|
200
|
+
turnIndex: number;
|
|
201
|
+
}): string;
|
|
202
|
+
|
|
303
203
|
/**
|
|
304
204
|
* @stable
|
|
305
205
|
*
|
|
@@ -322,37 +222,6 @@ declare function handleChatTurn(input: RunChatTurnInput): ChatTurnResult;
|
|
|
322
222
|
* importing the runtime.
|
|
323
223
|
*/
|
|
324
224
|
|
|
325
|
-
/**
|
|
326
|
-
* @stable
|
|
327
|
-
*
|
|
328
|
-
* Caller asked to resume a session against a backend whose `kind` does not
|
|
329
|
-
* match the session's recorded backend. This is a routing bug — the same
|
|
330
|
-
* session id was reused across two different backend implementations — and
|
|
331
|
-
* is not retryable without picking the right backend.
|
|
332
|
-
*/
|
|
333
|
-
declare class SessionMismatchError extends AgentEvalError {
|
|
334
|
-
readonly sessionBackend: string;
|
|
335
|
-
readonly requestedBackend: string;
|
|
336
|
-
constructor(sessionBackend: string, requestedBackend: string, options?: {
|
|
337
|
-
cause?: unknown;
|
|
338
|
-
});
|
|
339
|
-
}
|
|
340
|
-
/**
|
|
341
|
-
* @stable
|
|
342
|
-
*
|
|
343
|
-
* A backend transport call (HTTP, gRPC, sidecar IPC) failed with a non-success
|
|
344
|
-
* status. Distinct from `JudgeError` (which is structural / unrecoverable)
|
|
345
|
-
* because backend failures are sometimes retryable and consumers may want to
|
|
346
|
-
* branch on the upstream status code.
|
|
347
|
-
*/
|
|
348
|
-
declare class BackendTransportError extends AgentEvalError {
|
|
349
|
-
readonly backend: string;
|
|
350
|
-
readonly status?: number;
|
|
351
|
-
constructor(backend: string, message: string, options?: {
|
|
352
|
-
cause?: unknown;
|
|
353
|
-
status?: number;
|
|
354
|
-
});
|
|
355
|
-
}
|
|
356
225
|
/**
|
|
357
226
|
* @stable
|
|
358
227
|
*
|
|
@@ -365,59 +234,6 @@ declare class RuntimeRunStateError extends AgentEvalError {
|
|
|
365
234
|
});
|
|
366
235
|
}
|
|
367
236
|
|
|
368
|
-
/**
|
|
369
|
-
* Classify a user message against a profile's subagent map. Routes are
|
|
370
|
-
* declared on each `AgentSubagentProfile.metadata.matchers` (keywords +
|
|
371
|
-
* regex patterns); `classifyIntent` scores every subagent against the
|
|
372
|
-
* message and returns a typed result. Pure scoring — no LLM call. Caller
|
|
373
|
-
* decides whether the score is high enough to dispatch the subagent.
|
|
374
|
-
*/
|
|
375
|
-
|
|
376
|
-
/** Matcher shape attached to `subagent.metadata.matchers`. */
|
|
377
|
-
interface SubagentMatcher {
|
|
378
|
-
/** Literal keywords (case-insensitive substring match). +1 per match unless `weight` overrides. */
|
|
379
|
-
keywords?: readonly string[];
|
|
380
|
-
/** Regex patterns (case-insensitive). +`weight` per match (default 1.5). */
|
|
381
|
-
patterns?: readonly (string | RegExp)[];
|
|
382
|
-
/** Per-rule weight override. */
|
|
383
|
-
weight?: number;
|
|
384
|
-
/** Minimum score for this subagent to be considered "matched". Default 1. */
|
|
385
|
-
minScore?: number;
|
|
386
|
-
}
|
|
387
|
-
interface ClassifyIntentResult {
|
|
388
|
-
/** Best-scoring subagent id; null if no subagent crossed `minScore`. */
|
|
389
|
-
id: string | null;
|
|
390
|
-
/** Best subagent's `AgentSubagentProfile`; null if no match. */
|
|
391
|
-
subagent: AgentSubagentProfile | null;
|
|
392
|
-
/** Score of the chosen subagent. */
|
|
393
|
-
score: number;
|
|
394
|
-
/** All subagent scores keyed by id — useful for telemetry / debugging. */
|
|
395
|
-
scores: Record<string, number>;
|
|
396
|
-
/** The matchers checked, for debugging "why didn't X route?" */
|
|
397
|
-
evaluated: Record<string, {
|
|
398
|
-
keywordHits: number;
|
|
399
|
-
patternHits: number;
|
|
400
|
-
minScore: number;
|
|
401
|
-
}>;
|
|
402
|
-
}
|
|
403
|
-
interface ClassifyIntentOptions {
|
|
404
|
-
/** Override the global default `minScore` (used when a subagent omits its own). */
|
|
405
|
-
defaultMinScore?: number;
|
|
406
|
-
/** Subagent ids to skip (e.g. scaffold-only subagents with `metadata.status === 'scaffold'`). */
|
|
407
|
-
skip?: readonly string[];
|
|
408
|
-
/** Only consider subagents whose metadata predicate returns true (e.g. `m => m.status === 'full'`). */
|
|
409
|
-
filter?: (subagent: AgentSubagentProfile, id: string) => boolean;
|
|
410
|
-
}
|
|
411
|
-
/**
|
|
412
|
-
* Pure intent classifier.
|
|
413
|
-
*
|
|
414
|
-
* For each subagent in `profile.subagents`: read `metadata.matchers`,
|
|
415
|
-
* score keyword + pattern hits against the user message, return the
|
|
416
|
-
* highest-scoring subagent (or null if none crossed `minScore`). No LLM
|
|
417
|
-
* call, no side effects. The runtime decides what to do with the result.
|
|
418
|
-
*/
|
|
419
|
-
declare function classifyIntent(profile: AgentProfile, message: string, opts?: ClassifyIntentOptions): ClassifyIntentResult;
|
|
420
|
-
|
|
421
237
|
/**
|
|
422
238
|
* @stable
|
|
423
239
|
*
|
|
@@ -463,12 +279,6 @@ declare function resolveRouterBaseUrl(env?: RouterEnv): string;
|
|
|
463
279
|
* response — callers decide whether to fail open (empty catalog) or closed.
|
|
464
280
|
*/
|
|
465
281
|
declare function getModels(routerBaseUrl?: string): Promise<ModelInfo[]>;
|
|
466
|
-
/**
|
|
467
|
-
* Prepend synthetic catalog entries for ids the environment pins but the
|
|
468
|
-
* router may not list (e.g. a private or self-hosted chat model). Ids already
|
|
469
|
-
* present in `models` are not duplicated.
|
|
470
|
-
*/
|
|
471
|
-
declare function withConfiguredModels(models: ModelInfo[], extraIds: string[]): ModelInfo[];
|
|
472
282
|
/** Trim a candidate model id; `undefined` for non-strings and blanks. */
|
|
473
283
|
declare function cleanModelId(value: unknown): string | undefined;
|
|
474
284
|
interface ChatModelCandidate {
|
|
@@ -511,71 +321,6 @@ declare function validateChatModelId(modelId: unknown, options?: {
|
|
|
511
321
|
loadModels?: (routerBaseUrl: string) => Promise<ModelInfo[]>;
|
|
512
322
|
}): Promise<ChatModelValidation>;
|
|
513
323
|
|
|
514
|
-
/**
|
|
515
|
-
* Validate an AgentProfile against canonical conformance rules: tool keys
|
|
516
|
-
* must map to an MCP server entry (not be shell capabilities masquerading
|
|
517
|
-
* as tools), subagents marked `metadata.status: 'scaffold'` must not be
|
|
518
|
-
* dispatchable, system prompts must be substantive. Pure — no I/O — so
|
|
519
|
-
* callers run it in a unit test or at module load to fail-fast on
|
|
520
|
-
* misconfiguration.
|
|
521
|
-
*/
|
|
522
|
-
|
|
523
|
-
interface ConformanceIssue {
|
|
524
|
-
severity: 'error' | 'warn';
|
|
525
|
-
/** Stable kebab-case code, useful for CI matching. */
|
|
526
|
-
code: string;
|
|
527
|
-
/** Profile path the issue is anchored to, e.g. `tools.bash` or `subagents.foo`. */
|
|
528
|
-
path: string;
|
|
529
|
-
/** Human-readable failure reason. */
|
|
530
|
-
message: string;
|
|
531
|
-
}
|
|
532
|
-
interface ConformanceResult {
|
|
533
|
-
valid: boolean;
|
|
534
|
-
errors: ConformanceIssue[];
|
|
535
|
-
warnings: ConformanceIssue[];
|
|
536
|
-
}
|
|
537
|
-
interface ConformanceOptions {
|
|
538
|
-
/**
|
|
539
|
-
* Shell-style capabilities that may appear in `permissions` but NEVER in
|
|
540
|
-
* `tools`. Declaring these as tools is decorative — the runtime doesn't
|
|
541
|
-
* dispatch them as MCP servers. Default covers the observed offenders.
|
|
542
|
-
*/
|
|
543
|
-
knownShellCapabilities?: readonly string[];
|
|
544
|
-
/**
|
|
545
|
-
* If true, treat `subagents[id].metadata.status === 'scaffold'` as an
|
|
546
|
-
* error rather than a warning. Default false — scaffolds are honest
|
|
547
|
-
* stubs as long as the router skips them.
|
|
548
|
-
*/
|
|
549
|
-
strictNoScaffolds?: boolean;
|
|
550
|
-
/**
|
|
551
|
-
* Names that may appear in `tools` without a corresponding MCP server or
|
|
552
|
-
* resource mount. Default empty — kills decorative-tool anti-pattern.
|
|
553
|
-
*/
|
|
554
|
-
toolsAllowedWithoutMcp?: readonly string[];
|
|
555
|
-
/**
|
|
556
|
-
* Minimum length of `prompt.systemPrompt`. Profiles below this are
|
|
557
|
-
* likely incomplete. Default 800 chars (rough lower bound for the
|
|
558
|
-
* partner-tier prompts the product agents target).
|
|
559
|
-
*/
|
|
560
|
-
minSystemPromptChars?: number;
|
|
561
|
-
}
|
|
562
|
-
/**
|
|
563
|
-
* Run all conformance checks against a profile. Designed to be called from
|
|
564
|
-
* a unit test:
|
|
565
|
-
*
|
|
566
|
-
* it('legalAgentProfile passes conformance', () => {
|
|
567
|
-
* const result = assertProfileConformance(legalAgentProfile, {
|
|
568
|
-
* toolsAllowedWithoutMcp: ['agent-knowledge:query'], // in-process function
|
|
569
|
-
* })
|
|
570
|
-
* expect(result.valid).toBe(true)
|
|
571
|
-
* expect(result.errors).toEqual([])
|
|
572
|
-
* })
|
|
573
|
-
*
|
|
574
|
-
* Issues carry `path` + `code` so tests can pinpoint failures rather than
|
|
575
|
-
* collapse to a generic "validation failed."
|
|
576
|
-
*/
|
|
577
|
-
declare function assertProfileConformance(profile: AgentProfile, opts?: ConformanceOptions): ConformanceResult;
|
|
578
|
-
|
|
579
324
|
/**
|
|
580
325
|
* @stable
|
|
581
326
|
*
|
|
@@ -611,8 +356,6 @@ declare function decideKnowledgeReadiness(report: KnowledgeReadinessReport, opti
|
|
|
611
356
|
/** @stable */
|
|
612
357
|
declare function runAgentTask<TState, TAction, TActionResult, TEval extends ControlEvalResult = ControlEvalResult>(options: RunAgentTaskOptions<TState, TAction, TActionResult, TEval>): Promise<AgentTaskRunResult<TState, TAction, TActionResult, TEval>>;
|
|
613
358
|
/** @stable */
|
|
614
|
-
declare function summarizeAgentTaskRun<TState, TAction, TActionResult, TEval extends ControlEvalResult>(result: AgentTaskRunResult<TState, TAction, TActionResult, TEval>): AgentTaskRunSummary;
|
|
615
|
-
/** @stable */
|
|
616
359
|
declare function runAgentTaskStream<TInput extends AgentBackendInput = AgentBackendInput>(options: RunAgentTaskStreamOptions<TInput>): AsyncIterable<RuntimeStreamEvent>;
|
|
617
360
|
|
|
618
361
|
/**
|
|
@@ -893,67 +636,8 @@ interface ServerSentEventOptions {
|
|
|
893
636
|
retry?: number;
|
|
894
637
|
}
|
|
895
638
|
/** @stable */
|
|
896
|
-
declare function encodeServerSentEvent(data: unknown, options?: ServerSentEventOptions): string;
|
|
897
|
-
/** @stable */
|
|
898
639
|
declare function readinessServerSentEvent(report: KnowledgeReadinessReport, options?: RuntimeTelemetryOptions & ServerSentEventOptions): string;
|
|
899
640
|
/** @stable */
|
|
900
641
|
declare function runtimeStreamServerSentEvent(event: RuntimeStreamEvent, options?: RuntimeTelemetryOptions & ServerSentEventOptions): string;
|
|
901
642
|
|
|
902
|
-
|
|
903
|
-
* @stable
|
|
904
|
-
*
|
|
905
|
-
* One-way bridge from `RuntimeStreamEvent` to agent-eval's `TraceEvent`.
|
|
906
|
-
*
|
|
907
|
-
* The reverse direction is intentionally unsupported — agent-eval events
|
|
908
|
-
* have no session / task affinity, so round-tripping would erase information.
|
|
909
|
-
*/
|
|
910
|
-
|
|
911
|
-
/** @stable */
|
|
912
|
-
interface TraceBridgeOptions {
|
|
913
|
-
/**
|
|
914
|
-
* Stable `runId` to stamp on every emitted `TraceEvent`. Required because
|
|
915
|
-
* agent-eval's `TraceEvent.runId` is non-optional.
|
|
916
|
-
*/
|
|
917
|
-
runId: string;
|
|
918
|
-
/**
|
|
919
|
-
* Optional `spanId` to attach when an event maps to a known span (for
|
|
920
|
-
* example, an outer runtime-task span the consumer is already emitting).
|
|
921
|
-
*/
|
|
922
|
-
spanId?: string;
|
|
923
|
-
/**
|
|
924
|
-
* Optional id generator; default = monotonic counter scoped to this bridge
|
|
925
|
-
* instance. Override for deterministic tests or to integrate with a wider
|
|
926
|
-
* id-allocator (uuid, ksuid).
|
|
927
|
-
*/
|
|
928
|
-
newEventId?: () => string;
|
|
929
|
-
}
|
|
930
|
-
/** @stable */
|
|
931
|
-
interface TraceBridge {
|
|
932
|
-
/**
|
|
933
|
-
* Map a single `RuntimeStreamEvent` to a `TraceEvent`. Returns `undefined`
|
|
934
|
-
* for events that have no useful trace projection (text deltas, reasoning
|
|
935
|
-
* deltas — these belong inside an `LlmSpan.output`, not as separate trace
|
|
936
|
-
* events).
|
|
937
|
-
*/
|
|
938
|
-
toTraceEvent(event: RuntimeStreamEvent): TraceEvent | undefined;
|
|
939
|
-
/** Convenience: drain an iterable of stream events into trace events. */
|
|
940
|
-
drain(events: Iterable<RuntimeStreamEvent>): TraceEvent[];
|
|
941
|
-
}
|
|
942
|
-
/**
|
|
943
|
-
* @stable
|
|
944
|
-
*
|
|
945
|
-
* Build a stateful bridge. State is intentionally minimal — only the event-id
|
|
946
|
-
* counter — because the runtime stream already carries timestamps and the
|
|
947
|
-
* caller already knows the `runId`.
|
|
948
|
-
*/
|
|
949
|
-
declare function createTraceBridge(options: TraceBridgeOptions): TraceBridge;
|
|
950
|
-
/**
|
|
951
|
-
* @stable
|
|
952
|
-
*
|
|
953
|
-
* One-shot convenience for callers who don't want to hold a bridge instance.
|
|
954
|
-
* Internally allocates a single-use bridge so id-generation stays consistent
|
|
955
|
-
* within the call.
|
|
956
|
-
*/
|
|
957
|
-
declare function toAgentEvalTrace(event: RuntimeStreamEvent, options: TraceBridgeOptions): TraceEvent | undefined;
|
|
958
|
-
|
|
959
|
-
export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskRunSummary, AgentTaskSpec, AgentTaskStatus, type BackendRetryPolicy, BackendTransportError, type ChatModelCandidate, type ChatModelValidation, type ChatStreamEvent, ChatTurnError, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnMessage, type ChatTurnOverlay, type ChatTurnProducer, type ChatTurnResult, type ChatTurnSandbox, type ClassifyIntentOptions, type ClassifyIntentResult, type ConformanceIssue, type ConformanceOptions, type ConformanceResult, DEFAULT_ROUTER_BASE_URL, InMemoryRuntimeSessionStore, KnowledgeReadinessDecision, type ModelInfo, type ResolvedChatModel, type RouterEnv, RunAgentTaskOptions, RunAgentTaskStreamOptions, type RunChatTurnInput, type RunChatTurnOptions, type RuntimeEventCollector, type RuntimeRunCompleteInput, type RuntimeRunCost, type RuntimeRunHandle, type RuntimeRunOptions, type RuntimeRunPersistenceAdapter, type RuntimeRunRow, RuntimeRunStateError, type RuntimeRunStatus, RuntimeSession, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeStreamEventSink, type RuntimeStreamEventSummary, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, type SanitizedKnowledgeRequirement, type ServerSentEventOptions, SessionMismatchError, type SubagentMatcher, type TraceBridge, type TraceBridgeOptions, assertProfileConformance, classifyIntent, cleanModelId, composeTurnProfile, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, createTraceBridge, decideKnowledgeReadiness, deriveExecutionId, encodeServerSentEvent, getModels, handleChatTurn, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runChatTurn, runtimeStreamServerSentEvent, sandboxAsChatTurnTarget, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, startRuntimeRun, summarizeAgentTaskRun, toAgentEvalTrace, validateChatModelId, withConfiguredModels };
|
|
643
|
+
export { AgentBackendContext, AgentBackendInput, AgentExecutionBackend, AgentRuntimeEvent, AgentTaskRunResult, AgentTaskSpec, AgentTaskStatus, type ChatStreamEvent, type ChatTurnHooks, type ChatTurnIdentity, type ChatTurnProducer, type ChatTurnResult, DEFAULT_ROUTER_BASE_URL, InMemoryRuntimeSessionStore, type ModelInfo, type ResolvedChatModel, type RouterEnv, type RunChatTurnInput, type RuntimeEventCollector, type RuntimeRunHandle, type RuntimeRunPersistenceAdapter, type RuntimeRunRow, RuntimeRunStateError, RuntimeSessionStore, RuntimeStreamEvent, type RuntimeStreamEventCollector, type RuntimeTelemetryOptions, type SanitizedKnowledgeReadinessReport, cleanModelId, createIterableBackend, createOpenAICompatibleBackend, createRuntimeEventCollector, createRuntimeStreamEventCollector, createSandboxPromptBackend, decideKnowledgeReadiness, deriveExecutionId, getModels, handleChatTurn, readinessServerSentEvent, resolveChatModel, resolveRouterBaseUrl, runAgentTask, runAgentTaskStream, runtimeStreamServerSentEvent, sanitizeAgentRuntimeEvent, sanitizeKnowledgeReadinessReport, sanitizeRuntimeStreamEvent, startRuntimeRun, validateChatModelId };
|