@theokit/agents 4.23.0 → 4.24.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/agent-handle-DNbFlkrw.d.ts +227 -0
- package/dist/{bridge-entry-DMh--RZ5.d.ts → bridge-entry-Cq1aVJ_c.d.ts} +56 -58
- package/dist/bridge.d.ts +1 -1
- package/dist/bridge.js +1 -1
- package/dist/{chunk-IB7I44PO.js → chunk-2L5DI75P.js} +1 -1
- package/dist/chunk-2L5DI75P.js.map +1 -0
- package/dist/chunk-M2JFE6IM.js +520 -0
- package/dist/chunk-M2JFE6IM.js.map +1 -0
- package/dist/client-react.d.ts +57 -0
- package/dist/client-react.js +55 -0
- package/dist/client-react.js.map +1 -0
- package/dist/client.d.ts +81 -0
- package/dist/client.js +26 -0
- package/dist/client.js.map +1 -0
- package/dist/index.d.ts +73 -4
- package/dist/index.js +55 -1
- package/dist/index.js.map +1 -1
- package/package.json +14 -2
- package/dist/chunk-IB7I44PO.js.map +0 -1
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
import { ChatTransport, UIMessage, UIMessageChunk } from 'ai';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* M41 (ADR-0050 D2) — a HITL approval decision sent to settle a paused gated-tool call. Mirrors the
|
|
5
|
+
* `POST /api/agents/<name>/approve/<id>` wire body (`approve-agent.ts` `parseApprovalBody`). Defined
|
|
6
|
+
* on the client side (not imported from `server/`) as the client's view of the boundary contract.
|
|
7
|
+
*/
|
|
8
|
+
interface ApprovalDecision {
|
|
9
|
+
/** Whether the paused gated tool may proceed. */
|
|
10
|
+
approved: boolean;
|
|
11
|
+
/** Optional reason surfaced to the model on denial. */
|
|
12
|
+
reason?: string;
|
|
13
|
+
/** Optional small structured note (edited args, a reviewer comment) — capped server-side at 16 KiB. */
|
|
14
|
+
payload?: unknown;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* M43 (ADR-0052) — per-request context attached uniformly across every transport.
|
|
18
|
+
*
|
|
19
|
+
* `headers` is the serializable, HTTP-native half (an auth token → request headers on `HttpTransport`);
|
|
20
|
+
* `metadata` is the structured, same-process half forwarded to the in-process runner
|
|
21
|
+
* (`InProcessTransport`) / the Tauri `invoke` (`ChannelTransport`). Threaded through the seam's existing
|
|
22
|
+
* `ChatRequestOptions` — NOT a new channel. The turn input stays the request `body`.
|
|
23
|
+
*/
|
|
24
|
+
interface RequestContext {
|
|
25
|
+
/** Per-request headers (e.g. auth). HTTP-native; mapped to request headers by `HttpTransport`. */
|
|
26
|
+
headers?: Record<string, string>;
|
|
27
|
+
/** Structured per-request context (tenant, provider, …) forwarded to in-process / channel runners. */
|
|
28
|
+
metadata?: unknown;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* M41 (ADR-0050 D1/D2) — the client transport seam.
|
|
32
|
+
*
|
|
33
|
+
* It IS `ai`'s `ChatTransport<UIMessage>` (the adopted SOTA interface — we do NOT invent a parallel
|
|
34
|
+
* one) plus ONE optional method, `approve`, for TheoKit's OUT-OF-BAND HITL (the server pauses the run;
|
|
35
|
+
* the client settles it via a separate call). `ai`'s `ChatTransport` has no `approve` because its HITL
|
|
36
|
+
* is in-band (a re-sent message part); ours is out-of-band, and the settle route differs per transport
|
|
37
|
+
* (HTTP `POST /approve/<id>` vs an inline callback), so it belongs on the transport. `approve` is
|
|
38
|
+
* optional — agents without gated tools never settle an approval.
|
|
39
|
+
*
|
|
40
|
+
* `HttpTransport` (web) and `InProcessTransport` (TUI/desktop) implement this; `useAgent` drives it.
|
|
41
|
+
*/
|
|
42
|
+
type AgentTransport = ChatTransport<UIMessage> & {
|
|
43
|
+
approve?(approvalId: string, decision: ApprovalDecision): Promise<void>;
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
/** An inline approval request handed to the transport's resolver (structural — no server import). */
|
|
47
|
+
interface InProcessApprovalRequestLike {
|
|
48
|
+
approvalId: string;
|
|
49
|
+
toolName: string;
|
|
50
|
+
opts: unknown;
|
|
51
|
+
}
|
|
52
|
+
/** Resolve one gated-tool approval inline (mirrors the SDK's `boolean | HitlDecision` return). */
|
|
53
|
+
type InProcessAwaitApproval = (req: InProcessApprovalRequestLike) => Promise<boolean | ApprovalDecision>;
|
|
54
|
+
/** The input the injected runner receives (structurally compatible with `StreamAgentTurnInProcessInput`). */
|
|
55
|
+
interface InProcessRunInput {
|
|
56
|
+
message: string;
|
|
57
|
+
sessionId?: string;
|
|
58
|
+
signal?: AbortSignal;
|
|
59
|
+
awaitApproval?: InProcessAwaitApproval;
|
|
60
|
+
/** M43 — per-request context (from `sendMessages`'s `metadata`) — tenant / provider / auth for the runner. */
|
|
61
|
+
context?: unknown;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* The in-process turn runner. The consumer binds `streamAgentTurnInProcess(mod, apiKey, …)`:
|
|
65
|
+
* `new InProcessTransport({ run: (input) => streamAgentTurnInProcess(mod, apiKey, input) })`.
|
|
66
|
+
* Injecting it keeps this client module decoupled from `server/` and makes the transport testable.
|
|
67
|
+
*/
|
|
68
|
+
type InProcessRunner = (input: InProcessRunInput) => AsyncGenerator<UIMessageChunk>;
|
|
69
|
+
interface InProcessTransportOptions {
|
|
70
|
+
run: InProcessRunner;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* M41 (ADR-0050 D4) — `ChatTransport` over the in-process seam (`streamAgentTurnInProcess`), for the
|
|
74
|
+
* terminal/desktop surfaces that run client + server in ONE process (no HTTP loopback).
|
|
75
|
+
*
|
|
76
|
+
* - `sendMessages`: bridge the injected runner's `AsyncGenerator<UIMessageChunk>` into a
|
|
77
|
+
* `ReadableStream<UIMessageChunk>` (honoring `abortSignal`, which the runner forwards to the SDK).
|
|
78
|
+
* - `reconnectToStream`: always `null` — a single process has no dropped server-side stream to resume
|
|
79
|
+
* (mirrors `ai`'s `DirectChatTransport`).
|
|
80
|
+
* - `approve`: resolve the pending inline approval by id (the run parks on `awaitApproval`). An unknown
|
|
81
|
+
* id rejects (fail-fast, Rule 8 — never a silent resolve).
|
|
82
|
+
*
|
|
83
|
+
* Error asymmetry vs `HttpTransport` (by design, matching the `ChatTransport` contract): a runner that
|
|
84
|
+
* throws SYNCHRONOUSLY surfaces the error when the stream is READ (via `controller.error`), not from the
|
|
85
|
+
* `sendMessages` promise — whereas `HttpTransport` throws from `sendMessages` on a non-2xx response.
|
|
86
|
+
*/
|
|
87
|
+
declare class InProcessTransport implements AgentTransport {
|
|
88
|
+
#private;
|
|
89
|
+
constructor(options: InProcessTransportOptions);
|
|
90
|
+
sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
|
|
91
|
+
reconnectToStream(): Promise<ReadableStream<UIMessageChunk> | null>;
|
|
92
|
+
approve(approvalId: string, decision: ApprovalDecision): Promise<void>;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** Handlers the transport hands to the injected push source for one turn. */
|
|
96
|
+
interface ChannelTurnHandlers {
|
|
97
|
+
/** One pushed JSONL line (a serialized `UIMessageChunk`). */
|
|
98
|
+
onLine: (line: string) => void;
|
|
99
|
+
/** The turn ended — no more lines. */
|
|
100
|
+
onClose: () => void;
|
|
101
|
+
/** The push source failed. */
|
|
102
|
+
onError?: (err: unknown) => void;
|
|
103
|
+
}
|
|
104
|
+
/**
|
|
105
|
+
* The injected push source — a Tauri `Channel`/`invoke` bridge, kept STRUCTURAL so core adds no
|
|
106
|
+
* `@tauri-apps/*` dependency and the transport is testable with a fake (ADR-0051 D2). The Tauri app
|
|
107
|
+
* wires it: `new Channel()`, `channel.onmessage = onLine`, `invoke('run_agent', { message, channel })`,
|
|
108
|
+
* returning a teardown that aborts the sidecar turn.
|
|
109
|
+
*/
|
|
110
|
+
interface ChannelPushSource {
|
|
111
|
+
/**
|
|
112
|
+
* Start a turn; deliver each JSONL `UIMessageChunk` line to `onLine`, then `onClose`. Return a teardown.
|
|
113
|
+
* `turn.context` (M43) is the per-request context (from the seam's `metadata`) — the Tauri `invoke`
|
|
114
|
+
* forwards it to the sidecar. When no context is set it is present as `context: undefined` (the key is
|
|
115
|
+
* NOT absent) — a sidecar that checks `'context' in turn` should treat `undefined` as "no context".
|
|
116
|
+
*/
|
|
117
|
+
start(turn: {
|
|
118
|
+
message: string;
|
|
119
|
+
context?: unknown;
|
|
120
|
+
}, handlers: ChannelTurnHandlers): () => void;
|
|
121
|
+
/** Optional HITL settle (another Tauri `invoke`). */
|
|
122
|
+
settle?(approvalId: string, decision: ApprovalDecision): Promise<void>;
|
|
123
|
+
}
|
|
124
|
+
interface ChannelTransportOptions {
|
|
125
|
+
source: ChannelPushSource;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* M42 (ADR-0051) — `ChatTransport` over a Tauri-`Channel`-shaped push source, for the desktop webview.
|
|
129
|
+
*
|
|
130
|
+
* - `sendMessages`: start the turn via the injected source and bridge its pushed JSONL frames into a
|
|
131
|
+
* `ReadableStream<UIMessageChunk>` (built in `start` — a Channel is push, so the stream's queue buffers
|
|
132
|
+
* frames; ADR-0051 D3). A malformed JSONL line is SKIPPED, never fatal (ADR-0051 D4, Rule 8). `abortSignal`
|
|
133
|
+
* tears down the source and closes the stream.
|
|
134
|
+
* - `reconnectToStream`: always `null` — the M36 sidecar runs the turn directly (no durable server stream);
|
|
135
|
+
* this is the honest parity for a single-process push surface (ADR-0051 D5; mirrors `InProcessTransport`).
|
|
136
|
+
* - `approve`: routes to the injected `settle` (another Tauri `invoke`); absent `settle` → a typed error.
|
|
137
|
+
*
|
|
138
|
+
* The push source is INJECTED — core stays Tauri-agnostic and this transport is unit-tested with a fake.
|
|
139
|
+
*/
|
|
140
|
+
declare class ChannelTransport implements AgentTransport {
|
|
141
|
+
#private;
|
|
142
|
+
constructor(options: ChannelTransportOptions);
|
|
143
|
+
sendMessages(options: Parameters<ChatTransport<UIMessage>['sendMessages']>[0]): Promise<ReadableStream<UIMessageChunk>>;
|
|
144
|
+
reconnectToStream(): Promise<ReadableStream<UIMessageChunk> | null>;
|
|
145
|
+
approve(approvalId: string, decision: ApprovalDecision): Promise<void>;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
type UseAgentStatus = 'idle' | 'streaming' | 'done' | 'error';
|
|
149
|
+
/** The observable state the store exposes (stable reference between emits — `useSyncExternalStore` contract). */
|
|
150
|
+
interface AgentClientState {
|
|
151
|
+
/** The CURRENT turn's assistant messages (per-turn; reset each `send`). Back-compat — unchanged since M41. */
|
|
152
|
+
messages: UIMessage[];
|
|
153
|
+
/**
|
|
154
|
+
* M46 — the full conversation: committed turns + the current turn's user message + in-flight assistant.
|
|
155
|
+
* Accumulated across sends (never reset except by `reset()`), with stable ids committed exactly once.
|
|
156
|
+
* Render this instead of hand-rolling a transcript from `messages`.
|
|
157
|
+
*/
|
|
158
|
+
thread: UIMessage[];
|
|
159
|
+
status: UseAgentStatus;
|
|
160
|
+
error: Error | undefined;
|
|
161
|
+
}
|
|
162
|
+
/**
|
|
163
|
+
* M41 (ADR-0050 D6) — the framework-agnostic agent client store.
|
|
164
|
+
*
|
|
165
|
+
* Holds `messages`/`status`/`error`, drives an {@link AgentTransport}, and notifies subscribers on
|
|
166
|
+
* change. It is the SINGLE consolidation point: web (`HttpTransport`) and terminal/desktop
|
|
167
|
+
* (`InProcessTransport`) run the SAME store. `useAgent` is a thin React binding over it via
|
|
168
|
+
* `useSyncExternalStore`; a standalone (no-React) client (M44) can subscribe directly. Being
|
|
169
|
+
* framework-agnostic, it is unit-tested without a DOM.
|
|
170
|
+
*/
|
|
171
|
+
declare class AgentClient<TInput = unknown> {
|
|
172
|
+
#private;
|
|
173
|
+
constructor(transport: AgentTransport, contextResolver?: () => RequestContext | undefined);
|
|
174
|
+
/** Subscribe to state changes; returns an unsubscribe fn. */
|
|
175
|
+
subscribe: (listener: () => void) => (() => void);
|
|
176
|
+
/** The current immutable snapshot (stable reference until the next emit). */
|
|
177
|
+
getSnapshot: () => AgentClientState;
|
|
178
|
+
/** Send a typed input; opens a fresh stream (replaces prior messages). */
|
|
179
|
+
send: (input: TInput) => void;
|
|
180
|
+
/** Resume an interrupted stream via the transport's `reconnectToStream` (no-op when unavailable). */
|
|
181
|
+
reconnect: () => void;
|
|
182
|
+
/** Abort an in-flight stream (not an error — leaves messages as-is). */
|
|
183
|
+
abort: () => void;
|
|
184
|
+
/** Clear messages + error, back to idle. */
|
|
185
|
+
reset: () => void;
|
|
186
|
+
/** Settle a paused HITL approval via the transport's HITL path (HTTP POST or inline callback). */
|
|
187
|
+
approve: (approvalId: string, decision: ApprovalDecision) => Promise<void>;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* M47 (ADR-M47-2) — a typed, client-safe handle for an exposed agent.
|
|
192
|
+
*
|
|
193
|
+
* It carries ONLY the HTTP `path` at runtime plus phantom `input`/`toolNames` types (never populated) — so
|
|
194
|
+
* `useAgent(chat)` / `createAgentClient(chat…)` bind with NO magic string (the path is generated from the
|
|
195
|
+
* `@Expose` exposure, not hand-typed) and NO duplicated input type (the input type flows through the phantom
|
|
196
|
+
* generic, inferred from the agent's `.input()`). This mirrors tRPC/Hono's type-only handle: the client
|
|
197
|
+
* pulls the agent's TYPE via `import type`, never its server runtime. The generated `@theo/agents` module
|
|
198
|
+
* emits one `export const <name> = agentHandle('/api/agents/<name>')` per agent, typed with the phantoms.
|
|
199
|
+
*/
|
|
200
|
+
interface AgentHandle<TInput = unknown, TToolNames extends string = string> {
|
|
201
|
+
/** The agent's HTTP endpoint path (e.g. `/api/agents/chat`). The only serializable/runtime-bearing field. */
|
|
202
|
+
readonly path: string;
|
|
203
|
+
/**
|
|
204
|
+
* M47 — bind this agent in-process (TUI / single-process): wraps the app's runner in an
|
|
205
|
+
* {@link InProcessTransport}. `useAgent(chat.inProcess(run))` drives the SAME agent without HTTP.
|
|
206
|
+
*/
|
|
207
|
+
inProcess(run: InProcessRunner): InProcessTransport;
|
|
208
|
+
/**
|
|
209
|
+
* M47 — bind this agent over a push channel (Tauri desktop webview): wraps the source in a
|
|
210
|
+
* {@link ChannelTransport}. `createAgentClient(chat.channel(source))` drives the SAME agent.
|
|
211
|
+
*/
|
|
212
|
+
channel(source: ChannelPushSource): ChannelTransport;
|
|
213
|
+
/** Phantom — the agent's `input` type, carried for `useAgent(handle).send` inference. Never populated. */
|
|
214
|
+
readonly __input?: TInput;
|
|
215
|
+
/** Phantom — the agent's tool-name union, carried end-to-end. Never populated. */
|
|
216
|
+
readonly __toolNames?: TToolNames;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Build an {@link AgentHandle} from an agent's HTTP path. Types are supplied by the caller/codegen. The
|
|
220
|
+
* `inProcess`/`channel` binders are methods (dropped by `JSON.stringify`, so the `{ path }` core stays
|
|
221
|
+
* serializable + client-safe) that produce the M41 transports for the non-web surfaces.
|
|
222
|
+
*/
|
|
223
|
+
declare function agentHandle<TInput = unknown, TToolNames extends string = string>(path: string): AgentHandle<TInput, TToolNames>;
|
|
224
|
+
/** Narrow an unknown binding to an {@link AgentHandle} (has a string `path`, is not a transport). */
|
|
225
|
+
declare function isAgentHandle(value: unknown): value is AgentHandle;
|
|
226
|
+
|
|
227
|
+
export { type ApprovalDecision as A, type ChannelPushSource as C, type InProcessApprovalRequestLike as I, type RequestContext as R, type UseAgentStatus as U, type AgentHandle as a, type AgentTransport as b, AgentClient as c, type AgentClientState as d, ChannelTransport as e, type ChannelTransportOptions as f, type ChannelTurnHandlers as g, type InProcessAwaitApproval as h, type InProcessRunInput as i, type InProcessRunner as j, InProcessTransport as k, type InProcessTransportOptions as l, agentHandle as m, isAgentHandle as n };
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { ExecutionContext } from '@theokit/http';
|
|
2
|
-
import { SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings,
|
|
2
|
+
import { SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings, PreToolCallContext, PreToolCallDecision, PostToolCallContext, ToolResultTransformContext, TransformContext, SessionLifecycleContext, PreUserSendContext, PreUserSendResult, PostAssistantReplyContext, CustomTool, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, ModelSelection } from '@theokit/sdk';
|
|
3
3
|
import { z } from 'zod';
|
|
4
4
|
import { UIMessageChunk } from 'ai';
|
|
5
5
|
import { RetryOptions } from '@theokit/sdk/retry';
|
|
@@ -721,6 +721,59 @@ interface AgentRouteContext {
|
|
|
721
721
|
/** Generate HTTP routes for a single agent. Returns Web Standard handlers. */
|
|
722
722
|
declare function generateAgentRoutes(ctx: AgentRouteContext): AgentRoute[];
|
|
723
723
|
|
|
724
|
+
/**
|
|
725
|
+
* M82 — the typed shape of `AgentBuilder.create().hooks({...})`.
|
|
726
|
+
*
|
|
727
|
+
* ## Por que este tipo mora aqui
|
|
728
|
+
*
|
|
729
|
+
* Até o M82 a assinatura era `Readonly<Record<string, unknown>>`: qualquer chave era aceita e cada
|
|
730
|
+
* handler recebia `ctx: unknown`. O consumidor que quisesse tipo tinha de declarar o seu — e foi
|
|
731
|
+
* exatamente o que o agent-builder fez, com um alias local de cinco handlers, quatro deles com
|
|
732
|
+
* `ctx: unknown` porque não havia de onde importar os contextos.
|
|
733
|
+
*
|
|
734
|
+
* É a mesma classe que o M81 fechou com `discoverSubagents`: conhecimento do framework reimplementado
|
|
735
|
+
* no app porque o framework não o publicava. O tipo nasce onde o conhecimento mora.
|
|
736
|
+
*
|
|
737
|
+
* ## Sobre `transform_tool_result`
|
|
738
|
+
*
|
|
739
|
+
* Este é o ÚNICO canal de estágio-de-tool cujo retorno o SDK aplica — `#runTransform` dobra o valor
|
|
740
|
+
* devolvido; `#runFireAndForget`, usado por `post_tool_call`, descarta. Desde o M82 seu contexto
|
|
741
|
+
* carrega `toolCalls`, de modo que uma política com escopo (por nome de tool) possa AGIR sobre o
|
|
742
|
+
* resultado em vez de apenas observá-lo.
|
|
743
|
+
*/
|
|
744
|
+
|
|
745
|
+
/**
|
|
746
|
+
* Handlers de ciclo de vida chaveados por `HookName`.
|
|
747
|
+
*
|
|
748
|
+
* Cada campo é opcional: um agente registra só os eventos que lhe interessam. `.hooks()` aceita a
|
|
749
|
+
* UNIÃO deste tipo com o shape solto de antes (ADR-4 do M82), então não é preciso index signature
|
|
750
|
+
* implícita para o valor passar no call site — o estreitamento é gradual, não uma quebra.
|
|
751
|
+
*/
|
|
752
|
+
interface HookHandlers {
|
|
753
|
+
/**
|
|
754
|
+
* Roda ANTES da tool. Devolver `{ block: true, message }` VETA a chamada — é o único hook com
|
|
755
|
+
* poder de veto.
|
|
756
|
+
*/
|
|
757
|
+
pre_tool_call?: (ctx: PreToolCallContext) => Promise<PreToolCallDecision | undefined> | PreToolCallDecision | undefined;
|
|
758
|
+
/**
|
|
759
|
+
* Roda DEPOIS da tool, com `{name, args, result}`. Fire-and-forget: o retorno é **descartado**
|
|
760
|
+
* pelo SDK. Para AGIR sobre o resultado use {@link transform_tool_result}.
|
|
761
|
+
*/
|
|
762
|
+
post_tool_call?: (ctx: PostToolCallContext) => Promise<void> | void;
|
|
763
|
+
/**
|
|
764
|
+
* Dobra os resultados de tool do turn antes de eles subirem ao modelo. Desde o M82 o contexto traz
|
|
765
|
+
* `toolCalls` — plural, porque o seam recebe o LOTE do turn; correlacione por
|
|
766
|
+
* `toolUseId === id`.
|
|
767
|
+
*/
|
|
768
|
+
transform_tool_result?: <T>(results: T, ctx: ToolResultTransformContext) => Promise<T> | T;
|
|
769
|
+
/** Dobra o texto do modelo antes de ele ser consumido. Sem tool call envolvida. */
|
|
770
|
+
transform_llm_output?: (output: string, ctx: TransformContext) => Promise<string> | string;
|
|
771
|
+
on_session_start?: (ctx: SessionLifecycleContext) => Promise<void> | void;
|
|
772
|
+
on_session_end?: (ctx: SessionLifecycleContext) => Promise<void> | void;
|
|
773
|
+
pre_user_send?: (ctx: PreUserSendContext) => Promise<PreUserSendResult | undefined> | PreUserSendResult | undefined;
|
|
774
|
+
post_assistant_reply?: (ctx: PostAssistantReplyContext) => Promise<void> | void;
|
|
775
|
+
}
|
|
776
|
+
|
|
724
777
|
/**
|
|
725
778
|
* M2 (theokit-ai-first) — `defineAgent`, the zero-config imperative agent surface.
|
|
726
779
|
*
|
|
@@ -810,7 +863,7 @@ interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
|
|
|
810
863
|
* the builder's `hooks()`; converted into a code plugin at `build()` and never reaching the SDK
|
|
811
864
|
* under this name — the plugin is the TRANSPORT, this is the contract callers write against.
|
|
812
865
|
*/
|
|
813
|
-
hooks?: Readonly<Record<string, unknown>>;
|
|
866
|
+
hooks?: HookHandlers | Readonly<Record<string, unknown>>;
|
|
814
867
|
/**
|
|
815
868
|
* MCP servers available to the agent — the builder-chain equivalent of the `@MCP` class
|
|
816
869
|
* decorator. Each key is a server name; the value is the server configuration. Forwarded
|
|
@@ -1058,61 +1111,6 @@ declare function presentUIMessageStream(events: AsyncIterable<AgentStreamEvent>,
|
|
|
1058
1111
|
textId: string;
|
|
1059
1112
|
}): AsyncGenerator<UIMessageChunk, void, unknown>;
|
|
1060
1113
|
|
|
1061
|
-
/**
|
|
1062
|
-
* M82 — the typed shape of `AgentBuilder.create().hooks({...})`.
|
|
1063
|
-
*
|
|
1064
|
-
* ## Por que este tipo mora aqui
|
|
1065
|
-
*
|
|
1066
|
-
* Até o M82 a assinatura era `Readonly<Record<string, unknown>>`: qualquer chave era aceita e todo
|
|
1067
|
-
* handler recebia `ctx: unknown`. O consumidor que quisesse tipo tinha de declarar o seu — e foi
|
|
1068
|
-
* exatamente o que o agent-builder fez, com um alias local de cinco handlers, quatro deles com
|
|
1069
|
-
* `ctx: unknown` porque não havia de onde importar os contextos.
|
|
1070
|
-
*
|
|
1071
|
-
* É a mesma classe que o M81 fechou com `discoverSubagents`: conhecimento do framework reimplementado
|
|
1072
|
-
* no app porque o framework não o publicava. O tipo nasce onde o conhecimento mora.
|
|
1073
|
-
*
|
|
1074
|
-
* ## Sobre `transform_tool_result`
|
|
1075
|
-
*
|
|
1076
|
-
* Este é o ÚNICO canal de estágio-de-tool cujo retorno o SDK aplica — `#runTransform` dobra o valor
|
|
1077
|
-
* devolvido; `#runFireAndForget`, usado por `post_tool_call`, descarta. Desde o M82 seu contexto
|
|
1078
|
-
* carrega `toolCalls`, de modo que uma política com escopo (por nome de tool) possa AGIR sobre o
|
|
1079
|
-
* resultado em vez de apenas observá-lo.
|
|
1080
|
-
*/
|
|
1081
|
-
|
|
1082
|
-
/**
|
|
1083
|
-
* Handlers de ciclo de vida chaveados por `HookName`.
|
|
1084
|
-
*
|
|
1085
|
-
* TYPE ALIAS, não interface: só aliases ganham index signature implícita, e é isso que mantém o
|
|
1086
|
-
* valor atribuível ao parâmetro solto de `.hooks()` sem cast no call site (ADR-4 do M82 — o
|
|
1087
|
-
* estreitamento é gradual, não uma quebra).
|
|
1088
|
-
*
|
|
1089
|
-
* Todo campo é opcional: um agente registra só os eventos que lhe interessam.
|
|
1090
|
-
*/
|
|
1091
|
-
type HookHandlers = {
|
|
1092
|
-
/**
|
|
1093
|
-
* Roda ANTES da tool. Devolver `{ block: true, message }` VETA a chamada — é o único hook com
|
|
1094
|
-
* poder de veto.
|
|
1095
|
-
*/
|
|
1096
|
-
pre_tool_call?: (ctx: PreToolCallContext) => Promise<PreToolCallDecision | undefined> | PreToolCallDecision | undefined;
|
|
1097
|
-
/**
|
|
1098
|
-
* Roda DEPOIS da tool, com `{name, args, result}`. Fire-and-forget: o retorno é **descartado**
|
|
1099
|
-
* pelo SDK. Para AGIR sobre o resultado use {@link transform_tool_result}.
|
|
1100
|
-
*/
|
|
1101
|
-
post_tool_call?: (ctx: PostToolCallContext) => Promise<void> | void;
|
|
1102
|
-
/**
|
|
1103
|
-
* Dobra os resultados de tool do turn antes de eles subirem ao modelo. Desde o M82 o contexto traz
|
|
1104
|
-
* `toolCalls` — plural, porque o seam recebe o LOTE do turn; correlacione por
|
|
1105
|
-
* `toolUseId === id`.
|
|
1106
|
-
*/
|
|
1107
|
-
transform_tool_result?: <T>(results: T, ctx: ToolResultTransformContext) => Promise<T> | T;
|
|
1108
|
-
/** Dobra o texto do modelo antes de ele ser consumido. Sem tool call envolvida. */
|
|
1109
|
-
transform_llm_output?: (output: string, ctx: TransformContext) => Promise<string> | string;
|
|
1110
|
-
on_session_start?: (ctx: SessionLifecycleContext) => Promise<void> | void;
|
|
1111
|
-
on_session_end?: (ctx: SessionLifecycleContext) => Promise<void> | void;
|
|
1112
|
-
pre_user_send?: (ctx: PreUserSendContext) => Promise<PreUserSendResult | undefined> | PreUserSendResult | undefined;
|
|
1113
|
-
post_assistant_reply?: (ctx: PostAssistantReplyContext) => Promise<void> | void;
|
|
1114
|
-
};
|
|
1115
|
-
|
|
1116
1114
|
/**
|
|
1117
1115
|
* M8 — `AgentBuilder.create()`, the fluent agent builder with accumulative **type-state**.
|
|
1118
1116
|
*
|
|
@@ -2111,4 +2109,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
|
|
|
2111
2109
|
register(app: PluginApp): void;
|
|
2112
2110
|
};
|
|
2113
2111
|
|
|
2114
|
-
export { type
|
|
2112
|
+
export { type DoneEvent as $, type ApprovalOptions as A, type ApiErrorPolicy as B, type CompiledAgentOptions as C, type DelegationResult as D, type ApprovalRequiredEvent as E, type ArtifactChunkEvent as F, type Guardrail as G, type HumanInTheLoopOptions as H, type ArtifactStartEvent as I, type BackgroundDelegation as J, type BeforeToolCallContext as K, type LoopStrategy as L, type MainLoopMeta as M, BudgetExceededError as N, type BudgetOptions as O, type CheckpointSavedEvent as P, type CompiledContextWindow as Q, type ReflectionStrategy as R, type StreamEvent as S, type ToolOptions as T, ContextualTool as U, CostBudgetExceededError as V, DEFAULT_MAX_ITERATIONS as W, type DefineAgentConfig as X, type DelegateFn as Y, type DelegateOptions as Z, DelegationError as _, type CompiledTool as a, generateAgentManifest as a$, type ErrorEvent as a0, type FileEditEvent as a1, type GuardrailAction as a2, type GuardrailPhase as a3, type GuardrailResult as a4, GuardrailViolationError as a5, type HookHandlers as a6, type InferAgentInput as a7, type InferAgentToolNames as a8, type IterationEvent as a9, type ThinkingEvent as aA, type TimeoutAction as aB, type ToolCallEvent as aC, type ToolCallVeto as aD, type ToolHooks as aE, type ToolHooksPlugin as aF, type ToolResultEvent as aG, type ToolWalkResult as aH, type ToolboxOptions as aI, type ToolboxWalkResult as aJ, agentsPlugin as aK, buildModelSelection as aL, compileAgentDefinition as aM, compileAgentModule as aN, compileContextWindow as aO, compileProjectContext as aP, compileSkills as aQ, compileTools as aR, createAgentExecutionContext as aS, createApiErrorHandler as aT, createSdkAgentStream as aU, createThinkTagExtractor as aV, createToolHooksPlugin as aW, delegate as aX, delegateBackground as aY, delegateWithScoring as aZ, extractThinkTagStream as a_, type LLMCallContext as aa, type LoopFinishReason as ab, type LoopOutcome as ac, type LoopStrategyConfig as ad, type MainLoopOptions as ae, type McpApprovalSpec as af, type McpRegistryConfig as ag, type McpRequestContext as ah, type McpSelection as ai, type PartialToolCallEvent as aj, type PolicyHandler as ak, type ProcessInputContext as al, type ReflectionContext as am, type ReflectionResult as an, type ReflectionStrategyConfig as ao, type RunStartedEvent as ap, type ScoreVerdict as aq, type ScoredDelegation as ar, type Scorer as as, type SdkAgentHandle as at, type SdkMessage as au, type Segment as av, type SkillsRequestContext as aw, type SkillsSelection as ax, type StateUpdateEvent as ay, type TextDeltaEvent as az, type ReasoningEffort as b, generateAgentRoutes as b0, isAgentContext as b1, isAgentDefinition as b2, isApprovalRequired as b3, isDone as b4, isError as b5, isPartialToolCall as b6, isTextDelta as b7, isToolCall as b8, isToolResult as b9, ladderReflectionStrategy as ba, loopStrategyConfigSchema as bb, mcpRegistry as bc, mcpToolApprovals as bd, noopReflectionStrategy as be, presentUIMessageStream as bf, projectContextMetadataOnlyKnobs as bg, reflectionStrategyConfigSchema as bh, resolveEnabledSkills as bi, resolveLoopStrategy as bj, resolveMcpServers as bk, runWithApiErrorHandling as bl, streamAgentResponse as bm, toAgentFactory as bn, translateSdkEvent as bo, type RoundStreamFactory as c, type ContextWindowOptions as d, type SkillsOptions as e, type AgentManifestEntry as f, type HitlDecision as g, AGENT_BRAND as h, type AfterToolCallContext as i, AgentBuilder as j, type AgentDefinition as k, AgentDefinitionError as l, type AgentExecutionContext as m, type AgentManifest as n, type AgentManifestSource as o, type AgentManifestTool as p, type AgentOptions as q, type AgentRoute as r, streamAgentUIMessages as s, type AgentRouteContext as t, type AgentRunInfo as u, type AgentStreamEvent as v, type AgentTurnMetadata as w, type AgentsPluginOptions as x, type ApiErrorContext as y, type ApiErrorDecision as z };
|
package/dist/bridge.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export {
|
|
1
|
+
export { h as AGENT_BRAND, i as AfterToolCallContext, j as AgentBuilder, k as AgentDefinition, l as AgentDefinitionError, m as AgentExecutionContext, n as AgentManifest, f as AgentManifestEntry, o as AgentManifestSource, p as AgentManifestTool, r as AgentRoute, t as AgentRouteContext, u as AgentRunInfo, v as AgentStreamEvent, w as AgentTurnMetadata, x as AgentsPluginOptions, y as ApiErrorContext, z as ApiErrorDecision, B as ApiErrorPolicy, E as ApprovalRequiredEvent, F as ArtifactChunkEvent, I as ArtifactStartEvent, J as BackgroundDelegation, K as BeforeToolCallContext, N as BudgetExceededError, P as CheckpointSavedEvent, C as CompiledAgentOptions, Q as CompiledContextWindow, a as CompiledTool, U as ContextualTool, X as DefineAgentConfig, Y as DelegateFn, Z as DelegateOptions, _ as DelegationError, D as DelegationResult, $ as DoneEvent, a0 as ErrorEvent, a1 as FileEditEvent, a7 as InferAgentInput, a8 as InferAgentToolNames, a9 as IterationEvent, aa as LLMCallContext, af as McpApprovalSpec, ag as McpRegistryConfig, ah as McpRequestContext, ai as McpSelection, aj as PartialToolCallEvent, al as ProcessInputContext, ap as RunStartedEvent, aq as ScoreVerdict, ar as ScoredDelegation, as as Scorer, at as SdkAgentHandle, au as SdkMessage, av as Segment, ay as StateUpdateEvent, S as StreamEvent, az as TextDeltaEvent, aA as ThinkingEvent, aC as ToolCallEvent, aD as ToolCallVeto, aE as ToolHooks, aF as ToolHooksPlugin, aG as ToolResultEvent, aH as ToolWalkResult, aJ as ToolboxWalkResult, aK as agentsPlugin, aL as buildModelSelection, aM as compileAgentDefinition, aN as compileAgentModule, aO as compileContextWindow, aP as compileProjectContext, aQ as compileSkills, aR as compileTools, aS as createAgentExecutionContext, aT as createApiErrorHandler, aU as createSdkAgentStream, aV as createThinkTagExtractor, aW as createToolHooksPlugin, aX as delegate, aY as delegateBackground, aZ as delegateWithScoring, a_ as extractThinkTagStream, a$ as generateAgentManifest, b0 as generateAgentRoutes, b1 as isAgentContext, b2 as isAgentDefinition, b3 as isApprovalRequired, b4 as isDone, b5 as isError, b6 as isPartialToolCall, b7 as isTextDelta, b8 as isToolCall, b9 as isToolResult, bc as mcpRegistry, bd as mcpToolApprovals, bf as presentUIMessageStream, bg as projectContextMetadataOnlyKnobs, bk as resolveMcpServers, bl as runWithApiErrorHandling, bm as streamAgentResponse, s as streamAgentUIMessages, bn as toAgentFactory, bo as translateSdkEvent } from './bridge-entry-Cq1aVJ_c.js';
|
|
2
2
|
import '@theokit/http';
|
|
3
3
|
import '@theokit/sdk';
|
|
4
4
|
import 'zod';
|
package/dist/bridge.js
CHANGED