zeitlich 0.2.13 → 0.2.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +49 -38
- package/dist/adapters/sandbox/daytona/index.cjs +205 -0
- package/dist/adapters/sandbox/daytona/index.cjs.map +1 -0
- package/dist/adapters/sandbox/daytona/index.d.cts +86 -0
- package/dist/adapters/sandbox/daytona/index.d.ts +86 -0
- package/dist/adapters/sandbox/daytona/index.js +202 -0
- package/dist/adapters/sandbox/daytona/index.js.map +1 -0
- package/dist/adapters/sandbox/inmemory/index.cjs +174 -0
- package/dist/adapters/sandbox/inmemory/index.cjs.map +1 -0
- package/dist/adapters/sandbox/inmemory/index.d.cts +28 -0
- package/dist/adapters/sandbox/inmemory/index.d.ts +28 -0
- package/dist/adapters/sandbox/inmemory/index.js +172 -0
- package/dist/adapters/sandbox/inmemory/index.js.map +1 -0
- package/dist/adapters/sandbox/virtual/index.cjs +405 -0
- package/dist/adapters/sandbox/virtual/index.cjs.map +1 -0
- package/dist/adapters/sandbox/virtual/index.d.cts +85 -0
- package/dist/adapters/sandbox/virtual/index.d.ts +85 -0
- package/dist/adapters/sandbox/virtual/index.js +400 -0
- package/dist/adapters/sandbox/virtual/index.js.map +1 -0
- package/dist/adapters/thread/google-genai/index.cjs +284 -0
- package/dist/adapters/thread/google-genai/index.cjs.map +1 -0
- package/dist/adapters/thread/google-genai/index.d.cts +145 -0
- package/dist/adapters/thread/google-genai/index.d.ts +145 -0
- package/dist/adapters/thread/google-genai/index.js +278 -0
- package/dist/adapters/thread/google-genai/index.js.map +1 -0
- package/dist/adapters/{langchain → thread/langchain}/index.cjs +7 -9
- package/dist/adapters/thread/langchain/index.cjs.map +1 -0
- package/dist/adapters/{langchain → thread/langchain}/index.d.cts +17 -21
- package/dist/adapters/{langchain → thread/langchain}/index.d.ts +17 -21
- package/dist/adapters/{langchain → thread/langchain}/index.js +7 -9
- package/dist/adapters/thread/langchain/index.js.map +1 -0
- package/dist/index.cjs +816 -545
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +235 -74
- package/dist/index.d.ts +235 -74
- package/dist/index.js +804 -540
- package/dist/index.js.map +1 -1
- package/dist/types-B4C9txdq.d.ts +389 -0
- package/dist/{thread-manager-qc0g5Rvd.d.cts → types-B9ljZewB.d.cts} +1 -6
- package/dist/{thread-manager-qc0g5Rvd.d.ts → types-B9ljZewB.d.ts} +1 -6
- package/dist/types-BMXzv7TN.d.cts +476 -0
- package/dist/types-BMXzv7TN.d.ts +476 -0
- package/dist/types-BVP87m_W.d.cts +121 -0
- package/dist/types-CDubRtad.d.cts +115 -0
- package/dist/types-CDubRtad.d.ts +115 -0
- package/dist/types-CwwgQ_9H.d.ts +121 -0
- package/dist/types-GpMU4b0w.d.cts +389 -0
- package/dist/workflow.cjs +444 -318
- package/dist/workflow.cjs.map +1 -1
- package/dist/workflow.d.cts +271 -222
- package/dist/workflow.d.ts +271 -222
- package/dist/workflow.js +440 -316
- package/dist/workflow.js.map +1 -1
- package/package.json +59 -6
- package/src/adapters/sandbox/daytona/filesystem.ts +136 -0
- package/src/adapters/sandbox/daytona/index.ts +149 -0
- package/src/adapters/sandbox/daytona/types.ts +34 -0
- package/src/adapters/sandbox/inmemory/index.ts +213 -0
- package/src/adapters/sandbox/virtual/filesystem.ts +345 -0
- package/src/adapters/sandbox/virtual/index.ts +88 -0
- package/src/adapters/sandbox/virtual/mutations.ts +38 -0
- package/src/adapters/sandbox/virtual/provider.ts +101 -0
- package/src/adapters/sandbox/virtual/tree.ts +82 -0
- package/src/adapters/sandbox/virtual/types.ts +127 -0
- package/src/adapters/sandbox/virtual/virtual-sandbox.test.ts +523 -0
- package/src/adapters/sandbox/virtual/with-virtual-sandbox.ts +91 -0
- package/src/adapters/thread/google-genai/activities.ts +121 -0
- package/src/adapters/thread/google-genai/index.ts +41 -0
- package/src/adapters/thread/google-genai/model-invoker.ts +154 -0
- package/src/adapters/thread/google-genai/thread-manager.ts +169 -0
- package/src/adapters/{langchain → thread/langchain}/activities.ts +11 -15
- package/src/adapters/{langchain → thread/langchain}/index.ts +1 -1
- package/src/adapters/{langchain → thread/langchain}/model-invoker.ts +15 -18
- package/src/adapters/{langchain → thread/langchain}/thread-manager.ts +1 -1
- package/src/index.ts +32 -24
- package/src/lib/activity.ts +87 -0
- package/src/lib/hooks/index.ts +11 -0
- package/src/lib/hooks/types.ts +98 -0
- package/src/lib/model/helpers.ts +6 -0
- package/src/lib/model/index.ts +13 -0
- package/src/lib/{model-invoker.ts → model/types.ts} +18 -1
- package/src/lib/sandbox/index.ts +19 -0
- package/src/lib/sandbox/manager.ts +76 -0
- package/src/lib/sandbox/sandbox.test.ts +158 -0
- package/src/lib/{fs.ts → sandbox/tree.ts} +6 -6
- package/src/lib/sandbox/types.ts +164 -0
- package/src/lib/session/index.ts +11 -0
- package/src/lib/{session.ts → session/session.ts} +76 -48
- package/src/lib/session/types.ts +93 -0
- package/src/lib/skills/fs-provider.ts +16 -15
- package/src/lib/skills/handler.ts +31 -0
- package/src/lib/skills/index.ts +5 -1
- package/src/lib/skills/register.ts +20 -0
- package/src/lib/skills/tool.ts +47 -0
- package/src/lib/state/index.ts +9 -0
- package/src/lib/{state-manager.ts → state/manager.ts} +10 -147
- package/src/lib/state/types.ts +134 -0
- package/src/lib/subagent/define.ts +71 -0
- package/src/lib/subagent/handler.ts +99 -0
- package/src/lib/subagent/index.ts +13 -0
- package/src/lib/subagent/register.ts +53 -0
- package/src/lib/subagent/tool.ts +80 -0
- package/src/lib/subagent/types.ts +92 -0
- package/src/lib/thread/index.ts +7 -0
- package/src/lib/{thread-manager.ts → thread/manager.ts} +1 -33
- package/src/lib/thread/types.ts +33 -0
- package/src/lib/tool-router/auto-append.ts +55 -0
- package/src/lib/tool-router/index.ts +41 -0
- package/src/lib/tool-router/router.ts +462 -0
- package/src/lib/tool-router/types.ts +478 -0
- package/src/lib/tool-router/with-sandbox.ts +70 -0
- package/src/lib/types.ts +5 -382
- package/src/tools/bash/bash.test.ts +53 -55
- package/src/tools/bash/handler.ts +23 -51
- package/src/tools/edit/handler.ts +67 -81
- package/src/tools/glob/handler.ts +60 -17
- package/src/tools/read-file/handler.ts +67 -0
- package/src/tools/read-skill/handler.ts +1 -31
- package/src/tools/read-skill/tool.ts +5 -47
- package/src/tools/subagent/handler.ts +1 -100
- package/src/tools/subagent/tool.ts +5 -93
- package/src/tools/task-create/handler.ts +1 -1
- package/src/tools/task-get/handler.ts +1 -1
- package/src/tools/task-list/handler.ts +1 -1
- package/src/tools/task-update/handler.ts +1 -1
- package/src/tools/write-file/handler.ts +47 -0
- package/src/workflow.ts +88 -47
- package/tsup.config.ts +8 -1
- package/dist/adapters/langchain/index.cjs.map +0 -1
- package/dist/adapters/langchain/index.js.map +0 -1
- package/dist/model-invoker-y_zlyMqu.d.cts +0 -892
- package/dist/model-invoker-y_zlyMqu.d.ts +0 -892
- package/src/lib/tool-router.ts +0 -977
- package/src/lib/workflow-helpers.ts +0 -50
- /package/src/lib/{thread-id.ts → thread/id.ts} +0 -0
|
@@ -0,0 +1,476 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
/** A single content part within a structured message (text, image, etc.) */
|
|
4
|
+
type ContentPart = {
|
|
5
|
+
type: string;
|
|
6
|
+
[key: string]: unknown;
|
|
7
|
+
};
|
|
8
|
+
/** Message content — plain string or an array of structured content parts */
|
|
9
|
+
type MessageContent = string | ContentPart[];
|
|
10
|
+
/** Content returned by a tool handler */
|
|
11
|
+
type ToolMessageContent = MessageContent;
|
|
12
|
+
/**
|
|
13
|
+
* Agent execution status
|
|
14
|
+
*/
|
|
15
|
+
type AgentStatus = "RUNNING" | "WAITING_FOR_INPUT" | "COMPLETED" | "FAILED" | "CANCELLED";
|
|
16
|
+
/**
|
|
17
|
+
* Base state that all agents must have
|
|
18
|
+
*/
|
|
19
|
+
interface BaseAgentState {
|
|
20
|
+
tools: SerializableToolDefinition[];
|
|
21
|
+
status: AgentStatus;
|
|
22
|
+
version: number;
|
|
23
|
+
turns: number;
|
|
24
|
+
tasks: Map<string, WorkflowTask>;
|
|
25
|
+
systemPrompt?: string;
|
|
26
|
+
totalInputTokens: number;
|
|
27
|
+
totalOutputTokens: number;
|
|
28
|
+
cachedWriteTokens: number;
|
|
29
|
+
cachedReadTokens: number;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* File representation for agent workflows
|
|
33
|
+
*/
|
|
34
|
+
interface AgentFile {
|
|
35
|
+
/** Database/S3 file ID */
|
|
36
|
+
id: string;
|
|
37
|
+
/** Virtual path for agent (e.g., "evidence/invoice.pdf") */
|
|
38
|
+
path: string;
|
|
39
|
+
/** Original filename */
|
|
40
|
+
filename: string;
|
|
41
|
+
/** Generic description for prompt */
|
|
42
|
+
description?: string;
|
|
43
|
+
/** MIME type of the file */
|
|
44
|
+
mimeType?: string;
|
|
45
|
+
}
|
|
46
|
+
interface TokenUsage {
|
|
47
|
+
inputTokens?: number;
|
|
48
|
+
outputTokens?: number;
|
|
49
|
+
cachedWriteTokens?: number;
|
|
50
|
+
cachedReadTokens?: number;
|
|
51
|
+
reasonTokens?: number;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Configuration for a Zeitlich agent
|
|
55
|
+
*/
|
|
56
|
+
interface AgentConfig {
|
|
57
|
+
/** The name of the agent, should be unique within the workflows, ideally Pascal Case */
|
|
58
|
+
agentName: string;
|
|
59
|
+
/** Description, used for sub agents */
|
|
60
|
+
description?: string;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* A JSON-serializable tool definition for state storage.
|
|
64
|
+
* Uses a plain JSON Schema object instead of a live Zod instance,
|
|
65
|
+
* so it survives Temporal serialization without losing constraints (min, max, etc.).
|
|
66
|
+
*/
|
|
67
|
+
interface SerializableToolDefinition {
|
|
68
|
+
name: string;
|
|
69
|
+
description: string;
|
|
70
|
+
schema: Record<string, unknown>;
|
|
71
|
+
strict?: boolean;
|
|
72
|
+
max_uses?: number;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Configuration passed to runAgent activity
|
|
76
|
+
*/
|
|
77
|
+
interface RunAgentConfig extends AgentConfig {
|
|
78
|
+
/** The thread ID to use for the session */
|
|
79
|
+
threadId: string;
|
|
80
|
+
/** Metadata for the session */
|
|
81
|
+
metadata?: Record<string, unknown>;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Configuration for appending a tool result
|
|
85
|
+
*/
|
|
86
|
+
interface ToolResultConfig {
|
|
87
|
+
threadId: string;
|
|
88
|
+
toolCallId: string;
|
|
89
|
+
/** The name of the tool that produced this result */
|
|
90
|
+
toolName: string;
|
|
91
|
+
/** Content for the tool message (string or complex content parts) */
|
|
92
|
+
content: ToolMessageContent;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Status of a workflow task
|
|
96
|
+
*/
|
|
97
|
+
type TaskStatus = "pending" | "in_progress" | "completed";
|
|
98
|
+
/**
|
|
99
|
+
* A task managed within a workflow for tracking work items
|
|
100
|
+
*/
|
|
101
|
+
interface WorkflowTask {
|
|
102
|
+
/** Unique task identifier */
|
|
103
|
+
id: string;
|
|
104
|
+
/** Brief, actionable title in imperative form */
|
|
105
|
+
subject: string;
|
|
106
|
+
/** Detailed description of what needs to be done */
|
|
107
|
+
description: string;
|
|
108
|
+
/** Present continuous form shown in spinner when in_progress */
|
|
109
|
+
activeForm: string;
|
|
110
|
+
/** Current status of the task */
|
|
111
|
+
status: TaskStatus;
|
|
112
|
+
/** Arbitrary key-value pairs for tracking */
|
|
113
|
+
metadata: Record<string, string>;
|
|
114
|
+
/** IDs of tasks that must complete before this one can start */
|
|
115
|
+
blockedBy: string[];
|
|
116
|
+
/** IDs of tasks that are waiting for this one to complete */
|
|
117
|
+
blocks: string[];
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Exit reasons for session termination
|
|
121
|
+
*/
|
|
122
|
+
type SessionExitReason = "completed" | "max_turns" | "waiting_for_input" | "failed" | "cancelled";
|
|
123
|
+
/**
|
|
124
|
+
* Helper to check if status is terminal
|
|
125
|
+
*/
|
|
126
|
+
declare function isTerminalStatus(status: AgentStatus): boolean;
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* A tool definition with a name, description, and Zod schema for arguments.
|
|
130
|
+
* Does not include a handler - use ToolWithHandler for tools with handlers.
|
|
131
|
+
*/
|
|
132
|
+
interface ToolDefinition<TName extends string = string, TSchema extends z.ZodType = z.ZodType> {
|
|
133
|
+
name: TName;
|
|
134
|
+
description: string;
|
|
135
|
+
schema: TSchema;
|
|
136
|
+
strict?: boolean;
|
|
137
|
+
max_uses?: number;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* A tool definition with an integrated handler function.
|
|
141
|
+
* This is the primary type for defining tools in the router.
|
|
142
|
+
*/
|
|
143
|
+
interface ToolWithHandler<TName extends string = string, TSchema extends z.ZodType = z.ZodType, TResult = unknown, TContext extends RouterContext = RouterContext> {
|
|
144
|
+
name: TName;
|
|
145
|
+
description: string;
|
|
146
|
+
schema: TSchema;
|
|
147
|
+
handler: ToolHandler<z.infer<TSchema>, TResult, TContext>;
|
|
148
|
+
strict?: boolean;
|
|
149
|
+
max_uses?: number;
|
|
150
|
+
/** Whether this tool is available to the agent (default: true). Disabled tools are excluded from definitions and rejected at parse time. */
|
|
151
|
+
enabled?: boolean;
|
|
152
|
+
/** Per-tool lifecycle hooks (run in addition to global hooks) */
|
|
153
|
+
hooks?: ToolHooks<z.infer<TSchema>, TResult>;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* A map of tool keys to tool definitions with handlers.
|
|
157
|
+
*
|
|
158
|
+
* Handler uses `any` intentionally — this is a type-system boundary where heterogeneous
|
|
159
|
+
* tool types are stored together. Type safety for individual tools is enforced by
|
|
160
|
+
* `defineTool()` at the definition site and generic inference utilities like
|
|
161
|
+
* `InferToolResults<T>` at the consumption site.
|
|
162
|
+
*/
|
|
163
|
+
type ToolMap = Record<string, {
|
|
164
|
+
name: string;
|
|
165
|
+
description: string;
|
|
166
|
+
schema: z.ZodType;
|
|
167
|
+
handler: ToolHandler<any, any, any>;
|
|
168
|
+
strict?: boolean;
|
|
169
|
+
max_uses?: number;
|
|
170
|
+
enabled?: boolean;
|
|
171
|
+
hooks?: ToolHooks<any, any>;
|
|
172
|
+
}>;
|
|
173
|
+
/**
|
|
174
|
+
* Extract the tool names from a tool map (uses the tool's name property, not the key).
|
|
175
|
+
*/
|
|
176
|
+
type ToolNames<T extends ToolMap> = T[keyof T]["name"];
|
|
177
|
+
/**
|
|
178
|
+
* A raw tool call as received from the LLM before parsing.
|
|
179
|
+
*/
|
|
180
|
+
interface RawToolCall {
|
|
181
|
+
id?: string;
|
|
182
|
+
name: string;
|
|
183
|
+
args: unknown;
|
|
184
|
+
}
|
|
185
|
+
/**
|
|
186
|
+
* A parsed tool call with validated arguments for a specific tool.
|
|
187
|
+
*/
|
|
188
|
+
interface ParsedToolCall<TName extends string = string, TArgs = unknown> {
|
|
189
|
+
id: string;
|
|
190
|
+
name: TName;
|
|
191
|
+
args: TArgs;
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Union type of all possible parsed tool calls from a tool map.
|
|
195
|
+
*/
|
|
196
|
+
type ParsedToolCallUnion<T extends ToolMap> = {
|
|
197
|
+
[K in keyof T]: ParsedToolCall<T[K]["name"], z.infer<T[K]["schema"]>>;
|
|
198
|
+
}[keyof T];
|
|
199
|
+
/**
|
|
200
|
+
* Function signature for appending tool results to a thread.
|
|
201
|
+
*/
|
|
202
|
+
type AppendToolResultFn = (config: ToolResultConfig) => Promise<void>;
|
|
203
|
+
/**
|
|
204
|
+
* The response from a tool handler.
|
|
205
|
+
* Contains the content for the tool message and the result to return from processToolCalls.
|
|
206
|
+
*
|
|
207
|
+
* Tools that don't return additional data should use `data: null` (TResult defaults to null).
|
|
208
|
+
* Tools that may fail to produce data should type TResult as `SomeType | null`.
|
|
209
|
+
*/
|
|
210
|
+
interface ToolHandlerResponse<TResult = null> {
|
|
211
|
+
/** Content sent back to the LLM as the tool call response */
|
|
212
|
+
toolResponse: ToolMessageContent;
|
|
213
|
+
/** Data returned to the workflow and hooks for further processing */
|
|
214
|
+
data: TResult;
|
|
215
|
+
/**
|
|
216
|
+
* When true, the tool result has already been appended to the thread
|
|
217
|
+
* by the handler itself (e.g. via `withAutoAppend`), so the router
|
|
218
|
+
* will skip the `appendToolResult` call. This avoids sending large
|
|
219
|
+
* payloads through Temporal's activity payload limit.
|
|
220
|
+
*/
|
|
221
|
+
resultAppended?: boolean;
|
|
222
|
+
/** Token usage from the tool execution (e.g. child agent invocations) */
|
|
223
|
+
usage?: TokenUsage;
|
|
224
|
+
/** Thread ID used by the handler (surfaced to the LLM for subagent thread continuation) */
|
|
225
|
+
threadId?: string;
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Base context the router always injects into every handler invocation.
|
|
229
|
+
* Handlers can rely on these fields being present without casting.
|
|
230
|
+
*/
|
|
231
|
+
interface RouterContext {
|
|
232
|
+
threadId: string;
|
|
233
|
+
toolCallId: string;
|
|
234
|
+
toolName: string;
|
|
235
|
+
sandboxId?: string;
|
|
236
|
+
}
|
|
237
|
+
/**
|
|
238
|
+
* A handler function for a specific tool.
|
|
239
|
+
* Receives the parsed args and a context that always includes {@link RouterContext}
|
|
240
|
+
* fields, plus any additional properties when TContext extends RouterContext.
|
|
241
|
+
*/
|
|
242
|
+
type ToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext> = (args: TArgs, context: TContext) => ToolHandlerResponse<TResult> | Promise<ToolHandlerResponse<TResult>>;
|
|
243
|
+
/**
|
|
244
|
+
* Activity-compatible tool handler that always returns a Promise.
|
|
245
|
+
* Use this for tool handlers registered as Temporal activities.
|
|
246
|
+
*
|
|
247
|
+
* @example
|
|
248
|
+
* ```typescript
|
|
249
|
+
* const readHandler: ActivityToolHandler<
|
|
250
|
+
* FileReadArgs,
|
|
251
|
+
* ReadResult,
|
|
252
|
+
* RouterContext & { scopedNodes: FileNode[]; provider: FileSystemProvider }
|
|
253
|
+
* > = async (args, context) => {
|
|
254
|
+
* // context.threadId, context.sandboxId etc. are always available
|
|
255
|
+
* return readHandler(args, context.scopedNodes, context.provider);
|
|
256
|
+
* };
|
|
257
|
+
* ```
|
|
258
|
+
*/
|
|
259
|
+
type ActivityToolHandler<TArgs, TResult, TContext extends RouterContext = RouterContext> = (args: TArgs, context: TContext) => Promise<ToolHandlerResponse<TResult>>;
|
|
260
|
+
/**
|
|
261
|
+
* Extract the args type for a specific tool name from a tool map.
|
|
262
|
+
*/
|
|
263
|
+
type ToolArgs<T extends ToolMap, TName extends ToolNames<T>> = z.infer<Extract<T[keyof T], {
|
|
264
|
+
name: TName;
|
|
265
|
+
}>["schema"]>;
|
|
266
|
+
/**
|
|
267
|
+
* Extract the result type for a specific tool name from a tool map.
|
|
268
|
+
*/
|
|
269
|
+
type ToolResult<T extends ToolMap, TName extends ToolNames<T>> = Extract<T[keyof T], {
|
|
270
|
+
name: TName;
|
|
271
|
+
}>["handler"] extends ToolHandler<unknown, infer R, RouterContext> ? Awaited<R> : never;
|
|
272
|
+
/**
|
|
273
|
+
* The result of processing a tool call.
|
|
274
|
+
*/
|
|
275
|
+
interface ToolCallResult<TName extends string = string, TResult = unknown> {
|
|
276
|
+
toolCallId: string;
|
|
277
|
+
name: TName;
|
|
278
|
+
data: TResult;
|
|
279
|
+
usage?: TokenUsage;
|
|
280
|
+
}
|
|
281
|
+
/**
|
|
282
|
+
* Infer result types from a tool map based on handler return types.
|
|
283
|
+
*/
|
|
284
|
+
type InferToolResults<T extends ToolMap> = {
|
|
285
|
+
[K in keyof T as T[K]["name"]]: T[K]["handler"] extends ToolHandler<any, infer R, any> ? Awaited<R> : never;
|
|
286
|
+
};
|
|
287
|
+
/**
|
|
288
|
+
* Union of all possible tool call results based on handler return types.
|
|
289
|
+
*/
|
|
290
|
+
type ToolCallResultUnion<TResults extends Record<string, unknown>> = {
|
|
291
|
+
[TName in keyof TResults & string]: ToolCallResult<TName, TResults[TName]>;
|
|
292
|
+
}[keyof TResults & string];
|
|
293
|
+
/**
|
|
294
|
+
* Context passed to processToolCalls for hook execution and handler invocation
|
|
295
|
+
*/
|
|
296
|
+
interface ProcessToolCallsContext {
|
|
297
|
+
/** Current turn number (for hooks) */
|
|
298
|
+
turn?: number;
|
|
299
|
+
/** Active sandbox ID (when a sandbox is configured for this session) */
|
|
300
|
+
sandboxId?: string;
|
|
301
|
+
}
|
|
302
|
+
/**
|
|
303
|
+
* Result from PreToolUse hook - can block or modify execution
|
|
304
|
+
*/
|
|
305
|
+
interface PreToolUseHookResult {
|
|
306
|
+
/** Skip this tool call entirely */
|
|
307
|
+
skip?: boolean;
|
|
308
|
+
/** Modified args to use instead (must match schema) */
|
|
309
|
+
modifiedArgs?: unknown;
|
|
310
|
+
}
|
|
311
|
+
/**
|
|
312
|
+
* Result from PostToolUseFailure hook - can recover from errors
|
|
313
|
+
*/
|
|
314
|
+
interface PostToolUseFailureHookResult {
|
|
315
|
+
/** Provide a fallback result instead of throwing */
|
|
316
|
+
fallbackContent?: ToolMessageContent;
|
|
317
|
+
/** Whether to suppress the error (still logs, but continues) */
|
|
318
|
+
suppress?: boolean;
|
|
319
|
+
}
|
|
320
|
+
/**
|
|
321
|
+
* Per-tool lifecycle hooks - defined directly on a tool definition.
|
|
322
|
+
* Runs in addition to global hooks (global pre → tool pre → execute → tool post → global post).
|
|
323
|
+
*/
|
|
324
|
+
interface ToolHooks<TArgs = unknown, TResult = unknown> {
|
|
325
|
+
/** Called before this tool executes - can skip or modify args */
|
|
326
|
+
onPreToolUse?: (ctx: {
|
|
327
|
+
args: TArgs;
|
|
328
|
+
threadId: string;
|
|
329
|
+
turn: number;
|
|
330
|
+
}) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
|
|
331
|
+
/** Called after this tool executes successfully */
|
|
332
|
+
onPostToolUse?: (ctx: {
|
|
333
|
+
args: TArgs;
|
|
334
|
+
result: TResult;
|
|
335
|
+
threadId: string;
|
|
336
|
+
turn: number;
|
|
337
|
+
durationMs: number;
|
|
338
|
+
}) => void | Promise<void>;
|
|
339
|
+
/** Called when this tool execution fails */
|
|
340
|
+
onPostToolUseFailure?: (ctx: {
|
|
341
|
+
args: TArgs;
|
|
342
|
+
error: Error;
|
|
343
|
+
threadId: string;
|
|
344
|
+
turn: number;
|
|
345
|
+
}) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
|
|
346
|
+
}
|
|
347
|
+
/**
|
|
348
|
+
* Context for PreToolUse hook - called before tool execution
|
|
349
|
+
*/
|
|
350
|
+
interface PreToolUseHookContext<T extends ToolMap> {
|
|
351
|
+
/** The tool call about to be executed */
|
|
352
|
+
toolCall: ParsedToolCallUnion<T>;
|
|
353
|
+
/** Thread identifier */
|
|
354
|
+
threadId: string;
|
|
355
|
+
/** Current turn number */
|
|
356
|
+
turn: number;
|
|
357
|
+
}
|
|
358
|
+
/**
|
|
359
|
+
* PreToolUse hook - called before tool execution, can block or modify
|
|
360
|
+
*/
|
|
361
|
+
type PreToolUseHook<T extends ToolMap> = (ctx: PreToolUseHookContext<T>) => PreToolUseHookResult | Promise<PreToolUseHookResult>;
|
|
362
|
+
/**
|
|
363
|
+
* Context for PostToolUse hook - called after successful tool execution
|
|
364
|
+
*/
|
|
365
|
+
interface PostToolUseHookContext<T extends ToolMap, TResult = unknown> {
|
|
366
|
+
/** The tool call that was executed */
|
|
367
|
+
toolCall: ParsedToolCallUnion<T>;
|
|
368
|
+
/** The result from the tool handler */
|
|
369
|
+
result: TResult;
|
|
370
|
+
/** Thread identifier */
|
|
371
|
+
threadId: string;
|
|
372
|
+
/** Current turn number */
|
|
373
|
+
turn: number;
|
|
374
|
+
/** Execution duration in milliseconds */
|
|
375
|
+
durationMs: number;
|
|
376
|
+
}
|
|
377
|
+
/**
|
|
378
|
+
* PostToolUse hook - called after successful tool execution
|
|
379
|
+
*/
|
|
380
|
+
type PostToolUseHook<T extends ToolMap, TResult = unknown> = (ctx: PostToolUseHookContext<T, TResult>) => void | Promise<void>;
|
|
381
|
+
/**
|
|
382
|
+
* Context for PostToolUseFailure hook - called when tool execution fails
|
|
383
|
+
*/
|
|
384
|
+
interface PostToolUseFailureHookContext<T extends ToolMap> {
|
|
385
|
+
/** The tool call that failed */
|
|
386
|
+
toolCall: ParsedToolCallUnion<T>;
|
|
387
|
+
/** The error that occurred */
|
|
388
|
+
error: Error;
|
|
389
|
+
/** Thread identifier */
|
|
390
|
+
threadId: string;
|
|
391
|
+
/** Current turn number */
|
|
392
|
+
turn: number;
|
|
393
|
+
}
|
|
394
|
+
/**
|
|
395
|
+
* PostToolUseFailure hook - called when tool execution fails
|
|
396
|
+
*/
|
|
397
|
+
type PostToolUseFailureHook<T extends ToolMap> = (ctx: PostToolUseFailureHookContext<T>) => PostToolUseFailureHookResult | Promise<PostToolUseFailureHookResult>;
|
|
398
|
+
/**
|
|
399
|
+
* Tool execution hooks — the subset of hooks consumed by the tool router.
|
|
400
|
+
* Session/message lifecycle hooks live in lib/hooks/types.ts.
|
|
401
|
+
*/
|
|
402
|
+
interface ToolRouterHooks<T extends ToolMap, TResult = unknown> {
|
|
403
|
+
/** Called before each tool execution - can block or modify */
|
|
404
|
+
onPreToolUse?: PreToolUseHook<T>;
|
|
405
|
+
/** Called after each successful tool execution */
|
|
406
|
+
onPostToolUse?: PostToolUseHook<T, TResult>;
|
|
407
|
+
/** Called when tool execution fails */
|
|
408
|
+
onPostToolUseFailure?: PostToolUseFailureHook<T>;
|
|
409
|
+
}
|
|
410
|
+
/**
|
|
411
|
+
* Options for creating a tool router.
|
|
412
|
+
*/
|
|
413
|
+
interface ToolRouterOptions<T extends ToolMap> {
|
|
414
|
+
/** Map of tools with their handlers */
|
|
415
|
+
tools: T;
|
|
416
|
+
/** Thread ID for appending tool results */
|
|
417
|
+
threadId: string;
|
|
418
|
+
/** Function to append tool results to the thread (called automatically after each handler) */
|
|
419
|
+
appendToolResult: AppendToolResultFn;
|
|
420
|
+
/** Whether to process tools in parallel (default: true) */
|
|
421
|
+
parallel?: boolean;
|
|
422
|
+
/** Tool execution lifecycle hooks (pre/post tool use) */
|
|
423
|
+
hooks?: ToolRouterHooks<T, ToolCallResultUnion<InferToolResults<T>>>;
|
|
424
|
+
/** Additional tools to auto-register (e.g. subagent, skill tools built by register helpers) */
|
|
425
|
+
plugins?: ToolMap[string][];
|
|
426
|
+
}
|
|
427
|
+
/**
|
|
428
|
+
* The tool router interface with full type inference for both args and results.
|
|
429
|
+
*/
|
|
430
|
+
interface ToolRouter<T extends ToolMap> {
|
|
431
|
+
/** Check if the router has any tools */
|
|
432
|
+
hasTools(): boolean;
|
|
433
|
+
/**
|
|
434
|
+
* Parse and validate a raw tool call against the router's tools.
|
|
435
|
+
* Returns a typed tool call with validated arguments.
|
|
436
|
+
*/
|
|
437
|
+
parseToolCall(toolCall: RawToolCall): ParsedToolCallUnion<T>;
|
|
438
|
+
/**
|
|
439
|
+
* Check if a tool with the given name exists in the router.
|
|
440
|
+
*/
|
|
441
|
+
hasTool(name: string): boolean;
|
|
442
|
+
/**
|
|
443
|
+
* Get all tool names in the router.
|
|
444
|
+
*/
|
|
445
|
+
getToolNames(): ToolNames<T>[];
|
|
446
|
+
/**
|
|
447
|
+
* Get all tool definitions (without handlers) for passing to LLM.
|
|
448
|
+
*/
|
|
449
|
+
getToolDefinitions(): ToolDefinition[];
|
|
450
|
+
/**
|
|
451
|
+
* Process all tool calls using the registered handlers.
|
|
452
|
+
* Returns typed results based on handler return types.
|
|
453
|
+
* @param toolCalls - Array of parsed tool calls to process
|
|
454
|
+
* @param context - Optional context including turn number for hooks
|
|
455
|
+
*/
|
|
456
|
+
processToolCalls(toolCalls: ParsedToolCallUnion<T>[], context?: ProcessToolCallsContext): Promise<ToolCallResultUnion<InferToolResults<T>>[]>;
|
|
457
|
+
/**
|
|
458
|
+
* Process tool calls matching a specific name with a custom handler.
|
|
459
|
+
* Useful for overriding the default handler for specific cases.
|
|
460
|
+
*/
|
|
461
|
+
processToolCallsByName<TName extends ToolNames<T>, TResult>(toolCalls: ParsedToolCallUnion<T>[], toolName: TName, handler: ToolHandler<ToolArgs<T, TName>, TResult>, context?: ProcessToolCallsContext): Promise<ToolCallResult<TName, TResult>[]>;
|
|
462
|
+
/**
|
|
463
|
+
* Filter tool calls by name.
|
|
464
|
+
*/
|
|
465
|
+
filterByName<TName extends ToolNames<T>>(toolCalls: ParsedToolCallUnion<T>[], name: TName): ParsedToolCall<TName, ToolArgs<T, TName>>[];
|
|
466
|
+
/**
|
|
467
|
+
* Check if any tool call matches the given name.
|
|
468
|
+
*/
|
|
469
|
+
hasToolCall(toolCalls: ParsedToolCallUnion<T>[], name: ToolNames<T>): boolean;
|
|
470
|
+
/**
|
|
471
|
+
* Filter results by tool name.
|
|
472
|
+
*/
|
|
473
|
+
getResultsByName<TName extends ToolNames<T>>(results: ToolCallResultUnion<InferToolResults<T>>[], name: TName): ToolCallResult<TName, ToolResult<T, TName>>[];
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
export { type ActivityToolHandler as A, type BaseAgentState as B, type ContentPart as C, type ToolCallResult as D, type ToolHandler as E, type ToolHooks as F, type ToolNames as G, type ToolResult as H, type InferToolResults as I, type ToolRouter as J, type ToolWithHandler as K, isTerminalStatus as L, type MessageContent as M, type ToolRouterOptions as N, type PreToolUseHookResult as P, type RouterContext as R, type SessionExitReason as S, type ToolMessageContent as T, type WorkflowTask as W, type ToolMap as a, type ToolRouterHooks as b, type ToolHandlerResponse as c, type PostToolUseFailureHookResult as d, type RawToolCall as e, type TokenUsage as f, type RunAgentConfig as g, type AgentStatus as h, type ToolDefinition as i, type ToolResultConfig as j, type ToolCallResultUnion as k, type AgentConfig as l, type AgentFile as m, type AppendToolResultFn as n, type ParsedToolCall as o, type ParsedToolCallUnion as p, type PostToolUseFailureHook as q, type PostToolUseFailureHookContext as r, type PostToolUseHook as s, type PostToolUseHookContext as t, type PreToolUseHook as u, type PreToolUseHookContext as v, type ProcessToolCallsContext as w, type SerializableToolDefinition as x, type TaskStatus as y, type ToolArgs as z };
|
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
import { a as SandboxFileSystem, F as FileStat, D as DirentEntry, S as Sandbox, d as SandboxCreateOptions } from './types-CDubRtad.cjs';
|
|
2
|
+
import { R as RouterContext } from './types-BMXzv7TN.cjs';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Ephemeral {@link SandboxFileSystem} backed by a {@link FileResolver}.
|
|
6
|
+
*
|
|
7
|
+
* Created fresh for each tool invocation from the current workflow file tree.
|
|
8
|
+
* Directory structure is inferred from file paths. All mutations are tracked
|
|
9
|
+
* and can be retrieved via {@link getMutations} after the handler completes.
|
|
10
|
+
*/
|
|
11
|
+
declare class VirtualSandboxFileSystem<TCtx = unknown, TMeta = FileEntryMetadata> implements SandboxFileSystem {
|
|
12
|
+
private resolver;
|
|
13
|
+
private ctx;
|
|
14
|
+
private entries;
|
|
15
|
+
private directories;
|
|
16
|
+
private mutations;
|
|
17
|
+
constructor(tree: FileEntry<TMeta>[], resolver: FileResolver<TCtx, TMeta>, ctx: TCtx);
|
|
18
|
+
/** Return all mutations accumulated during this invocation. */
|
|
19
|
+
getMutations(): TreeMutation<TMeta>[];
|
|
20
|
+
/** Look up a file entry by virtual path. */
|
|
21
|
+
getEntry(path: string): FileEntry<TMeta> | undefined;
|
|
22
|
+
readFile(path: string): Promise<string>;
|
|
23
|
+
readFileBuffer(path: string): Promise<Uint8Array>;
|
|
24
|
+
exists(path: string): Promise<boolean>;
|
|
25
|
+
stat(path: string): Promise<FileStat>;
|
|
26
|
+
readdir(path: string): Promise<string[]>;
|
|
27
|
+
readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
|
|
28
|
+
writeFile(path: string, content: string | Uint8Array): Promise<void>;
|
|
29
|
+
appendFile(path: string, content: string | Uint8Array): Promise<void>;
|
|
30
|
+
mkdir(_path: string, _options?: {
|
|
31
|
+
recursive?: boolean;
|
|
32
|
+
}): Promise<void>;
|
|
33
|
+
rm(path: string, options?: {
|
|
34
|
+
recursive?: boolean;
|
|
35
|
+
force?: boolean;
|
|
36
|
+
}): Promise<void>;
|
|
37
|
+
cp(src: string, dest: string, _options?: {
|
|
38
|
+
recursive?: boolean;
|
|
39
|
+
}): Promise<void>;
|
|
40
|
+
mv(src: string, dest: string): Promise<void>;
|
|
41
|
+
readlink(_path: string): Promise<string>;
|
|
42
|
+
resolvePath(base: string, path: string): string;
|
|
43
|
+
private addParentDirectories;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** Allowed value types for file-entry metadata. */
|
|
47
|
+
type FileEntryMetadata = Record<string, string | number | boolean | null>;
|
|
48
|
+
/** JSON-serializable metadata for a single file in the virtual tree. */
|
|
49
|
+
interface FileEntry<TMeta = FileEntryMetadata> {
|
|
50
|
+
id: string;
|
|
51
|
+
/** Virtual path inside the sandbox, e.g. "/src/index.ts" */
|
|
52
|
+
path: string;
|
|
53
|
+
size: number;
|
|
54
|
+
/** ISO-8601 date string (JSON-safe) */
|
|
55
|
+
mtime: string;
|
|
56
|
+
metadata: TMeta;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Flat list of file entries.
|
|
60
|
+
* Directories are inferred from file paths at runtime.
|
|
61
|
+
*/
|
|
62
|
+
type VirtualFileTree<TMeta = FileEntryMetadata> = FileEntry<TMeta>[];
|
|
63
|
+
type TreeMutation<TMeta = FileEntryMetadata> = {
|
|
64
|
+
type: "add";
|
|
65
|
+
entry: FileEntry<TMeta>;
|
|
66
|
+
} | {
|
|
67
|
+
type: "remove";
|
|
68
|
+
path: string;
|
|
69
|
+
} | {
|
|
70
|
+
type: "update";
|
|
71
|
+
path: string;
|
|
72
|
+
entry: Partial<FileEntry<TMeta>>;
|
|
73
|
+
};
|
|
74
|
+
/**
|
|
75
|
+
* Consumer-provided bridge to the existing DB / S3 / CRUD layer.
|
|
76
|
+
*
|
|
77
|
+
* Generic over `TCtx` so every call receives workflow-level context
|
|
78
|
+
* (e.g. `{ projectId: string }`) without the resolver holding state.
|
|
79
|
+
*
|
|
80
|
+
* Generic over `TMeta` so resolved entries carry typed metadata.
|
|
81
|
+
*/
|
|
82
|
+
interface FileResolver<TCtx = unknown, TMeta = FileEntryMetadata> {
|
|
83
|
+
resolveEntries(ctx: TCtx): Promise<FileEntry<TMeta>[]>;
|
|
84
|
+
readFile(id: string, ctx: TCtx): Promise<string>;
|
|
85
|
+
readFileBuffer(id: string, ctx: TCtx): Promise<Uint8Array>;
|
|
86
|
+
writeFile(id: string, content: string | Uint8Array, ctx: TCtx): Promise<void>;
|
|
87
|
+
createFile(path: string, content: string | Uint8Array, ctx: TCtx): Promise<FileEntry<TMeta>>;
|
|
88
|
+
deleteFile(id: string, ctx: TCtx): Promise<void>;
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Options for {@link VirtualSandboxProvider.create}.
|
|
92
|
+
* Extends base options with resolver context.
|
|
93
|
+
*/
|
|
94
|
+
interface VirtualSandboxCreateOptions<TCtx> extends SandboxCreateOptions {
|
|
95
|
+
resolverContext: TCtx;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* The portion of workflow `AgentState` that the virtual sandbox reads via
|
|
99
|
+
* {@link queryParentWorkflowState}. Populated automatically by the session
|
|
100
|
+
* from the provider's `stateUpdate` after `createSandbox`.
|
|
101
|
+
*/
|
|
102
|
+
interface VirtualSandboxState<TCtx = unknown, TMeta = FileEntryMetadata> {
|
|
103
|
+
sandboxId: string;
|
|
104
|
+
fileTree: FileEntry<TMeta>[];
|
|
105
|
+
resolverContext: TCtx;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* A {@link Sandbox} whose filesystem is backed by a {@link VirtualSandboxFileSystem}.
|
|
109
|
+
*/
|
|
110
|
+
type VirtualSandbox<TCtx = unknown, TMeta = FileEntryMetadata> = Sandbox & {
|
|
111
|
+
fs: VirtualSandboxFileSystem<TCtx, TMeta>;
|
|
112
|
+
};
|
|
113
|
+
/**
|
|
114
|
+
* Extended router context injected by {@link withVirtualSandbox}.
|
|
115
|
+
* Guarantees a live (ephemeral) sandbox built from the workflow file tree.
|
|
116
|
+
*/
|
|
117
|
+
interface VirtualSandboxContext<TCtx = unknown, TMeta = FileEntryMetadata> extends RouterContext {
|
|
118
|
+
sandbox: VirtualSandbox<TCtx, TMeta>;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export { type FileEntryMetadata as F, type TreeMutation as T, type VirtualSandboxCreateOptions as V, type FileResolver as a, type VirtualSandboxContext as b, type FileEntry as c, type VirtualSandbox as d, type VirtualFileTree as e, VirtualSandboxFileSystem as f, type VirtualSandboxState as g };
|