@theokit/agents 0.6.0 → 0.8.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/dist/bridge-entry-CAI1139f.d.ts +625 -0
- package/dist/bridge.d.ts +4 -552
- package/dist/bridge.js +2 -2
- package/dist/{chunk-KTYBQ7HY.js → chunk-BCSRKDP6.js} +189 -40
- package/dist/chunk-BCSRKDP6.js.map +1 -0
- package/dist/{chunk-MVEY7HEY.js → chunk-GVPUUKKE.js} +19 -1
- package/dist/chunk-GVPUUKKE.js.map +1 -0
- package/dist/{chunk-XWVZS2PQ.js → chunk-SKTJS4QQ.js} +2 -2
- package/dist/decorators.d.ts +2 -2
- package/dist/decorators.js +6 -2
- package/dist/index.d.ts +122 -74
- package/dist/index.js +15 -3
- package/dist/{skills-DmN1HGUb.d.ts → skills-BHnHPn7p.d.ts} +13 -1
- package/package.json +3 -3
- package/dist/chunk-KTYBQ7HY.js.map +0 -1
- package/dist/chunk-MVEY7HEY.js.map +0 -1
- /package/dist/{chunk-XWVZS2PQ.js.map → chunk-SKTJS4QQ.js.map} +0 -0
package/dist/bridge.d.ts
CHANGED
|
@@ -1,553 +1,5 @@
|
|
|
1
|
-
|
|
2
|
-
import
|
|
3
|
-
import
|
|
1
|
+
export { A as AgentExecutionContext, b as AgentManifest, c as AgentManifestEntry, d as AgentManifestTool, e as AgentRoute, f as AgentRouteContext, g as AgentRunInfo, h as AgentStreamEvent, i as AgentWalkResult, j as AgentWarningCode, k as AgentsPluginOptions, l as ApprovalRequiredEvent, m as ArtifactChunkEvent, n as ArtifactStartEvent, B as BudgetExceededError, o as CheckpointSavedEvent, C as CompiledAgentOptions, p as CompiledContextWindow, q as CompiledTool, s as DelegateOptions, t as DelegationError, D as DelegationResult, u as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as IterationEvent, R as RunStartedEvent, x as SdkMessage, y as StateUpdateEvent, S as StreamEvent, T as TextDeltaEvent, z as ThinkingEvent, G as ToolCallEvent, H as ToolResultEvent, J as ToolWalkResult, K as ToolboxWalkResult, M as agentsPlugin, N as compileAgent, O as compileContextWindow, P as compileProjectContext, Q as compileSkills, U as compileTools, V as createAgentExecutionContext, W as createSdkAgentStream, X as delegate, Y as generateAgentManifest, Z as generateAgentRoutes, _ as isAgentContext, $ as isApprovalRequired, a0 as isDone, a1 as isError, a2 as isTextDelta, a3 as isToolCall, a4 as isToolResult, a6 as projectContextMetadataOnlyKnobs, a8 as streamAgentResponse, a9 as translateSdkEvent, aa as validateUniqueRoutes, ab as walkAgentMetadata } from './bridge-entry-CAI1139f.js';
|
|
2
|
+
import '@theokit/http';
|
|
3
|
+
import './skills-BHnHPn7p.js';
|
|
4
4
|
import 'zod';
|
|
5
|
-
|
|
6
|
-
/**
|
|
7
|
-
* AgentExecutionContext — extends http-decorators' ExecutionContext with agent-specific methods.
|
|
8
|
-
*
|
|
9
|
-
* Per ADR D2 (LSP): any guard that accepts ExecutionContext works unchanged with
|
|
10
|
-
* AgentExecutionContext. Agent-specific guards can narrow via isAgentContext().
|
|
11
|
-
*/
|
|
12
|
-
|
|
13
|
-
interface AgentRunInfo {
|
|
14
|
-
id: string;
|
|
15
|
-
startedAt: Date;
|
|
16
|
-
}
|
|
17
|
-
interface AgentExecutionContext extends ExecutionContext {
|
|
18
|
-
/** The agent's configuration from @Agent() decorator. */
|
|
19
|
-
getAgent(): AgentOptions;
|
|
20
|
-
/** The current run information. */
|
|
21
|
-
getRun(): AgentRunInfo;
|
|
22
|
-
/** The tool being called, or null if in the main agent handler. */
|
|
23
|
-
getToolCall(): ToolOptions | null;
|
|
24
|
-
/** Type guard — always true for AgentExecutionContext. */
|
|
25
|
-
isAgentContext(): true;
|
|
26
|
-
}
|
|
27
|
-
/** Create an AgentExecutionContext from a base ExecutionContext + agent state. */
|
|
28
|
-
declare function createAgentExecutionContext(base: ExecutionContext, agent: AgentOptions, run: AgentRunInfo, toolCall?: ToolOptions): AgentExecutionContext;
|
|
29
|
-
/** Narrow an ExecutionContext to AgentExecutionContext if it is one. */
|
|
30
|
-
declare function isAgentContext(ctx: ExecutionContext): ctx is AgentExecutionContext;
|
|
31
|
-
|
|
32
|
-
/**
|
|
33
|
-
* Walk decorator metadata on agent + toolbox classes.
|
|
34
|
-
* Mirrors http-decorators' walkControllerMetadata() pattern.
|
|
35
|
-
*
|
|
36
|
-
* EC-1: throws if @Agent class is missing @MainLoop.
|
|
37
|
-
* EC-4: throws on duplicate routes across agents.
|
|
38
|
-
*/
|
|
39
|
-
|
|
40
|
-
/**
|
|
41
|
-
* Stable warning codes for agent pipeline metadata-only decorators.
|
|
42
|
-
* Test by code, not by message string. Document in agent support matrix.
|
|
43
|
-
*/
|
|
44
|
-
declare const AgentWarningCode: {
|
|
45
|
-
readonly INTERCEPTOR_METADATA_ONLY: "THEO_AGENT_INTERCEPTOR_METADATA_ONLY";
|
|
46
|
-
readonly FILTER_METADATA_ONLY: "THEO_AGENT_FILTER_METADATA_ONLY";
|
|
47
|
-
readonly BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY";
|
|
48
|
-
readonly CONTEXT_STRATEGY_METADATA_ONLY: "THEO_AGENT_CONTEXT_STRATEGY_METADATA_ONLY";
|
|
49
|
-
readonly PROJECT_CONTEXT_KNOB_METADATA_ONLY: "THEO_AGENT_PROJECT_CONTEXT_KNOB_METADATA_ONLY";
|
|
50
|
-
};
|
|
51
|
-
interface AgentWalkResult {
|
|
52
|
-
agentConfig: AgentOptions;
|
|
53
|
-
mainLoop: MainLoopMeta;
|
|
54
|
-
toolboxes: ToolboxWalkResult[];
|
|
55
|
-
guards: Function[];
|
|
56
|
-
interceptors: Function[];
|
|
57
|
-
filters: Function[];
|
|
58
|
-
route: string;
|
|
59
|
-
gateway?: GatewayOptions;
|
|
60
|
-
subAgentClasses: Function[];
|
|
61
|
-
memory?: MemoryOptions;
|
|
62
|
-
skills?: SkillsOptions;
|
|
63
|
-
contextWindow?: ContextWindowOptions;
|
|
64
|
-
projectContext?: ProjectContextOptions;
|
|
65
|
-
mcpServers?: McpServersMap;
|
|
66
|
-
}
|
|
67
|
-
interface ToolboxWalkResult {
|
|
68
|
-
class: Function;
|
|
69
|
-
namespace: string;
|
|
70
|
-
tools: ToolWalkResult[];
|
|
71
|
-
guards: Function[];
|
|
72
|
-
}
|
|
73
|
-
interface ToolWalkResult {
|
|
74
|
-
propertyKey: string | symbol;
|
|
75
|
-
config: ToolOptions;
|
|
76
|
-
guards: Function[];
|
|
77
|
-
approval?: ApprovalOptions;
|
|
78
|
-
capabilities?: string[];
|
|
79
|
-
budget?: BudgetOptions;
|
|
80
|
-
trace: boolean;
|
|
81
|
-
audit: boolean;
|
|
82
|
-
}
|
|
83
|
-
/**
|
|
84
|
-
* Walk all metadata on an agent class and its toolboxes.
|
|
85
|
-
* Memoized per AgentClass via WeakMap.
|
|
86
|
-
*
|
|
87
|
-
* @throws Error if @Agent is missing @MainLoop (EC-1)
|
|
88
|
-
*/
|
|
89
|
-
declare function walkAgentMetadata(AgentClass: Function, toolboxClasses?: Function[]): AgentWalkResult;
|
|
90
|
-
/**
|
|
91
|
-
* Validate that no two agents share the same route prefix.
|
|
92
|
-
*
|
|
93
|
-
* @throws Error on duplicate routes (EC-4)
|
|
94
|
-
*/
|
|
95
|
-
declare function validateUniqueRoutes(results: AgentWalkResult[]): void;
|
|
96
|
-
|
|
97
|
-
/**
|
|
98
|
-
* Agent compiler — transforms decorator metadata into SDK calls.
|
|
99
|
-
*
|
|
100
|
-
* Per ADR D1: @Agent is a macro over Agent.create().
|
|
101
|
-
* Per ADR D3: @Tool compiles to defineTool().
|
|
102
|
-
*
|
|
103
|
-
* EC-3: throws if toolbox instance is missing from the instances map.
|
|
104
|
-
*/
|
|
105
|
-
|
|
106
|
-
/** Minimal interface matching defineTool() result shape. */
|
|
107
|
-
interface CompiledTool {
|
|
108
|
-
name: string;
|
|
109
|
-
description: string;
|
|
110
|
-
inputSchema: unknown;
|
|
111
|
-
handler: (input: unknown) => string | Promise<string>;
|
|
112
|
-
}
|
|
113
|
-
/**
|
|
114
|
-
* Compile @Tool metadata into tool definitions.
|
|
115
|
-
*
|
|
116
|
-
* @param toolboxes - Walked toolbox metadata
|
|
117
|
-
* @param toolboxInstances - Map of Toolbox class → instantiated object (for `this` binding)
|
|
118
|
-
*/
|
|
119
|
-
declare function compileTools(toolboxes: ToolboxWalkResult[], toolboxInstances: Map<Function, object>): CompiledTool[];
|
|
120
|
-
/** Compiled sub-agent definition matching SDK AgentDefinition shape. */
|
|
121
|
-
interface CompiledSubAgent {
|
|
122
|
-
model?: string;
|
|
123
|
-
systemPrompt?: string;
|
|
124
|
-
}
|
|
125
|
-
/** Compiled agent options ready for SDK Agent.create(). */
|
|
126
|
-
interface CompiledAgentOptions {
|
|
127
|
-
model?: string;
|
|
128
|
-
systemPrompt?: string;
|
|
129
|
-
tools: CompiledTool[];
|
|
130
|
-
agents: Record<string, CompiledSubAgent>;
|
|
131
|
-
memory?: MemoryOptions;
|
|
132
|
-
skills?: SkillsSettings;
|
|
133
|
-
context?: ContextSettings;
|
|
134
|
-
/** Raw @ProjectContext config; the adapter builds the (async) systemPrompt resolver from it. */
|
|
135
|
-
projectContext?: ProjectContextOptions;
|
|
136
|
-
mcpServers?: McpServersMap;
|
|
137
|
-
maxIterations?: number;
|
|
138
|
-
timeoutMs?: number;
|
|
139
|
-
stream: boolean;
|
|
140
|
-
}
|
|
141
|
-
/**
|
|
142
|
-
* Compile @Agent metadata into SDK-compatible options.
|
|
143
|
-
*
|
|
144
|
-
* EC-7: agents without toolboxes produce tools: [].
|
|
145
|
-
*/
|
|
146
|
-
declare function compileAgent(walkResult: AgentWalkResult, toolboxInstances?: Map<Function, object>): CompiledAgentOptions;
|
|
147
|
-
|
|
148
|
-
/**
|
|
149
|
-
* M8-3 — compile `@Skills` metadata into the SDK's `SkillsSettings`.
|
|
150
|
-
*
|
|
151
|
-
* Per sdk-runtime.md: the bridge COMPILES decorator metadata into a format the
|
|
152
|
-
* SDK accepts; the SDK is the runtime. `Agent.create({ skills })` natively
|
|
153
|
-
* discovers `.theokit/skills/<name>/SKILL.md` files and injects the `<skills>`
|
|
154
|
-
* block — so giving `@Skills` runtime is a pure shape translation, not a
|
|
155
|
-
* reimplementation of discovery.
|
|
156
|
-
*
|
|
157
|
-
* Mapping (ADR D4):
|
|
158
|
-
* - `{ include }` → `{ enabled: include, autoInject: true }`
|
|
159
|
-
* - `{ autoDiscover: true }` → `{ autoInject: true }` (enabled omitted ⇒ the SDK
|
|
160
|
-
* enables every discovered skill)
|
|
161
|
-
*/
|
|
162
|
-
|
|
163
|
-
declare function compileSkills(options: SkillsOptions): SkillsSettings;
|
|
164
|
-
|
|
165
|
-
/**
|
|
166
|
-
* M8-1 — compile `@ContextWindow` metadata into the SDK's `ContextSettings`.
|
|
167
|
-
*
|
|
168
|
-
* Per sdk-runtime.md, the SDK owns session/transcript storage + compaction.
|
|
169
|
-
* The bridge therefore maps the one knob the SDK natively exposes as a budget —
|
|
170
|
-
* `maxTokens` → `ContextSettings.maxTokens` — and reports the strategy knobs that
|
|
171
|
-
* have NO native `AgentOptions` equivalent (`compactionStrategy`, `preserveLastN`,
|
|
172
|
-
* `preserveToolResults`, `preserveSystemPrompt`). Those are surfaced as
|
|
173
|
-
* `metadataOnlyKnobs` so the walk can emit an honest `metadata-only` warning
|
|
174
|
-
* (ADR D2) instead of silently dropping them (G10 — honest enforcement).
|
|
175
|
-
*/
|
|
176
|
-
|
|
177
|
-
interface CompiledContextWindow {
|
|
178
|
-
/** SDK-shaped context budget passed to `Agent.create({ context })`. */
|
|
179
|
-
context: ContextSettings;
|
|
180
|
-
/** Declared knobs the SDK does not expose — reported, never silently dropped. */
|
|
181
|
-
metadataOnlyKnobs: string[];
|
|
182
|
-
}
|
|
183
|
-
declare function compileContextWindow(options: ContextWindowOptions): CompiledContextWindow;
|
|
184
|
-
|
|
185
|
-
/**
|
|
186
|
-
* M8-2 — compile `@ProjectContext` metadata into an SDK `SystemPromptResolver`.
|
|
187
|
-
*
|
|
188
|
-
* There is no native `AgentOptions` field that carries a repo map, so the bridge
|
|
189
|
-
* composes the documented `systemPrompt` seam (`string | SystemPromptResolver`):
|
|
190
|
-
* the resolver prepends `buildEnvContext` + `buildRepoMap` (`@theokit/sdk-tools`)
|
|
191
|
-
* and the nearest `THEO.md` (`@theokit/sdk/project#readProjectInstructions`) to
|
|
192
|
-
* the agent's base prompt (ADR D3). The SDK primitives are dynamically imported
|
|
193
|
-
* so `@theokit/sdk-tools` stays an OPTIONAL peer — only loaded when a `@ProjectContext`
|
|
194
|
-
* agent actually sends.
|
|
195
|
-
*
|
|
196
|
-
* Knobs with no primitive mapping (`indexStrategy`, `relevanceStrategy`,
|
|
197
|
-
* `maxFilesInContext`, `includeExtensions`, `rootMarkers`) are reported via
|
|
198
|
-
* {@link projectContextMetadataOnlyKnobs} so the walk warns honestly (G10).
|
|
199
|
-
* Only `ignorePatterns` is forwarded (to `buildRepoMap`).
|
|
200
|
-
*/
|
|
201
|
-
|
|
202
|
-
declare function projectContextMetadataOnlyKnobs(options: ProjectContextOptions): string[];
|
|
203
|
-
/**
|
|
204
|
-
* Build a `SystemPromptResolver` that prepends env + repo map + project
|
|
205
|
-
* instructions to `base`. When the SDK provides no `cwd`, the resolver returns
|
|
206
|
-
* `base` unchanged (no filesystem guess — keeps `packages/agents/src` free of
|
|
207
|
-
* direct Node `process` access per G8; the repo map needs a real cwd).
|
|
208
|
-
*/
|
|
209
|
-
declare function compileProjectContext(options: ProjectContextOptions, base?: string): SystemPromptResolver;
|
|
210
|
-
|
|
211
|
-
/**
|
|
212
|
-
* SSE streaming handler — Web Standard Response with ReadableStream.
|
|
213
|
-
*
|
|
214
|
-
* Per ADR D4: SSE is the v1 transport.
|
|
215
|
-
* Per EC-2: uses ReadableStream with controller.enqueue() instead of res.write().
|
|
216
|
-
* Works natively on Node, Bun, Deno, CF Workers.
|
|
217
|
-
*/
|
|
218
|
-
/** Minimal event shape matching SDK's SDKMessage discriminated union. */
|
|
219
|
-
interface StreamEvent {
|
|
220
|
-
type: string;
|
|
221
|
-
[key: string]: unknown;
|
|
222
|
-
}
|
|
223
|
-
/**
|
|
224
|
-
* Create a Web Standard Response that streams SSE events.
|
|
225
|
-
* Each event becomes: `event: {type}\ndata: {json}\n\n`
|
|
226
|
-
*/
|
|
227
|
-
declare function streamAgentResponse(eventStream: AsyncIterable<StreamEvent>): Response;
|
|
228
|
-
|
|
229
|
-
/**
|
|
230
|
-
* Typed discriminated union for agent SSE stream events.
|
|
231
|
-
*
|
|
232
|
-
* Every event has a `type` field for discrimination.
|
|
233
|
-
* Clients narrow via `if (event.type === 'text_delta') event.content`.
|
|
234
|
-
*/
|
|
235
|
-
/** Partial text content from the LLM. */
|
|
236
|
-
interface TextDeltaEvent {
|
|
237
|
-
type: 'text_delta';
|
|
238
|
-
content: string;
|
|
239
|
-
}
|
|
240
|
-
/** Agent started a tool call. */
|
|
241
|
-
interface ToolCallEvent {
|
|
242
|
-
type: 'tool_call';
|
|
243
|
-
callId: string;
|
|
244
|
-
toolName: string;
|
|
245
|
-
input: unknown;
|
|
246
|
-
}
|
|
247
|
-
/** Tool execution completed. */
|
|
248
|
-
interface ToolResultEvent {
|
|
249
|
-
type: 'tool_result';
|
|
250
|
-
callId: string;
|
|
251
|
-
toolName: string;
|
|
252
|
-
output: string;
|
|
253
|
-
durationMs: number;
|
|
254
|
-
isError: boolean;
|
|
255
|
-
}
|
|
256
|
-
/** Extended thinking / reasoning (when model supports it). */
|
|
257
|
-
interface ThinkingEvent {
|
|
258
|
-
type: 'thinking';
|
|
259
|
-
content: string;
|
|
260
|
-
}
|
|
261
|
-
/** Agent loop iteration. */
|
|
262
|
-
interface IterationEvent {
|
|
263
|
-
type: 'iteration';
|
|
264
|
-
step: number;
|
|
265
|
-
totalSteps: number | null;
|
|
266
|
-
}
|
|
267
|
-
/** Human approval required before proceeding. */
|
|
268
|
-
interface ApprovalRequiredEvent {
|
|
269
|
-
type: 'approval_required';
|
|
270
|
-
callId: string;
|
|
271
|
-
toolName: string;
|
|
272
|
-
question: string;
|
|
273
|
-
input?: unknown;
|
|
274
|
-
callbackUrl: string;
|
|
275
|
-
timeoutMs: number;
|
|
276
|
-
}
|
|
277
|
-
/** Agent encountered an error. */
|
|
278
|
-
interface ErrorEvent {
|
|
279
|
-
type: 'error';
|
|
280
|
-
code: string;
|
|
281
|
-
message: string;
|
|
282
|
-
retryable: boolean;
|
|
283
|
-
}
|
|
284
|
-
/** Agent completed with a final result. */
|
|
285
|
-
interface DoneEvent {
|
|
286
|
-
type: 'done';
|
|
287
|
-
result: string;
|
|
288
|
-
usage: {
|
|
289
|
-
inputTokens: number;
|
|
290
|
-
outputTokens: number;
|
|
291
|
-
totalTokens: number;
|
|
292
|
-
};
|
|
293
|
-
durationMs: number;
|
|
294
|
-
/** Total cost in USD for this agent run (EC-2: added for budget tracking). */
|
|
295
|
-
cost?: number;
|
|
296
|
-
}
|
|
297
|
-
/** Agent run started. */
|
|
298
|
-
interface RunStartedEvent {
|
|
299
|
-
type: 'run_started';
|
|
300
|
-
runId: string;
|
|
301
|
-
agentName: string;
|
|
302
|
-
model?: string;
|
|
303
|
-
}
|
|
304
|
-
/** Artifact generation started (code, document, diagram). */
|
|
305
|
-
interface ArtifactStartEvent {
|
|
306
|
-
type: 'artifact_start';
|
|
307
|
-
artifactId: string;
|
|
308
|
-
mimeType: string;
|
|
309
|
-
filename?: string;
|
|
310
|
-
metadata?: Record<string, unknown>;
|
|
311
|
-
}
|
|
312
|
-
/** Artifact content chunk (streamable artifacts). */
|
|
313
|
-
interface ArtifactChunkEvent {
|
|
314
|
-
type: 'artifact_chunk';
|
|
315
|
-
artifactId: string;
|
|
316
|
-
chunk: string;
|
|
317
|
-
isLast: boolean;
|
|
318
|
-
}
|
|
319
|
-
/** Real-time state update from @Observable channels. */
|
|
320
|
-
interface StateUpdateEvent {
|
|
321
|
-
type: 'state_update';
|
|
322
|
-
channel: string;
|
|
323
|
-
data: unknown;
|
|
324
|
-
}
|
|
325
|
-
/** Checkpoint saved (resumable agents). */
|
|
326
|
-
interface CheckpointSavedEvent {
|
|
327
|
-
type: 'checkpoint_saved';
|
|
328
|
-
checkpointId: string;
|
|
329
|
-
step: number;
|
|
330
|
-
resumeToken: string;
|
|
331
|
-
}
|
|
332
|
-
/** File edit produced by a code assistant tool. */
|
|
333
|
-
interface FileEditEvent {
|
|
334
|
-
type: 'file_edit';
|
|
335
|
-
file: string;
|
|
336
|
-
format: 'search-replace' | 'unified-diff' | 'full-file' | 'line-range';
|
|
337
|
-
search?: string;
|
|
338
|
-
replace?: string;
|
|
339
|
-
content?: string;
|
|
340
|
-
diff?: string;
|
|
341
|
-
startLine?: number;
|
|
342
|
-
endLine?: number;
|
|
343
|
-
}
|
|
344
|
-
/** Discriminated union of all agent stream events. */
|
|
345
|
-
type AgentStreamEvent = RunStartedEvent | TextDeltaEvent | ToolCallEvent | ToolResultEvent | ThinkingEvent | IterationEvent | ApprovalRequiredEvent | ArtifactStartEvent | ArtifactChunkEvent | StateUpdateEvent | CheckpointSavedEvent | FileEditEvent | ErrorEvent | DoneEvent;
|
|
346
|
-
/** Type guard helpers. */
|
|
347
|
-
declare function isTextDelta(e: AgentStreamEvent): e is TextDeltaEvent;
|
|
348
|
-
declare function isToolCall(e: AgentStreamEvent): e is ToolCallEvent;
|
|
349
|
-
declare function isToolResult(e: AgentStreamEvent): e is ToolResultEvent;
|
|
350
|
-
declare function isDone(e: AgentStreamEvent): e is DoneEvent;
|
|
351
|
-
declare function isError(e: AgentStreamEvent): e is ErrorEvent;
|
|
352
|
-
declare function isApprovalRequired(e: AgentStreamEvent): e is ApprovalRequiredEvent;
|
|
353
|
-
|
|
354
|
-
/**
|
|
355
|
-
* Auto-generate HTTP routes from @Agent metadata — Web Standard.
|
|
356
|
-
*
|
|
357
|
-
* Per ADR D5: @Agent({ route }) auto-generates two endpoints:
|
|
358
|
-
* - POST {route}/chat — send message, receive SSE stream
|
|
359
|
-
* - GET {route}/runs/:runId — get run status/result
|
|
360
|
-
*
|
|
361
|
-
* Routes are convention-based, generated at registration time.
|
|
362
|
-
*/
|
|
363
|
-
|
|
364
|
-
interface AgentRoute {
|
|
365
|
-
method: 'POST' | 'GET';
|
|
366
|
-
path: string;
|
|
367
|
-
handler: (request: Request) => Promise<Response>;
|
|
368
|
-
}
|
|
369
|
-
interface AgentRouteContext {
|
|
370
|
-
walkResult: AgentWalkResult;
|
|
371
|
-
compiledOptions: CompiledAgentOptions;
|
|
372
|
-
createRun: (message: string, sessionId: string) => AsyncIterable<StreamEvent>;
|
|
373
|
-
getRun?: (runId: string) => Promise<{
|
|
374
|
-
id: string;
|
|
375
|
-
status: string;
|
|
376
|
-
result?: string;
|
|
377
|
-
} | null>;
|
|
378
|
-
}
|
|
379
|
-
/** Generate HTTP routes for a single agent. Returns Web Standard handlers. */
|
|
380
|
-
declare function generateAgentRoutes(ctx: AgentRouteContext): AgentRoute[];
|
|
381
|
-
|
|
382
|
-
/**
|
|
383
|
-
* Creates an agent stream factory using @theokit/sdk as the runtime.
|
|
384
|
-
*
|
|
385
|
-
* Returns a function that, given a message + sessionId, yields TheoKit
|
|
386
|
-
* AgentStreamEvent via the SDK's Agent.create() + Run.stream() pipeline.
|
|
387
|
-
*/
|
|
388
|
-
declare function createSdkAgentStream(compiled: CompiledAgentOptions, compiledTools: CompiledTool[], apiKey: string, envModel?: string): (message: string, _sessionId: string) => AsyncIterable<StreamEvent>;
|
|
389
|
-
|
|
390
|
-
/**
|
|
391
|
-
* Translates @theokit/sdk SDKMessage events → TheoKit AgentStreamEvent.
|
|
392
|
-
*
|
|
393
|
-
* The SDK yields SDKMessage (system/assistant/tool_call/thinking/status).
|
|
394
|
-
* TheoKit devtools + SSE handler expect AgentStreamEvent (run_started/text_delta/tool_call/done).
|
|
395
|
-
* This module bridges the two — Adapter pattern (per sdk-integration-blueprint ADR-D2).
|
|
396
|
-
*/
|
|
397
|
-
|
|
398
|
-
/** Minimal SDK message shape — duck-typed to avoid hard import of @theokit/sdk types. */
|
|
399
|
-
interface SdkMessage {
|
|
400
|
-
type: string;
|
|
401
|
-
[key: string]: unknown;
|
|
402
|
-
}
|
|
403
|
-
/**
|
|
404
|
-
* Translate a single SDK message to zero or more TheoKit stream events.
|
|
405
|
-
* Returns an array because one SDK message may map to multiple TheoKit events.
|
|
406
|
-
*/
|
|
407
|
-
declare function translateSdkEvent(msg: SdkMessage, runId: string): StreamEvent[];
|
|
408
|
-
|
|
409
|
-
/**
|
|
410
|
-
* Shared delegation value types + typed errors.
|
|
411
|
-
*
|
|
412
|
-
* Extracted from `agent-orchestrator.ts` so BOTH the orchestrator (`delegate`)
|
|
413
|
-
* and the loop driver (`loop/run-reflective-loop.ts`) can import them WITHOUT a
|
|
414
|
-
* cycle (orchestrator → loop → delegation-types; orchestrator → delegation-types;
|
|
415
|
-
* delegation-types depends on nothing — Acyclic Dependencies Principle, G1).
|
|
416
|
-
* `agent-orchestrator.ts` re-exports these for backward compatibility.
|
|
417
|
-
*/
|
|
418
|
-
interface DelegationResult {
|
|
419
|
-
response: string;
|
|
420
|
-
toolCalls: {
|
|
421
|
-
name: string;
|
|
422
|
-
input: unknown;
|
|
423
|
-
output: string;
|
|
424
|
-
}[];
|
|
425
|
-
cost: number;
|
|
426
|
-
tokens: number;
|
|
427
|
-
/** Rounds the reflective loop ran (set by `runReflectiveLoop`; absent for the single-shot path). */
|
|
428
|
-
rounds?: number;
|
|
429
|
-
}
|
|
430
|
-
declare class BudgetExceededError extends Error {
|
|
431
|
-
readonly agentName: string;
|
|
432
|
-
readonly actualCost: number;
|
|
433
|
-
readonly budgetLimit: number;
|
|
434
|
-
constructor(agentName: string, actualCost: number, budgetLimit: number);
|
|
435
|
-
}
|
|
436
|
-
declare class DelegationError extends Error {
|
|
437
|
-
readonly agentName: string;
|
|
438
|
-
readonly cause: unknown;
|
|
439
|
-
constructor(agentName: string, cause: unknown);
|
|
440
|
-
}
|
|
441
|
-
|
|
442
|
-
interface DelegateOptions {
|
|
443
|
-
/** Max USD for this sub-agent call. */
|
|
444
|
-
budget?: number;
|
|
445
|
-
/** Parent's remaining budget (for clamping). */
|
|
446
|
-
parentBudgetRemaining?: number;
|
|
447
|
-
/** Parent's tools (for sharing — sub-agent inherits these). */
|
|
448
|
-
parentTools?: CompiledTool[];
|
|
449
|
-
/** LLM API key (inherited from parent). */
|
|
450
|
-
apiKey?: string;
|
|
451
|
-
/** Session ID override (default: crypto.randomUUID for isolation). */
|
|
452
|
-
sessionId?: string;
|
|
453
|
-
/** Cancellation — aborts stop the reflective loop from re-entering. */
|
|
454
|
-
signal?: AbortSignal;
|
|
455
|
-
}
|
|
456
|
-
/**
|
|
457
|
-
* Delegate a task to a sub-agent and collect its result.
|
|
458
|
-
*
|
|
459
|
-
* - Budget clamping: `min(parentBudgetRemaining, budget)` (D4)
|
|
460
|
-
* - Tool sharing: parent tools merged with sub-agent tools (sub wins on collision)
|
|
461
|
-
* - Toolbox auto-instantiation: sub-agent toolboxes instantiated without DI (EC-1)
|
|
462
|
-
* - Session isolation: each delegation gets a unique session ID (EC-4)
|
|
463
|
-
* - `@MainLoop` strategy runtime: routes through `runReflectiveLoop` (the same loop
|
|
464
|
-
* `AgentRunner.run` uses — one runtime for both on-ramps, ADR D4). The runtime
|
|
465
|
-
* metric (`THEO_AGENT_MAINLOOP_RUNTIME_APPLIED`) + typed-error + cumulative budget
|
|
466
|
-
* all live in the shared driver, so they fire identically on both paths.
|
|
467
|
-
*/
|
|
468
|
-
declare function delegate(SubAgentClass: Function, message: string, opts?: DelegateOptions): Promise<DelegationResult>;
|
|
469
|
-
|
|
470
|
-
/**
|
|
471
|
-
* Agent manifest generator — build-time JSON describing all agents, tools, guards, policies.
|
|
472
|
-
*
|
|
473
|
-
* Feeds: theokit agents list/inspect, TheoCloud deploy, UI agent consoles.
|
|
474
|
-
*/
|
|
475
|
-
|
|
476
|
-
interface AgentManifest {
|
|
477
|
-
version: '1.0';
|
|
478
|
-
generatedAt: string;
|
|
479
|
-
agents: AgentManifestEntry[];
|
|
480
|
-
}
|
|
481
|
-
interface AgentManifestEntry {
|
|
482
|
-
name: string;
|
|
483
|
-
route: string;
|
|
484
|
-
model?: string;
|
|
485
|
-
stream: boolean;
|
|
486
|
-
mainLoop: {
|
|
487
|
-
method: string;
|
|
488
|
-
strategy: string;
|
|
489
|
-
};
|
|
490
|
-
guards: string[];
|
|
491
|
-
interceptors: string[];
|
|
492
|
-
tools: AgentManifestTool[];
|
|
493
|
-
gateway?: {
|
|
494
|
-
platforms: string[];
|
|
495
|
-
sessionStrategy: string;
|
|
496
|
-
};
|
|
497
|
-
subAgents: string[];
|
|
498
|
-
memory?: {
|
|
499
|
-
provider: string;
|
|
500
|
-
embeddings: boolean;
|
|
501
|
-
fts: boolean;
|
|
502
|
-
scope: string;
|
|
503
|
-
};
|
|
504
|
-
skills?: string[];
|
|
505
|
-
mcpServers?: string[];
|
|
506
|
-
}
|
|
507
|
-
interface AgentManifestTool {
|
|
508
|
-
name: string;
|
|
509
|
-
description: string;
|
|
510
|
-
risk?: string;
|
|
511
|
-
approval: boolean;
|
|
512
|
-
capabilities?: string[];
|
|
513
|
-
trace: boolean;
|
|
514
|
-
audit: boolean;
|
|
515
|
-
}
|
|
516
|
-
/**
|
|
517
|
-
* Generate a serializable agent manifest from walked metadata.
|
|
518
|
-
* All Function references are converted to string names for JSON safety.
|
|
519
|
-
*/
|
|
520
|
-
declare function generateAgentManifest(walkResults: AgentWalkResult[]): AgentManifest;
|
|
521
|
-
|
|
522
|
-
/**
|
|
523
|
-
* agentsPlugin() — TheoKit dev-server plugin for agent routes.
|
|
524
|
-
*
|
|
525
|
-
* Mirrors httpDecoratorsPlugin() pattern. Registers agent HTTP endpoints
|
|
526
|
-
* (POST /chat, GET /runs/:id) via the TheoKit plugin hook system.
|
|
527
|
-
*
|
|
528
|
-
* Per ADR D6: structural { name, register } shape (no compile-time theokit dep).
|
|
529
|
-
*/
|
|
530
|
-
|
|
531
|
-
interface AgentsPluginOptions {
|
|
532
|
-
/** Agent classes decorated with @Agent(). */
|
|
533
|
-
agents: Function[];
|
|
534
|
-
/** Toolbox classes (or use @Mixin on agents). */
|
|
535
|
-
toolboxes?: Function[];
|
|
536
|
-
/** Factory that creates agent runs — bridges to SDK Agent.create() + agent.send(). */
|
|
537
|
-
createRunFactory?: (compiled: CompiledAgentOptions, walkResult: AgentWalkResult) => (message: string, sessionId: string) => AsyncIterable<StreamEvent>;
|
|
538
|
-
}
|
|
539
|
-
interface PluginApp {
|
|
540
|
-
addHook(name: string, fn: (ctx: {
|
|
541
|
-
request: Request;
|
|
542
|
-
}) => Promise<Response | undefined>): void;
|
|
543
|
-
}
|
|
544
|
-
/**
|
|
545
|
-
* Create a TheoKit plugin that mounts agent routes.
|
|
546
|
-
* Web Standard Request/Response — runtime-agnostic.
|
|
547
|
-
*/
|
|
548
|
-
declare function agentsPlugin(opts: AgentsPluginOptions): {
|
|
549
|
-
name: string;
|
|
550
|
-
register(app: PluginApp): void;
|
|
551
|
-
};
|
|
552
|
-
|
|
553
|
-
export { type AgentExecutionContext, type AgentManifest, type AgentManifestEntry, type AgentManifestTool, type AgentRoute, type AgentRouteContext, type AgentRunInfo, type AgentStreamEvent, type AgentWalkResult, AgentWarningCode, type AgentsPluginOptions, type ApprovalRequiredEvent, type ArtifactChunkEvent, type ArtifactStartEvent, BudgetExceededError, type CheckpointSavedEvent, type CompiledAgentOptions, type CompiledContextWindow, type CompiledTool, type DelegateOptions, DelegationError, type DelegationResult, type DoneEvent, type ErrorEvent, type FileEditEvent, type IterationEvent, type RunStartedEvent, type SdkMessage, type StateUpdateEvent, type StreamEvent, type TextDeltaEvent, type ThinkingEvent, type ToolCallEvent, type ToolResultEvent, type ToolWalkResult, type ToolboxWalkResult, agentsPlugin, compileAgent, compileContextWindow, compileProjectContext, compileSkills, compileTools, createAgentExecutionContext, createSdkAgentStream, delegate, generateAgentManifest, generateAgentRoutes, isAgentContext, isApprovalRequired, isDone, isError, isTextDelta, isToolCall, isToolResult, projectContextMetadataOnlyKnobs, streamAgentResponse, translateSdkEvent, validateUniqueRoutes, walkAgentMetadata };
|
|
5
|
+
import '@theokit/sdk';
|
package/dist/bridge.js
CHANGED
|
@@ -25,8 +25,8 @@ import {
|
|
|
25
25
|
translateSdkEvent,
|
|
26
26
|
validateUniqueRoutes,
|
|
27
27
|
walkAgentMetadata
|
|
28
|
-
} from "./chunk-
|
|
29
|
-
import "./chunk-
|
|
28
|
+
} from "./chunk-BCSRKDP6.js";
|
|
29
|
+
import "./chunk-GVPUUKKE.js";
|
|
30
30
|
import "./chunk-7QVYU63E.js";
|
|
31
31
|
export {
|
|
32
32
|
AgentWarningCode,
|