@amaranthic/hernex 0.0.0-stage → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (272) hide show
  1. package/CHANGELOG.md +261 -0
  2. package/LICENSE +21 -0
  3. package/README.md +66 -2
  4. package/dist/ai.d.ts +11 -0
  5. package/dist/ai.d.ts.map +1 -0
  6. package/dist/ai.js +11 -0
  7. package/dist/ai.js.map +1 -0
  8. package/dist/checkpoints/FileCheckpointStore.d.ts +95 -0
  9. package/dist/checkpoints/FileCheckpointStore.d.ts.map +1 -0
  10. package/dist/checkpoints/FileCheckpointStore.js +502 -0
  11. package/dist/checkpoints/FileCheckpointStore.js.map +1 -0
  12. package/dist/checkpoints/index.d.ts +7 -0
  13. package/dist/checkpoints/index.d.ts.map +1 -0
  14. package/dist/checkpoints/index.js +7 -0
  15. package/dist/checkpoints/index.js.map +1 -0
  16. package/dist/checkpoints/types.d.ts +157 -0
  17. package/dist/checkpoints/types.d.ts.map +1 -0
  18. package/dist/checkpoints/types.js +6 -0
  19. package/dist/checkpoints/types.js.map +1 -0
  20. package/dist/engine/AgentEngine.d.ts +156 -0
  21. package/dist/engine/AgentEngine.d.ts.map +1 -0
  22. package/dist/engine/AgentEngine.js +290 -0
  23. package/dist/engine/AgentEngine.js.map +1 -0
  24. package/dist/engine/engineConfig.d.ts +138 -0
  25. package/dist/engine/engineConfig.d.ts.map +1 -0
  26. package/dist/engine/engineConfig.js +6 -0
  27. package/dist/engine/engineConfig.js.map +1 -0
  28. package/dist/engine/eventQueue.d.ts +42 -0
  29. package/dist/engine/eventQueue.d.ts.map +1 -0
  30. package/dist/engine/eventQueue.js +93 -0
  31. package/dist/engine/eventQueue.js.map +1 -0
  32. package/dist/engine/index.d.ts +7 -0
  33. package/dist/engine/index.d.ts.map +1 -0
  34. package/dist/engine/index.js +6 -0
  35. package/dist/engine/index.js.map +1 -0
  36. package/dist/engine/runTurn.d.ts +17 -0
  37. package/dist/engine/runTurn.d.ts.map +1 -0
  38. package/dist/engine/runTurn.js +718 -0
  39. package/dist/engine/runTurn.js.map +1 -0
  40. package/dist/errors.d.ts +194 -0
  41. package/dist/errors.d.ts.map +1 -0
  42. package/dist/errors.js +219 -0
  43. package/dist/errors.js.map +1 -0
  44. package/dist/events/checkpointEvents.d.ts +20 -0
  45. package/dist/events/checkpointEvents.d.ts.map +1 -0
  46. package/dist/events/checkpointEvents.js +6 -0
  47. package/dist/events/checkpointEvents.js.map +1 -0
  48. package/dist/events/errorEvents.d.ts +23 -0
  49. package/dist/events/errorEvents.d.ts.map +1 -0
  50. package/dist/events/errorEvents.js +6 -0
  51. package/dist/events/errorEvents.js.map +1 -0
  52. package/dist/events/index.d.ts +11 -0
  53. package/dist/events/index.d.ts.map +1 -0
  54. package/dist/events/index.js +6 -0
  55. package/dist/events/index.js.map +1 -0
  56. package/dist/events/stepEvents.d.ts +68 -0
  57. package/dist/events/stepEvents.d.ts.map +1 -0
  58. package/dist/events/stepEvents.js +6 -0
  59. package/dist/events/stepEvents.js.map +1 -0
  60. package/dist/events/streamEvents.d.ts +41 -0
  61. package/dist/events/streamEvents.d.ts.map +1 -0
  62. package/dist/events/streamEvents.js +6 -0
  63. package/dist/events/streamEvents.js.map +1 -0
  64. package/dist/events/toolEvents.d.ts +64 -0
  65. package/dist/events/toolEvents.d.ts.map +1 -0
  66. package/dist/events/toolEvents.js +6 -0
  67. package/dist/events/toolEvents.js.map +1 -0
  68. package/dist/events/types.d.ts +44 -0
  69. package/dist/events/types.d.ts.map +1 -0
  70. package/dist/events/types.js +25 -0
  71. package/dist/events/types.js.map +1 -0
  72. package/dist/hooks/composeAgentHooks.d.ts +14 -0
  73. package/dist/hooks/composeAgentHooks.d.ts.map +1 -0
  74. package/dist/hooks/composeAgentHooks.js +154 -0
  75. package/dist/hooks/composeAgentHooks.js.map +1 -0
  76. package/dist/hooks/index.d.ts +7 -0
  77. package/dist/hooks/index.d.ts.map +1 -0
  78. package/dist/hooks/index.js +6 -0
  79. package/dist/hooks/index.js.map +1 -0
  80. package/dist/hooks/types.d.ts +133 -0
  81. package/dist/hooks/types.d.ts.map +1 -0
  82. package/dist/hooks/types.js +6 -0
  83. package/dist/hooks/types.js.map +1 -0
  84. package/dist/index.d.ts +28 -0
  85. package/dist/index.d.ts.map +1 -0
  86. package/dist/index.js +26 -0
  87. package/dist/index.js.map +1 -0
  88. package/dist/model/ProviderRegistry.d.ts +62 -0
  89. package/dist/model/ProviderRegistry.d.ts.map +1 -0
  90. package/dist/model/ProviderRegistry.js +114 -0
  91. package/dist/model/ProviderRegistry.js.map +1 -0
  92. package/dist/model/providers/alibaba.d.ts +11 -0
  93. package/dist/model/providers/alibaba.d.ts.map +1 -0
  94. package/dist/model/providers/alibaba.js +16 -0
  95. package/dist/model/providers/alibaba.js.map +1 -0
  96. package/dist/model/providers/anthropic.d.ts +11 -0
  97. package/dist/model/providers/anthropic.d.ts.map +1 -0
  98. package/dist/model/providers/anthropic.js +16 -0
  99. package/dist/model/providers/anthropic.js.map +1 -0
  100. package/dist/model/providers/cohere.d.ts +11 -0
  101. package/dist/model/providers/cohere.d.ts.map +1 -0
  102. package/dist/model/providers/cohere.js +16 -0
  103. package/dist/model/providers/cohere.js.map +1 -0
  104. package/dist/model/providers/compatible.d.ts +11 -0
  105. package/dist/model/providers/compatible.d.ts.map +1 -0
  106. package/dist/model/providers/compatible.js +17 -0
  107. package/dist/model/providers/compatible.js.map +1 -0
  108. package/dist/model/providers/deepseek.d.ts +11 -0
  109. package/dist/model/providers/deepseek.d.ts.map +1 -0
  110. package/dist/model/providers/deepseek.js +16 -0
  111. package/dist/model/providers/deepseek.js.map +1 -0
  112. package/dist/model/providers/google.d.ts +11 -0
  113. package/dist/model/providers/google.d.ts.map +1 -0
  114. package/dist/model/providers/google.js +16 -0
  115. package/dist/model/providers/google.js.map +1 -0
  116. package/dist/model/providers/groq.d.ts +11 -0
  117. package/dist/model/providers/groq.d.ts.map +1 -0
  118. package/dist/model/providers/groq.js +16 -0
  119. package/dist/model/providers/groq.js.map +1 -0
  120. package/dist/model/providers/mistral.d.ts +11 -0
  121. package/dist/model/providers/mistral.d.ts.map +1 -0
  122. package/dist/model/providers/mistral.js +16 -0
  123. package/dist/model/providers/mistral.js.map +1 -0
  124. package/dist/model/providers/openai.d.ts +11 -0
  125. package/dist/model/providers/openai.d.ts.map +1 -0
  126. package/dist/model/providers/openai.js +16 -0
  127. package/dist/model/providers/openai.js.map +1 -0
  128. package/dist/model/providers/openrouter.d.ts +14 -0
  129. package/dist/model/providers/openrouter.d.ts.map +1 -0
  130. package/dist/model/providers/openrouter.js +20 -0
  131. package/dist/model/providers/openrouter.js.map +1 -0
  132. package/dist/model/providers/togetherai.d.ts +11 -0
  133. package/dist/model/providers/togetherai.d.ts.map +1 -0
  134. package/dist/model/providers/togetherai.js +16 -0
  135. package/dist/model/providers/togetherai.js.map +1 -0
  136. package/dist/model/providers/vercelGateway.d.ts +14 -0
  137. package/dist/model/providers/vercelGateway.d.ts.map +1 -0
  138. package/dist/model/providers/vercelGateway.js +19 -0
  139. package/dist/model/providers/vercelGateway.js.map +1 -0
  140. package/dist/model/providers/xai.d.ts +11 -0
  141. package/dist/model/providers/xai.d.ts.map +1 -0
  142. package/dist/model/providers/xai.js +16 -0
  143. package/dist/model/providers/xai.js.map +1 -0
  144. package/dist/model/resolveModel.d.ts +45 -0
  145. package/dist/model/resolveModel.d.ts.map +1 -0
  146. package/dist/model/resolveModel.js +109 -0
  147. package/dist/model/resolveModel.js.map +1 -0
  148. package/dist/model/types.d.ts +98 -0
  149. package/dist/model/types.d.ts.map +1 -0
  150. package/dist/model/types.js +6 -0
  151. package/dist/model/types.js.map +1 -0
  152. package/dist/runtime.d.ts +74 -0
  153. package/dist/runtime.d.ts.map +1 -0
  154. package/dist/runtime.js +41 -0
  155. package/dist/runtime.js.map +1 -0
  156. package/dist/storage/atomicFile.d.ts +28 -0
  157. package/dist/storage/atomicFile.d.ts.map +1 -0
  158. package/dist/storage/atomicFile.js +82 -0
  159. package/dist/storage/atomicFile.js.map +1 -0
  160. package/dist/storage/homeDirectory.d.ts +21 -0
  161. package/dist/storage/homeDirectory.d.ts.map +1 -0
  162. package/dist/storage/homeDirectory.js +36 -0
  163. package/dist/storage/homeDirectory.js.map +1 -0
  164. package/dist/storage/index.d.ts +11 -0
  165. package/dist/storage/index.d.ts.map +1 -0
  166. package/dist/storage/index.js +11 -0
  167. package/dist/storage/index.js.map +1 -0
  168. package/dist/storage/jsonl.d.ts +55 -0
  169. package/dist/storage/jsonl.d.ts.map +1 -0
  170. package/dist/storage/jsonl.js +142 -0
  171. package/dist/storage/jsonl.js.map +1 -0
  172. package/dist/storage/lock.d.ts +70 -0
  173. package/dist/storage/lock.d.ts.map +1 -0
  174. package/dist/storage/lock.js +274 -0
  175. package/dist/storage/lock.js.map +1 -0
  176. package/dist/storage/valueCodec.d.ts +74 -0
  177. package/dist/storage/valueCodec.d.ts.map +1 -0
  178. package/dist/storage/valueCodec.js +165 -0
  179. package/dist/storage/valueCodec.js.map +1 -0
  180. package/dist/storage/workspaceLock.d.ts +38 -0
  181. package/dist/storage/workspaceLock.d.ts.map +1 -0
  182. package/dist/storage/workspaceLock.js +77 -0
  183. package/dist/storage/workspaceLock.js.map +1 -0
  184. package/dist/tasks/TaskManager.d.ts +155 -0
  185. package/dist/tasks/TaskManager.d.ts.map +1 -0
  186. package/dist/tasks/TaskManager.js +810 -0
  187. package/dist/tasks/TaskManager.js.map +1 -0
  188. package/dist/tasks/index.d.ts +7 -0
  189. package/dist/tasks/index.d.ts.map +1 -0
  190. package/dist/tasks/index.js +6 -0
  191. package/dist/tasks/index.js.map +1 -0
  192. package/dist/tasks/types.d.ts +166 -0
  193. package/dist/tasks/types.d.ts.map +1 -0
  194. package/dist/tasks/types.js +8 -0
  195. package/dist/tasks/types.js.map +1 -0
  196. package/dist/threads/FileThreadStore.d.ts +118 -0
  197. package/dist/threads/FileThreadStore.d.ts.map +1 -0
  198. package/dist/threads/FileThreadStore.js +324 -0
  199. package/dist/threads/FileThreadStore.js.map +1 -0
  200. package/dist/threads/index.d.ts +9 -0
  201. package/dist/threads/index.d.ts.map +1 -0
  202. package/dist/threads/index.js +9 -0
  203. package/dist/threads/index.js.map +1 -0
  204. package/dist/threads/transcriptMigration.d.ts +52 -0
  205. package/dist/threads/transcriptMigration.d.ts.map +1 -0
  206. package/dist/threads/transcriptMigration.js +100 -0
  207. package/dist/threads/transcriptMigration.js.map +1 -0
  208. package/dist/threads/transcriptProjection.d.ts +21 -0
  209. package/dist/threads/transcriptProjection.d.ts.map +1 -0
  210. package/dist/threads/transcriptProjection.js +123 -0
  211. package/dist/threads/transcriptProjection.js.map +1 -0
  212. package/dist/threads/types.d.ts +250 -0
  213. package/dist/threads/types.d.ts.map +1 -0
  214. package/dist/threads/types.js +6 -0
  215. package/dist/threads/types.js.map +1 -0
  216. package/dist/tools/AgentTool.d.ts +38 -0
  217. package/dist/tools/AgentTool.d.ts.map +1 -0
  218. package/dist/tools/AgentTool.js +6 -0
  219. package/dist/tools/AgentTool.js.map +1 -0
  220. package/dist/tools/BashTool.d.ts +61 -0
  221. package/dist/tools/BashTool.d.ts.map +1 -0
  222. package/dist/tools/BashTool.js +158 -0
  223. package/dist/tools/BashTool.js.map +1 -0
  224. package/dist/tools/EditFileTool.d.ts +49 -0
  225. package/dist/tools/EditFileTool.d.ts.map +1 -0
  226. package/dist/tools/EditFileTool.js +119 -0
  227. package/dist/tools/EditFileTool.js.map +1 -0
  228. package/dist/tools/GlobTool.d.ts +48 -0
  229. package/dist/tools/GlobTool.d.ts.map +1 -0
  230. package/dist/tools/GlobTool.js +117 -0
  231. package/dist/tools/GlobTool.js.map +1 -0
  232. package/dist/tools/GrepTool.d.ts +76 -0
  233. package/dist/tools/GrepTool.d.ts.map +1 -0
  234. package/dist/tools/GrepTool.js +276 -0
  235. package/dist/tools/GrepTool.js.map +1 -0
  236. package/dist/tools/ReadFileTool.d.ts +51 -0
  237. package/dist/tools/ReadFileTool.d.ts.map +1 -0
  238. package/dist/tools/ReadFileTool.js +153 -0
  239. package/dist/tools/ReadFileTool.js.map +1 -0
  240. package/dist/tools/TaskManagerTool.d.ts +102 -0
  241. package/dist/tools/TaskManagerTool.d.ts.map +1 -0
  242. package/dist/tools/TaskManagerTool.js +132 -0
  243. package/dist/tools/TaskManagerTool.js.map +1 -0
  244. package/dist/tools/ToolExecutionContext.d.ts +61 -0
  245. package/dist/tools/ToolExecutionContext.d.ts.map +1 -0
  246. package/dist/tools/ToolExecutionContext.js +8 -0
  247. package/dist/tools/ToolExecutionContext.js.map +1 -0
  248. package/dist/tools/ToolRegistry.d.ts +82 -0
  249. package/dist/tools/ToolRegistry.d.ts.map +1 -0
  250. package/dist/tools/ToolRegistry.js +116 -0
  251. package/dist/tools/ToolRegistry.js.map +1 -0
  252. package/dist/tools/WriteFileTool.d.ts +46 -0
  253. package/dist/tools/WriteFileTool.d.ts.map +1 -0
  254. package/dist/tools/WriteFileTool.js +92 -0
  255. package/dist/tools/WriteFileTool.js.map +1 -0
  256. package/dist/tools/index.d.ts +17 -0
  257. package/dist/tools/index.d.ts.map +1 -0
  258. package/dist/tools/index.js +17 -0
  259. package/dist/tools/index.js.map +1 -0
  260. package/dist/tools/internal/bashEnvironment.d.ts +20 -0
  261. package/dist/tools/internal/bashEnvironment.d.ts.map +1 -0
  262. package/dist/tools/internal/bashEnvironment.js +65 -0
  263. package/dist/tools/internal/bashEnvironment.js.map +1 -0
  264. package/dist/tools/internal/pathGuard.d.ts +27 -0
  265. package/dist/tools/internal/pathGuard.d.ts.map +1 -0
  266. package/dist/tools/internal/pathGuard.js +99 -0
  267. package/dist/tools/internal/pathGuard.js.map +1 -0
  268. package/dist/tools/prompts.d.ts +33 -0
  269. package/dist/tools/prompts.d.ts.map +1 -0
  270. package/dist/tools/prompts.js +48 -0
  271. package/dist/tools/prompts.js.map +1 -0
  272. package/package.json +65 -4
