@theokit/agents 16.0.0 → 16.1.1
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 +32 -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-A7RXWJZE.js} +62 -1137
- package/dist/chunk-A7RXWJZE.js.map +1 -0
- package/dist/{chunk-FIGLHWR2.js → chunk-CJMYZKUL.js} +7 -7
- package/dist/chunk-MB23MSOK.js +353 -0
- package/dist/chunk-MB23MSOK.js.map +1 -0
- package/dist/chunk-SAKSZKVK.js +799 -0
- package/dist/chunk-SAKSZKVK.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-CJMYZKUL.js.map} +0 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,37 @@
|
|
|
1
1
|
# @theokit/agents
|
|
2
2
|
|
|
3
|
+
## 16.1.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- cbb431c: A guarded turn's `stream()` now rejects with a guard defect, such as the `MalformedGuardrailResultError` a guard returning `redact` with no `text` raises, instead of ending the stream with an `ERROR` status as if the guard had refused. A guard that blocks (`GuardrailViolationError`) still ends the stream with the `ERROR` status message, and `wait()` behaves as before: it rejects with the same error in both cases. A `checkOutput` that throws its own `GuardrailError` subclass now makes `stream()` reject too; return `{ action: 'block' }` to refuse. (B-457)
|
|
8
|
+
|
|
9
|
+
## 16.1.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- 159d559: New subpath `@theokit/agents/evals`. `runAgentEvals({ agent, apiKey, approvals, cases, scorers })` runs each case against your agent definition, on a fresh agent per case, and returns a verdict per case: `pass` or `fail` against `threshold` (default 0.5), or `error`. Each case result carries the output, the scores, the mean score and the duration, and the result counts each verdict. (B-413)
|
|
14
|
+
|
|
15
|
+
`approvals` is required, as it is on `toAgentFactory`: an eval runs with nobody watching, so you say what a gated tool's approval request gets. A case is `error`, never `fail`, when its run did not finish, a guard blocked the input or the output, the agent could not be built, a scorer threw, or a scorer returned a malformed score, a score outside [0, 1] or a reason that is not a string; `error` carries the reason. A scorer's own `reason` text never makes a case an `error`. Options it cannot run (no cases, a case without a string `input`, no scorers, a threshold outside [0, 1]) throw `EvalConfigError` before any agent is built. Unnamed runs get a fresh name, so two runs never collide. The subpath re-exports `Scorers` and `EvalAlreadyRunningError` from `@theokit/sdk/eval`.
|
|
16
|
+
|
|
17
|
+
The result type of `SdkTurnHandle.wait()` gains two optional fields, `status` and `error`, which the SDK eval runner reads.
|
|
18
|
+
|
|
19
|
+
- 8617aa5: New subpath `@theokit/agents/handoff`. `createHandoffConversation({ agents, initial, conversationId? })` holds a roster of compiled agents and the name of the one that answers. The answering agent gets a `transfer_to_agent` tool that names only the other agents. When it calls the tool, it still answers the current message, and your next `send()` is answered by the receiver, which reads the transferring agent's note before your message. (B-410)
|
|
20
|
+
|
|
21
|
+
Each agent runs on its own session, `<conversationId>:<agentName>`. A transfer counts only when the run returns normally: a run that throws, or whose `signal` was aborted, leaves the responder where it was. `send()` takes the `AgentRunner.run` options except `sessionId`, `tools`, `streamFactory` and `maxIterations`, which the conversation owns, and drops them at run time if they arrive through a wider object. `handoffTo(name, note?)` moves the next turn from your code. A roster below two agents, a duplicate name, an unknown agent, an agent whose `maxIterations` is 1 and an agent that already has a tool named `transfer_to_agent` (`reserved_tool_name`) and an agent name that contains `:` (`invalid_agent_name`, since each session id is `<conversationId>:<agentName>`) throw `HandoffError` with a `code`. So do `send()` and `handoffTo()` while a turn is running (`turn_in_progress`), `send()` while another conversation runs a turn on the same `conversationId`, a per-run `sdkTools` entry named `transfer_to_agent`, and `handoffTo()` with a note for the agent that already answers (`already_responder`), which would otherwise drop the note.
|
|
22
|
+
|
|
23
|
+
The note is written by a model and the message by the user, so `[Handoff from` inside either one, and its lookalikes (fullwidth or accented letters, Cyrillic or Greek letters that look Latin, zero-width characters, another opening bracket, `_` or `-` for the space), is rewritten to `[quoted: Handoff from`. A spelling outside those classes still arrives as written. The responder and a waiting note live in memory. To resume after a restart while the receiver has not answered, create the conversation with `initial` set to the last transfer's `from` and call `handoffTo(handoff.to, handoff.note)`; once the receiver has answered, set `initial` to its `to`.
|
|
24
|
+
|
|
25
|
+
`@theokit/sdk-handoff` stays call-and-return: there the caller keeps the turn.
|
|
26
|
+
|
|
27
|
+
### Patch Changes
|
|
28
|
+
|
|
29
|
+
- 72cff7f: An agent on an Anthropic model now reads its system prompt from the provider cache on later turns. `@theokit/agents` requires `@theokit/sdk` `^5.11.0`, the release that marks the configured prompt with `cache_control` for model ids starting with `anthropic/` or `claude` (also behind `openrouter/` or `vertex/`; Bedrock ids such as `bedrock/us.anthropic.claude-…` are not matched and their requests do not change) and reports the cache counters Anthropic returns. A consumer on @theokit/sdk 5.3 to 5.10 must upgrade to 5.11.0. Measured through OpenRouter on `anthropic/claude-haiku-4.5` with a 12 261-token cached prefix: the second turn reported `cacheReadTokens` 12 261. (B-412)
|
|
30
|
+
|
|
31
|
+
Two things a caller sees change with that SDK. On the chat-completions client (OpenRouter included) `tokensInput` is now the uncached part of the prompt, so the whole prompt is `tokensInput + cacheReadTokens + cacheWriteTokens`. `tokens` and the `done` event's `usage.totalTokens` stay input plus output, so they leave the cached prompt out too. And the first turn of an Anthropic run pays the cache-write premium (1.25 times the input price); a run with one turn never reads it back.
|
|
32
|
+
|
|
33
|
+
- 0e692a2: An agent from `toAgentFactory` can be served over ACP by `@theokit/acp` when it declares guardrails or a step ceiling. Its turn now has `stream()`, which the server reads: it yields one assistant message with the text after the output guards, and shares one guard run with `wait()`. When the run ends with status `error` or a guard blocks, the stream ends with `{ type: 'status', status: 'ERROR', message }`, as the SDK's own stream does, and any other error is rethrown from `stream()`. Both wrappers now forward `pluginManager`, so the server's default `ask` mode can install its permission plugin instead of refusing the prompt with `permission enforcement unavailable on this runtime (no plugin manager)`. A guarded agent served this way sends its text once the turn completes, with no token streaming and no tool activity, because streaming the raw text would pass it before the output guards ran. `SdkTurnHandle.stream` and `SdkAgentHandle.pluginManager` are new optional members.
|
|
34
|
+
|
|
3
35
|
## 16.0.0
|
|
4
36
|
|
|
5
37
|
### Major Changes
|
package/README.md
CHANGED
|
@@ -29,7 +29,7 @@ you mount HTTP surfaces).
|
|
|
29
29
|
|
|
30
30
|
## Subpath map
|
|
31
31
|
|
|
32
|
-
Twenty-
|
|
32
|
+
Twenty-three entry points. Import the one you need — the barrel is not the API.
|
|
33
33
|
|
|
34
34
|
| Subpath | What lives there |
|
|
35
35
|
|---|---|
|
|
@@ -54,6 +54,8 @@ Twenty-one entry points. Import the one you need — the barrel is not the API.
|
|
|
54
54
|
| `./commands` | Command routing and the shutdown/cleanup contract |
|
|
55
55
|
| `./doctor` | Environment diagnostics |
|
|
56
56
|
| `./usage` | Token and cost accounting |
|
|
57
|
+
| `./evals` | `runAgentEvals` — run cases against an agent and read pass, fail or error per case |
|
|
58
|
+
| `./handoff` | `createHandoffConversation`: one agent hands the conversation to another, and the next turn is answered by the receiver |
|
|
57
59
|
|
|
58
60
|
## The shapes worth knowing before you start
|
|
59
61
|
|
|
@@ -75,6 +77,50 @@ never subtractive.
|
|
|
75
77
|
matters more than it looks: without provenance, "why is it calling Anthropic?" has no answer in the
|
|
76
78
|
data, and a user cannot tell an explicit choice from a precedence fallback.
|
|
77
79
|
|
|
80
|
+
## Handing a conversation to another agent
|
|
81
|
+
|
|
82
|
+
`@theokit/agents/handoff` keeps a roster of compiled agents and the name of the one that answers.
|
|
83
|
+
|
|
84
|
+
```ts
|
|
85
|
+
import { createHandoffConversation } from '@theokit/agents/handoff'
|
|
86
|
+
|
|
87
|
+
const conversation = createHandoffConversation({ agents: [triage, billing], initial: 'triage' })
|
|
88
|
+
const first = await conversation.send('I want a refund', { apiKey })
|
|
89
|
+
// triage called transfer_to_agent: first.handoff is { from: 'triage', to: 'billing', note }
|
|
90
|
+
const second = await conversation.send('It was a gift', { apiKey })
|
|
91
|
+
// second.responder is 'billing'
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The answering agent gets a `transfer_to_agent` tool for its run. The transfer takes effect when that
|
|
95
|
+
run returns normally, so a run that throws, or whose `signal` was aborted, leaves the responder where
|
|
96
|
+
it was. Each agent keeps its own session, and the receiver reads the transferring agent's note before
|
|
97
|
+
the next message. `handoffTo(name, note?)` moves the next turn from your code; it replaces any note
|
|
98
|
+
still waiting. Naming the agent that already answers changes nothing, and naming it with a note
|
|
99
|
+
throws `already_responder`, since no transfer would deliver the note.
|
|
100
|
+
|
|
101
|
+
The note opens the receiver's message as `[Handoff from <agent>] <note>`. A model wrote the note
|
|
102
|
+
and the user wrote the message, so neither is trusted: `[Handoff from` inside either one is rewritten
|
|
103
|
+
to `[quoted: Handoff from`, and so are its lookalikes (fullwidth or accented letters, Cyrillic or
|
|
104
|
+
Greek letters that look Latin, zero-width characters, another opening bracket, `_` or `-` for the
|
|
105
|
+
space). This narrows the forgery but does not close it: a spelling outside those classes still
|
|
106
|
+
arrives as written, so a receiver with tools that matter should not act on a note alone.
|
|
107
|
+
|
|
108
|
+
The responder and a waiting note are kept in the conversation object's memory. One `conversationId`
|
|
109
|
+
belongs to one conversation at a time: a second conversation on the same id cannot run a turn while
|
|
110
|
+
the first one is running (`turn_in_progress`). Each agent's session id is
|
|
111
|
+
`<conversationId>:<agentName>`, so an agent name that contains `:` is refused with
|
|
112
|
+
`invalid_agent_name`; a `conversationId` may contain one.
|
|
113
|
+
|
|
114
|
+
To resume after a restart, store the last `turn.handoff`. If the receiver has not answered yet,
|
|
115
|
+
create the conversation with `initial` set to its `from` and call
|
|
116
|
+
`handoffTo(handoff.to, handoff.note)`: the receiver's next message opens with
|
|
117
|
+
`[Handoff from <from>] <note>`, as it would have before the restart. Once the receiver has answered,
|
|
118
|
+
create the conversation with `initial` set to its `to`. A roster agent, or a per-run `sdkTools`
|
|
119
|
+
entry, that brings its own `transfer_to_agent` tool is refused with `reserved_tool_name`.
|
|
120
|
+
|
|
121
|
+
`@theokit/sdk-handoff` and `createDelegateTool` work differently. They are call-and-return: the
|
|
122
|
+
agent you call answers the caller, and the caller keeps the turn.
|
|
123
|
+
|
|
78
124
|
## What changed recently
|
|
79
125
|
|
|
80
126
|
See [`CHANGELOG.md`](./CHANGELOG.md) — shipped inside this package, so `node_modules` answers the
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { InlineSkill, CustomTool, MemorySettings, TelemetrySettings, SystemPromptResolver, SessionStore, PermissionGate, SkillsSettings, ContextSettings } from '@theokit/sdk';
|
|
2
2
|
import { AgentDefinition as AgentDefinition$1 } from '@theokit/sdk/subagents-loader';
|
|
3
3
|
import { TheokitAgentError } from '@theokit/sdk/errors';
|
|
4
|
-
import { R as ReasoningEffort, H as HumanInTheLoopOptions,
|
|
4
|
+
import { R as ReasoningEffort, H as HumanInTheLoopOptions, a as McpServersMap, b as MemoryOptions, P as ProjectContextOptions, C as CheckpointOptions, T as ToolOptions, A as ApprovalOptions, B as BudgetOptions } from './types-D5cHmSLi.js';
|
|
5
5
|
import { z } from 'zod';
|
|
6
6
|
import { S as SettingSourcesSelection, G as GatedSettingSource, a as GatedCompatSource } from './setting-sources-gate-BJJiKq33.js';
|
|
7
7
|
import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
|
|
@@ -695,4 +695,4 @@ interface CompiledAgentOptions {
|
|
|
695
695
|
skillsResolver?: SkillsSelection;
|
|
696
696
|
}
|
|
697
697
|
|
|
698
|
-
export { type AgentDefinition as A, type
|
|
698
|
+
export { type AgentDefinition as A, type CompiledTool as C, type DefineAgentConfig as D, type Guardrail as G, type HookApprovalGate as H, type InferAgentInput as I, MalformedGuardrailResultError as M, type SkillsRequestContext as S, type ToolWalkResult as T, UnreadableTextPayloadError as U, type CompiledAgentOptions as a, AGENT_BRAND as b, CompatImportUnsupportedError as c, CostBudgetExceededError as d, type GuardrailAction as e, GuardrailError as f, type GuardrailPhase as g, type GuardrailResult as h, GuardrailViolationError as i, type HookApprovalRequest as j, HookGateUnsupportedError as k, type InferAgentToolNames as l, type SkillsSelection as m, type ToolboxWalkResult as n, compileAgentDefinition as o, compileTools as p, isAgentDefinition as q, resolveEnabledSkills as r, type SubagentAgentDefinition as s, type CodePlugin as t };
|
|
@@ -1,357 +1,12 @@
|
|
|
1
1
|
import { PluginsSettings, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool } from '@theokit/sdk';
|
|
2
2
|
import { RetryOptions } from '@theokit/sdk/retry';
|
|
3
|
-
import {
|
|
3
|
+
import { a as CompiledAgentOptions, C as CompiledTool } from './agent-compiler-JSYkHpa7.js';
|
|
4
4
|
import { TheokitAgentError } from '@theokit/sdk/errors';
|
|
5
5
|
import { z } from 'zod';
|
|
6
|
-
import {
|
|
7
|
-
import {
|
|
6
|
+
import { M as MainLoopMeta } from './types-D5cHmSLi.js';
|
|
7
|
+
import { S as StreamEvent } from './agent-sse-handler-BRp9vHrb.js';
|
|
8
8
|
import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
|
|
9
9
|
|
|
10
|
-
/**
|
|
11
|
-
* Typed discriminated union for agent SSE stream events.
|
|
12
|
-
*
|
|
13
|
-
* Every event has a `type` field for discrimination.
|
|
14
|
-
* Clients narrow via `if (event.type === 'text_delta') event.content`.
|
|
15
|
-
*/
|
|
16
|
-
/** Partial text content from the LLM. */
|
|
17
|
-
interface TextDeltaEvent {
|
|
18
|
-
type: 'text_delta';
|
|
19
|
-
content: string;
|
|
20
|
-
}
|
|
21
|
-
/** Agent started a tool call. */
|
|
22
|
-
interface ToolCallEvent {
|
|
23
|
-
type: 'tool_call';
|
|
24
|
-
callId: string;
|
|
25
|
-
toolName: string;
|
|
26
|
-
input: unknown;
|
|
27
|
-
}
|
|
28
|
-
/**
|
|
29
|
-
* Tool-call arguments streaming in incrementally (theokit-sdk#70). Emitted repeatedly as the
|
|
30
|
-
* model generates a tool call's args, BEFORE they are committed. The same `callId` correlates to
|
|
31
|
-
* the later `tool_call` (args committed) and `tool_result`. Consumers opt in to render tool-input
|
|
32
|
-
* progressively; those that don't simply ignore this variant (it never replaces `tool_call`).
|
|
33
|
-
*/
|
|
34
|
-
interface PartialToolCallEvent {
|
|
35
|
-
type: 'partial_tool_call';
|
|
36
|
-
callId: string;
|
|
37
|
-
toolName: string;
|
|
38
|
-
input: unknown;
|
|
39
|
-
}
|
|
40
|
-
/** Tool execution completed. */
|
|
41
|
-
interface ToolResultEvent {
|
|
42
|
-
type: 'tool_result';
|
|
43
|
-
callId: string;
|
|
44
|
-
toolName: string;
|
|
45
|
-
output: string;
|
|
46
|
-
durationMs: number;
|
|
47
|
-
isError: boolean;
|
|
48
|
-
}
|
|
49
|
-
/** Extended thinking / reasoning (when model supports it). */
|
|
50
|
-
interface ThinkingEvent {
|
|
51
|
-
type: 'thinking';
|
|
52
|
-
content: string;
|
|
53
|
-
}
|
|
54
|
-
/** Agent loop iteration. */
|
|
55
|
-
interface IterationEvent {
|
|
56
|
-
type: 'iteration';
|
|
57
|
-
step: number;
|
|
58
|
-
totalSteps: number | null;
|
|
59
|
-
}
|
|
60
|
-
/** Human approval required before proceeding. */
|
|
61
|
-
interface ApprovalRequiredEvent {
|
|
62
|
-
type: 'approval_required';
|
|
63
|
-
callId: string;
|
|
64
|
-
toolName: string;
|
|
65
|
-
question: string;
|
|
66
|
-
input?: unknown;
|
|
67
|
-
callbackUrl: string;
|
|
68
|
-
timeoutMs: number;
|
|
69
|
-
/** M20 — JSON-schema descriptor of the custom payload the approver may attach (optional). */
|
|
70
|
-
payloadSchema?: Record<string, unknown>;
|
|
71
|
-
}
|
|
72
|
-
/**
|
|
73
|
-
* The run is blocked awaiting user input or approval — theokit#141.
|
|
74
|
-
*
|
|
75
|
-
* The SDK's low-fidelity pause signal (`SDKRequestMessage`), distinct from {@link
|
|
76
|
-
* ApprovalRequiredEvent}. The latter is the framework's own, produced by `createHitlPlugin`, and
|
|
77
|
-
* carries everything an approval UI needs to be actionable. This one carries only the request id,
|
|
78
|
-
* because that is all the SDK provides — and it matters most exactly where the plugin is absent
|
|
79
|
-
* (the ACP/serving path of theokit#139), which is where a dropped pause reads to the user as a
|
|
80
|
-
* hang with no explanation.
|
|
81
|
-
*
|
|
82
|
-
* A consumer that cannot resolve the request should still SHOW that the run is waiting. Silence is
|
|
83
|
-
* the one response that is always wrong.
|
|
84
|
-
*/
|
|
85
|
-
interface InputRequestedEvent {
|
|
86
|
-
type: 'input_requested';
|
|
87
|
-
requestId: string;
|
|
88
|
-
}
|
|
89
|
-
/** Task-level milestone or summary — theokit#141. Both fields are optional at the source. */
|
|
90
|
-
interface TaskProgressEvent {
|
|
91
|
-
type: 'task_progress';
|
|
92
|
-
status?: string;
|
|
93
|
-
text?: string;
|
|
94
|
-
}
|
|
95
|
-
/**
|
|
96
|
-
* Live output from a shell command the SDK is running — theokit#141.
|
|
97
|
-
*
|
|
98
|
-
* `event` is passed through opaquely because the SDK types it as `Record<string, unknown>`. The
|
|
99
|
-
* layer deliberately does not interpret or render it: guessing a shape here would be a second,
|
|
100
|
-
* weaker oracle over a payload whose real contract lives upstream.
|
|
101
|
-
*/
|
|
102
|
-
interface ShellOutputEvent {
|
|
103
|
-
type: 'shell_output';
|
|
104
|
-
event: Record<string, unknown>;
|
|
105
|
-
}
|
|
106
|
-
/** Agent encountered an error. */
|
|
107
|
-
interface ErrorEvent {
|
|
108
|
-
type: 'error';
|
|
109
|
-
code: string;
|
|
110
|
-
message: string;
|
|
111
|
-
retryable: boolean;
|
|
112
|
-
}
|
|
113
|
-
/**
|
|
114
|
-
* Why a run stopped short of finishing on its own — theokit#379.
|
|
115
|
-
*
|
|
116
|
-
* ## Why it is an enum and not a `truncated: boolean`
|
|
117
|
-
*
|
|
118
|
-
* The two members demand OPPOSITE reactions from the caller, and a boolean cannot carry the
|
|
119
|
-
* difference:
|
|
120
|
-
*
|
|
121
|
-
* - `'step_limit'` — the loop ran out of tool-calling turns while the model still wanted more.
|
|
122
|
-
* The work is unfinished but progressing; re-sending is the sane continuation.
|
|
123
|
-
* - `'no_progress'` — the doom-loop guard stopped the model repeating IDENTICAL tool calls. The
|
|
124
|
-
* SDK's own wording: "a controlled stop, NOT a truncation to re-send". Re-sending repeats the
|
|
125
|
-
* loop that was just cut.
|
|
126
|
-
*
|
|
127
|
-
* A caller that reads `truncated: true` and re-sends does the right thing in the first case and
|
|
128
|
-
* feeds the doom loop in the second.
|
|
129
|
-
*
|
|
130
|
-
* ## Why these spellings
|
|
131
|
-
*
|
|
132
|
-
* Both sides of the boundary had already agreed on them before this field existed: the framework's
|
|
133
|
-
* own `LoopFinishReason` (`../loop/loop-strategy.ts`) spells the outer-loop terminals `step_limit`
|
|
134
|
-
* and `no_progress`, and so does the SDK's continuation driver
|
|
135
|
-
* (`RunToCompletionResult.terminal: "done" | "step_limit" | "no_progress"`). Inventing a third
|
|
136
|
-
* vocabulary for the same two outcomes was the only way to get this wrong.
|
|
137
|
-
*
|
|
138
|
-
* ## Why there is no `'finished'` member
|
|
139
|
-
*
|
|
140
|
-
* A clean run carries NO `stopReason` at all — absence is the finished case. Stamping every
|
|
141
|
-
* ordinary turn with a new field would change what every existing consumer receives in order to
|
|
142
|
-
* describe the one case that was already correct. A consumer that has never heard of `stopReason`
|
|
143
|
-
* therefore keeps receiving byte-identical frames for every run that finishes on its own, and for a
|
|
144
|
-
* truncated one it receives one extra optional key it ignores — the same degradation the ai-sdk
|
|
145
|
-
* `finish` chunk already allows, since its `messageMetadata` is `unknown`.
|
|
146
|
-
*/
|
|
147
|
-
type AgentStopReason = 'step_limit' | 'no_progress';
|
|
148
|
-
/** Agent completed with a final result. */
|
|
149
|
-
interface DoneEvent {
|
|
150
|
-
type: 'done';
|
|
151
|
-
result: string;
|
|
152
|
-
usage: {
|
|
153
|
-
inputTokens: number;
|
|
154
|
-
outputTokens: number;
|
|
155
|
-
totalTokens: number;
|
|
156
|
-
/** V4-O: SDK reasoning/cache token buckets (0 when the provider omits them). */
|
|
157
|
-
reasoningTokens?: number;
|
|
158
|
-
cacheReadTokens?: number;
|
|
159
|
-
cacheWriteTokens?: number;
|
|
160
|
-
};
|
|
161
|
-
durationMs: number;
|
|
162
|
-
/**
|
|
163
|
-
* Total cost in USD for this agent run, as the SDK priced it (`CostBreakdown.amountUsd`).
|
|
164
|
-
*
|
|
165
|
-
* Absent when the run's price is not known (the SDK has no pricing data for the model); 0 means
|
|
166
|
-
* the SDK priced the run at zero, for example a subscription-included route. A consumer summing
|
|
167
|
-
* runs must not read an absent cost as 0 (usetheokit/theokit#969).
|
|
168
|
-
*/
|
|
169
|
-
cost?: number;
|
|
170
|
-
/**
|
|
171
|
-
* theokit#379 — why the run stopped, when it did NOT stop because the agent was done.
|
|
172
|
-
*
|
|
173
|
-
* ABSENT on a clean finish. Present only when the SDK reports that the run was cut: the terminal
|
|
174
|
-
* frame is a `done` either way (a reached ceiling is not an error — see `sdk-adapter.ts`'s
|
|
175
|
-
* `applyStepCeiling`), so without this field a cut run and a finished one are the same event.
|
|
176
|
-
*
|
|
177
|
-
* Read from `RunResult.stoppedByDoomLoop` / `RunResult.stoppedAtIterationLimit` at the adapter
|
|
178
|
-
* boundary. See {@link AgentStopReason} for why the caller needs to tell the two apart.
|
|
179
|
-
*/
|
|
180
|
-
stopReason?: AgentStopReason;
|
|
181
|
-
/**
|
|
182
|
-
* The model this turn actually ran on — the EFFECTIVE id, not the declared one.
|
|
183
|
-
*
|
|
184
|
-
* It is resolved at the one place that knows: `createSdkAgentStream`, where
|
|
185
|
-
* `overrides.model ?? compiled.model ?? 'openai/gpt-4o-mini'` is decided. A consumer reading
|
|
186
|
-
* `CompiledAgentOptions.model` instead would be wrong twice — it misses a per-run override, and
|
|
187
|
-
* it reads `undefined` for an agent that declared no model and still ran one.
|
|
188
|
-
*
|
|
189
|
-
* Tokens are on this event already, and tokens alone convert to no cost: price is per model.
|
|
190
|
-
* This is the other half of that question, and the reason it travels rather than staying inside
|
|
191
|
-
* the adapter (usetheokit/theokit#368's fifth criterion).
|
|
192
|
-
*
|
|
193
|
-
* Optional so a producer that predates it — or one building a `done` from a source with no model
|
|
194
|
-
* to report — degrades to absence rather than to a fabricated id.
|
|
195
|
-
*/
|
|
196
|
-
model?: string;
|
|
197
|
-
}
|
|
198
|
-
/**
|
|
199
|
-
* Per-turn usage the translator attaches to the ai-sdk `finish` chunk's `messageMetadata`, so it
|
|
200
|
-
* lands on the reconstructed assistant `UIMessage.metadata` on the client (via `readUIMessageStream`)
|
|
201
|
-
* with NO extra header/store wiring. It is the seam that lets a surface (a TUI status bar, a web
|
|
202
|
-
* cost meter) show real tokens/cost for the turn it just streamed. Mirrors `DoneEvent`'s usage/cost
|
|
203
|
-
* (the authoritative totals the SDK reports at turn end) plus the wall-clock `durationMs`.
|
|
204
|
-
*/
|
|
205
|
-
interface AgentTurnMetadata {
|
|
206
|
-
usage: DoneEvent['usage'];
|
|
207
|
-
/** Total cost in USD for the turn (present iff the SDK reported it). */
|
|
208
|
-
cost?: number;
|
|
209
|
-
durationMs: number;
|
|
210
|
-
/**
|
|
211
|
-
* theokit#379 — mirrors {@link DoneEvent.stopReason} so a surface that only ever sees the wire
|
|
212
|
-
* (a web client reading `UIMessage.metadata`, the observability translator reading the `finish`
|
|
213
|
-
* chunk) can tell a cut turn from a finished one without a second transport. Absent on a clean
|
|
214
|
-
* finish, exactly as on `DoneEvent`.
|
|
215
|
-
*/
|
|
216
|
-
stopReason?: AgentStopReason;
|
|
217
|
-
/**
|
|
218
|
-
* Mirrors {@link DoneEvent.model} — the model the turn ran on, carried to whoever only ever sees
|
|
219
|
-
* the wire. The observability translator is the caller that needs it: it reads the `finish`
|
|
220
|
-
* chunk and records the model beside the token counts, which is what makes a cost answerable
|
|
221
|
-
* from a trace at all. Absent when the producer reported none.
|
|
222
|
-
*/
|
|
223
|
-
model?: string;
|
|
224
|
-
}
|
|
225
|
-
/** Agent run started. */
|
|
226
|
-
interface RunStartedEvent {
|
|
227
|
-
type: 'run_started';
|
|
228
|
-
runId: string;
|
|
229
|
-
agentName: string;
|
|
230
|
-
model?: string;
|
|
231
|
-
}
|
|
232
|
-
/** Artifact generation started (code, document, diagram). */
|
|
233
|
-
interface ArtifactStartEvent {
|
|
234
|
-
type: 'artifact_start';
|
|
235
|
-
artifactId: string;
|
|
236
|
-
mimeType: string;
|
|
237
|
-
filename?: string;
|
|
238
|
-
metadata?: Record<string, unknown>;
|
|
239
|
-
}
|
|
240
|
-
/** Artifact content chunk (streamable artifacts). */
|
|
241
|
-
interface ArtifactChunkEvent {
|
|
242
|
-
type: 'artifact_chunk';
|
|
243
|
-
artifactId: string;
|
|
244
|
-
chunk: string;
|
|
245
|
-
isLast: boolean;
|
|
246
|
-
}
|
|
247
|
-
/** Real-time state update from @Observable channels. */
|
|
248
|
-
interface StateUpdateEvent {
|
|
249
|
-
type: 'state_update';
|
|
250
|
-
channel: string;
|
|
251
|
-
data: unknown;
|
|
252
|
-
}
|
|
253
|
-
/** Checkpoint saved (resumable agents). */
|
|
254
|
-
interface CheckpointSavedEvent {
|
|
255
|
-
type: 'checkpoint_saved';
|
|
256
|
-
checkpointId: string;
|
|
257
|
-
step: number;
|
|
258
|
-
resumeToken: string;
|
|
259
|
-
}
|
|
260
|
-
/** File edit produced by a code assistant tool. */
|
|
261
|
-
interface FileEditEvent {
|
|
262
|
-
type: 'file_edit';
|
|
263
|
-
file: string;
|
|
264
|
-
format: 'search-replace' | 'unified-diff' | 'full-file' | 'line-range';
|
|
265
|
-
search?: string;
|
|
266
|
-
replace?: string;
|
|
267
|
-
content?: string;
|
|
268
|
-
diff?: string;
|
|
269
|
-
startLine?: number;
|
|
270
|
-
endLine?: number;
|
|
271
|
-
}
|
|
272
|
-
/** Discriminated union of all agent stream events. */
|
|
273
|
-
type AgentStreamEvent = RunStartedEvent | TextDeltaEvent | ToolCallEvent | PartialToolCallEvent | ToolResultEvent | ThinkingEvent | IterationEvent | ApprovalRequiredEvent | InputRequestedEvent | TaskProgressEvent | ShellOutputEvent | ArtifactStartEvent | ArtifactChunkEvent | StateUpdateEvent | CheckpointSavedEvent | FileEditEvent | ErrorEvent | DoneEvent;
|
|
274
|
-
/** Type guard helpers. */
|
|
275
|
-
declare function isTextDelta(e: AgentStreamEvent): e is TextDeltaEvent;
|
|
276
|
-
declare function isToolCall(e: AgentStreamEvent): e is ToolCallEvent;
|
|
277
|
-
declare function isPartialToolCall(e: AgentStreamEvent): e is PartialToolCallEvent;
|
|
278
|
-
declare function isToolResult(e: AgentStreamEvent): e is ToolResultEvent;
|
|
279
|
-
declare function isDone(e: AgentStreamEvent): e is DoneEvent;
|
|
280
|
-
declare function isError(e: AgentStreamEvent): e is ErrorEvent;
|
|
281
|
-
declare function isApprovalRequired(e: AgentStreamEvent): e is ApprovalRequiredEvent;
|
|
282
|
-
|
|
283
|
-
/**
|
|
284
|
-
* The failure, as chunks the protocol accepts — theokit#161 (B).
|
|
285
|
-
*
|
|
286
|
-
* ## The measured defect
|
|
287
|
-
*
|
|
288
|
-
* M95 put the `code` INSIDE the error chunk (`{type:'error', errorText, errorCode}`), for a good
|
|
289
|
-
* reason: without it a consumer that must DISTINGUISH the failure has only the message, and matching
|
|
290
|
-
* on error text is the heuristic this ecosystem already paid for once — M93 classified failures as
|
|
291
|
-
* transient by regex over the message and read `ECONNREFUSED ...:443` as definitive because the PORT
|
|
292
|
-
* matched its "4xx" pattern.
|
|
293
|
-
*
|
|
294
|
-
* But the `error` variant of ai's `uiMessageChunkSchema` is STRICT: any extra key invalidates it.
|
|
295
|
-
* Measured against `ai@7.0.14` — `{type:'error',errorText:'boom'}` validates; the same chunk with
|
|
296
|
-
* `errorCode` does NOT. So since M95 this path emitted a chunk outside the protocol it claims to
|
|
297
|
-
* speak, and a consumer that validates would reject the whole frame — losing the text along with it.
|
|
298
|
-
*
|
|
299
|
-
* Nobody saw it because the test written to catch exactly this stopped BEFORE validating: its
|
|
300
|
-
* precondition (`toContainEqual({type:'error',errorText:'boom'})`) went stale when `errorCode`
|
|
301
|
-
* appeared, `expect` threw, and the validation loop never ran.
|
|
302
|
-
*
|
|
303
|
-
* ## Why a data part, and not one of the easy exits
|
|
304
|
-
*
|
|
305
|
-
* Dropping the code returns the consumer to the text matching M95 removed. Embedding it in
|
|
306
|
-
* `errorText` is the same thing under another name. The protocol already has the right place — a
|
|
307
|
-
* data part — and this file already uses one for `data-checkpoint`. Measured: it validates.
|
|
308
|
-
*
|
|
309
|
-
* `transient: true` because an error code is turn diagnostics, not message content: the SDK does not
|
|
310
|
-
* persist it in history, which is exactly what we want.
|
|
311
|
-
*
|
|
312
|
-
* The data part comes BEFORE the error chunk deliberately: a sequential consumer already holds the
|
|
313
|
-
* code when the failure arrives. In the other order it would have to handle the error first and only
|
|
314
|
-
* then learn which one it was.
|
|
315
|
-
*/
|
|
316
|
-
/**
|
|
317
|
-
* What the browser is told a failure was.
|
|
318
|
-
*
|
|
319
|
-
* Masked by default (usetheokit/theokit#390): the server's raw text — a driver's message, an HTTP
|
|
320
|
-
* client's, a filesystem call's — reached the client verbatim, and `ai@7` on the same protocol
|
|
321
|
-
* masks by default for the reason its own comment gives, "prevent leaking server error details to
|
|
322
|
-
* the client by default".
|
|
323
|
-
*
|
|
324
|
-
* The full text is NOT lost: it reaches the server's logs and the `agent.run` span, and it reaches
|
|
325
|
-
* this hook. What stops is it reaching the browser unless a host decides otherwise.
|
|
326
|
-
*/
|
|
327
|
-
type MaskError = (error: {
|
|
328
|
-
message: string;
|
|
329
|
-
code?: string;
|
|
330
|
-
}) => string;
|
|
331
|
-
declare function presentUIMessageStream(events: AsyncIterable<AgentStreamEvent>, opts: {
|
|
332
|
-
textId: string;
|
|
333
|
-
onError?: MaskError;
|
|
334
|
-
}): AsyncGenerator<WireChunk, void, unknown>;
|
|
335
|
-
|
|
336
|
-
/** Minimal event shape matching SDK's SDKMessage discriminated union. */
|
|
337
|
-
interface StreamEvent {
|
|
338
|
-
type: string;
|
|
339
|
-
[key: string]: unknown;
|
|
340
|
-
}
|
|
341
|
-
/**
|
|
342
|
-
* Create a Web Standard Response that streams the agent's turn as UIMessage wire chunks.
|
|
343
|
-
*
|
|
344
|
-
* The `event:` line carries the chunk's own type. It is informational — `parseWireStream` reads
|
|
345
|
-
* only `data:` lines, per WHATWG SSE — and kept because an `EventSource` consumer can dispatch on
|
|
346
|
-
* it.
|
|
347
|
-
*
|
|
348
|
-
* @param eventStream - the framework's own run events
|
|
349
|
-
* @param opts.onError - what a consumer is told a failure was; masked by default (#390)
|
|
350
|
-
*/
|
|
351
|
-
declare function streamAgentResponse(eventStream: AsyncIterable<StreamEvent>, opts?: {
|
|
352
|
-
onError?: Parameters<typeof presentUIMessageStream>[1]['onError'];
|
|
353
|
-
}): Response;
|
|
354
|
-
|
|
355
10
|
/**
|
|
356
11
|
* LoopStrategy — the per-round terminal-decision contract that gives runtime to
|
|
357
12
|
* `@MainLoop({ strategy })`.
|
|
@@ -445,8 +100,14 @@ interface DelegationResult {
|
|
|
445
100
|
* consumer summing runs must not read such a `cost` as the run's price (#969).
|
|
446
101
|
*/
|
|
447
102
|
costUnknown?: true;
|
|
103
|
+
/**
|
|
104
|
+
* Input plus output tokens across rounds, the SDK's `TokenUsage.totalTokens`. Cache reads and
|
|
105
|
+
* writes are not in it: from `@theokit/sdk` 5.11.0 `tokensInput` is the uncached part of the
|
|
106
|
+
* prompt on the chat-completions and Anthropic clients, so the whole prompt there is `tokensInput + cacheReadTokens +
|
|
107
|
+
* cacheWriteTokens`, and a consumer pricing a run must add the cache buckets.
|
|
108
|
+
*/
|
|
448
109
|
tokens: number;
|
|
449
|
-
/** V4-N: split token usage accumulated across rounds
|
|
110
|
+
/** V4-N: split token usage accumulated across rounds; `tokensInput` excludes cache reads and writes. Absent for the single-shot path. */
|
|
450
111
|
tokensInput?: number;
|
|
451
112
|
tokensOutput?: number;
|
|
452
113
|
/** V4-O: reasoning/cache token buckets accumulated across rounds (0 on any loop-driven run; the loop seeds them). Optional for type compat. */
|
|
@@ -785,80 +446,4 @@ interface SubAgentSpec {
|
|
|
785
446
|
}
|
|
786
447
|
declare function delegate(spec: SubAgentSpec, message: string, opts?: DelegateOptions): Promise<DelegationResult>;
|
|
787
448
|
|
|
788
|
-
|
|
789
|
-
* M25 (theokit-ai-first) — background delegation + task-completion scoring.
|
|
790
|
-
*
|
|
791
|
-
* Two THIN wrappers over the M12 `delegate` (ADR 0038/0040): no new orchestration engine, no second
|
|
792
|
-
* loop, no new store. `delegateBackground` kicks off a sub-agent without blocking the supervisor and
|
|
793
|
-
* hands back a handle to await later. `delegateWithScoring` runs `delegate`, scores the result with
|
|
794
|
-
* an injected scorer, and re-delegates with the scorer's feedback until it passes or `maxRounds` is
|
|
795
|
-
* hit. The `delegate` implementation is injectable (`delegateFn`) so this is testable without a
|
|
796
|
-
* SubAgent class or an LLM — and so it NEVER re-implements the delegation runtime.
|
|
797
|
-
*/
|
|
798
|
-
|
|
799
|
-
/**
|
|
800
|
-
* M81 — anything that can run a delegation.
|
|
801
|
-
*
|
|
802
|
-
* The reach gap this closes: both wrappers took a `SubAgentSpec` produced by the capability
|
|
803
|
-
* compiler, so a consumer holding an SDK `SubAgent` or `Squad` could not feed them. That is why the
|
|
804
|
-
* scoring loop — the layer's highest-value piece — had ZERO adoption in a product that runs an
|
|
805
|
-
* explicit review pass: it was unreachable from the primitives that product actually holds.
|
|
806
|
-
*
|
|
807
|
-
* An SDK `SubAgent` or `Squad` satisfies this by having `run`. So does a test double, which is why
|
|
808
|
-
* the loop is now testable without a compiler, a class or an LLM.
|
|
809
|
-
*/
|
|
810
|
-
interface DelegationPort {
|
|
811
|
-
run(message: string): Promise<DelegationResult>;
|
|
812
|
-
}
|
|
813
|
-
/** What both wrappers accept: the compiled spec (unchanged) or the port (M81, additive). */
|
|
814
|
-
type DelegationTarget = SubAgentSpec | DelegationPort;
|
|
815
|
-
/** The delegation primitive both wrappers drive. Defaults to the M12 {@link delegate}. */
|
|
816
|
-
type DelegateFn = (subAgent: SubAgentSpec, message: string, opts?: DelegateOptions) => Promise<DelegationResult>;
|
|
817
|
-
/** A running background delegation the supervisor can await/poll later. */
|
|
818
|
-
interface BackgroundDelegation {
|
|
819
|
-
/** Await the sub-agent's result (or rejection). Idempotent — returns the same settled promise. */
|
|
820
|
-
wait(): Promise<DelegationResult>;
|
|
821
|
-
/** Whether the underlying delegation has resolved or rejected. */
|
|
822
|
-
settled(): boolean;
|
|
823
|
-
}
|
|
824
|
-
/**
|
|
825
|
-
* Start a sub-agent WITHOUT blocking the supervisor. Returns immediately with a handle; the
|
|
826
|
-
* supervisor keeps working and calls `wait()` when it needs the result. A thin async wrapper over
|
|
827
|
-
* `delegate` — not a scheduler (Top-risk 1). Rejections are still observable via `wait()`.
|
|
828
|
-
*/
|
|
829
|
-
declare function delegateBackground(subAgent: DelegationTarget, message: string, opts?: DelegateOptions & {
|
|
830
|
-
delegateFn?: DelegateFn;
|
|
831
|
-
}): BackgroundDelegation;
|
|
832
|
-
/** A scorer's verdict on a sub-agent result. `feedback` is fed back into the next round on failure. */
|
|
833
|
-
interface ScoreVerdict {
|
|
834
|
-
pass: boolean;
|
|
835
|
-
/** Optional numeric score (0..1) for logging/telemetry. */
|
|
836
|
-
score?: number;
|
|
837
|
-
/** Guidance appended to the next delegation when `pass` is false. */
|
|
838
|
-
feedback?: string;
|
|
839
|
-
}
|
|
840
|
-
/** Scores a sub-agent result. Opt-in (Top-risk 2) — the caller supplies it, and pays its cost. */
|
|
841
|
-
type Scorer = (result: DelegationResult) => ScoreVerdict | Promise<ScoreVerdict>;
|
|
842
|
-
/** The outcome of a scored delegation: the final result plus the per-round verdict trail. */
|
|
843
|
-
interface ScoredDelegation {
|
|
844
|
-
result: DelegationResult;
|
|
845
|
-
/** Rounds actually run (1..maxRounds). */
|
|
846
|
-
rounds: number;
|
|
847
|
-
/** Whether the final round passed the scorer. */
|
|
848
|
-
passed: boolean;
|
|
849
|
-
/** The verdict from each round, in order. */
|
|
850
|
-
verdicts: ScoreVerdict[];
|
|
851
|
-
}
|
|
852
|
-
/**
|
|
853
|
-
* Run `delegate`, score the result, and re-delegate with the scorer's feedback until it passes or
|
|
854
|
-
* `maxRounds` is reached. Each round is ONE `delegate` call — no second loop, no new store. Returns
|
|
855
|
-
* the final result (passing, or the last attempt) with the per-round verdict trail.
|
|
856
|
-
*/
|
|
857
|
-
declare function delegateWithScoring(subAgent: DelegationTarget, message: string, opts: DelegateOptions & {
|
|
858
|
-
scorer: Scorer;
|
|
859
|
-
maxRounds?: number;
|
|
860
|
-
delegateFn?: DelegateFn;
|
|
861
|
-
feedbackTemplate?: (message: string, feedback: string) => string;
|
|
862
|
-
}): Promise<ScoredDelegation>;
|
|
863
|
-
|
|
864
|
-
export { loopStrategyConfigSchema as $, type AgentStopReason as A, type BackgroundDelegation as B, type CheckpointSavedEvent as C, type DelegationTarget as D, type ErrorEvent as E, type FileEditEvent as F, type StateUpdateEvent as G, type ThinkingEvent as H, type IterationEvent as I, type ToolCallEvent as J, type ToolResultEvent as K, type LoopStrategy as L, delegate as M, delegateBackground as N, delegateWithScoring as O, type PartialToolCallEvent as P, isApprovalRequired as Q, type ReflectionStrategy as R, type StreamEvent as S, type TextDeltaEvent as T, isDone as U, isError as V, isPartialToolCall as W, isTextDelta as X, isToolCall as Y, isToolResult as Z, ladderReflectionStrategy as _, type DelegateOptions as a, noopReflectionStrategy as a0, presentUIMessageStream as a1, reflectionStrategyConfigSchema as a2, resolveLoopStrategy as a3, streamAgentResponse as a4, type MaskError as a5, type RoundStreamFactory as b, type DelegationResult as c, type AgentStreamEvent as d, type AgentTurnMetadata as e, type ApprovalRequiredEvent as f, type ArtifactChunkEvent as g, type ArtifactStartEvent as h, BudgetExceededError as i, DEFAULT_MAX_ITERATIONS as j, type DelegateFn as k, DelegationBudgetCostUnknownError as l, DelegationBudgetExceededError as m, DelegationError as n, type DelegationPort as o, type DoneEvent as p, type LoopFinishReason as q, type LoopOutcome as r, type LoopStrategyConfig as s, type ReflectionContext as t, type ReflectionResult as u, type ReflectionStrategyConfig as v, type RunStartedEvent as w, type ScoreVerdict as x, type ScoredDelegation as y, type Scorer as z };
|
|
449
|
+
export { BudgetExceededError as B, type DelegationResult as D, type LoopStrategy as L, type RoundStreamFactory as R, type SubAgentSpec as S, type DelegateOptions as a, type ReflectionStrategy as b, DEFAULT_MAX_ITERATIONS as c, DelegationBudgetCostUnknownError as d, DelegationBudgetExceededError as e, DelegationError as f, type LoopFinishReason as g, type LoopOutcome as h, type LoopStrategyConfig as i, type ReflectionContext as j, type ReflectionResult as k, type ReflectionStrategyConfig as l, delegate as m, ladderReflectionStrategy as n, loopStrategyConfigSchema as o, noopReflectionStrategy as p, resolveLoopStrategy as q, reflectionStrategyConfigSchema as r };
|