Repository navigation
Expand file tree
/
Copy pathtypes.ts
More file actions
701 lines (649 loc) · 29.1 KB
/
Copy pathtypes.ts
File metadata and controls
701 lines (649 loc) · 29.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
import type {
Api,
AssistantMessage,
AssistantMessageEvent,
AssistantMessageEventStream,
CursorExecHandlers,
ImageContent,
JsonValue,
Message,
Model,
ProviderDiagnostic,
SimpleStreamOptions,
TextContent,
ThinkingSelection,
Tool,
ToolResultMessage,
TranscriptContext,
Usage,
} from "@earendil-works/pi-ai";
import type { Static, TSchema } from "typebox";
import type { DurableStore } from "./durable/store.ts";
import type { ExecutionPipelineWitness, ExecutionScope, ToolHost } from "./execution/tool-host.ts";
/**
* Opens a new, empty store for one tool batch, which the batch claims at epoch 1. A batch never reuses another's
* store: a call's command ID is the model's call ID, and providers reuse those across turns.
*/
export type BatchStoreFactory = () => DurableStore;
export type {
ExecutionPipelineWitness,
ExecutionScope,
ToolHost,
ToolHostCall,
ToolHostOptions,
ToolHostResult,
} from "./execution/tool-host.ts";
/**
* Stream function used by the agent loop. `Models.streamSimple` satisfies
* this shape.
*
* The loop passes a normalized transcript: the system prompt and tool
* declarations are carried by the transcript's system messages, never by
* `context.systemPrompt` or `context.tools`.
*
* Contract:
* - Must not throw or return a rejected promise for request/model/runtime failures.
* - Must return an AssistantMessageEventStream.
* - Failures must be encoded in the returned stream via protocol events and a
* final AssistantMessage with stopReason "error" or "aborted" and errorMessage.
*/
export type StreamFn = (
model: Model<Api>,
context: TranscriptContext,
options?: SimpleStreamOptions,
) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
/**
* Configuration for how tool calls from a single assistant message are executed.
*
* - "sequential": each tool call is prepared, executed, and finalized before the next one starts.
* - "parallel": tool calls are prepared sequentially, then scheduled in concurrent waves.
* Tools with `executionMode: "sequential"` run as exclusive barriers; parallel tools before
* or after the barrier can still execute concurrently with each other.
* `tool_execution_end` is emitted in tool completion order after each tool is finalized,
* while tool-result message artifacts are emitted later in assistant source order.
*/
export type ToolExecutionMode = "sequential" | "parallel";
/**
* Controls how many queued user messages are injected when the agent loop reaches a queue drain point.
*
* - "all": drain and inject every queued message at that point.
* - "one-at-a-time": drain and inject only the oldest queued message, leaving the rest queued for later drain points.
* A run of consecutive app-defined notices (any role other than user, assistant, toolResult or system)
* is drained together as that oldest entry, so a burst of background events takes one turn.
*/
export type QueueMode = "all" | "one-at-a-time";
/** A single tool call content block emitted by an assistant message. */
export type AgentToolCall = Extract<AssistantMessage["content"][number], { type: "toolCall" }>;
/**
* Result returned from `beforeToolCall`.
*
* Returning `{ block: true }` prevents the tool from executing. The loop emits an error tool result instead.
* `reason` becomes the text shown in that error result. If omitted, a default blocked message is used.
*/
export interface BeforeToolCallResult {
block?: boolean;
reason?: string;
/**
* Hint that the agent should stop after the current tool batch when this call is blocked.
* Early termination only happens when every finalized tool result in the batch sets this to true.
*/
terminate?: boolean;
}
/**
* Partial override returned from `afterToolCall`.
*
* Merge semantics are field-by-field:
* - `content`: if provided, replaces the tool result content array in full
* - `details`: if provided, replaces the tool result details value in full
* - `isError`: if provided, replaces the tool result error flag
* - `usage`: if provided, replaces the tool result usage
* - `terminate`: if provided, replaces the early-termination hint
* - `structuredContent`: if provided, replaces the structured content. If `content` is provided
* without it, the structured content is dropped, because it may no longer match the content.
* Return it along with `content` to keep it.
*
* Other omitted fields keep the original executed tool result values.
* There is no deep merge for `content`, `details`, or `usage`.
*/
export interface AfterToolCallResult {
content?: (TextContent | ImageContent)[];
details?: unknown;
structuredContent?: JsonValue;
isError?: boolean;
/** Usage from the final tool execution itself, if available. Not used for main LLM context accounting. */
usage?: Usage;
/**
* Hint that the agent should stop after the current tool batch.
* Early termination only happens when every finalized tool result in the batch sets this to true.
*/
terminate?: boolean;
}
/** Context passed to `beforeToolCall`. */
export interface BeforeToolCallContext {
/** The assistant message that requested the tool call. */
assistantMessage: AssistantMessage;
/** The raw tool call block from `assistantMessage.content`. */
toolCall: AgentToolCall;
/** Validated tool arguments for the target tool schema. */
args: unknown;
/** Current agent context at the time the tool call is prepared. */
context: AgentContext;
}
/** Context passed to `afterToolCall`. */
export interface AfterToolCallContext {
/** The assistant message that requested the tool call. */
assistantMessage: AssistantMessage;
/** The raw tool call block from `assistantMessage.content`. */
toolCall: AgentToolCall;
/** Validated tool arguments for the target tool schema. */
args: unknown;
/** The executed tool result before any `afterToolCall` overrides are applied. */
result: AgentToolResult<any>;
/** Whether the executed tool result is currently treated as an error. */
isError: boolean;
/** Current agent context at the time the tool call is finalized. */
context: AgentContext;
}
/** Context passed to completed-turn callbacks. */
export interface AgentTurnContext {
/** The assistant message that completed the turn. */
message: AssistantMessage;
/** Tool result messages emitted for the completed turn. */
toolResults: ToolResultMessage[];
/** Current agent context after the turn's assistant message and tool results have been appended. */
context: AgentContext;
/** Messages that this loop invocation will return if it exits at this point. Prompt runs include the initial prompt messages; continuation runs do not include pre-existing context messages. */
newMessages: AgentMessage[];
}
/** Decision returned by {@link FinishTurn}. Returning undefined preserves normal scheduling. */
export type AgentTurnDecision = { action: "continue" } | { action: "end" };
/**
* Called after a completed assistant turn and all of its tool-result messages, but before `turn_end`.
* On a normal turn, `{ action: "continue" }` ensures one next provider request. Tool-result, steering, or
* follow-up scheduling can satisfy that request and adds no extra request; otherwise the loop continues once
* with the current context. Error and aborted responses remain hard exits.
*/
export type FinishTurn = (
turn: AgentTurnContext,
signal?: AbortSignal,
) => AgentTurnDecision | void | Promise<AgentTurnDecision | undefined> | Promise<void>;
/** One model step as the loop finished it: its terminal assistant message and the provider tool results emitted for it. */
export interface StepCommit {
readonly message: AssistantMessage;
readonly providerToolResults: readonly ToolResultMessage[];
}
/**
* Makes one finished model step durable before the loop acts on it. A rejection leaves the loop with no further
* events and no tool dispatch for that step.
*/
export type StepCommitFn = (step: StepCommit) => Promise<void>;
/** Replacement runtime state used by the agent loop before starting another provider request. */
export interface AgentLoopTurnUpdate {
/** Context for the next provider request. */
context?: AgentContext;
/** Messages to append before the next provider request, with normal lifecycle events. */
messages?: AgentMessage[];
/** Model for the next provider request. */
model?: Model<any>;
/** Thinking level for the next provider request. */
thinkingLevel?: ThinkingLevel;
/** Thinking selection for the next provider request: undefined leaves it unchanged, null clears it. */
thinkingSelection?: ThinkingSelection | null;
/** Whether the next provider request should abort a server-selected fallback. */
abortServerSideFallback?: boolean;
}
/** Runtime state available immediately before a conversational provider request. */
export interface PrepareRequestContext {
context: AgentContext;
model: Model<any>;
thinkingLevel: ThinkingLevel;
}
/** Replacement runtime state for the provider request being prepared. */
export type AgentRequestUpdate = Omit<AgentLoopTurnUpdate, "messages">;
/**
* Called immediately before every conversational provider request, including the first.
* Pending messages have already been appended and emitted when this callback runs.
*/
export type PrepareRequest = (
request: PrepareRequestContext,
signal?: AbortSignal,
) => AgentRequestUpdate | void | Promise<AgentRequestUpdate | undefined> | Promise<void>;
export interface PrepareNextTurnContext extends AgentTurnContext {}
export interface AgentLoopConfig extends SimpleStreamOptions {
model: Model<any>;
/**
* Cursor exec-channel tool handlers (cursor-agent models only).
*
* Cursor's server-driven protocol executes tools MID-STREAM: the server
* blocks on an in-band reply, so the provider runs these handlers while
* the Run stream is open, synthesizes already-resolved `toolCall` blocks
* (marked `kCursorExecResolved`, which this loop skips), and buffers each
* paired `ToolResultMessage` for emission right after the assistant
* message. Other providers ignore this field.
*/
cursorExecHandlers?: CursorExecHandlers | ((runSignal: AbortSignal) => CursorExecHandlers);
/**
* Maximum time in milliseconds to wait for the FIRST provider stream event.
* Providers emit their first event only once the HTTP response begins, so a
* dead upstream that accepts the request but never answers is otherwise only
* bounded by `timeoutMs` (the idle timeout, default 5 minutes). After the
* first event arrives, `timeoutMs` governs inter-event idleness as before.
* Unset or non-positive values disable the start bound.
*/
streamStartTimeoutMs?: number;
/**
* Bytes the provider reports through `onTransportActivity` (SSE pings, keep-alive comments) keep the start and
* idle bounds from firing while they keep arriving within one bound. This caps how long keep-alives alone may
* hold a request without any assistant event. Unset or non-positive values leave keep-alives unbounded.
*/
streamKeepAliveTimeoutMs?: number;
/** Provider/SDK timeout override for only the first request in this loop invocation. */
initialRequestTimeoutMs?: number;
/** Stream-start timeout override for only the first request in this loop invocation. */
initialRequestStreamStartTimeoutMs?: number;
/**
* Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
*
* Each AgentMessage must be converted to a SystemMessage, UserMessage, AssistantMessage, or ToolResultMessage
* that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,
* status messages) should be filtered out.
*
* Contract: must not throw or reject. Return a safe fallback value instead.
* Throwing interrupts the low-level agent loop without producing a normal event sequence.
*
* @example
* ```typescript
* convertToLlm: (messages) => messages.flatMap(m => {
* if (m.role === "custom") {
* // Convert custom message to user message
* return [{ role: "user", content: m.content, timestamp: m.timestamp }];
* }
* if (m.role === "notification") {
* // Filter out UI-only messages
* return [];
* }
* // Pass through standard LLM messages
* return [m];
* })
* ```
*/
convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
/**
* Optional transform applied to the context before `convertToLlm`.
*
* Use this for operations that work at the AgentMessage level:
* - Context window management (pruning old messages)
* - Injecting context from external sources
*
* Contract: must not throw or reject. Return the original messages or another
* safe fallback value instead.
*
* @example
* ```typescript
* transformContext: async (messages) => {
* if (estimateTokens(messages) > MAX_TOKENS) {
* return pruneOldMessages(messages);
* }
* return messages;
* }
* ```
*/
transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
/**
* Resolves an API key dynamically for each LLM call.
*
* Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire
* during long-running tool execution phases.
*
* Contract: must not throw or reject. Return undefined when no key is available.
*/
getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
/**
* Called after the assistant message and all tool-result messages have been emitted, immediately before `turn_end`.
* `{ action: "end" }` ends the run without polling queues or preparing another request.
* On a normal turn, `{ action: "continue" }` ensures one next provider request. Tool-result, steering, or
* follow-up scheduling can satisfy that request and adds no extra request; otherwise the loop continues once
* with the current context. Returning undefined preserves normal scheduling. Error and aborted responses remain
* hard exits.
*/
finishTurn?: FinishTurn;
/**
* Called once per model step, after the step's provider tool results are emitted and before the loop decides
* whether the turn ends or dispatches tools; it covers success and terminal-failure messages alike. Unset on
* every local assembly; a hosted brain host sets it to commit the step durably.
*/
commitStep?: StepCommitFn;
/**
* Called immediately before every conversational provider request, including the first.
* Pending messages have already been appended. The returned context, model, and thinking level
* replace the runtime values for this and later requests in the run. This hook does not poll queues.
*/
prepareRequest?: PrepareRequest;
/**
* Called after each completed assistant turn, including a normal stop response, before the loop decides whether another provider request starts.
* A terminating-tool continuation emits its `turn_start` boundary first so queue owners can clear
* or replace pending input before preparation finishes and the continuation is admitted.
* `finishTurn` returning `{ action: "end" }` and an empty terminating tool batch can end the run before preparation.
* Return replacement context/model/thinking state or messages to append to affect the next turn.
* Return undefined to keep using the current context/config.
*/
prepareNextTurn?: (
context: PrepareNextTurnContext,
) => AgentLoopTurnUpdate | undefined | Promise<AgentLoopTurnUpdate | undefined>;
/**
* Returns steering messages to inject into the conversation mid-run.
*
* Called after the current assistant turn finishes executing its tool calls, unless `finishTurn` ends the run.
* If messages are returned, they are added to the context before the next LLM call.
* Tool calls from the current assistant message are not skipped.
*
* Use this for "steering" the agent while it's working.
*
* Contract: must not throw or reject. Return [] when no steering messages are available.
*/
getSteeringMessages?: () => Promise<AgentMessage[]>;
/**
* Returns follow-up messages to process after the agent would otherwise stop.
*
* Called when the agent has no more tool calls and no steering messages.
* If messages are returned, they're added to the context and the agent
* continues with another turn.
*
* Use this for follow-up messages that should wait until the agent finishes.
*
* Contract: must not throw or reject. Return [] when no follow-up messages are available.
*/
getFollowUpMessages?: () => Promise<AgentMessage[]>;
/**
* Restores messages previously returned by a queue callback when next-turn preparation cannot continue.
* Restored messages must be placed before messages queued after the drain.
*/
restorePendingMessages?: (queue: "steering" | "followUp", messages: AgentMessage[]) => Promise<void> | void;
/**
* Called with the queued messages the loop is about to put into the context, after they were drained and
* before any of them is inserted or sent. A rejection keeps them out of this turn (they are restored), so a
* message is never seen by a provider without its consumption committed first (senpi#3549).
*/
commitQueuedConsumption?: (queue: "steering" | "followUp", messages: AgentMessage[]) => Promise<void>;
/**
* Tool execution mode.
* - "sequential": execute tool calls one by one
* - "parallel": preflight tool calls sequentially, then execute allowed tools in concurrent waves;
* per-tool `executionMode: "sequential"` calls act as exclusive barriers,
* emit `tool_execution_end` in tool completion order after each tool is finalized,
* then emit tool-result message artifacts later in assistant source order
*
* Default: "parallel"
*/
toolExecution?: ToolExecutionMode;
/** Unprepared batch boundary. Omitted selects the prepared pipeline (batch coordinator + prepared executor) in this process. */
toolHost?: ToolHost;
/**
* Opens each batch's execution ledger for the default (prepared) pipeline. The loop builds no store itself: with no
* `toolHost` and no factory, a tool batch fails closed with `BatchStoreMissingError`. The package entry's `Agent` and
* `agentLoop` default it to `openMemoryBatchStore`.
*/
batchStoreFactory?: BatchStoreFactory;
/**
* Runs once per call on the prepared pipeline, after the call is frozen and before it executes, with the arguments
* object `beforeToolCall` saw and the frozen copy the tool will receive. A host whose `beforeToolCall` binds facts to
* that object (an approval, a symbol property) moves them here. Synchronous and must not throw. With no `toolHost`
* and no hook, a tool batch fails closed with `PreflightCarryMissingError`; the package entry's `Agent` and
* `agentLoop` default it to `noPreflightCarry` (senpi#5795).
*/
afterToolFreeze?: (prepared: unknown, frozen: unknown) => void;
executionScope?: ExecutionScope;
onExecutionPipeline?: (witness: ExecutionPipelineWitness) => Promise<void> | void;
/**
* Optional migration guidance for tool names intentionally removed by an extension.
* The matching hint is appended to the normal unknown-tool error before hooks run.
*/
removedToolHints?: Record<string, string>;
/**
* Called when a model names a tool absent from the current context snapshot.
* Return a newly available tool to continue normal validation and execution, or
* undefined to emit the existing unknown-tool result. Hosts may use this to
* activate a registered lazy tool at call time.
*/
resolveUnknownToolCall?: (
toolName: string,
context: AgentContext,
) => AgentTool | undefined | Promise<AgentTool | undefined>;
/**
* Called before a tool is executed, after arguments have been validated.
*
* Return `{ block: true }` to prevent execution. The loop emits an error tool result instead.
* A blocked result can also set `terminate: true` to participate in the batch early-termination rule.
* The hook receives the agent abort signal and is responsible for honoring it.
*/
beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
/**
* Called after a tool finishes executing, before `tool_execution_end` and tool-result message events are emitted.
*
* Return an `AfterToolCallResult` to override parts of the executed tool result:
* - `content` replaces the full content array
* - `details` replaces the full details payload
* - `isError` replaces the error flag
* - `usage` replaces the tool result usage
* - `terminate` replaces the early-termination hint
*
* Any omitted fields keep their original values. No deep merge is performed.
* The hook receives the agent abort signal and is responsible for honoring it.
*/
afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
}
/**
* Thinking/reasoning level for models that support it.
* Note: "xhigh" and "max" are only supported by selected model families. Use model
* thinking-level metadata from @earendil-works/pi-ai to detect support for a concrete model.
*/
export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
/**
* Extensible interface for custom app messages.
* Apps can extend via declaration merging:
*
* @example
* ```typescript
* declare module "@earendil-works/pi-agent-core" {
* interface CustomAgentMessages {
* artifact: ArtifactMessage;
* notification: NotificationMessage;
* }
* }
* ```
*/
export interface CustomAgentMessages {
// Empty by default - apps extend via declaration merging
}
/**
* AgentMessage: Union of LLM messages + custom messages.
* This abstraction allows apps to add custom message types while maintaining
* type safety and compatibility with the base LLM messages.
*/
export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
/**
* Public agent state.
*
* `tools` and `messages` use accessor properties so implementations can copy
* assigned arrays before storing them.
*/
export interface AgentState {
/**
* Base system prompt sent with each model request (fork: assignable; the loop folds it into the
* leading system message through `normalizeContext()`). Later transcript system messages with
* `content` or `sections` still apply on top of it.
*/
systemPrompt: string;
/**
* Leading part of `systemPrompt` that is the same across sessions; see
* {@link AgentContext.systemPromptStablePrefix} (senpi#4447).
*/
systemPromptStablePrefix?: string;
/** Active model used for future turns. */
model: Model<any>;
/** Requested reasoning level for future turns. */
thinkingLevel: ThinkingLevel;
/**
* Provenance-bearing thinking selection, when the user or a legacy variant
* alias explicitly chose a level. Absent for defaulted effective levels.
*/
thinkingSelection?: ThinkingSelection;
/** First reasoning effort on the branch, used to preserve Responses cache prefixes. */
reasoningBaseline?: string;
/**
* Executable tools. Assigning a new array copies the top-level array.
*
* Differences from the tools declared in the transcript are announced to the model
* with a system message before the next request.
*/
set tools(tools: AgentTool<any>[]);
get tools(): AgentTool<any>[];
/** Tool list the provider receives when it differs from `tools`; see {@link AgentContext.declaredTools}. */
declaredTools?: AgentTool<any>[];
/**
* Conversation transcript. Assigning a new array copies the top-level array.
*
* System messages in the transcript carry the prompt and tool declarations.
*/
set messages(messages: AgentMessage[]);
get messages(): AgentMessage[];
/**
* True while the agent is processing a prompt or continuation.
*
* This remains true until awaited `agent_end` listeners settle.
*/
readonly isStreaming: boolean;
/** Partial assistant message for the current streamed response, if any. */
readonly streamingMessage?: AgentMessage;
/** Tool call ids currently executing. */
readonly pendingToolCalls: ReadonlySet<string>;
/** Error message from the most recent failed or aborted assistant turn, if any. */
readonly errorMessage?: string;
/** Structured provider failure family of the turn that set `errorMessage`, when its provider adapter supplied one. */
readonly providerDiagnostic?: ProviderDiagnostic;
}
/** Final or partial result produced by a tool. */
export interface AgentToolResult<T = JsonValue | undefined> {
/** Text or image content returned to the model. */
content: (TextContent | ImageContent)[];
/** Arbitrary structured details for logs or UI rendering. */
details: T;
/**
* Machine-readable result matching the tool's `outputSchema`, for programmatic callers. Not sent
* to the model; `content` remains the model-facing result.
*/
structuredContent?: JsonValue;
/** Usage from the final tool execution itself, if available. Not used for main LLM context accounting. */
usage?: Usage;
/**
* Report a failure without throwing. The model sees `content` as an error result, like a thrown
* error, but `details` and `structuredContent` are kept for the UI and programmatic callers.
*/
isError?: boolean;
/**
* Hint that the agent should stop after the current tool batch.
* Early termination only happens when every finalized tool result in the batch sets this to true.
*/
terminate?: boolean;
/**
* Names of tools introduced by this result and available from this transcript point onward
* (fork lazy-tool activation and tool-search native deferred loading).
*/
addedToolNames?: string[];
}
/** Final outcome of a tool call after hooks ran. */
export interface AgentToolCallOutcome {
toolCall: AgentToolCall;
result: AgentToolResult<any>;
isError: boolean;
}
/**
* Callback used by tools to stream partial execution updates.
*
* The callback is scoped to the current `execute()` invocation. Calls made after
* the tool promise settles are ignored.
*/
export type AgentToolUpdateCallback<T = any> = (partialResult: AgentToolResult<T>) => void;
/** Tool definition used by the agent runtime. */
export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
/** Human-readable label for UI display. */
label: string;
/**
* Optional compatibility shim for raw tool-call arguments before schema validation.
* Must return an object that matches `TParameters`.
*/
prepareArguments?: (args: unknown) => Static<TParameters>;
/**
* JSON Schema of `structuredContent` in successful results. Tools that declare it should always
* set `structuredContent`.
*/
outputSchema?: TSchema;
/**
* Execute the tool call. Throw on failure, or return a result with `isError: true`; do not only
* describe the failure in `content`.
*/
execute: (
toolCallId: string,
params: Static<TParameters>,
signal?: AbortSignal,
onUpdate?: AgentToolUpdateCallback<TDetails>,
) => Promise<AgentToolResult<TDetails>>;
/** Recovery policy for an effect whose durable intent exists but whose outcome is unknown. */
replay?: "never" | "safe";
/**
* Per-tool execution mode override.
* - "sequential": this tool acts as an exclusive barrier in parallel batches.
* - "parallel": this tool can execute concurrently with other tool calls.
*
* If omitted, the default execution mode applies.
*/
executionMode?: ToolExecutionMode;
}
/** Context snapshot passed into the low-level agent loop. */
export interface AgentContext {
/**
* Fork shorthand for the leading system message; `buildProviderContext` folds it with
* `normalizeContext()`. Upstream-built contexts carry the prompt in transcript system messages.
*/
systemPrompt?: string;
/**
* Leading part of `systemPrompt` that is the same across sessions, followed by content that is not
* (memory, MCP instructions). Providers with block-level prompt caching put the system breakpoint at
* its end so another session can read it from cache. Ignored unless `systemPrompt` starts with it
* (senpi#4447).
*/
systemPromptStablePrefix?: string;
/** Transcript visible to the model. */
messages: AgentMessage[];
/** Tools available for execution in this run. */
tools?: AgentTool<any>[];
/**
* Superset of `tools` to declare to the provider, keeping the tool prefix byte-stable while the
* callable set changes (senpi#2095). Honored only for models that accept an allowed-tools
* restriction; tool calls still resolve against `tools` alone.
*/
declaredTools?: AgentTool<any>[];
}
/**
* Events emitted by the Agent for UI updates.
*
* `agent_end` is the last event emitted for a run, but awaited `Agent.subscribe()`
* listeners for that event are still part of run settlement. The agent becomes
* idle only after those listeners finish.
*/
export type AgentEvent =
// Agent lifecycle
| { type: "agent_start" }
| { type: "agent_end"; messages: AgentMessage[] }
// Turn lifecycle - a turn is one assistant response + any tool calls/results
| { type: "turn_start" }
| { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
// Message lifecycle - emitted for system, user, assistant, and toolResult messages
| { type: "message_start"; message: AgentMessage; streaming?: true }
// Only emitted for assistant messages during streaming
| { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
| { type: "message_end"; message: AgentMessage }
// Tool execution lifecycle
| { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
| { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
| { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };