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.
Files changed (135) hide show
  1. package/README.md +49 -38
  2. package/dist/adapters/sandbox/daytona/index.cjs +205 -0
  3. package/dist/adapters/sandbox/daytona/index.cjs.map +1 -0
  4. package/dist/adapters/sandbox/daytona/index.d.cts +86 -0
  5. package/dist/adapters/sandbox/daytona/index.d.ts +86 -0
  6. package/dist/adapters/sandbox/daytona/index.js +202 -0
  7. package/dist/adapters/sandbox/daytona/index.js.map +1 -0
  8. package/dist/adapters/sandbox/inmemory/index.cjs +174 -0
  9. package/dist/adapters/sandbox/inmemory/index.cjs.map +1 -0
  10. package/dist/adapters/sandbox/inmemory/index.d.cts +28 -0
  11. package/dist/adapters/sandbox/inmemory/index.d.ts +28 -0
  12. package/dist/adapters/sandbox/inmemory/index.js +172 -0
  13. package/dist/adapters/sandbox/inmemory/index.js.map +1 -0
  14. package/dist/adapters/sandbox/virtual/index.cjs +405 -0
  15. package/dist/adapters/sandbox/virtual/index.cjs.map +1 -0
  16. package/dist/adapters/sandbox/virtual/index.d.cts +85 -0
  17. package/dist/adapters/sandbox/virtual/index.d.ts +85 -0
  18. package/dist/adapters/sandbox/virtual/index.js +400 -0
  19. package/dist/adapters/sandbox/virtual/index.js.map +1 -0
  20. package/dist/adapters/thread/google-genai/index.cjs +284 -0
  21. package/dist/adapters/thread/google-genai/index.cjs.map +1 -0
  22. package/dist/adapters/thread/google-genai/index.d.cts +145 -0
  23. package/dist/adapters/thread/google-genai/index.d.ts +145 -0
  24. package/dist/adapters/thread/google-genai/index.js +278 -0
  25. package/dist/adapters/thread/google-genai/index.js.map +1 -0
  26. package/dist/adapters/{langchain → thread/langchain}/index.cjs +7 -9
  27. package/dist/adapters/thread/langchain/index.cjs.map +1 -0
  28. package/dist/adapters/{langchain → thread/langchain}/index.d.cts +17 -21
  29. package/dist/adapters/{langchain → thread/langchain}/index.d.ts +17 -21
  30. package/dist/adapters/{langchain → thread/langchain}/index.js +7 -9
  31. package/dist/adapters/thread/langchain/index.js.map +1 -0
  32. package/dist/index.cjs +816 -545
  33. package/dist/index.cjs.map +1 -1
  34. package/dist/index.d.cts +235 -74
  35. package/dist/index.d.ts +235 -74
  36. package/dist/index.js +804 -540
  37. package/dist/index.js.map +1 -1
  38. package/dist/types-B4C9txdq.d.ts +389 -0
  39. package/dist/{thread-manager-qc0g5Rvd.d.cts → types-B9ljZewB.d.cts} +1 -6
  40. package/dist/{thread-manager-qc0g5Rvd.d.ts → types-B9ljZewB.d.ts} +1 -6
  41. package/dist/types-BMXzv7TN.d.cts +476 -0
  42. package/dist/types-BMXzv7TN.d.ts +476 -0
  43. package/dist/types-BVP87m_W.d.cts +121 -0
  44. package/dist/types-CDubRtad.d.cts +115 -0
  45. package/dist/types-CDubRtad.d.ts +115 -0
  46. package/dist/types-CwwgQ_9H.d.ts +121 -0
  47. package/dist/types-GpMU4b0w.d.cts +389 -0
  48. package/dist/workflow.cjs +444 -318
  49. package/dist/workflow.cjs.map +1 -1
  50. package/dist/workflow.d.cts +271 -222
  51. package/dist/workflow.d.ts +271 -222
  52. package/dist/workflow.js +440 -316
  53. package/dist/workflow.js.map +1 -1
  54. package/package.json +59 -6
  55. package/src/adapters/sandbox/daytona/filesystem.ts +136 -0
  56. package/src/adapters/sandbox/daytona/index.ts +149 -0
  57. package/src/adapters/sandbox/daytona/types.ts +34 -0
  58. package/src/adapters/sandbox/inmemory/index.ts +213 -0
  59. package/src/adapters/sandbox/virtual/filesystem.ts +345 -0
  60. package/src/adapters/sandbox/virtual/index.ts +88 -0
  61. package/src/adapters/sandbox/virtual/mutations.ts +38 -0
  62. package/src/adapters/sandbox/virtual/provider.ts +101 -0
  63. package/src/adapters/sandbox/virtual/tree.ts +82 -0
  64. package/src/adapters/sandbox/virtual/types.ts +127 -0
  65. package/src/adapters/sandbox/virtual/virtual-sandbox.test.ts +523 -0
  66. package/src/adapters/sandbox/virtual/with-virtual-sandbox.ts +91 -0
  67. package/src/adapters/thread/google-genai/activities.ts +121 -0
  68. package/src/adapters/thread/google-genai/index.ts +41 -0
  69. package/src/adapters/thread/google-genai/model-invoker.ts +154 -0
  70. package/src/adapters/thread/google-genai/thread-manager.ts +169 -0
  71. package/src/adapters/{langchain → thread/langchain}/activities.ts +11 -15
  72. package/src/adapters/{langchain → thread/langchain}/index.ts +1 -1
  73. package/src/adapters/{langchain → thread/langchain}/model-invoker.ts +15 -18
  74. package/src/adapters/{langchain → thread/langchain}/thread-manager.ts +1 -1
  75. package/src/index.ts +32 -24
  76. package/src/lib/activity.ts +87 -0
  77. package/src/lib/hooks/index.ts +11 -0
  78. package/src/lib/hooks/types.ts +98 -0
  79. package/src/lib/model/helpers.ts +6 -0
  80. package/src/lib/model/index.ts +13 -0
  81. package/src/lib/{model-invoker.ts → model/types.ts} +18 -1
  82. package/src/lib/sandbox/index.ts +19 -0
  83. package/src/lib/sandbox/manager.ts +76 -0
  84. package/src/lib/sandbox/sandbox.test.ts +158 -0
  85. package/src/lib/{fs.ts → sandbox/tree.ts} +6 -6
  86. package/src/lib/sandbox/types.ts +164 -0
  87. package/src/lib/session/index.ts +11 -0
  88. package/src/lib/{session.ts → session/session.ts} +76 -48
  89. package/src/lib/session/types.ts +93 -0
  90. package/src/lib/skills/fs-provider.ts +16 -15
  91. package/src/lib/skills/handler.ts +31 -0
  92. package/src/lib/skills/index.ts +5 -1
  93. package/src/lib/skills/register.ts +20 -0
  94. package/src/lib/skills/tool.ts +47 -0
  95. package/src/lib/state/index.ts +9 -0
  96. package/src/lib/{state-manager.ts → state/manager.ts} +10 -147
  97. package/src/lib/state/types.ts +134 -0
  98. package/src/lib/subagent/define.ts +71 -0
  99. package/src/lib/subagent/handler.ts +99 -0
  100. package/src/lib/subagent/index.ts +13 -0
  101. package/src/lib/subagent/register.ts +53 -0
  102. package/src/lib/subagent/tool.ts +80 -0
  103. package/src/lib/subagent/types.ts +92 -0
  104. package/src/lib/thread/index.ts +7 -0
  105. package/src/lib/{thread-manager.ts → thread/manager.ts} +1 -33
  106. package/src/lib/thread/types.ts +33 -0
  107. package/src/lib/tool-router/auto-append.ts +55 -0
  108. package/src/lib/tool-router/index.ts +41 -0
  109. package/src/lib/tool-router/router.ts +462 -0
  110. package/src/lib/tool-router/types.ts +478 -0
  111. package/src/lib/tool-router/with-sandbox.ts +70 -0
  112. package/src/lib/types.ts +5 -382
  113. package/src/tools/bash/bash.test.ts +53 -55
  114. package/src/tools/bash/handler.ts +23 -51
  115. package/src/tools/edit/handler.ts +67 -81
  116. package/src/tools/glob/handler.ts +60 -17
  117. package/src/tools/read-file/handler.ts +67 -0
  118. package/src/tools/read-skill/handler.ts +1 -31
  119. package/src/tools/read-skill/tool.ts +5 -47
  120. package/src/tools/subagent/handler.ts +1 -100
  121. package/src/tools/subagent/tool.ts +5 -93
  122. package/src/tools/task-create/handler.ts +1 -1
  123. package/src/tools/task-get/handler.ts +1 -1
  124. package/src/tools/task-list/handler.ts +1 -1
  125. package/src/tools/task-update/handler.ts +1 -1
  126. package/src/tools/write-file/handler.ts +47 -0
  127. package/src/workflow.ts +88 -47
  128. package/tsup.config.ts +8 -1
  129. package/dist/adapters/langchain/index.cjs.map +0 -1
  130. package/dist/adapters/langchain/index.js.map +0 -1
  131. package/dist/model-invoker-y_zlyMqu.d.cts +0 -892
  132. package/dist/model-invoker-y_zlyMqu.d.ts +0 -892
  133. package/src/lib/tool-router.ts +0 -977
  134. package/src/lib/workflow-helpers.ts +0 -50
  135. /package/src/lib/{thread-id.ts → thread/id.ts} +0 -0