@@ -0,0 +1,718 @@
1
+ /**
2
+ * @fileoverview Autonomous multi-step turn runner for the agent engine microkernel.
3
+ * @packageDocumentation
4
+ */
5
+ import { streamText } from "../runtime.js";
6
+ import { AsyncEventQueue } from "./eventQueue.js";
7
+ import { CURRENT_TRANSCRIPT_VERSION } from "../threads/transcriptMigration.js";
8
+ /**
9
+ * Extracts normalized provider identifier from a model string if formatted as "provider/model_id".
10
+ */
11
+ function getModelProvider(model) {
12
+ if (typeof model === "string") {
13
+ const slashIndex = model.indexOf("/");
14
+ if (slashIndex > 0) {
15
+ return model.slice(0, slashIndex).trim().toLowerCase();
16
+ }
17
+ }
18
+ return undefined;
19
+ }
20
+ /**
21
+ * Converts any unknown error into a normalized serializable ErrorInfo object.
22
+ */
23
+ function toErrorInfo(error) {
24
+ if (error instanceof Error) {
25
+ return {
26
+ name: error.name,
27
+ message: error.message,
28
+ ...(error.stack ? { stack: error.stack } : {}),
29
+ ...(typeof error.code === "string"
30
+ ? { code: error.code }
31
+ : {}),
32
+ };
33
+ }
34
+ return {
35
+ name: "Error",
36
+ message: String(error),
37
+ };
38
+ }
39
+ /**
40
+ * Converts any arbitrary value into pure serializable JSON-compatible data.
41
+ */
42
+ function toJsonValue(value) {
43
+ if (value === null ||
44
+ typeof value === "boolean" ||
45
+ typeof value === "number" ||
46
+ typeof value === "string") {
47
+ return value;
48
+ }
49
+ try {
50
+ return JSON.parse(JSON.stringify(value));
51
+ }
52
+ catch {
53
+ return String(value);
54
+ }
55
+ }
56
+ /**
57
+ * Combines multiple AbortSignal instances into a single signal.
58
+ */
59
+ function combineAbortSignals(...signals) {
60
+ const activeSignals = signals.filter((s) => Boolean(s));
61
+ if (activeSignals.length === 0)
62
+ return undefined;
63
+ if (activeSignals.length === 1)
64
+ return activeSignals[0];
65
+ if (typeof AbortSignal.any === "function") {
66
+ return AbortSignal.any(activeSignals);
67
+ }
68
+ const controller = new AbortController();
69
+ for (const signal of activeSignals) {
70
+ if (signal.aborted) {
71
+ controller.abort(signal.reason);
72
+ return controller.signal;
73
+ }
74
+ signal.addEventListener("abort", () => controller.abort(signal.reason), {
75
+ once: true,
76
+ });
77
+ }
78
+ return controller.signal;
79
+ }
80
+ /**
81
+ * Runs a single autonomous turn within the agent engine microkernel.
82
+ *
83
+ * @param config - The active engine configuration.
84
+ * @param options - Per-turn options including user prompt and overrides.
85
+ * @param conversationMessages - Mutable array of thread conversation messages.
86
+ * @returns An async generator yielding pure serializable `AgentEvent` objects.
87
+ */
88
+ export async function* runTurn(config, options, conversationMessages) {
89
+ const turnIndex = options.turnIndex ?? 1;
90
+ const userPrompt = options.userPrompt;
91
+ const turnAbortController = new AbortController();
92
+ const effectiveSignal = combineAbortSignals(options.abortSignal, config.abortSignal, turnAbortController.signal);
93
+ const maxSteps = options.maxSteps ?? config.maxSteps ?? 25;
94
+ const reasoning = options.reasoning ?? config.reasoning;
95
+ // Persistence and Checkpoint invariants: if persist is false, checkpoint is strictly false
96
+ const isPersist = Boolean(config.persist ?? Boolean(config.threadStore));
97
+ const isCheckpointEnabled = isPersist && Boolean(config.checkpoint ?? Boolean(config.checkpointStore));
98
+ let totalPromptTokens = 0;
99
+ let totalCompletionTokens = 0;
100
+ let totalTokens = 0;
101
+ let totalReasoningTokens = 0;
102
+ const buildTotalUsage = () => {
103
+ const usage = {
104
+ promptTokens: totalPromptTokens,
105
+ completionTokens: totalCompletionTokens,
106
+ totalTokens,
107
+ };
108
+ if (totalReasoningTokens > 0) {
109
+ usage.reasoningTokens = totalReasoningTokens;
110
+ }
111
+ return usage;
112
+ };
113
+ let finishReason = "completed";
114
+ const initialHistoryLength = conversationMessages.length;
115
+ let hasEmittedTurnFinished = false;
116
+ const finalizeTurn = async function* (finalReason) {
117
+ if (hasEmittedTurnFinished) {
118
+ return;
119
+ }
120
+ hasEmittedTurnFinished = true;
121
+ // 1. Persist turnFinished to thread store FIRST
122
+ if (config.threadStore) {
123
+ try {
124
+ await config.threadStore.appendTranscript(config.threadId, {
125
+ version: CURRENT_TRANSCRIPT_VERSION,
126
+ type: "turnFinished",
127
+ turnIndex,
128
+ finishReason: finalReason,
129
+ usage: buildTotalUsage(),
130
+ timestamp: Date.now(),
131
+ });
132
+ }
133
+ catch (persistenceError) {
134
+ // Emit error as non-fatal secondary diagnostic; do not crash terminal event emission
135
+ yield {
136
+ type: "error",
137
+ origin: "engine",
138
+ error: toErrorInfo(persistenceError instanceof Error
139
+ ? persistenceError
140
+ : new Error(String(persistenceError))),
141
+ isFatal: false,
142
+ };
143
+ }
144
+ }
145
+ // 2. Emit turnFinished event exactly once
146
+ yield {
147
+ type: "turnFinished",
148
+ turnIndex,
149
+ finishReason: finalReason,
150
+ totalUsage: buildTotalUsage(),
151
+ };
152
+ };
153
+ try {
154
+ // Partial credential override check
155
+ const hasPartialApiKey = options.apiKey !== undefined;
156
+ const hasPartialBaseUrl = options.baseUrl !== undefined;
157
+ if ((hasPartialApiKey && !hasPartialBaseUrl) ||
158
+ (!hasPartialApiKey && hasPartialBaseUrl)) {
159
+ throw new Error("Per-turn credential override is incomplete: both apiKey and baseUrl must be provided together.");
160
+ }
161
+ // Credential invariant check: ensure per-turn model cannot silently reuse another provider's credentials
162
+ if (options.model !== undefined) {
163
+ const isConfigString = typeof config.model === "string";
164
+ const isOverrideString = typeof options.model === "string";
165
+ if (!isConfigString || !isOverrideString) {
166
+ if (!options.apiKey || !options.baseUrl) {
167
+ throw new Error("Per-turn model override with LanguageModel instance requires explicit per-turn credentials (both apiKey and baseUrl).");
168
+ }
169
+ }
170
+ else {
171
+ const configProvider = getModelProvider(config.model);
172
+ const overrideProvider = getModelProvider(options.model);
173
+ if (overrideProvider &&
174
+ configProvider &&
175
+ overrideProvider !== configProvider &&
176
+ (!options.apiKey || !options.baseUrl)) {
177
+ throw new Error(`Per-turn model override changed provider from "${configProvider}" to "${overrideProvider}", but explicit per-turn credentials (apiKey and baseUrl) were not supplied. Falling back across different providers is forbidden.`);
178
+ }
179
+ }
180
+ }
181
+ // 1. Emit 'turnStarted'
182
+ yield {
183
+ type: "turnStarted",
184
+ turnIndex,
185
+ userMessage: userPrompt,
186
+ };
187
+ if (config.threadStore) {
188
+ await config.threadStore.appendTranscript(config.threadId, {
189
+ version: CURRENT_TRANSCRIPT_VERSION,
190
+ type: "turnStarted",
191
+ turnIndex,
192
+ userPrompt,
193
+ timestamp: Date.now(),
194
+ });
195
+ }
196
+ // 2. Call hooks.onBeforeTurn() -> await product decision
197
+ let effectiveUserPrompt = userPrompt;
198
+ let injectedInstructions = "";
199
+ if (config.hooks?.onBeforeTurn) {
200
+ const beforeTurnResult = await config.hooks.onBeforeTurn({
201
+ turnIndex,
202
+ userPrompt,
203
+ });
204
+ if (beforeTurnResult) {
205
+ if (beforeTurnResult.veto) {
206
+ finishReason = "vetoed";
207
+ yield* finalizeTurn("vetoed");
208
+ return;
209
+ }
210
+ if (beforeTurnResult.userPrompt) {
211
+ effectiveUserPrompt = beforeTurnResult.userPrompt;
212
+ }
213
+ if (beforeTurnResult.injectedInstructions) {
214
+ injectedInstructions = beforeTurnResult.injectedInstructions;
215
+ }
216
+ }
217
+ }
218
+ // Append user message to conversation history
219
+ const userMessage = {
220
+ role: "user",
221
+ content: effectiveUserPrompt,
222
+ };
223
+ conversationMessages.push(userMessage);
224
+ if (config.threadStore) {
225
+ await config.threadStore.appendTranscript(config.threadId, {
226
+ version: CURRENT_TRANSCRIPT_VERSION,
227
+ type: "modelMessage",
228
+ turnIndex,
229
+ message: userMessage,
230
+ timestamp: Date.now(),
231
+ });
232
+ }
233
+ // Combined instructions for this turn
234
+ const combinedInstructions = [config.instructions, injectedInstructions]
235
+ .filter((s) => Boolean(s && s.trim().length > 0))
236
+ .join("\n\n");
237
+ // 3. Step Loop (1 to maxSteps)
238
+ for (let stepIndex = 1; stepIndex <= maxSteps; stepIndex++) {
239
+ if (effectiveSignal?.aborted) {
240
+ finishReason = "interrupted";
241
+ break;
242
+ }
243
+ yield {
244
+ type: "stepStarted",
245
+ stepIndex,
246
+ timestamp: Date.now(),
247
+ };
248
+ const sdkToolDefinitions = config.tools.toSdkToolDefinitions();
249
+ const hasTools = Object.keys(sdkToolDefinitions).length > 0;
250
+ const streamOptions = {
251
+ model: options.model ?? config.model,
252
+ apiKey: options.apiKey ?? config.apiKey,
253
+ baseUrl: options.baseUrl ?? config.baseUrl,
254
+ ...(config.providerRegistry
255
+ ? { providerRegistry: config.providerRegistry }
256
+ : {}),
257
+ messages: conversationMessages,
258
+ ...(combinedInstructions ? { instructions: combinedInstructions } : {}),
259
+ ...(hasTools ? { tools: sdkToolDefinitions } : {}),
260
+ ...(reasoning ? { reasoning } : {}),
261
+ ...(effectiveSignal ? { abortSignal: effectiveSignal } : {}),
262
+ };
263
+ const proposedToolCalls = [];
264
+ const streamResult = streamText(streamOptions);
265
+ for await (const chunk of streamResult.stream) {
266
+ if (chunk.type === "text-delta") {
267
+ yield {
268
+ type: "tokenDelta",
269
+ text: chunk.text,
270
+ messageId: chunk.id,
271
+ };
272
+ }
273
+ else if (chunk.type === "reasoning-delta") {
274
+ yield {
275
+ type: "thoughtDelta",
276
+ text: chunk.text,
277
+ messageId: chunk.id,
278
+ };
279
+ }
280
+ else if (chunk.type === "tool-call") {
281
+ const toolCall = {
282
+ callId: chunk.toolCallId,
283
+ toolName: chunk.toolName,
284
+ parameters: chunk.input,
285
+ };
286
+ proposedToolCalls.push(toolCall);
287
+ yield {
288
+ type: "toolCallProposed",
289
+ callId: toolCall.callId,
290
+ toolName: toolCall.toolName,
291
+ parameters: toJsonValue(toolCall.parameters),
292
+ };
293
+ }
294
+ else if (chunk.type === "error") {
295
+ const streamError = chunk.error instanceof Error
296
+ ? chunk.error
297
+ : new Error(String(chunk.error));
298
+ yield {
299
+ type: "error",
300
+ origin: "model",
301
+ error: toErrorInfo(streamError),
302
+ isFatal: false,
303
+ };
304
+ }
305
+ }
306
+ const responseMessages = [
307
+ ...(await streamResult.responseMessages),
308
+ ];
309
+ const rawUsage = await streamResult.usage;
310
+ // Collect assistant response messages and step token metrics
311
+ conversationMessages.push(...responseMessages);
312
+ if (config.threadStore) {
313
+ for (const msg of responseMessages) {
314
+ await config.threadStore.appendTranscript(config.threadId, {
315
+ version: CURRENT_TRANSCRIPT_VERSION,
316
+ type: "modelMessage",
317
+ turnIndex,
318
+ message: msg,
319
+ timestamp: Date.now(),
320
+ });
321
+ }
322
+ }
323
+ const stepUsage = {
324
+ promptTokens: rawUsage.inputTokens ?? 0,
325
+ completionTokens: rawUsage.outputTokens ?? 0,
326
+ totalTokens: rawUsage.totalTokens ?? 0,
327
+ ...(typeof rawUsage.outputTokenDetails?.reasoningTokens === "number"
328
+ ? { reasoningTokens: rawUsage.outputTokenDetails.reasoningTokens }
329
+ : {}),
330
+ };
331
+ totalPromptTokens += stepUsage.promptTokens;
332
+ totalCompletionTokens += stepUsage.completionTokens;
333
+ totalTokens += stepUsage.totalTokens;
334
+ if (stepUsage.reasoningTokens) {
335
+ totalReasoningTokens += stepUsage.reasoningTokens;
336
+ }
337
+ // If the model called no tools, evaluate whether stopping is allowed
338
+ if (proposedToolCalls.length === 0) {
339
+ if (config.hooks?.onShouldStop) {
340
+ const stopDecision = await config.hooks.onShouldStop({
341
+ turnIndex,
342
+ finishReason: "completed",
343
+ transcript: conversationMessages,
344
+ });
345
+ if (!stopDecision.shouldStop) {
346
+ const reminderMessage = {
347
+ role: "user",
348
+ content: stopDecision.reminderPrompt,
349
+ };
350
+ conversationMessages.push(reminderMessage);
351
+ if (config.threadStore) {
352
+ await config.threadStore.appendTranscript(config.threadId, {
353
+ version: CURRENT_TRANSCRIPT_VERSION,
354
+ type: "modelMessage",
355
+ turnIndex,
356
+ message: reminderMessage,
357
+ timestamp: Date.now(),
358
+ });
359
+ }
360
+ yield {
361
+ type: "stepFinished",
362
+ stepIndex,
363
+ usage: stepUsage,
364
+ };
365
+ continue;
366
+ }
367
+ }
368
+ yield {
369
+ type: "stepFinished",
370
+ stepIndex,
371
+ usage: stepUsage,
372
+ };
373
+ finishReason = "completed";
374
+ break;
375
+ }
376
+ // Execute proposed tools
377
+ const toolResults = [];
378
+ for (const toolCall of proposedToolCalls) {
379
+ if (effectiveSignal?.aborted) {
380
+ finishReason = "interrupted";
381
+ break;
382
+ }
383
+ const agentTool = config.tools.resolve(toolCall.toolName);
384
+ if (!agentTool) {
385
+ const missingErrorResult = {
386
+ isError: true,
387
+ error: `Tool "${toolCall.toolName}" is not registered in the tool registry.`,
388
+ };
389
+ yield {
390
+ type: "toolExecutionFinished",
391
+ callId: toolCall.callId,
392
+ toolName: toolCall.toolName,
393
+ result: toJsonValue(missingErrorResult),
394
+ isError: true,
395
+ durationMs: 0,
396
+ };
397
+ toolResults.push({
398
+ toolCallId: toolCall.callId,
399
+ toolName: toolCall.toolName,
400
+ result: missingErrorResult,
401
+ isError: true,
402
+ });
403
+ if (config.threadStore) {
404
+ await config.threadStore.appendTranscript(config.threadId, {
405
+ version: CURRENT_TRANSCRIPT_VERSION,
406
+ type: "toolResult",
407
+ turnIndex,
408
+ callId: toolCall.callId,
409
+ toolName: toolCall.toolName,
410
+ result: missingErrorResult,
411
+ isError: true,
412
+ timestamp: Date.now(),
413
+ });
414
+ }
415
+ continue;
416
+ }
417
+ // Validate tool input parameters before authorization
418
+ let parsedParameters;
419
+ try {
420
+ parsedParameters = agentTool.inputSchema.parse(toolCall.parameters);
421
+ }
422
+ catch (validationError) {
423
+ const schemaErrorResult = {
424
+ isError: true,
425
+ error: `Schema validation error for tool "${toolCall.toolName}": ${validationError instanceof Error ? validationError.message : String(validationError)}`,
426
+ };
427
+ yield {
428
+ type: "toolExecutionFinished",
429
+ callId: toolCall.callId,
430
+ toolName: toolCall.toolName,
431
+ result: toJsonValue(schemaErrorResult),
432
+ isError: true,
433
+ durationMs: 0,
434
+ };
435
+ toolResults.push({
436
+ toolCallId: toolCall.callId,
437
+ toolName: toolCall.toolName,
438
+ result: schemaErrorResult,
439
+ isError: true,
440
+ });
441
+ if (config.threadStore) {
442
+ await config.threadStore.appendTranscript(config.threadId, {
443
+ version: CURRENT_TRANSCRIPT_VERSION,
444
+ type: "toolResult",
445
+ turnIndex,
446
+ callId: toolCall.callId,
447
+ toolName: toolCall.toolName,
448
+ result: schemaErrorResult,
449
+ isError: true,
450
+ timestamp: Date.now(),
451
+ });
452
+ }
453
+ continue;
454
+ }
455
+ // Tool authorization check - FAIL CLOSED BY DEFAULT FOR ALL TOOLS
456
+ let isAllowed = false;
457
+ let denialReason = "Tool execution denied: no authorization policy configured. All tools fail closed by default.";
458
+ if (config.hooks?.onAuthorizeTool) {
459
+ try {
460
+ const decision = await config.hooks.onAuthorizeTool({
461
+ toolName: toolCall.toolName,
462
+ parameters: parsedParameters,
463
+ workingDirectory: config.workingDirectory,
464
+ });
465
+ if (decision.decision === "allow") {
466
+ isAllowed = true;
467
+ }
468
+ else if (decision.decision === "deny") {
469
+ isAllowed = false;
470
+ denialReason = decision.reason;
471
+ }
472
+ }
473
+ catch (authError) {
474
+ isAllowed = false;
475
+ const authErrorInstance = authError instanceof Error
476
+ ? authError
477
+ : new Error(String(authError));
478
+ denialReason = `Authorization check failed: ${authErrorInstance.message}`;
479
+ yield {
480
+ type: "error",
481
+ origin: "hook",
482
+ error: toErrorInfo(authErrorInstance),
483
+ toolName: toolCall.toolName,
484
+ hookName: "onAuthorizeTool",
485
+ isFatal: false,
486
+ };
487
+ if (config.hooks?.onError) {
488
+ try {
489
+ await config.hooks.onError({
490
+ error: authErrorInstance,
491
+ origin: "hook",
492
+ toolName: toolCall.toolName,
493
+ hookName: "onAuthorizeTool",
494
+ turnIndex,
495
+ isFatal: false,
496
+ });
497
+ }
498
+ catch {
499
+ // Do not recursively handle hook errors
500
+ }
501
+ }
502
+ }
503
+ }
504
+ if (!isAllowed) {
505
+ const denialResult = {
506
+ isError: true,
507
+ error: denialReason,
508
+ };
509
+ yield {
510
+ type: "toolExecutionFinished",
511
+ callId: toolCall.callId,
512
+ toolName: toolCall.toolName,
513
+ result: toJsonValue(denialResult),
514
+ isError: true,
515
+ durationMs: 0,
516
+ };
517
+ toolResults.push({
518
+ toolCallId: toolCall.callId,
519
+ toolName: toolCall.toolName,
520
+ result: denialResult,
521
+ isError: true,
522
+ });
523
+ if (config.threadStore) {
524
+ await config.threadStore.appendTranscript(config.threadId, {
525
+ version: CURRENT_TRANSCRIPT_VERSION,
526
+ type: "toolResult",
527
+ turnIndex,
528
+ callId: toolCall.callId,
529
+ toolName: toolCall.toolName,
530
+ result: denialResult,
531
+ isError: true,
532
+ timestamp: Date.now(),
533
+ });
534
+ }
535
+ continue;
536
+ }
537
+ // Execute authorized tool
538
+ const startTime = Date.now();
539
+ yield {
540
+ type: "toolExecutionStarted",
541
+ callId: toolCall.callId,
542
+ toolName: toolCall.toolName,
543
+ timestamp: startTime,
544
+ };
545
+ const progressQueue = new AsyncEventQueue();
546
+ const executionContext = {
547
+ threadId: config.threadId,
548
+ toolCallId: toolCall.callId,
549
+ workingDirectory: config.workingDirectory,
550
+ turnIndex,
551
+ abortSignal: effectiveSignal,
552
+ checkpointStore: config.checkpointStore,
553
+ isCheckpointEnabled,
554
+ taskManager: config.taskManager,
555
+ onCheckpointCreated: (evt) => {
556
+ const checkpointEvent = {
557
+ type: "checkpointCreated",
558
+ checkpointId: evt.checkpointId,
559
+ sequence: evt.sequence,
560
+ label: evt.label,
561
+ filesTouched: evt.filesTouched,
562
+ };
563
+ progressQueue.push(checkpointEvent);
564
+ },
565
+ emitProgress: (chunk) => {
566
+ progressQueue.push({
567
+ type: "toolExecutionDelta",
568
+ callId: toolCall.callId,
569
+ toolName: toolCall.toolName,
570
+ chunk,
571
+ });
572
+ },
573
+ };
574
+ let executionResult;
575
+ let isToolError = false;
576
+ const executionPromise = (async () => {
577
+ try {
578
+ return await agentTool.execute(parsedParameters, executionContext);
579
+ }
580
+ catch (execError) {
581
+ isToolError = true;
582
+ return {
583
+ isError: true,
584
+ error: execError instanceof Error
585
+ ? execError.message
586
+ : String(execError),
587
+ };
588
+ }
589
+ finally {
590
+ progressQueue.close();
591
+ }
592
+ })();
593
+ // Yield queued delta and checkpoint events as they arrive
594
+ for await (const progressEvent of progressQueue) {
595
+ yield progressEvent;
596
+ }
597
+ executionResult = await executionPromise;
598
+ if (executionResult !== null &&
599
+ typeof executionResult === "object" &&
600
+ "isError" in executionResult &&
601
+ executionResult.isError === true) {
602
+ isToolError = true;
603
+ }
604
+ const durationMs = Date.now() - startTime;
605
+ yield {
606
+ type: "toolExecutionFinished",
607
+ callId: toolCall.callId,
608
+ toolName: toolCall.toolName,
609
+ result: toJsonValue(executionResult),
610
+ isError: isToolError,
611
+ durationMs,
612
+ };
613
+ toolResults.push({
614
+ toolCallId: toolCall.callId,
615
+ toolName: toolCall.toolName,
616
+ result: executionResult,
617
+ isError: isToolError,
618
+ });
619
+ if (config.threadStore) {
620
+ await config.threadStore.appendTranscript(config.threadId, {
621
+ version: CURRENT_TRANSCRIPT_VERSION,
622
+ type: "toolResult",
623
+ turnIndex,
624
+ callId: toolCall.callId,
625
+ toolName: toolCall.toolName,
626
+ result: executionResult,
627
+ isError: isToolError,
628
+ timestamp: Date.now(),
629
+ });
630
+ }
631
+ }
632
+ // Append tool results message
633
+ conversationMessages.push({
634
+ role: "tool",
635
+ content: toolResults.map((tr) => ({
636
+ type: "tool-result",
637
+ toolCallId: tr.toolCallId,
638
+ toolName: tr.toolName,
639
+ output: typeof tr.result === "string"
640
+ ? {
641
+ type: "text",
642
+ value: tr.result,
643
+ }
644
+ : {
645
+ type: "json",
646
+ value: toJsonValue(tr.result),
647
+ },
648
+ })),
649
+ });
650
+ // Emit stepFinished
651
+ yield {
652
+ type: "stepFinished",
653
+ stepIndex,
654
+ usage: stepUsage,
655
+ };
656
+ }
657
+ if (finishReason === "completed" &&
658
+ conversationMessages.length > initialHistoryLength) {
659
+ // Check if maxSteps was hit
660
+ const lastMessage = conversationMessages[conversationMessages.length - 1];
661
+ if (lastMessage?.role === "tool") {
662
+ finishReason = "maxSteps";
663
+ }
664
+ }
665
+ // 4. Conclude turn
666
+ yield* finalizeTurn(finishReason);
667
+ }
668
+ catch (turnError) {
669
+ const errorInstance = turnError instanceof Error ? turnError : new Error(String(turnError));
670
+ // Rollback conversational messages added during failed turn
671
+ conversationMessages.length = initialHistoryLength;
672
+ finishReason = "error";
673
+ yield {
674
+ type: "error",
675
+ origin: "engine",
676
+ error: toErrorInfo(errorInstance),
677
+ isFatal: true,
678
+ };
679
+ if (config.hooks?.onError) {
680
+ try {
681
+ await config.hooks.onError({
682
+ error: errorInstance,
683
+ origin: "engine",
684
+ turnIndex,
685
+ isFatal: true,
686
+ });
687
+ }
688
+ catch (hookError) {
689
+ // Yield hook error as non-fatal diagnostic so terminal turnFinished is guaranteed
690
+ yield {
691
+ type: "error",
692
+ origin: "hook",
693
+ error: toErrorInfo(hookError instanceof Error
694
+ ? hookError
695
+ : new Error(String(hookError))),
696
+ hookName: "onError",
697
+ isFatal: false,
698
+ };
699
+ }
700
+ }
701
+ yield* finalizeTurn("error");
702
+ }
703
+ finally {
704
+ if (config.hooks?.onAfterTurn) {
705
+ try {
706
+ await config.hooks.onAfterTurn({
707
+ turnIndex,
708
+ finishReason,
709
+ totalUsage: buildTotalUsage(),
710
+ });
711
+ }
712
+ catch {
713
+ // Collect cleanup error without masking primary turn outcome
714
+ }
715
+ }
716
+ }
717
+ }
718
+ //# sourceMappingURL=runTurn.js.map