@@ -1,109 +1,89 @@
1
- import { QueryDefinition, proxyActivities } from '@temporalio/workflow';
2
- import { B as BaseAgentState, g as AgentStatus, a9 as WorkflowTask, Z as ToolDefinition, G as SessionStartHook, D as SessionEndHook, F as SessionExitReason, a2 as ToolMap, z as SessionConfig, e as AgentConfig, T as ThreadOps, c as SkillMetadata, d as Skill, a0 as ToolHandlerResponse, _ as ToolHandler, b as ActivityToolHandler } from './model-invoker-y_zlyMqu.cjs';
3
- export { f as AgentFile, A as AgentResponse, h as AppendToolResultFn, C as ContentPart, H as Hooks, I as InferToolResults, i as MessageContent, M as ModelInvoker, a as ModelInvokerConfig, P as ParsedToolCall, j as ParsedToolCallUnion, k as PostHumanMessageAppendHook, l as PostHumanMessageAppendHookContext, m as PostToolUseFailureHook, n as PostToolUseFailureHookContext, o as PostToolUseFailureHookResult, p as PostToolUseHook, q as PostToolUseHookContext, r as PreHumanMessageAppendHook, s as PreHumanMessageAppendHookContext, t as PreToolUseHook, u as PreToolUseHookContext, v as PreToolUseHookResult, w as ProcessToolCallsContext, x as RawToolCall, y as RunAgentActivity, R as RunAgentConfig, E as SessionEndHookContext, J as SessionStartHookContext, S as SkillProvider, K as SubagentArgs, L as SubagentConfig, N as SubagentHooks, O as SubagentInput, Q as SubagentWorkflow, U as TaskStatus, V as TokenUsage, W as ToolArgs, X as ToolCallResult, Y as ToolCallResultUnion, $ as ToolHandlerContext, a1 as ToolHooks, a3 as ToolMessageContent, a4 as ToolNames, a5 as ToolResult, a6 as ToolResultConfig, a7 as ToolRouter, a8 as ToolWithHandler, aa as agentQueryName, ab as agentStateChangeUpdateName, ac as createSubagentTool, ad as createToolRouter, ae as defineSubagent, af as defineTool, ag as hasNoOtherToolCalls, ah as isTerminalStatus } from './model-invoker-y_zlyMqu.cjs';
4
- import { UpdateDefinition } from '@temporalio/common/lib/interfaces';
5
- import z, { z as z$1 } from 'zod';
1
+ import { proxyActivities } from '@temporalio/workflow';
2
+ import { k as SessionConfig, Z as ZeitlichSession, T as ThreadOps, f as JsonSerializable, e as AgentStateManager, p as SubagentConfig, q as SubagentHandlerResponse, r as SubagentHooks, b as SkillMetadata, c as Skill } from './types-GpMU4b0w.cjs';
3
+ export { A as AgentResponse, d as AgentState, H as Hooks, J as JsonPrimitive, g as JsonValue, M as ModelInvoker, a as ModelInvokerConfig, P as PostHumanMessageAppendHook, h as PostHumanMessageAppendHookContext, i as PreHumanMessageAppendHook, j as PreHumanMessageAppendHookContext, R as RunAgentActivity, l as SessionEndHook, m as SessionEndHookContext, n as SessionStartHook, o as SessionStartHookContext, S as SkillProvider, s as SubagentInput, t as SubagentWorkflow } from './types-GpMU4b0w.cjs';
4
+ import { g as SandboxOps } from './types-CDubRtad.cjs';
5
+ export { h as ExecOptions, E as ExecResult, S as Sandbox, c as SandboxCapabilities, d as SandboxCreateOptions, e as SandboxCreateResult, D as SandboxDirentEntry, F as SandboxFileStat, a as SandboxFileSystem, i as SandboxNotFoundError, j as SandboxNotSupportedError, b as SandboxProvider, f as SandboxSnapshot } from './types-CDubRtad.cjs';
6
+ import { a as ToolMap, B as BaseAgentState, N as ToolRouterOptions, J as ToolRouter, R as RouterContext, K as ToolWithHandler, p as ParsedToolCallUnion, G as ToolNames, c as ToolHandlerResponse, E as ToolHandler, W as WorkflowTask, A as ActivityToolHandler } from './types-BMXzv7TN.cjs';
7
+ export { l as AgentConfig, m as AgentFile, h as AgentStatus, n as AppendToolResultFn, C as ContentPart, I as InferToolResults, M as MessageContent, o as ParsedToolCall, q as PostToolUseFailureHook, r as PostToolUseFailureHookContext, d as PostToolUseFailureHookResult, s as PostToolUseHook, t as PostToolUseHookContext, u as PreToolUseHook, v as PreToolUseHookContext, P as PreToolUseHookResult, w as ProcessToolCallsContext, e as RawToolCall, g as RunAgentConfig, x as SerializableToolDefinition, S as SessionExitReason, y as TaskStatus, f as TokenUsage, z as ToolArgs, D as ToolCallResult, k as ToolCallResultUnion, i as ToolDefinition, F as ToolHooks, T as ToolMessageContent, H as ToolResult, j as ToolResultConfig, b as ToolRouterHooks, L as isTerminalStatus } from './types-BMXzv7TN.cjs';
8
+ import z$1, { z } from 'zod';
9
+ import { F as FileEntryMetadata, e as VirtualFileTree, T as TreeMutation, c as FileEntry } from './types-BVP87m_W.cjs';
10
+ export { a as FileResolver, g as VirtualSandboxState } from './types-BVP87m_W.cjs';
6
11
  import '@temporalio/common';
12
+ import '@temporalio/common/lib/interfaces';
7
13
 
8
14
  /**
9
- * JSON primitive types that Temporal can serialize
10
- */
11
- type JsonPrimitive = string | number | boolean | null | undefined;
12
- /**
13
- * JSON-serializable value (recursive type for Temporal compatibility)
15
+ * Creates an agent session that manages the agent loop: LLM invocation,
16
+ * tool routing, subagent coordination, and lifecycle hooks.
17
+ *
18
+ * @param config - Session and agent configuration (merged `SessionConfig` and `AgentConfig`)
19
+ * @returns A session object with `runSession()` to start the agent loop
20
+ *
21
+ * @example
22
+ * ```typescript
23
+ * import { createSession, createAgentStateManager, defineTool, bashTool } from 'zeitlich/workflow';
24
+ *
25
+ * const stateManager = createAgentStateManager({
26
+ * initialState: { systemPrompt: "You are a helpful assistant." },
27
+ * agentName: "my-agent",
28
+ * });
29
+ *
30
+ * const session = await createSession({
31
+ * agentName: "my-agent",
32
+ * maxTurns: 20,
33
+ * threadId: runId,
34
+ * runAgent: runAgentActivity,
35
+ * buildContextMessage: () => [{ type: "text", text: prompt }],
36
+ * subagents: [researcherSubagent],
37
+ * tools: {
38
+ * Bash: defineTool({ ...bashTool, handler: bashHandlerActivity }),
39
+ * },
40
+ * });
41
+ *
42
+ * const { finalMessage, exitReason } = await session.runSession({ stateManager });
43
+ * ```
14
44
  */
15
- type JsonValue = JsonPrimitive | JsonValue[] | {
16
- [key: string]: JsonValue;
17
- };
45
+ declare const createSession: <T extends ToolMap, M = unknown>({ threadId: providedThreadId, agentName, maxTurns, metadata, runAgent, threadOps, buildContextMessage, subagents, skills, tools, processToolsInParallel, hooks, appendSystemPrompt, continueThread, waitForInputTimeout, sandbox: sandboxOps, sandboxId: inheritedSandboxId, }: SessionConfig<T, M>) => Promise<ZeitlichSession<M>>;
18
46
  /**
19
- * Type constraint ensuring T only contains JSON-serializable values.
20
- * Use this for custom state to ensure Temporal workflow compatibility.
47
+ * Proxy the adapter's thread operations as Temporal activities.
48
+ * Call this in workflow code to delegate thread operations to the
49
+ * adapter-provided activities registered on the worker.
21
50
  *
22
- * Allows: primitives, arrays, plain objects, and JsonValue
23
- * Rejects: functions, symbols, undefined, class instances with methods
51
+ * @example
52
+ * ```typescript
53
+ * const session = await createSession({
54
+ * threadOps: proxyDefaultThreadOps(),
55
+ * // ...
56
+ * });
57
+ * ```
24
58
  */
25
- type JsonSerializable<T> = {
26
- [K in keyof T]: T[K] extends JsonValue ? T[K] : T[K] extends JsonPrimitive ? T[K] : T[K] extends (infer U)[] ? U extends JsonValue ? T[K] : JsonSerializable<U>[] : T[K] extends object ? JsonSerializable<T[K]> : never;
27
- };
59
+ declare function proxyDefaultThreadOps(options?: Parameters<typeof proxyActivities>[0]): ThreadOps;
28
60
  /**
29
- * Full state type combining base state with custom state
61
+ * Proxy sandbox lifecycle operations as Temporal activities.
62
+ * Call this in workflow code when the agent needs a sandbox.
63
+ *
64
+ * @example
65
+ * ```typescript
66
+ * const session = await createSession({
67
+ * sandbox: proxySandboxOps(),
68
+ * // ...
69
+ * });
70
+ * ```
30
71
  */
31
- type AgentState<TCustom extends JsonSerializable<TCustom>> = BaseAgentState & TCustom;
72
+ declare function proxySandboxOps(options?: Parameters<typeof proxyActivities>[0]): SandboxOps;
73
+
32
74
  /**
33
- * Agent state manager interface
34
- * Note: Temporal handlers must be set up in the workflow file due to
35
- * Temporal's workflow isolation requirements. This manager provides
36
- * the state and helpers needed for those handlers.
75
+ * Generate a compact, workflow-deterministic identifier.
76
+ *
77
+ * Uses Temporal's `uuid4()` internally (seeded by the workflow's RNG),
78
+ * then re-encodes the hex bytes into a base-62 alphabet for a shorter,
79
+ * more token-efficient identifier (~3 tokens vs ~10 for a full UUID).
80
+ *
81
+ * Suitable for thread IDs, child workflow IDs, or any workflow-scoped identifier.
82
+ *
83
+ * @param length - Number of base-62 characters (default 12, ~71 bits of entropy)
37
84
  */
38
- interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
39
- /** Typed query definition registered for this agent's state */
40
- readonly stateQuery: QueryDefinition<AgentState<TCustom>>;
41
- /** Typed update definition registered for waiting on this agent's state change */
42
- readonly stateChangeUpdate: UpdateDefinition<AgentState<TCustom>, [number]>;
43
- /** Get current status */
44
- getStatus(): AgentStatus;
45
- /** Check if agent is running */
46
- isRunning(): boolean;
47
- /** Check if agent is in terminal state */
48
- isTerminal(): boolean;
49
- /** Get current state version */
50
- getVersion(): number;
51
- /** Set status to RUNNING */
52
- run(): void;
53
- /** Set status to WAITING_FOR_INPUT */
54
- waitForInput(): void;
55
- /** Set status to COMPLETED */
56
- complete(): void;
57
- /** Set status to FAILED */
58
- fail(): void;
59
- /** Set status to CANCELLED */
60
- cancel(): void;
61
- /** Increment state version (call after state changes) */
62
- incrementVersion(): void;
63
- /** Increment turns (call after each turn) */
64
- incrementTurns(): void;
65
- /** Get current turns */
66
- getTurns(): number;
67
- /** Get the system prompt */
68
- getSystemPrompt(): string | undefined;
69
- /** Set the system prompt */
70
- setSystemPrompt(newSystemPrompt: string): void;
71
- /** Get a custom state value by key */
72
- get<K extends keyof TCustom>(key: K): TCustom[K];
73
- /** Set a custom state value by key */
74
- set<K extends keyof TCustom>(key: K, value: TCustom[K]): void;
75
- /** Get full state for query handler */
76
- getCurrentState(): AgentState<TCustom>;
77
- /** Check if should return from waitForStateChange */
78
- shouldReturnFromWait(lastKnownVersion: number): boolean;
79
- /** Get all tasks */
80
- getTasks(): WorkflowTask[];
81
- /** Get a task by ID */
82
- getTask(id: string): WorkflowTask | undefined;
83
- /** Add or update a task */
84
- setTask(task: WorkflowTask): void;
85
- /** Delete a task by ID */
86
- deleteTask(id: string): boolean;
87
- /** Set the tools (converts Zod schemas to JSON Schema for serialization) */
88
- setTools(newTools: ToolDefinition[]): void;
89
- /** Update the usage */
90
- updateUsage(usage: {
91
- inputTokens?: number;
92
- outputTokens?: number;
93
- cachedWriteTokens?: number;
94
- cachedReadTokens?: number;
95
- reasonTokens?: number;
96
- }): void;
97
- /** Get the total usage */
98
- getTotalUsage(): {
99
- totalInputTokens: number;
100
- totalOutputTokens: number;
101
- totalCachedWriteTokens: number;
102
- totalCachedReadTokens: number;
103
- totalReasonTokens: number;
104
- turns: number;
105
- };
106
- }
85
+ declare function getShortId(length?: number): string;
86
+
107
87
  /**
108
88
  * Creates an agent state manager for tracking workflow state.
109
89
  * Automatically registers Temporal query and update handlers for the agent.
@@ -132,88 +112,157 @@ interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
132
112
  * });
133
113
  * ```
134
114
  */
135
- declare function createAgentStateManager<TCustom extends JsonSerializable<TCustom> = Record<string, never>>({ initialState, agentName, }: {
115
+ declare function createAgentStateManager<TCustom extends JsonSerializable<TCustom> = Record<string, never>>({ initialState, }: {
136
116
  initialState?: Partial<BaseAgentState> & TCustom;
137
- agentName: string;
138
117
  }): AgentStateManager<TCustom>;
139
118
 
140
- interface ZeitlichSession<M = unknown> {
141
- runSession<T extends JsonSerializable<T>>(args: {
142
- stateManager: AgentStateManager<T>;
143
- }): Promise<{
144
- finalMessage: M | null;
145
- exitReason: SessionExitReason;
146
- usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
147
- }>;
148
- }
149
- /**
150
- * Session-level hooks for lifecycle events
151
- */
152
- interface SessionLifecycleHooks {
153
- /** Called when session starts */
154
- onSessionStart?: SessionStartHook;
155
- /** Called when session ends */
156
- onSessionEnd?: SessionEndHook;
157
- }
158
119
  /**
159
- * Creates an agent session that manages the agent loop: LLM invocation,
160
- * tool routing, subagent coordination, and lifecycle hooks.
161
- *
162
- * @param config - Session and agent configuration (merged `SessionConfig` and `AgentConfig`)
163
- * @returns A session object with `runSession()` to start the agent loop
120
+ * Creates a tool router for declarative tool call processing.
121
+ * Combines tool definitions with handlers in a single API.
164
122
  *
165
123
  * @example
166
124
  * ```typescript
167
- * import { createSession, createAgentStateManager, defineTool, bashTool } from 'zeitlich/workflow';
168
- *
169
- * const stateManager = createAgentStateManager({
170
- * initialState: { systemPrompt: "You are a helpful assistant." },
171
- * agentName: "my-agent",
172
- * });
173
- *
174
- * const session = await createSession({
175
- * agentName: "my-agent",
176
- * maxTurns: 20,
177
- * threadId: runId,
178
- * runAgent: runAgentActivity,
179
- * buildContextMessage: () => [{ type: "text", text: prompt }],
180
- * subagents: [researcherSubagent],
125
+ * const router = createToolRouter({
126
+ * threadId,
181
127
  * tools: {
182
- * Bash: defineTool({ ...bashTool, handler: bashHandlerActivity }),
128
+ * Read: {
129
+ * name: "FileRead",
130
+ * description: "Read file contents",
131
+ * schema: z.object({ path: z.string() }),
132
+ * handler: async (args, ctx) => ({
133
+ * content: `Read ${args.path}`,
134
+ * result: { path: args.path, content: "..." },
135
+ * }),
136
+ * },
183
137
  * },
138
+ * hooks: { onPreToolUse, onPostToolUse },
184
139
  * });
185
140
  *
186
- * const { finalMessage, exitReason } = await session.runSession({ stateManager });
141
+ * // Parse raw tool calls from LLM
142
+ * const parsed = router.parseToolCall(rawToolCall);
143
+ *
144
+ * // Process tool calls
145
+ * const results = await router.processToolCalls([parsed]);
187
146
  * ```
188
147
  */
189
- declare const createSession: <T extends ToolMap, M = unknown>({ threadId: providedThreadId, agentName, maxTurns, metadata, runAgent, threadOps, buildContextMessage, subagents, skills, tools, processToolsInParallel, hooks, appendSystemPrompt, continueThread, waitForInputTimeout, }: SessionConfig<T, M> & AgentConfig) => Promise<ZeitlichSession<M>>;
148
+ declare function createToolRouter<T extends ToolMap>(options: ToolRouterOptions<T>): ToolRouter<T>;
190
149
  /**
191
- * Proxy the adapter's thread operations as Temporal activities.
192
- * Call this in workflow code to delegate thread operations to the
193
- * adapter-provided activities registered on the worker.
150
+ * Identity function that creates a generic inference context for a tool definition.
151
+ * TypeScript infers TResult from the handler and flows it to hooks automatically.
194
152
  *
195
153
  * @example
196
154
  * ```typescript
197
- * const session = await createSession({
198
- * threadOps: proxyDefaultThreadOps(),
199
- * // ...
155
+ * tools: {
156
+ * AskUser: defineTool({
157
+ * ...askUserTool,
158
+ * handler: handleAskUser,
159
+ * hooks: {
160
+ * onPostToolUse: ({ result }) => {
161
+ * // result is correctly typed as the handler's return data type
162
+ * },
163
+ * },
164
+ * }),
165
+ * }
166
+ * ```
167
+ */
168
+ declare function defineTool<TName extends string, TSchema extends z.ZodType, TResult, TContext extends RouterContext = RouterContext>(tool: ToolWithHandler<TName, TSchema, TResult, TContext>): ToolWithHandler<TName, TSchema, TResult, TContext>;
169
+ /**
170
+ * Utility to check if there were no tool calls besides a specific one
171
+ */
172
+ declare function hasNoOtherToolCalls<T extends ToolMap>(toolCalls: ParsedToolCallUnion<T>[], excludeName: ToolNames<T>): boolean;
173
+
174
+ /**
175
+ * Subagent tool args type (when subagent names are not known at compile time)
176
+ */
177
+ type SubagentArgs = {
178
+ subagent: string;
179
+ description: string;
180
+ prompt: string;
181
+ threadId?: string | null;
182
+ };
183
+
184
+ /**
185
+ * Identity function that provides full type inference for subagent configurations.
186
+ * Verifies the workflow function's input parameters match the configured context,
187
+ * and properly types the lifecycle hooks with Task tool args and inferred result type.
188
+ *
189
+ * @example
190
+ * ```ts
191
+ * // With typed context — workflow must accept { prompt, context }
192
+ * const researcher = defineSubagent({
193
+ * name: "researcher",
194
+ * description: "Researches topics",
195
+ * workflow: researcherWorkflow, // (input: { prompt: string; context: { apiKey: string } }) => Promise<...>
196
+ * context: { apiKey: "..." },
197
+ * resultSchema: z.object({ findings: z.string() }),
198
+ * hooks: {
199
+ * onPostExecution: ({ result }) => {
200
+ * // result is typed as { findings: string }
201
+ * },
202
+ * },
203
+ * });
204
+ *
205
+ * // Without context — workflow only needs { prompt }
206
+ * const writer = defineSubagent({
207
+ * name: "writer",
208
+ * description: "Writes content",
209
+ * workflow: writerWorkflow, // (input: { prompt: string }) => Promise<...>
210
+ * resultSchema: z.object({ content: z.string() }),
200
211
  * });
201
212
  * ```
202
213
  */
203
- declare function proxyDefaultThreadOps(options?: Parameters<typeof proxyActivities>[0]): ThreadOps;
214
+ declare function defineSubagent<TResult extends z.ZodType = z.ZodType, TContext extends Record<string, unknown> = Record<string, unknown>>(config: Omit<SubagentConfig<TResult>, "hooks" | "workflow" | "context"> & {
215
+ workflow: string | ((input: {
216
+ prompt: string;
217
+ previousThreadId?: string;
218
+ context: TContext;
219
+ }) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>);
220
+ context: TContext;
221
+ hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
222
+ }): SubagentConfig<TResult>;
223
+ declare function defineSubagent<TResult extends z.ZodType = z.ZodType>(config: Omit<SubagentConfig<TResult>, "hooks" | "workflow"> & {
224
+ workflow: string | ((input: {
225
+ prompt: string;
226
+ previousThreadId?: string;
227
+ }) => Promise<SubagentHandlerResponse<z.infer<TResult> | null>>);
228
+ hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
229
+ }): SubagentConfig<TResult>;
204
230
 
205
231
  /**
206
- * Generate a compact, workflow-deterministic identifier.
232
+ * Apply a list of {@link TreeMutation}s to the `fileTree` stored in a state
233
+ * manager instance, updating it in place and returning the new tree.
207
234
  *
208
- * Uses Temporal's `uuid4()` internally (seeded by the workflow's RNG),
209
- * then re-encodes the hex bytes into a base-62 alphabet for a shorter,
210
- * more token-efficient identifier (~3 tokens vs ~10 for a full UUID).
235
+ * The `stateManager` parameter is structurally typed so any
236
+ * {@link AgentStateManager} whose custom state includes
237
+ * `fileTree: VirtualFileTree<TMeta>` will satisfy it.
238
+ */
239
+ declare function applyVirtualTreeMutations<TMeta = FileEntryMetadata>(stateManager: {
240
+ get(key: "fileTree"): VirtualFileTree<TMeta>;
241
+ set(key: "fileTree", value: VirtualFileTree<TMeta>): void;
242
+ }, mutations: TreeMutation<TMeta>[]): VirtualFileTree<TMeta>;
243
+
244
+ /**
245
+ * Generates a formatted file tree string from a flat {@link FileEntry} list.
246
+ * Directories are inferred from file paths — no filesystem access needed.
211
247
  *
212
- * Suitable for thread IDs, child workflow IDs, or any workflow-scoped identifier.
248
+ * @param entries - Flat list of file entries
249
+ * @param opts - Optional configuration
250
+ * @param opts.sort - Sort entries alphabetically with directories first (defaults to true)
251
+ * @returns Formatted file tree string
213
252
  *
214
- * @param length - Number of base-62 characters (default 12, ~71 bits of entropy)
253
+ * @example
254
+ * ```typescript
255
+ * const tree = formatVirtualFileTree(state.fileTree);
256
+ * // /
257
+ * // ├─ src/
258
+ * // │ ├─ index.ts
259
+ * // │ └─ utils.ts
260
+ * // └─ package.json
261
+ * ```
215
262
  */
216
- declare function getShortId(length?: number): string;
263
+ declare function formatVirtualFileTree<T>(entries: FileEntry<T>[], opts?: {
264
+ sort?: boolean;
265
+ }): string;
217
266
 
218
267
  /**
219
268
  * Parse a SKILL.md file into its frontmatter fields and markdown body.
@@ -235,8 +284,8 @@ declare function parseSkillFile(raw: string): {
235
284
  declare function createReadSkillTool(skills: Skill[]): {
236
285
  name: string;
237
286
  description: string;
238
- schema: z.ZodObject<{
239
- skill_name: z.ZodEnum<Record<string, string>>;
287
+ schema: z$1.ZodObject<{
288
+ skill_name: z$1.ZodEnum<Record<string, string>>;
240
289
  }>;
241
290
  };
242
291
  type ReadSkillArgs = {
@@ -252,76 +301,76 @@ declare function createReadSkillHandler(skills: Skill[]): (args: ReadSkillArgs)
252
301
  declare const globTool: {
253
302
  name: "Glob";
254
303
  description: string;
255
- schema: z$1.ZodObject<{
256
- pattern: z$1.ZodString;
257
- root: z$1.ZodOptional<z$1.ZodString>;
258
- }, z$1.core.$strip>;
304
+ schema: z.ZodObject<{
305
+ pattern: z.ZodString;
306
+ root: z.ZodOptional<z.ZodString>;
307
+ }, z.core.$strip>;
259
308
  strict: true;
260
309
  };
261
- type GlobArgs = z$1.infer<typeof globTool.schema>;
310
+ type GlobArgs = z.infer<typeof globTool.schema>;
262
311
 
263
312
  declare const grepTool: {
264
313
  name: "Grep";
265
314
  description: string;
266
- schema: z$1.ZodObject<{
267
- pattern: z$1.ZodString;
268
- ignoreCase: z$1.ZodOptional<z$1.ZodBoolean>;
269
- maxMatches: z$1.ZodOptional<z$1.ZodNumber>;
270
- includePatterns: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
271
- excludePatterns: z$1.ZodOptional<z$1.ZodArray<z$1.ZodString>>;
272
- contextLines: z$1.ZodOptional<z$1.ZodNumber>;
273
- }, z$1.core.$strip>;
315
+ schema: z.ZodObject<{
316
+ pattern: z.ZodString;
317
+ ignoreCase: z.ZodOptional<z.ZodBoolean>;
318
+ maxMatches: z.ZodOptional<z.ZodNumber>;
319
+ includePatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
320
+ excludePatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
321
+ contextLines: z.ZodOptional<z.ZodNumber>;
322
+ }, z.core.$strip>;
274
323
  strict: true;
275
324
  };
276
- type GrepArgs = z$1.infer<typeof grepTool.schema>;
325
+ type GrepArgs = z.infer<typeof grepTool.schema>;
277
326
 
278
327
  declare const readFileTool: {
279
328
  name: "FileRead";
280
329
  description: string;
281
- schema: z$1.ZodObject<{
282
- path: z$1.ZodString;
283
- offset: z$1.ZodOptional<z$1.ZodNumber>;
284
- limit: z$1.ZodOptional<z$1.ZodNumber>;
285
- }, z$1.core.$strip>;
330
+ schema: z.ZodObject<{
331
+ path: z.ZodString;
332
+ offset: z.ZodOptional<z.ZodNumber>;
333
+ limit: z.ZodOptional<z.ZodNumber>;
334
+ }, z.core.$strip>;
286
335
  strict: true;
287
336
  };
288
- type FileReadArgs = z$1.infer<typeof readFileTool.schema>;
337
+ type FileReadArgs = z.infer<typeof readFileTool.schema>;
289
338
 
290
339
  declare const writeFileTool: {
291
340
  name: "FileWrite";
292
341
  description: string;
293
- schema: z$1.ZodObject<{
294
- file_path: z$1.ZodString;
295
- content: z$1.ZodString;
296
- }, z$1.core.$strip>;
342
+ schema: z.ZodObject<{
343
+ file_path: z.ZodString;
344
+ content: z.ZodString;
345
+ }, z.core.$strip>;
297
346
  strict: true;
298
347
  };
299
- type FileWriteArgs = z$1.infer<typeof writeFileTool.schema>;
348
+ type FileWriteArgs = z.infer<typeof writeFileTool.schema>;
300
349
 
301
350
  declare const editTool: {
302
351
  name: "FileEdit";
303
352
  description: string;
304
- schema: z$1.ZodObject<{
305
- file_path: z$1.ZodString;
306
- old_string: z$1.ZodString;
307
- new_string: z$1.ZodString;
308
- replace_all: z$1.ZodOptional<z$1.ZodBoolean>;
309
- }, z$1.core.$strip>;
353
+ schema: z.ZodObject<{
354
+ file_path: z.ZodString;
355
+ old_string: z.ZodString;
356
+ new_string: z.ZodString;
357
+ replace_all: z.ZodOptional<z.ZodBoolean>;
358
+ }, z.core.$strip>;
310
359
  strict: true;
311
360
  };
312
- type FileEditArgs = z$1.infer<typeof editTool.schema>;
361
+ type FileEditArgs = z.infer<typeof editTool.schema>;
313
362
 
314
363
  declare const taskCreateTool: {
315
364
  name: "TaskCreate";
316
365
  description: string;
317
- schema: z.ZodObject<{
318
- subject: z.ZodString;
319
- description: z.ZodString;
320
- activeForm: z.ZodString;
321
- metadata: z.ZodRecord<z.ZodString, z.ZodString>;
322
- }, z.core.$strip>;
366
+ schema: z$1.ZodObject<{
367
+ subject: z$1.ZodString;
368
+ description: z$1.ZodString;
369
+ activeForm: z$1.ZodString;
370
+ metadata: z$1.ZodRecord<z$1.ZodString, z$1.ZodString>;
371
+ }, z$1.core.$strip>;
323
372
  };
324
- type TaskCreateArgs = z.infer<typeof taskCreateTool.schema>;
373
+ type TaskCreateArgs = z$1.infer<typeof taskCreateTool.schema>;
325
374
 
326
375
  /**
327
376
  * Creates a TaskCreate handler that adds tasks to the workflow state.
@@ -334,11 +383,11 @@ declare function createTaskCreateHandler<TCustom extends JsonSerializable<TCusto
334
383
  declare const taskGetTool: {
335
384
  name: "TaskGet";
336
385
  description: string;
337
- schema: z.ZodObject<{
338
- taskId: z.ZodString;
339
- }, z.core.$strip>;
386
+ schema: z$1.ZodObject<{
387
+ taskId: z$1.ZodString;
388
+ }, z$1.core.$strip>;
340
389
  };
341
- type TaskGetArgs = z.infer<typeof taskGetTool.schema>;
390
+ type TaskGetArgs = z$1.infer<typeof taskGetTool.schema>;
342
391
 
343
392
  /**
344
393
  * Creates a TaskGet handler that retrieves a task by ID.
@@ -351,9 +400,9 @@ declare function createTaskGetHandler<TCustom extends JsonSerializable<TCustom>>
351
400
  declare const taskListTool: {
352
401
  name: "TaskList";
353
402
  description: string;
354
- schema: z.ZodObject<{}, z.core.$strip>;
403
+ schema: z$1.ZodObject<{}, z$1.core.$strip>;
355
404
  };
356
- type TaskListArgs = z.infer<typeof taskListTool.schema>;
405
+ type TaskListArgs = z$1.infer<typeof taskListTool.schema>;
357
406
 
358
407
  /**
359
408
  * Creates a TaskList handler that returns all tasks.
@@ -366,18 +415,18 @@ declare function createTaskListHandler<TCustom extends JsonSerializable<TCustom>
366
415
  declare const taskUpdateTool: {
367
416
  name: "TaskUpdate";
368
417
  description: string;
369
- schema: z.ZodObject<{
370
- taskId: z.ZodString;
371
- status: z.ZodEnum<{
418
+ schema: z$1.ZodObject<{
419
+ taskId: z$1.ZodString;
420
+ status: z$1.ZodEnum<{
372
421
  pending: "pending";
373
422
  in_progress: "in_progress";
374
423
  completed: "completed";
375
424
  }>;
376
- addBlockedBy: z.ZodArray<z.ZodString>;
377
- addBlocks: z.ZodArray<z.ZodString>;
378
- }, z.core.$strip>;
425
+ addBlockedBy: z$1.ZodArray<z$1.ZodString>;
426
+ addBlocks: z$1.ZodArray<z$1.ZodString>;
427
+ }, z$1.core.$strip>;
379
428
  };
380
- type TaskUpdateArgs = z.infer<typeof taskUpdateTool.schema>;
429
+ type TaskUpdateArgs = z$1.infer<typeof taskUpdateTool.schema>;
381
430
 
382
431
  /**
383
432
  * Creates a TaskUpdate handler that modifies task status and dependencies.
@@ -393,30 +442,30 @@ declare const createBashToolDescription: ({ fileTree, }: {
393
442
  declare const bashTool: {
394
443
  name: "Bash";
395
444
  description: string;
396
- schema: z.ZodObject<{
397
- command: z.ZodString;
398
- }, z.core.$strip>;
445
+ schema: z$1.ZodObject<{
446
+ command: z$1.ZodString;
447
+ }, z$1.core.$strip>;
399
448
  strict: true;
400
449
  };
401
- type BashArgs = z.infer<typeof bashTool.schema>;
450
+ type BashArgs = z$1.infer<typeof bashTool.schema>;
402
451
 
403
452
  declare const askUserQuestionTool: {
404
453
  name: "AskUserQuestion";
405
454
  description: string;
406
- schema: z.ZodObject<{
407
- questions: z.ZodArray<z.ZodObject<{
408
- question: z.ZodString;
409
- header: z.ZodString;
410
- options: z.ZodArray<z.ZodObject<{
411
- label: z.ZodString;
412
- description: z.ZodString;
413
- }, z.core.$strip>>;
414
- multiSelect: z.ZodBoolean;
415
- }, z.core.$strip>>;
416
- }, z.core.$strip>;
455
+ schema: z$1.ZodObject<{
456
+ questions: z$1.ZodArray<z$1.ZodObject<{
457
+ question: z$1.ZodString;
458
+ header: z$1.ZodString;
459
+ options: z$1.ZodArray<z$1.ZodObject<{
460
+ label: z$1.ZodString;
461
+ description: z$1.ZodString;
462
+ }, z$1.core.$strip>>;
463
+ multiSelect: z$1.ZodBoolean;
464
+ }, z$1.core.$strip>>;
465
+ }, z$1.core.$strip>;
417
466
  strict: true;
418
467
  };
419
- type AskUserQuestionArgs = z.infer<typeof askUserQuestionTool.schema>;
468
+ type AskUserQuestionArgs = z$1.infer<typeof askUserQuestionTool.schema>;
420
469
 
421
470
  /**
422
471
  * Creates a handler for the AskUserQuestion tool.
@@ -457,4 +506,4 @@ declare const createAskUserQuestionHandler: () => ActivityToolHandler<AskUserQue
457
506
  }[];
458
507
  }>;
459
508
 
460
- export { ActivityToolHandler, AgentConfig, type AgentState, type AgentStateManager, AgentStatus, type AskUserQuestionArgs, BaseAgentState, type BashArgs, type FileEditArgs, type FileReadArgs, type FileWriteArgs, type GlobArgs, type GrepArgs, type JsonPrimitive, type JsonSerializable, type JsonValue, type ReadSkillArgs, SessionConfig, SessionEndHook, SessionExitReason, type SessionLifecycleHooks, SessionStartHook, Skill, SkillMetadata, type TaskCreateArgs, type TaskGetArgs, type TaskListArgs, type TaskUpdateArgs, ThreadOps, ToolDefinition, ToolHandler, ToolHandlerResponse, ToolMap, WorkflowTask, type ZeitlichSession, askUserQuestionTool, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, editTool, getShortId, globTool, grepTool, parseSkillFile, proxyDefaultThreadOps, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, writeFileTool };
509
+ export { ActivityToolHandler, AgentStateManager, type AskUserQuestionArgs, BaseAgentState, type BashArgs, type FileEditArgs, FileEntry, FileEntryMetadata, type FileReadArgs, type FileWriteArgs, type GlobArgs, type GrepArgs, JsonSerializable, ParsedToolCallUnion, type ReadSkillArgs, RouterContext, SandboxOps, SessionConfig, Skill, SkillMetadata, type SubagentArgs, SubagentConfig, SubagentHandlerResponse, SubagentHooks, type TaskCreateArgs, type TaskGetArgs, type TaskListArgs, type TaskUpdateArgs, ThreadOps, ToolHandler, ToolHandlerResponse, ToolMap, ToolNames, ToolRouter, ToolWithHandler, TreeMutation, VirtualFileTree, WorkflowTask, ZeitlichSession, applyVirtualTreeMutations, askUserQuestionTool, bashTool, createAgentStateManager, createAskUserQuestionHandler, createBashToolDescription, createReadSkillHandler, createReadSkillTool, createSession, createTaskCreateHandler, createTaskGetHandler, createTaskListHandler, createTaskUpdateHandler, createToolRouter, defineSubagent, defineTool, editTool, formatVirtualFileTree, getShortId, globTool, grepTool, hasNoOtherToolCalls, parseSkillFile, proxyDefaultThreadOps, proxySandboxOps, readFileTool, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, writeFileTool };