@hexdecimal16/nexo 0.0.0-stage → 0.2.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 (208) hide show
  1. package/LICENSE +75 -0
  2. package/README.md +75 -2
  3. package/cli/src/bin.js +12 -0
  4. package/cli/src/common.js +77 -0
  5. package/cli/src/doctor.js +27 -0
  6. package/cli/src/eval-cases.js +65 -0
  7. package/cli/src/eval.js +67 -0
  8. package/cli/src/init.js +186 -0
  9. package/cli/src/interactive.js +171 -0
  10. package/cli/src/learn.js +178 -0
  11. package/cli/src/main.js +261 -0
  12. package/cli/src/optimize.js +289 -0
  13. package/cli/src/prompter.js +47 -0
  14. package/cli/src/review.js +120 -0
  15. package/cli/src/runtime.js +2 -0
  16. package/cli/src/sessions.js +34 -0
  17. package/cli/src/settings.js +169 -0
  18. package/cli/src/ui.js +112 -0
  19. package/core/src/approval/classifier.js +152 -0
  20. package/core/src/config/load.js +283 -0
  21. package/core/src/config/schema.js +186 -0
  22. package/core/src/cost/admission.js +90 -0
  23. package/core/src/cost/budget.js +67 -0
  24. package/core/src/cost/pricing.js +53 -0
  25. package/core/src/engine/charged-completion.js +79 -0
  26. package/core/src/engine/errors.js +77 -0
  27. package/core/src/engine/mcp.js +11 -0
  28. package/core/src/engine/messages.js +86 -0
  29. package/core/src/engine/prompts.js +32 -0
  30. package/core/src/engine/provider-gate.js +33 -0
  31. package/core/src/engine/recorder.js +61 -0
  32. package/core/src/engine/run.js +1115 -0
  33. package/core/src/engine/semaphore.js +45 -0
  34. package/core/src/engine/spawn-tool.js +119 -0
  35. package/core/src/engine/task-graph.js +153 -0
  36. package/core/src/index.js +32 -0
  37. package/core/src/learn/caller.js +171 -0
  38. package/core/src/learn/context.js +112 -0
  39. package/core/src/learn/embedder.js +216 -0
  40. package/core/src/learn/job.js +196 -0
  41. package/core/src/learn/wiki.js +116 -0
  42. package/core/src/learn/worker.js +141 -0
  43. package/core/src/optimize/adapter.js +250 -0
  44. package/core/src/optimize/climb.js +338 -0
  45. package/core/src/optimize/mine.js +95 -0
  46. package/core/src/optimize/optimize.js +377 -0
  47. package/core/src/optimize/optimizer-run.js +67 -0
  48. package/core/src/optimize/reflect.js +100 -0
  49. package/core/src/optimize/scratchpad-wiki.js +69 -0
  50. package/core/src/providers/claude-p.js +363 -0
  51. package/core/src/providers/kiro-p.js +408 -0
  52. package/core/src/providers/models.js +10 -0
  53. package/core/src/scoring/calibration.js +31 -0
  54. package/core/src/scoring/continuation.js +24 -0
  55. package/core/src/scoring/runner.js +322 -0
  56. package/core/src/scoring/sources.js +88 -0
  57. package/core/src/session/lock.js +88 -0
  58. package/core/src/session/session.js +647 -0
  59. package/core/src/session/shell.js +26 -0
  60. package/core/src/session/transcript.js +86 -0
  61. package/core/src/settings/config-edit.js +472 -0
  62. package/core/src/settings/credentials.js +120 -0
  63. package/core/src/settings/doctor.js +103 -0
  64. package/core/src/settings/settings.js +265 -0
  65. package/mcp/src/hub.js +184 -0
  66. package/mcp/src/index.js +1 -0
  67. package/memory/src/curate.js +121 -0
  68. package/memory/src/index.js +4 -0
  69. package/memory/src/prompts.js +143 -0
  70. package/memory/src/retrieval.js +91 -0
  71. package/memory/src/similarity.js +47 -0
  72. package/optimize/src/engine.js +206 -0
  73. package/optimize/src/index.js +8 -0
  74. package/optimize/src/merge.js +73 -0
  75. package/optimize/src/novelty.js +37 -0
  76. package/optimize/src/pareto.js +83 -0
  77. package/optimize/src/proposer.js +148 -0
  78. package/optimize/src/report.js +107 -0
  79. package/optimize/src/rng.js +34 -0
  80. package/optimize/src/target.js +34 -0
  81. package/package.json +47 -4
  82. package/router/src/effort.js +5 -0
  83. package/router/src/escalation.js +171 -0
  84. package/router/src/index.js +4 -0
  85. package/router/src/registry.js +21 -0
  86. package/router/src/resolve.js +117 -0
  87. package/scorers/src/deterministic.js +194 -0
  88. package/scorers/src/family.js +48 -0
  89. package/scorers/src/index.js +6 -0
  90. package/scorers/src/judge.js +284 -0
  91. package/scorers/src/regex-worker.js +3 -0
  92. package/scorers/src/spec.js +147 -0
  93. package/scorers/src/trajectory.js +22 -0
  94. package/scorers/src/types.js +1 -0
  95. package/sdk/src/index.js +3 -0
  96. package/sdk/src/nexo.js +94 -0
  97. package/sdk/src/runtime.js +39 -0
  98. package/skills/bundled/browser/SKILL.md +57 -0
  99. package/skills/bundled/wiki/SKILL.md +73 -0
  100. package/skills/src/frontmatter.js +25 -0
  101. package/skills/src/index.js +3 -0
  102. package/skills/src/load-skill-tool.js +41 -0
  103. package/skills/src/loader.js +95 -0
  104. package/store/src/artifacts.js +124 -0
  105. package/store/src/budget-ledger.js +18 -0
  106. package/store/src/cost-report.js +46 -0
  107. package/store/src/cursor.js +35 -0
  108. package/store/src/db.js +83 -0
  109. package/store/src/errors.js +9 -0
  110. package/store/src/eval-cases.js +255 -0
  111. package/store/src/feedback.js +154 -0
  112. package/store/src/goldens.js +61 -0
  113. package/store/src/ids.js +6 -0
  114. package/store/src/index.js +25 -0
  115. package/store/src/judge-calibration.js +182 -0
  116. package/store/src/learn-jobs.js +145 -0
  117. package/store/src/memories.js +261 -0
  118. package/store/src/migrations/001_init.sql +81 -0
  119. package/store/src/migrations/002_feedback.sql +9 -0
  120. package/store/src/migrations/003_sessions.sql +19 -0
  121. package/store/src/migrations/004_scoring.sql +22 -0
  122. package/store/src/migrations/005_judge_calibration.sql +27 -0
  123. package/store/src/migrations/006_learning.sql +77 -0
  124. package/store/src/migrations/007_optimize.sql +55 -0
  125. package/store/src/migrations/008_mined_cases_and_climb.sql +46 -0
  126. package/store/src/mine.js +51 -0
  127. package/store/src/optim.js +291 -0
  128. package/store/src/paths.js +22 -0
  129. package/store/src/playbooks.js +199 -0
  130. package/store/src/reindex.js +143 -0
  131. package/store/src/run-dir.js +151 -0
  132. package/store/src/runs.js +310 -0
  133. package/store/src/scores.js +92 -0
  134. package/store/src/sessions.js +304 -0
  135. package/store/src/span-tree.js +98 -0
  136. package/store/src/spans.js +84 -0
  137. package/store/src/sql.js +13 -0
  138. package/store/src/workspace-copy.js +80 -0
  139. package/telemetry/src/errors.js +32 -0
  140. package/telemetry/src/index.js +3 -0
  141. package/telemetry/src/logger.js +39 -0
  142. package/telemetry/src/redact.js +106 -0
  143. package/tools/src/builtin.js +269 -0
  144. package/tools/src/change-tracker.js +57 -0
  145. package/tools/src/confine.js +101 -0
  146. package/tools/src/index.js +7 -0
  147. package/tools/src/leases.js +57 -0
  148. package/tools/src/policy.js +162 -0
  149. package/tools/src/read-only.js +338 -0
  150. package/tools/src/session-rules.js +140 -0
  151. package/tui/src/app.js +948 -0
  152. package/tui/src/approvals.js +96 -0
  153. package/tui/src/commands.js +38 -0
  154. package/tui/src/components.js +248 -0
  155. package/tui/src/index.js +5 -0
  156. package/tui/src/picker.js +78 -0
  157. package/tui/src/session-picker.js +100 -0
  158. package/tui/src/settings-screen.js +346 -0
  159. package/tui/src/text.js +70 -0
  160. package/tui/src/theme.js +44 -0
  161. package/web/public/cost.html +25 -0
  162. package/web/public/fonts/GeistMono-400.woff2 +0 -0
  163. package/web/public/fonts/GeistMono-600.woff2 +0 -0
  164. package/web/public/fonts/InstrumentSans-400.woff2 +0 -0
  165. package/web/public/fonts/InstrumentSans-600.woff2 +0 -0
  166. package/web/public/index.html +39 -0
  167. package/web/public/judge.html +21 -0
  168. package/web/public/learning.html +46 -0
  169. package/web/public/lib/api-types.ts +616 -0
  170. package/web/public/lib/common-view.ts +47 -0
  171. package/web/public/lib/cost-view.ts +35 -0
  172. package/web/public/lib/files-view.ts +90 -0
  173. package/web/public/lib/format.ts +35 -0
  174. package/web/public/lib/html.ts +51 -0
  175. package/web/public/lib/judge-view.ts +62 -0
  176. package/web/public/lib/learning-view.ts +102 -0
  177. package/web/public/lib/optim-view.ts +148 -0
  178. package/web/public/lib/pager.ts +56 -0
  179. package/web/public/lib/poller.ts +79 -0
  180. package/web/public/lib/run-view.ts +61 -0
  181. package/web/public/lib/runs-view.ts +87 -0
  182. package/web/public/lib/score-view.ts +94 -0
  183. package/web/public/lib/sessions-view.ts +28 -0
  184. package/web/public/lib/span-view.ts +90 -0
  185. package/web/public/lib/theme.ts +60 -0
  186. package/web/public/lib/timeline.ts +97 -0
  187. package/web/public/lib/wikis-view.ts +257 -0
  188. package/web/public/optim.html +30 -0
  189. package/web/public/pages/api.ts +60 -0
  190. package/web/public/pages/cost.ts +36 -0
  191. package/web/public/pages/judge.ts +15 -0
  192. package/web/public/pages/learning.ts +92 -0
  193. package/web/public/pages/optim.ts +68 -0
  194. package/web/public/pages/paging.ts +18 -0
  195. package/web/public/pages/run.ts +221 -0
  196. package/web/public/pages/runs.ts +91 -0
  197. package/web/public/pages/sessions.ts +25 -0
  198. package/web/public/pages/wikis.ts +103 -0
  199. package/web/public/run.html +36 -0
  200. package/web/public/sessions.html +28 -0
  201. package/web/public/style.css +288 -0
  202. package/web/public/wikis.html +25 -0
  203. package/web/src/api.js +682 -0
  204. package/web/src/http-errors.js +60 -0
  205. package/web/src/index.js +5 -0
  206. package/web/src/server.js +292 -0
  207. package/web/src/static.js +86 -0
  208. package/web/src/strip.js +22 -0
@@ -0,0 +1,1115 @@
1
+ import { Agent } from "@earendil-works/pi-agent-core";
2
+ import { isContextOverflow, isRetryableAssistantError, normalizeContext, } from "@earendil-works/pi-ai";
3
+ import { createModelRegistry, DEFAULT_ROUTER_POLICY, ESCALATION_BLOCK_REASONS, endOfRunSignals, escalationBlock, isModelAllowed, resolveModel, TriggerMonitor, } from "../../../router/src/index.js";
4
+ import { createLoadSkillTool, formatSkillIndex, parseSkillFile } from "../../../skills/src/index.js";
5
+ import { createArtifactSet, enqueueLearnJob, getActiveArtifact, insertRun, isPidAlive, listPlaybookItems, listSpans, newId, recoverCrashedRuns, resolveSourcedArtifact, RunDir, sessionRunDirs, updateRun, } from "../../../store/src/index.js";
6
+ import { NexoError, toErrorPayload } from "../../../telemetry/src/index.js";
7
+ import { createBuiltinTools, createChangeTracker, createPolicy, FileLeases, TOOL_OUTPUT_PREFIX, } from "../../../tools/src/index.js";
8
+ import { realpathSync, statSync } from "node:fs";
9
+ import { join } from "node:path";
10
+ import { createApprovalClassifier } from "../approval/classifier.js";
11
+ import { budgetExhaustedError, checkAdmission, recordSpend, runBudgetLimit } from "../cost/admission.js";
12
+ import { budgetLine, RunBudget } from "../cost/budget.js";
13
+ import { estimateCallCostUsd, priceUsage } from "../cost/pricing.js";
14
+ import { classifyProviderError, contextOverflowError, providerRetryDelayMs, toolErrorText, withToolErrorCodes } from "./errors.js";
15
+ import { assistantText, contentText, estimatePromptChars, foreignToolCallsAsText, lastAssistant, recordedContent, withBudgetLine } from "./messages.js";
16
+ import { DEFAULT_PLANNER_PROMPT, DEFAULT_SYSTEM_PROMPT, renderSystemPrompt } from "./prompts.js";
17
+ import { createGatedStreamFn } from "./provider-gate.js";
18
+ import { Recorder } from "./recorder.js";
19
+ import { activePlaybook, emptyMemoryContext, playbookSection, retrieveRunMemories, skillAppendix } from "../learn/context.js";
20
+ import { continuationPrompt } from "../scoring/continuation.js";
21
+ import { planScoring, runScoringRound, runSelfCheck, summarizeSpans } from "../scoring/runner.js";
22
+ import { judgeFamilyWarnings, loadJudgeRubric, loadRouterPolicy } from "../scoring/sources.js";
23
+ const TOOL_RESULT_INLINE_LIMIT = 32_768;
24
+ const TOOL_RESULT_EXCERPT_CHARS = 8_000;
25
+ /** The head and tail of a large tool result, with a note pointing at the saved full text. */
26
+ function toolOutputExcerpt(text, pointer) {
27
+ const omitted = text.length - 2 * TOOL_RESULT_EXCERPT_CHARS;
28
+ const note = `[${omitted} characters omitted. The full output is saved; read it with read({ path: "${pointer}", offset, limit }), where offset and limit count lines.]`;
29
+ return `${text.slice(0, TOOL_RESULT_EXCERPT_CHARS)}\n\n${note}\n\n${text.slice(-TOOL_RESULT_EXCERPT_CHARS)}`;
30
+ }
31
+ /** Longest tool result text carried by a `tool_end` preview (`output` carries all of it). */
32
+ export const TOOL_END_PREVIEW_CHARS = 2_000;
33
+ const extraToolFactories = [];
34
+ /** Registers tools that every run receives in addition to the built-ins (used by the spawn tool). Returns an unregister function. */
35
+ export function registerExtraTools(factory) {
36
+ extraToolFactories.push(factory);
37
+ return () => {
38
+ const index = extraToolFactories.indexOf(factory);
39
+ if (index >= 0)
40
+ extraToolFactories.splice(index, 1);
41
+ };
42
+ }
43
+ function defaultSleep(ms, signal) {
44
+ return new Promise((resolve, reject) => {
45
+ if (signal?.aborted)
46
+ return reject(signal.reason);
47
+ const timer = setTimeout(resolve, ms);
48
+ signal?.addEventListener("abort", () => {
49
+ clearTimeout(timer);
50
+ reject(signal.reason);
51
+ }, { once: true });
52
+ });
53
+ }
54
+ function failedResult(redact, error, status = "failed") {
55
+ return {
56
+ trajectoryId: null,
57
+ runDir: null,
58
+ status,
59
+ output: "",
60
+ costUsd: 0,
61
+ costUnknown: false,
62
+ error: redact(toErrorPayload(error)),
63
+ messages: [],
64
+ model: null,
65
+ };
66
+ }
67
+ /** Builds the run-tree-wide services and marks runs of dead processes as aborted. */
68
+ export function createEngineEnv(deps) {
69
+ const now = deps.now ?? (() => new Date());
70
+ const limits = {};
71
+ for (const [name, p] of Object.entries(deps.config.providers))
72
+ limits[name] = p.maxConcurrent;
73
+ const env = {
74
+ deps,
75
+ now,
76
+ sleep: deps.sleep ?? defaultSleep,
77
+ registry: createModelRegistry(deps.models),
78
+ policy: createPolicy(deps.config.tools),
79
+ streamFn: createGatedStreamFn(deps.models, limits, deps.resolveApiKey),
80
+ };
81
+ const recovered = recoverCrashedRuns(deps.db, isPidAlive, now().toISOString());
82
+ if (recovered.length > 0)
83
+ deps.logger.warn("marked crashed runs as aborted", { run_ids: recovered });
84
+ for (const warning of judgeFamilyWarnings(deps.config))
85
+ deps.logger.warn(warning);
86
+ return env;
87
+ }
88
+ export function createEngine(deps) {
89
+ const env = createEngineEnv(deps);
90
+ const { now } = env;
91
+ return {
92
+ env,
93
+ async run(request, signal) {
94
+ try {
95
+ checkAdmission(deps.db, deps.config.budgets, now());
96
+ }
97
+ catch (error) {
98
+ return failedResult(deps.redact, error, "budget_exceeded");
99
+ }
100
+ let budget;
101
+ let limit;
102
+ try {
103
+ const own = request.budgetUsd ?? deps.config.budgets.perRunUsd;
104
+ new RunBudget(own); // validates --budget / budgets.perRunUsd
105
+ limit = runBudgetLimit(deps.db, deps.config.budgets, now(), { run: own });
106
+ budget = new RunBudget(limit.usd);
107
+ }
108
+ catch (error) {
109
+ return failedResult(deps.redact, error);
110
+ }
111
+ return executeRun(env, { request, budget, budgetLimit: limit.by, signal });
112
+ },
113
+ };
114
+ }
115
+ /** The shared workspace a run edits in place, or null when it uses its own isolated run workspace. */
116
+ function resolveSharedWorkspace(request, parent) {
117
+ if (parent)
118
+ return parent.sharedWorkspace;
119
+ if (!request.workspace)
120
+ return null;
121
+ let real;
122
+ try {
123
+ real = realpathSync(request.workspace);
124
+ }
125
+ catch (cause) {
126
+ throw new NexoError({ code: "CONFIG_INVALID", message: `Workspace ${request.workspace} does not exist`, hint: "Pass an existing directory to --workspace", cause });
127
+ }
128
+ if (!statSync(real).isDirectory())
129
+ throw new NexoError({ code: "CONFIG_INVALID", message: `Workspace ${request.workspace} is not a directory` });
130
+ return real;
131
+ }
132
+ export async function executeRun(env, input) {
133
+ const { deps, now } = env;
134
+ const { config, db } = deps;
135
+ const { request, budget, parent } = input;
136
+ const depth = parent ? parent.depth : 0;
137
+ const sessionId = parent ? parent.sessionId : (request.sessionId ?? null);
138
+ const rollout = parent ? undefined : input.rollout;
139
+ const rolloutCandidate = parent ? parent.rolloutCandidate : (rollout?.candidate ?? null);
140
+ const optimRunId = parent ? parent.optimRunId : (rollout?.optimRunId ?? null);
141
+ /** Session rules and auto mode: from the request for a root run, inherited by subagents, none for rollouts. */
142
+ const approvals = rollout
143
+ ? null
144
+ : parent
145
+ ? parent.approvals
146
+ : {
147
+ sessionRules: request.sessionRules ?? (() => []),
148
+ ...(request.addSessionRule ? { addSessionRule: request.addSessionRule } : {}),
149
+ auto: request.autoApprove ?? config.tools.autoApprove === "on",
150
+ userRequest: request.instruction,
151
+ };
152
+ // Resolve skill, model and workspace before creating anything on disk.
153
+ const skill = request.skill ? deps.skills.skills.get(request.skill) : undefined;
154
+ if (request.skill && !skill) {
155
+ return failedResult(deps.redact, new NexoError({
156
+ code: "SKILL_NOT_FOUND",
157
+ message: `Unknown skill "${request.skill}"`,
158
+ hint: `Available: ${[...deps.skills.skills.keys()].join(", ") || "(none)"}`,
159
+ }));
160
+ }
161
+ const pin = request.skill ? config.skills.pins[request.skill] : undefined;
162
+ let resolved;
163
+ let model;
164
+ let escalationTarget;
165
+ let sharedWorkspace;
166
+ let runDir;
167
+ const runId = newId();
168
+ try {
169
+ const user = { model: (parent ? undefined : request.model) ?? pin?.model, effort: (parent ? undefined : request.effort) ?? pin?.effort };
170
+ const parentChoice = parent ? { model: request.model, effort: request.effort } : undefined;
171
+ resolved = resolveModel({
172
+ user,
173
+ parent: parentChoice,
174
+ skill: skill ? { model: skill.meta.model, effort: skill.meta.effort, allowed: skill.meta.modelAllowed } : undefined,
175
+ roles: { s1: config.models.s1, s2: config.models.s2 },
176
+ remainingFraction: parent ? parent.parentRemainingFraction : budget.remainingFraction(),
177
+ });
178
+ model = env.registry.get(resolved.provider, resolved.id);
179
+ resolved = { ...resolved, effort: env.registry.clampEffort(model, resolved.effort) };
180
+ escalationTarget = env.registry.get(config.models.s2.provider, config.models.s2.id);
181
+ const s2Allowed = isModelAllowed("s2", skill?.meta.modelAllowed ?? ["s1", "s2"], { s1: config.models.s1, s2: config.models.s2 });
182
+ if (request.startOnS2 && !parent && resolved.source !== "user" && resolved.role !== "s2" && s2Allowed) {
183
+ // Same model and effort an escalation would switch to.
184
+ const s2 = config.models.s2;
185
+ model = escalationTarget;
186
+ resolved = {
187
+ provider: s2.provider,
188
+ id: s2.id,
189
+ role: "s2",
190
+ effort: env.registry.clampEffort(escalationTarget, s2.effort ?? resolved.effort),
191
+ source: "router",
192
+ effortSource: "router",
193
+ };
194
+ }
195
+ // A rollout always works in its own run workspace, never in a --workspace directory.
196
+ sharedWorkspace = rollout ? null : resolveSharedWorkspace(request, parent);
197
+ runDir = parent ? parent.runDir.child(runId) : RunDir.create(rollout?.runsRoot ?? deps.paths.runs, runId, deps.redact);
198
+ }
199
+ catch (error) {
200
+ return failedResult(deps.redact, error);
201
+ }
202
+ const rootRunId = parent?.rootRunId ?? runId;
203
+ const startedAt = now().toISOString();
204
+ const leases = parent?.leases ?? new FileLeases();
205
+ if (parent)
206
+ leases.link(runId, parent.runId);
207
+ const logger = deps.logger.child({ run_id: runId, correlation_id: rootRunId });
208
+ const taskGraphs = [];
209
+ let ownCost = 0;
210
+ let childCost = 0;
211
+ /** Approver spend (own and subagents'), kept out of every budget and ledger; the `approval_call` spans hold the detail. */
212
+ let approvalCost = 0;
213
+ let costUnknown = false;
214
+ let tokensIn = 0;
215
+ let tokensOut = 0;
216
+ const workspace = sharedWorkspace ?? runDir.workspaceDir;
217
+ let changeTracker = parent?.changeTracker ?? null;
218
+ let artifactSetId = null;
219
+ let workspaceFrom = null;
220
+ /** The model requests go to; replaced by S2 when an escalation takes effect. */
221
+ let active = { model, resolved };
222
+ let escalations = 0;
223
+ let continuationFailure = null;
224
+ /** Model calls of this run that ended without an error; the retry loop resets its attempt count when this grows. */
225
+ let completedCalls = 0;
226
+ /** Every model that generated part of the run (S1, and S2 after an escalation), for the judge's same-family check. */
227
+ const usedModels = new Map([[`${model.provider}/${model.id}`, { provider: model.provider, id: model.id }]]);
228
+ /** Every scorer result of the run, and those of its latest round. */
229
+ const scoreRows = [];
230
+ let latestScores = [];
231
+ let policy = DEFAULT_ROUTER_POLICY;
232
+ let rubric = "";
233
+ // The scorers are fixed before the run starts, so the agent cannot change them by editing a scorer file.
234
+ const plan = planScoring(env, skill, depth, workspace);
235
+ /** The skill's active playbook when the run starts with `--skill` (spec §6), snapshotted with the run's artifacts. */
236
+ const startPlaybook = skill ? getActiveArtifact(db, "playbook", skill.name) : undefined;
237
+ const startPlaybookSection = skill && startPlaybook?.content.trim() ? playbookSection(skill.name, listPlaybookItems(db, skill.name)) : "";
238
+ /** Memories injected at run start; load_skill adds the skill memories it shows. */
239
+ let memoryContext = emptyMemoryContext();
240
+ /** Charges calls made for memory (the query embedding) to this run; set once the run span exists. */
241
+ let memoryDeps = null;
242
+ /** The version a run uses for an artifact with a source: the rollout's candidate, else the sourced version (spec D2). */
243
+ const versionOf = (kind, name, source, nowIso) => rolloutCandidate && rolloutCandidate.kind === kind && rolloutCandidate.name === name
244
+ ? rolloutCandidate
245
+ : resolveSourcedArtifact(db, kind, name, deps.redact(source), nowIso);
246
+ /** The text a run uses: the source itself while its manual mirror is in use, else the promoted or candidate text. */
247
+ const textOf = (artifact, source) => (artifact.origin === "manual" ? source : artifact.content);
248
+ /** A skill with the body of the version this run uses. */
249
+ const effectiveSkill = (s, nowIso) => {
250
+ const artifact = versionOf("skill", s.name, s.content, nowIso);
251
+ if (artifact.origin === "manual")
252
+ return { skill: s, artifact };
253
+ return { skill: { ...s, content: artifact.content, body: parseSkillFile(artifact.content, s.filePath).body }, artifact };
254
+ };
255
+ let systemPromptText = DEFAULT_SYSTEM_PROMPT;
256
+ let plannerPromptText = DEFAULT_PLANNER_PROMPT;
257
+ /** The `--skill` skill with the body this run uses. */
258
+ let runSkill = skill;
259
+ const recorder = new Recorder({ db, runDir, runId, now, redact: deps.redact });
260
+ const runJson = (status, output, error) => ({
261
+ id: runId,
262
+ parentRunId: parent?.runId ?? null,
263
+ rootRunId,
264
+ instruction: request.instruction,
265
+ skill: request.skill ?? null,
266
+ status,
267
+ model: {
268
+ provider: active.resolved.provider,
269
+ id: active.resolved.id,
270
+ effort: active.resolved.effort,
271
+ source: active.resolved.source,
272
+ role: active.resolved.role,
273
+ },
274
+ startedAt,
275
+ endedAt: status === "running" ? null : now().toISOString(),
276
+ costUsd: ownCost + childCost,
277
+ costUnknown,
278
+ approvalCostUsd: approvalCost,
279
+ tokensIn,
280
+ tokensOut,
281
+ output,
282
+ error,
283
+ artifactSetId,
284
+ configSnapshotHash: deps.configHash,
285
+ workspace,
286
+ taskGraphs,
287
+ ...(parent ? {} : { sessionId, turnIndex: request.turnIndex ?? null }),
288
+ ...(scoreRows.length > 0 ? { scores: scoreRows } : {}),
289
+ escalations,
290
+ ...(optimRunId ? { optimRunId } : {}),
291
+ ...(workspaceFrom ? { workspaceFrom } : {}),
292
+ });
293
+ // Setup up to and including the DB row. A failure here leaves no row, only a failed run.json.
294
+ try {
295
+ if (!parent && sharedWorkspace)
296
+ changeTracker = createChangeTracker(sharedWorkspace, runDir.changesDir, (s) => deps.redact(s));
297
+ // A session turn continues from the previous turn's files.
298
+ const from = request.workspaceFrom;
299
+ if (from && !parent && !sharedWorkspace && !rollout) {
300
+ workspaceFrom = { runId: from.runId, bytes: await runDir.copyIntoWorkspace(from, { signal: input.signal }) };
301
+ }
302
+ // Snapshot the exact artifacts this run uses.
303
+ const nowIso = now().toISOString();
304
+ const members = [];
305
+ /** Adds the version to the run's artifact set and writes the text the run uses into `artifacts/`. */
306
+ const snapshot = (artifact, content, relPath) => {
307
+ members.push({ kind: artifact.kind, name: artifact.name, artifactId: artifact.id, version: artifact.version });
308
+ runDir.writeArtifact(relPath, content);
309
+ };
310
+ const systemVersion = versionOf("system_prompt", "default", DEFAULT_SYSTEM_PROMPT, nowIso);
311
+ systemPromptText = textOf(systemVersion, DEFAULT_SYSTEM_PROMPT);
312
+ snapshot(systemVersion, systemPromptText, "system_prompt.md");
313
+ const plannerVersion = versionOf("planner_prompt", "default", DEFAULT_PLANNER_PROMPT, nowIso);
314
+ plannerPromptText = textOf(plannerVersion, DEFAULT_PLANNER_PROMPT);
315
+ snapshot(plannerVersion, plannerPromptText, "planner_prompt.md");
316
+ if (skill) {
317
+ const effective = effectiveSkill(skill, nowIso);
318
+ runSkill = effective.skill;
319
+ snapshot(effective.artifact, effective.skill.content, `skills/${skill.name}/SKILL.md`);
320
+ }
321
+ if (skill && startPlaybook?.content.trim()) {
322
+ members.push({ kind: "playbook", name: skill.name, artifactId: startPlaybook.id, version: startPlaybook.version });
323
+ runDir.writeArtifact(`playbooks/${skill.name}.md`, startPlaybook.content);
324
+ }
325
+ const routerPolicy = loadRouterPolicy(db, config, nowIso, deps.redact);
326
+ policy = routerPolicy.policy;
327
+ members.push({ kind: "router_policy", name: routerPolicy.artifact.name, artifactId: routerPolicy.artifact.id, version: routerPolicy.artifact.version });
328
+ runDir.writeArtifact("router_policy.json", routerPolicy.artifact.content);
329
+ if (plan.specs.some((s) => s.kind === "llm_judge")) {
330
+ const judgeRubric = loadJudgeRubric(db, config, nowIso, deps.redact);
331
+ rubric = judgeRubric.rubric;
332
+ members.push({ kind: "judge_rubric", name: judgeRubric.artifact.name, artifactId: judgeRubric.artifact.id, version: judgeRubric.artifact.version });
333
+ runDir.writeArtifact("judge_rubric.md", judgeRubric.artifact.content);
334
+ }
335
+ artifactSetId = createArtifactSet(db, members, nowIso);
336
+ runDir.writeArtifact("config.json", JSON.stringify(config, null, 2));
337
+ insertRun(db, {
338
+ id: runId,
339
+ parentRunId: parent?.runId ?? null,
340
+ rootRunId,
341
+ dirPath: runDir.root,
342
+ instruction: deps.redact(request.instruction),
343
+ skill: request.skill ?? null,
344
+ status: "running",
345
+ configSnapshotHash: deps.configHash,
346
+ artifactSetId,
347
+ modelFinal: `${resolved.provider}/${resolved.id}`,
348
+ tierFinal: resolved.role,
349
+ escalations: 0,
350
+ startedAt,
351
+ endedAt: null,
352
+ costUsd: 0,
353
+ costUnknown: false,
354
+ tokensIn: 0,
355
+ tokensOut: 0,
356
+ pid: process.pid,
357
+ error: null,
358
+ sessionId: parent ? null : sessionId,
359
+ turnIndex: parent ? null : (request.turnIndex ?? null),
360
+ optimRunId,
361
+ });
362
+ }
363
+ catch (caught) {
364
+ const setupStatus = input.signal?.aborted ? "aborted" : "failed";
365
+ if (setupStatus === "aborted")
366
+ logger.info("run aborted during setup", { error: caught });
367
+ else
368
+ logger.error("run setup failed", { error: caught });
369
+ const payload = deps.redact(toErrorPayload(caught));
370
+ try {
371
+ runDir.writeRunJson(runJson(setupStatus, "", payload));
372
+ }
373
+ catch { }
374
+ return {
375
+ trajectoryId: runId,
376
+ runDir: runDir.root,
377
+ status: setupStatus,
378
+ output: "",
379
+ costUsd: 0,
380
+ costUnknown: false,
381
+ error: payload,
382
+ messages: [],
383
+ model: modelInfo(model, resolved),
384
+ };
385
+ }
386
+ // From here the DB row exists: every path below ends by writing a terminal status to run.json and the DB.
387
+ let status = "succeeded";
388
+ let error = null;
389
+ let output = "";
390
+ let runSpan = null;
391
+ let turnSpan = null;
392
+ let llmSpan = null;
393
+ let agent = null;
394
+ let budgetExceeded = false;
395
+ let seededCount = 0;
396
+ const onAbort = () => agent?.abort();
397
+ try {
398
+ runSpan = recorder.start({
399
+ kind: "run",
400
+ name: request.skill ? `skill:${request.skill}` : "run",
401
+ parentSpanId: null,
402
+ attrs: { instruction: deps.redact(request.instruction), parentSpanId: parent?.spanId ?? null, depth },
403
+ });
404
+ const rootSpan = runSpan;
405
+ runDir.writeRunJson(runJson("running", "", null));
406
+ deps.onEvent?.({
407
+ type: "run_start",
408
+ runId,
409
+ parentRunId: parent?.runId ?? null,
410
+ instruction: deps.redact(request.instruction),
411
+ depth,
412
+ model: `${model.provider}/${model.id}`,
413
+ effort: resolved.effort,
414
+ });
415
+ // System 1 -> System 2 escalation (spec §7.2).
416
+ const monitor = new TriggerMonitor(policy);
417
+ const blockedOnce = new Set();
418
+ /** Estimated cost of one S2 request at the run's current context size; set once the agent exists. */
419
+ let s2RequestUsd = () => 0;
420
+ /** Why an escalation may not happen now, or null when it may. Reserved budget counts as spent. */
421
+ const currentBlock = () => {
422
+ const perS2Request = s2RequestUsd();
423
+ return escalationBlock({
424
+ escalations,
425
+ maxEscalations: config.router.maxEscalations,
426
+ spentFraction: 1 - budget.remainingFraction(),
427
+ cutoff: config.budgets.escalationCutoff,
428
+ skillAllows: skill?.meta.escalate ?? true,
429
+ modelAllowed: isModelAllowed("s2", skill?.meta.modelAllowed ?? ["s1", "s2"], { s1: config.models.s1, s2: config.models.s2 }),
430
+ userPinned: resolved.source === "user",
431
+ // Unpriced S2 (estimate 0): the headroom check is skipped and the cutoff alone applies.
432
+ ...(perS2Request > 0 ? { s2CallsAffordable: budget.remainingUsd() / perS2Request } : {}),
433
+ });
434
+ };
435
+ /**
436
+ * Applies or records one escalation and returns its span when it took effect, else null. An applied end-of-run
437
+ * escalation's span is left open for the caller, which finishes it once the continuation has run.
438
+ */
439
+ const escalate = (signal, phase) => {
440
+ if (phase === "mid_run" && active.resolved.role === "s2")
441
+ return null;
442
+ const from = `${active.model.provider}/${active.model.id}`;
443
+ const blockedBy = currentBlock();
444
+ if (blockedBy) {
445
+ // A suppressed trigger is recorded once per reason, not on every tool error that re-fires it.
446
+ const key = `${signal.trigger}:${blockedBy}`;
447
+ if (blockedOnce.has(key))
448
+ return null;
449
+ blockedOnce.add(key);
450
+ }
451
+ else {
452
+ const s2 = config.models.s2;
453
+ const userEffort = resolved.effortSource === "user";
454
+ const effort = env.registry.clampEffort(escalationTarget, userEffort ? resolved.effort : (s2.effort ?? resolved.effort));
455
+ active = {
456
+ model: escalationTarget,
457
+ resolved: { provider: escalationTarget.provider, id: escalationTarget.id, role: "s2", effort, source: "router", effortSource: userEffort ? "user" : "router" },
458
+ };
459
+ usedModels.set(`${escalationTarget.provider}/${escalationTarget.id}`, { provider: escalationTarget.provider, id: escalationTarget.id });
460
+ escalations++;
461
+ }
462
+ const to = `${active.model.provider}/${active.model.id}`;
463
+ const span = recorder.start({
464
+ kind: "escalation",
465
+ name: signal.trigger,
466
+ parentSpanId: rootSpan,
467
+ model: active.model.id,
468
+ provider: active.model.provider,
469
+ tier: active.resolved.role ?? "custom",
470
+ effort: active.resolved.effort,
471
+ modelSource: active.resolved.source,
472
+ attrs: {
473
+ trigger: signal.trigger,
474
+ reason: signal.reason,
475
+ phase,
476
+ applied: blockedBy === null,
477
+ blockedBy,
478
+ blockedReason: blockedBy ? ESCALATION_BLOCK_REASONS[blockedBy] : null,
479
+ from,
480
+ to,
481
+ },
482
+ });
483
+ if (blockedBy !== null || phase === "mid_run")
484
+ recorder.finish(span, { status: "ok" });
485
+ deps.onEvent?.({
486
+ type: "escalation",
487
+ runId,
488
+ depth,
489
+ trigger: signal.trigger,
490
+ reason: deps.redact(signal.reason),
491
+ phase,
492
+ applied: blockedBy === null,
493
+ blockedBy,
494
+ model: to,
495
+ effort: active.resolved.effort,
496
+ });
497
+ logger.info(blockedBy ? "escalation suppressed" : "escalated to s2", {
498
+ trigger: signal.trigger,
499
+ reason: signal.reason,
500
+ blocked_by: blockedBy,
501
+ ...(blockedBy ? { blocked_reason: ESCALATION_BLOCK_REASONS[blockedBy] } : {}),
502
+ });
503
+ return blockedBy === null ? span : null;
504
+ };
505
+ // Tools.
506
+ const toolSpans = new Map();
507
+ const toolPayloadRefs = new Map();
508
+ const baseTools = [
509
+ ...createBuiltinTools({
510
+ workspaceRoot: workspace,
511
+ holder: runId,
512
+ leases,
513
+ changeTracker: changeTracker ?? undefined,
514
+ bashTimeoutMs: config.tools.bashTimeoutMs,
515
+ nexoHome: deps.paths.home,
516
+ ...(sharedWorkspace ? {} : { runWorkspace: runDir.workspaceDir }),
517
+ ...(rollout ? {} : { wikiRoots: [deps.paths.wikis] }),
518
+ toolOutputsDir: runDir.toolOutputsDir,
519
+ // Large-output pointers in a session's history name files saved by earlier turns' runs.
520
+ earlierToolOutputsDirs: sessionId
521
+ ? () => sessionRunDirs(db, sessionId).filter((dir) => dir !== runDir.root).map((dir) => join(dir, "tool_outputs"))
522
+ : undefined,
523
+ }),
524
+ createLoadSkillTool({
525
+ catalog: deps.skills,
526
+ // Records the version in use (sourced, promoted or the rollout's candidate) and serves its body.
527
+ resolve: (s) => effectiveSkill(s, now().toISOString()).skill,
528
+ onLoad: (s) => {
529
+ runDir.writeArtifact(`skills/${s.name}/SKILL.md`, s.content);
530
+ const hint = monitor.skillLoaded(s.name, s.meta.model);
531
+ if (hint)
532
+ escalate(hint, "mid_run");
533
+ },
534
+ appendix: (s) => {
535
+ if (!memoryDeps)
536
+ return "";
537
+ const playbook = activePlaybook(memoryDeps, s.name);
538
+ if (playbook)
539
+ runDir.writeArtifact(`playbooks/${s.name}.md`, playbook.content);
540
+ return skillAppendix(memoryDeps, memoryContext, s.name);
541
+ },
542
+ }),
543
+ ];
544
+ const toolCtx = {
545
+ env,
546
+ runId,
547
+ rootRunId,
548
+ runDir,
549
+ depth,
550
+ budget,
551
+ leases,
552
+ sharedWorkspace,
553
+ changeTracker,
554
+ recorder,
555
+ toolSpanId: (id) => toolSpans.get(id) ?? null,
556
+ recordTaskGraph: (record) => taskGraphs.push(record),
557
+ addChildCost: (usd, unknown, approvalUsd = 0) => {
558
+ childCost += usd;
559
+ approvalCost += approvalUsd;
560
+ costUnknown ||= unknown;
561
+ },
562
+ sessionId,
563
+ optimRunId,
564
+ rolloutCandidate,
565
+ approvals,
566
+ };
567
+ for (const factory of extraToolFactories)
568
+ baseTools.push(...factory(toolCtx));
569
+ if (deps.mcp)
570
+ baseTools.push(...(await deps.mcp.tools()));
571
+ const tools = baseTools.map(withToolErrorCodes);
572
+ // Retrieval at run start (spec §8.3); the query embedding is charged to this run like any of its calls.
573
+ memoryDeps = {
574
+ env,
575
+ recorder,
576
+ parentSpanId: rootSpan,
577
+ budget,
578
+ signal: input.signal ?? new AbortController().signal,
579
+ charge: (usd, unknown) => {
580
+ recordSpend(db, rootRunId, usd, now(), sessionId, optimRunId);
581
+ ownCost += usd;
582
+ costUnknown ||= unknown;
583
+ },
584
+ };
585
+ if (input.memoryContext) {
586
+ // load_skill adds to `ids`, so the run works on its own copy.
587
+ memoryContext = { ...input.memoryContext, ids: new Set(input.memoryContext.ids) };
588
+ }
589
+ else if (!input.signal?.aborted) {
590
+ memoryContext = await retrieveRunMemories(memoryDeps, request.instruction, ["user", "global", ...(skill ? [`skill:${skill.name}`] : [])]);
591
+ input.onMemoryContext?.({ ...memoryContext, ids: new Set(memoryContext.ids) });
592
+ }
593
+ // The run directory keeps the memories the run started with (spec §5.1 `context/`).
594
+ if (memoryContext.block)
595
+ runDir.writeContext("memories.md", memoryContext.block);
596
+ const systemPrompt = renderSystemPrompt({
597
+ systemPrompt: systemPromptText,
598
+ plannerPrompt: tools.some((t) => t.name === "spawn") ? plannerPromptText : null,
599
+ workspace,
600
+ ...(rollout ? {} : { wikisDir: deps.paths.wikis }),
601
+ skillIndex: formatSkillIndex(deps.skills),
602
+ activeSkill: runSkill
603
+ ? { name: runSkill.name, body: startPlaybookSection ? `${runSkill.body}\n\n${startPlaybookSection}` : runSkill.body }
604
+ : undefined,
605
+ memories: memoryContext.block,
606
+ });
607
+ /** Prompt size for the pre-call estimate: the system prompt, the tool definitions and the non-system transcript. */
608
+ const requestChars = (messages, requestTools) => systemPrompt.length +
609
+ JSON.stringify(requestTools.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters }))).length +
610
+ estimatePromptChars(messages.filter((m) => m.role !== "system"));
611
+ const overrides = config.pricingOverrides;
612
+ /** Charges one priced call to this run: its budget, its own cost, its token totals and the spend ledger. */
613
+ const chargeCall = (callModel, msg) => {
614
+ const priced = priceUsage(callModel, msg.usage, overrides);
615
+ budget.charge(priced.costUsd);
616
+ recordSpend(db, rootRunId, priced.costUsd, now(), sessionId, optimRunId);
617
+ ownCost += priced.costUsd;
618
+ costUnknown ||= priced.costUnknown;
619
+ tokensIn += msg.usage.input + msg.usage.cacheRead + msg.usage.cacheWrite;
620
+ tokensOut += msg.usage.output;
621
+ deps.onEvent?.({
622
+ type: "llm_end",
623
+ runId,
624
+ depth,
625
+ costUsd: priced.costUsd,
626
+ costUnknown: priced.costUnknown,
627
+ tokensIn: msg.usage.input + msg.usage.cacheRead + msg.usage.cacheWrite,
628
+ tokensOut: msg.usage.output,
629
+ });
630
+ return priced;
631
+ };
632
+ const summarize = async (req) => {
633
+ const role = config.models.s1;
634
+ const summaryModel = env.registry.get(role.provider, role.id);
635
+ const effort = env.registry.clampEffort(summaryModel, role.effort ?? "off");
636
+ const estimate = estimateCallCostUsd(summaryModel, overrides, req.system.length + req.text.length, config.budgets.estimateOutputTokens);
637
+ if (!budget.canAfford(estimate)) {
638
+ throw new NexoError({
639
+ code: "BUDGET_EXCEEDED",
640
+ message: `The run budget cannot cover the compaction call (estimated $${estimate.toFixed(4)}, $${budget.remainingUsd().toFixed(4)} left)`,
641
+ hint: budgetExhaustedError(budget, input.budgetLimit ?? "run", sessionId !== null && !parent).hint,
642
+ });
643
+ }
644
+ const span = recorder.start({
645
+ kind: "compaction",
646
+ name: summaryModel.id,
647
+ parentSpanId: rootSpan,
648
+ model: summaryModel.id,
649
+ provider: summaryModel.provider,
650
+ tier: "s1",
651
+ effort,
652
+ modelSource: "default",
653
+ });
654
+ deps.onEvent?.({ type: "compaction_start", runId, depth });
655
+ let costUsd = 0;
656
+ let ok = false;
657
+ try {
658
+ const context = normalizeContext({ systemPrompt: req.system, messages: [{ role: "user", content: req.text, timestamp: now().getTime() }] });
659
+ const stream = await env.streamFn(summaryModel, context, { reasoning: effort === "off" ? undefined : effort, signal: input.signal });
660
+ const msg = await stream.result();
661
+ const priced = chargeCall(summaryModel, msg);
662
+ costUsd = priced.costUsd;
663
+ const summary = assistantText(msg);
664
+ const failed = msg.stopReason === "error" || msg.stopReason === "aborted";
665
+ recorder.finish(span, {
666
+ status: failed ? "error" : "ok",
667
+ tokensIn: msg.usage.input,
668
+ tokensOut: msg.usage.output,
669
+ cacheRead: msg.usage.cacheRead,
670
+ cacheWrite: msg.usage.cacheWrite,
671
+ costUsd: priced.costUsd,
672
+ costUnknown: priced.costUnknown,
673
+ attrs: { stopReason: msg.stopReason, errorMessage: msg.errorMessage, summary: deps.redact(summary) },
674
+ });
675
+ if (msg.stopReason === "aborted")
676
+ throw new NexoError({ code: "INTERNAL", message: "The compaction call was aborted" });
677
+ if (failed)
678
+ throw classifyProviderError(msg.errorMessage ?? "Provider error");
679
+ ok = true;
680
+ return summary;
681
+ }
682
+ catch (caught) {
683
+ if (recorder.get(span)?.status === "running")
684
+ recorder.finish(span, { status: "error", attrs: { error: deps.redact(toErrorPayload(caught)) } });
685
+ throw caught;
686
+ }
687
+ finally {
688
+ deps.onEvent?.({ type: "compaction_end", runId, depth, ok, costUsd });
689
+ }
690
+ };
691
+ let history = (request.history ?? []).filter((m) => m.role !== "system");
692
+ if (request.prepareHistory && !input.signal?.aborted) {
693
+ const tokensFor = (messages) => Math.ceil(requestChars([...messages, { role: "user", content: request.instruction, timestamp: 0 }], tools) / 4);
694
+ history = (await request.prepareHistory({ history, model, estimateTokens: tokensFor, summarize, signal: input.signal })).filter((m) => m.role !== "system");
695
+ }
696
+ const approvedBy = new Map();
697
+ let classify = null;
698
+ const runAgent = new Agent({
699
+ streamFn: env.streamFn,
700
+ initialState: { systemPrompt, model, thinkingLevel: resolved.effort, tools, messages: history },
701
+ toolExecution: "parallel",
702
+ prepareRequest: async ({ context, model: requestModel }) => {
703
+ const target = active.model;
704
+ const chars = requestChars(context.messages, context.tools ?? tools);
705
+ const estimate = estimateCallCostUsd(target, overrides, chars, config.budgets.estimateOutputTokens);
706
+ if (!budget.canAfford(estimate)) {
707
+ budgetExceeded = true;
708
+ runAgent.abort();
709
+ }
710
+ if (requestModel.provider === target.provider && requestModel.id === target.id)
711
+ return undefined;
712
+ return { model: target, thinkingLevel: active.resolved.effort };
713
+ },
714
+ transformContext: async (messages) => withBudgetLine(foreignToolCallsAsText(messages, active.model), budgetLine(budget)),
715
+ beforeToolCall: async ({ toolCall, args }, signal) => {
716
+ if (budget.isExhausted()) {
717
+ budgetExceeded = true;
718
+ return { block: true, reason: "BUDGET_EXCEEDED: the run budget is exhausted", terminate: true };
719
+ }
720
+ const classifier = classify;
721
+ const auth = await env.policy.authorize(deps.prompter, toolCall.name, args, signal, depth > 0 ? `subagent ${runId.slice(-6)}` : undefined, approvals
722
+ ? {
723
+ sessionRules: approvals.sessionRules,
724
+ ...(approvals.addSessionRule ? { addSessionRule: approvals.addSessionRule } : {}),
725
+ ...(classifier ? { classify: (name, a, s) => classifier(name, a, toolCall.id, s) } : {}),
726
+ }
727
+ : undefined);
728
+ if (!auth.allowed)
729
+ return { block: true, reason: toolErrorText(auth.error) };
730
+ approvedBy.set(toolCall.id, auth.by);
731
+ if (auth.by === "auto")
732
+ deps.onEvent?.({ type: "approval", runId, depth, toolCallId: toolCall.id, toolName: toolCall.name, reason: deps.redact(auth.reason ?? "") });
733
+ return undefined;
734
+ },
735
+ afterToolCall: async ({ toolCall, result }) => {
736
+ const text = contentText(result.content);
737
+ const spanId = toolSpans.get(toolCall.id);
738
+ if (text.length <= TOOL_RESULT_INLINE_LIMIT || !spanId)
739
+ return undefined;
740
+ const payloadRef = runDir.writeToolOutput(spanId, text);
741
+ toolPayloadRefs.set(toolCall.id, payloadRef);
742
+ const pointer = `${TOOL_OUTPUT_PREFIX}${payloadRef.slice("tool_outputs/".length)}`;
743
+ const nonText = result.content.filter((block) => block.type !== "text");
744
+ return { content: [{ type: "text", text: toolOutputExcerpt(text, pointer) }, ...nonText] };
745
+ },
746
+ });
747
+ if (approvals?.auto) {
748
+ classify = createApprovalClassifier({
749
+ env,
750
+ recorder,
751
+ // Approver calls are audited, not budgeted: they reserve from an unlimited budget and never touch the run's
752
+ // budget, cost or spend ledgers (so a turn cannot run out of budget because of its approvals).
753
+ budget: new RunBudget(Number.MAX_SAFE_INTEGER),
754
+ charge: (callModel, msg) => {
755
+ const priced = priceUsage(callModel, msg.usage, overrides);
756
+ approvalCost += priced.costUsd;
757
+ return priced;
758
+ },
759
+ parentSpanId: (toolCallId) => toolSpans.get(toolCallId) ?? turnSpan ?? rootSpan,
760
+ context: () => ({
761
+ request: approvals.userRequest,
762
+ ...(depth > 0 ? { task: request.instruction } : {}),
763
+ recent: runAgent.state.messages.filter((m) => m.role !== "system"),
764
+ workspace,
765
+ ...(depth > 0 ? { label: `subagent ${runId.slice(-6)}` } : {}),
766
+ }),
767
+ });
768
+ }
769
+ s2RequestUsd = () => estimateCallCostUsd(escalationTarget, overrides, requestChars(runAgent.state.messages, tools), config.budgets.estimateOutputTokens);
770
+ agent = runAgent;
771
+ seededCount = runAgent.state.messages.length;
772
+ // Steered texts in the order they were queued; the agent takes them one at a time between steps.
773
+ const pendingSteer = [];
774
+ let sawPrompt = false;
775
+ request.onSteeringReady?.({
776
+ steer: (text) => {
777
+ pendingSteer.push(text);
778
+ runAgent.steer({ role: "user", content: [{ type: "text", text }], timestamp: Date.now() });
779
+ },
780
+ clear: () => {
781
+ pendingSteer.length = 0;
782
+ runAgent.clearSteeringQueue();
783
+ },
784
+ });
785
+ let turnIndex = 0;
786
+ runAgent.subscribe((event) => {
787
+ switch (event.type) {
788
+ case "turn_start":
789
+ turnSpan = recorder.start({ kind: "turn", name: `turn ${++turnIndex}`, parentSpanId: rootSpan });
790
+ break;
791
+ case "message_start":
792
+ // The first user message is the instruction; later ones are steered messages being injected.
793
+ if (event.message.role === "user") {
794
+ if (!sawPrompt)
795
+ sawPrompt = true;
796
+ else {
797
+ const text = pendingSteer.shift();
798
+ if (text !== undefined)
799
+ deps.onEvent?.({ type: "steer_injected", runId, depth, text: deps.redact(text) });
800
+ }
801
+ }
802
+ if (event.message.role === "assistant") {
803
+ if (llmSpan)
804
+ recorder.finish(llmSpan, { status: "error", attrs: { reason: "superseded by a new assistant message" } });
805
+ llmSpan = recorder.start({
806
+ kind: "llm_call",
807
+ name: active.model.id,
808
+ parentSpanId: turnSpan ?? rootSpan,
809
+ model: active.model.id,
810
+ provider: active.model.provider,
811
+ tier: active.resolved.role ?? "custom",
812
+ effort: active.resolved.effort,
813
+ modelSource: active.resolved.source,
814
+ });
815
+ }
816
+ break;
817
+ case "message_update":
818
+ if (event.assistantMessageEvent.type === "text_delta") {
819
+ deps.onEvent?.({ type: "text_delta", runId, depth, delta: event.assistantMessageEvent.delta });
820
+ }
821
+ break;
822
+ case "message_end": {
823
+ if (event.message.role !== "assistant" || !llmSpan)
824
+ break;
825
+ const msg = event.message;
826
+ if (msg.stopReason !== "error" && msg.stopReason !== "aborted")
827
+ completedCalls++;
828
+ const priced = chargeCall(active.model, msg);
829
+ const content = deps.redact(recordedContent(msg));
830
+ const contentJson = JSON.stringify(content);
831
+ const contentRef = contentJson.length > TOOL_RESULT_INLINE_LIMIT ? runDir.writeToolOutput(llmSpan, contentJson) : null;
832
+ recorder.finish(llmSpan, {
833
+ status: msg.stopReason === "error" || msg.stopReason === "aborted" ? "error" : "ok",
834
+ tokensIn: msg.usage.input,
835
+ tokensOut: msg.usage.output,
836
+ cacheRead: msg.usage.cacheRead,
837
+ cacheWrite: msg.usage.cacheWrite,
838
+ costUsd: priced.costUsd,
839
+ costUnknown: priced.costUnknown,
840
+ payloadRef: contentRef,
841
+ attrs: {
842
+ stopReason: msg.stopReason,
843
+ errorMessage: msg.errorMessage,
844
+ responseModel: msg.responseModel,
845
+ content: contentRef ? undefined : content,
846
+ },
847
+ });
848
+ llmSpan = null;
849
+ break;
850
+ }
851
+ case "tool_execution_start": {
852
+ const kind = event.toolName === "load_skill" ? "skill_load" : "tool_call";
853
+ toolSpans.set(event.toolCallId, recorder.start({ kind, name: event.toolName, parentSpanId: turnSpan ?? rootSpan, attrs: { args: deps.redact(event.args) } }));
854
+ deps.onEvent?.({ type: "tool_start", runId, depth, toolName: event.toolName, toolCallId: event.toolCallId, args: deps.redact(event.args) });
855
+ break;
856
+ }
857
+ case "tool_execution_end": {
858
+ const text = contentText(event.result?.content);
859
+ const output = deps.redact(text);
860
+ deps.onEvent?.({
861
+ type: "tool_end",
862
+ runId,
863
+ depth,
864
+ toolName: event.toolName,
865
+ toolCallId: event.toolCallId,
866
+ isError: event.isError,
867
+ durationMs: event.durationMs ?? 0,
868
+ preview: output.slice(0, TOOL_END_PREVIEW_CHARS),
869
+ output,
870
+ });
871
+ const spanId = toolSpans.get(event.toolCallId);
872
+ if (spanId) {
873
+ const payloadRef = toolPayloadRefs.get(event.toolCallId) ?? null;
874
+ recorder.finish(spanId, {
875
+ status: event.isError ? "error" : "ok",
876
+ payloadRef,
877
+ attrs: { durationMs: event.durationMs, result: payloadRef ? undefined : output, approvedBy: approvedBy.get(event.toolCallId) },
878
+ });
879
+ }
880
+ const failures = monitor.toolResult(event.isError);
881
+ if (failures)
882
+ escalate(failures, "mid_run");
883
+ break;
884
+ }
885
+ case "turn_end": {
886
+ if (turnSpan)
887
+ recorder.finish(turnSpan, { status: "ok" });
888
+ turnSpan = null;
889
+ const calls = event.message.role === "assistant" ? event.message.content : [];
890
+ const argsOf = (id) => {
891
+ const call = calls.find((b) => b.type === "toolCall" && b.id === id);
892
+ return JSON.stringify(call?.type === "toolCall" ? call.arguments : null);
893
+ };
894
+ const stagnation = monitor.turnEnd(event.toolResults.map((r) => `${r.toolName}\u0000${argsOf(r.toolCallId)}\u0000${contentText(r.content)}`));
895
+ if (stagnation)
896
+ escalate(stagnation, "mid_run");
897
+ break;
898
+ }
899
+ default:
900
+ break;
901
+ }
902
+ });
903
+ /** Sends one prompt (the instruction, or a continuation), retries retryable provider errors, and sets status and output. */
904
+ const drive = async (text) => {
905
+ await runAgent.prompt(text);
906
+ // Retries are counted per streak of consecutive failures: a successful call since the last retry starts over.
907
+ let attempt = 0;
908
+ let succeededCalls = completedCalls;
909
+ for (;;) {
910
+ const last = lastAssistant(runAgent.state.messages);
911
+ if (!last || last.stopReason !== "error" || isContextOverflow(last) || !isRetryableAssistantError(last))
912
+ break;
913
+ if (completedCalls !== succeededCalls) {
914
+ attempt = 0;
915
+ succeededCalls = completedCalls;
916
+ }
917
+ attempt++;
918
+ const providerCfg = config.providers[active.model.provider] ?? {};
919
+ if (attempt > (providerCfg.maxRetries ?? 3) || input.signal?.aborted || budgetExceeded)
920
+ break;
921
+ const delay = providerRetryDelayMs(attempt, last.errorMessage ?? "", providerCfg);
922
+ logger.warn("retrying provider error", { attempt, delay_ms: Math.round(delay), error_message: last.errorMessage });
923
+ await env.sleep(delay, input.signal);
924
+ runAgent.state.messages = runAgent.state.messages.slice(0, -1);
925
+ await runAgent.continue();
926
+ }
927
+ const last = lastAssistant(runAgent.state.messages);
928
+ output = assistantText(last);
929
+ if (budgetExceeded) {
930
+ status = "budget_exceeded";
931
+ error = budgetExhaustedError(budget, input.budgetLimit ?? "run", sessionId !== null && !parent).toPayload();
932
+ }
933
+ else if (input.signal?.aborted || last?.stopReason === "aborted") {
934
+ status = "aborted";
935
+ }
936
+ else if (last?.stopReason === "error") {
937
+ status = "failed";
938
+ const message = last.errorMessage ?? "Provider error";
939
+ error = (isContextOverflow(last) ? contextOverflowError(message) : classifyProviderError(message)).toPayload();
940
+ }
941
+ };
942
+ input.signal?.addEventListener("abort", onAbort, { once: true });
943
+ if (input.signal?.aborted) {
944
+ status = "aborted";
945
+ }
946
+ else {
947
+ await drive(request.instruction);
948
+ // Scoring (spec §7.1 step 5): each failing round may start one S2 continuation, up to router.maxEscalations.
949
+ const selfCheckOn = policy.triggers.self_check.enabled;
950
+ if (status === "succeeded" && (plan.specs.length > 0 || plan.specError !== null || selfCheckOn)) {
951
+ const scoring = {
952
+ env,
953
+ runId,
954
+ depth,
955
+ runDir,
956
+ recorder,
957
+ runSpanId: rootSpan,
958
+ budget,
959
+ charge: chargeCall,
960
+ rubric,
961
+ generators: () => [...usedModels.values()],
962
+ signal: input.signal,
963
+ };
964
+ for (let round = 0; status === "succeeded" && !input.signal?.aborted; round++) {
965
+ const scoreInput = {
966
+ runId,
967
+ instruction: request.instruction,
968
+ finalOutput: output,
969
+ runDir: runDir.root,
970
+ workspace,
971
+ trajectory: summarizeSpans(listSpans(db, runId)),
972
+ ...(rollout?.reference ? { reference: rollout.reference } : {}),
973
+ };
974
+ // The self-check only feeds escalation, so it is skipped when an escalation could not happen anyway.
975
+ const selfCheck = selfCheckOn && !optimRunId && currentBlock() === null ? await runSelfCheck(scoring, active.model, active.resolved.effort, active.resolved.role ?? "custom", scoreInput) : null;
976
+ latestScores = await runScoringRound(scoring, plan, scoreInput, round);
977
+ scoreRows.push(...latestScores);
978
+ const judge = latestScores.find((r) => r.scorerType === "llm_judge" && r.status === "ok");
979
+ const signals = endOfRunSignals(policy, {
980
+ selfCheck,
981
+ failedDeterministic: latestScores.filter((r) => r.scorerKind === "deterministic" && r.status === "ok" && r.passed === false).map((r) => r.scorerName),
982
+ judgeScore: judge?.value ?? null,
983
+ });
984
+ const first = signals[0];
985
+ // A rollout's quality is its single scoring round: an S2 continuation would be prompted with judge rationales written against the case reference.
986
+ if (!first || optimRunId || input.signal?.aborted)
987
+ break;
988
+ const combined = { trigger: first.trigger, reason: signals.map((x) => x.reason).join("; ") };
989
+ // A continuation that fails or runs out of budget keeps the answer that was scored, and the model that wrote it;
990
+ // an abort still aborts the run.
991
+ const before = { output, status, error, active };
992
+ const escalationSpan = escalate(combined, "end_of_run");
993
+ if (!escalationSpan)
994
+ break;
995
+ let continuationError = null;
996
+ try {
997
+ await drive(continuationPrompt(signals, latestScores));
998
+ // drive() updates status and error; the casts undo the narrowing from the loop condition.
999
+ const ended = status;
1000
+ const endedError = error;
1001
+ if ((ended === "failed" || ended === "budget_exceeded") && !input.signal?.aborted) {
1002
+ continuationError = deps.redact(endedError ?? { code: "INTERNAL", message: `continuation ended ${ended}`, retryable: false });
1003
+ logger.warn("S2 continuation failed; keeping the previous answer", { status: ended, error: continuationError });
1004
+ output = before.output;
1005
+ status = before.status;
1006
+ error = before.error;
1007
+ active = before.active;
1008
+ budgetExceeded = false;
1009
+ continuationFailure = continuationError;
1010
+ deps.onEvent?.({
1011
+ type: "escalation_failed",
1012
+ runId,
1013
+ depth,
1014
+ trigger: combined.trigger,
1015
+ error: { code: continuationError.code, message: continuationError.message },
1016
+ model: `${active.model.provider}/${active.model.id}`,
1017
+ effort: active.resolved.effort,
1018
+ });
1019
+ }
1020
+ }
1021
+ finally {
1022
+ recorder.finish(escalationSpan, { status: "ok", attrs: continuationError ? { continuationError: { code: continuationError.code, message: continuationError.message } } : {} });
1023
+ }
1024
+ if (continuationError)
1025
+ break;
1026
+ }
1027
+ if (input.signal?.aborted)
1028
+ status = "aborted";
1029
+ }
1030
+ }
1031
+ }
1032
+ catch (caught) {
1033
+ if (input.signal?.aborted) {
1034
+ // An abort surfaces as a rejection from whatever was awaiting (for example the retry backoff); it is not a failure.
1035
+ status = "aborted";
1036
+ logger.info("run aborted", { error: caught });
1037
+ }
1038
+ else {
1039
+ status = "failed";
1040
+ error = toErrorPayload(caught);
1041
+ logger.error("run failed", { error: caught });
1042
+ }
1043
+ }
1044
+ finally {
1045
+ input.signal?.removeEventListener("abort", onAbort);
1046
+ leases.releaseAll(runId);
1047
+ }
1048
+ const safeError = error ? deps.redact(error) : null;
1049
+ const totalCost = ownCost + childCost;
1050
+ const attempt = (what, fn) => {
1051
+ try {
1052
+ fn();
1053
+ }
1054
+ catch (caught) {
1055
+ logger.error(`${what} failed`, { error: caught });
1056
+ }
1057
+ };
1058
+ if (!parent && changeTracker) {
1059
+ const tracker = changeTracker;
1060
+ attempt("change tracking", () => tracker.finalize());
1061
+ }
1062
+ const spanStatus = status === "succeeded" ? "ok" : "error";
1063
+ for (const open of [llmSpan, turnSpan]) {
1064
+ if (open)
1065
+ attempt("closing open span", () => recorder.finish(open, { status: "error", attrs: { reason: `run ended: ${status}` } }));
1066
+ }
1067
+ if (runSpan) {
1068
+ const span = runSpan;
1069
+ attempt("finishing run span", () => recorder.finish(span, { status: spanStatus, costUsd: 0, attrs: { status, totalCostUsd: totalCost } }));
1070
+ }
1071
+ const finalJson = runJson(status, output, safeError);
1072
+ attempt("writing run.json", () => runDir.writeRunJson(finalJson));
1073
+ attempt("updating run row", () => updateRun(db, runId, {
1074
+ status,
1075
+ endedAt: finalJson.endedAt,
1076
+ costUsd: totalCost,
1077
+ costUnknown,
1078
+ tokensIn,
1079
+ tokensOut,
1080
+ error: safeError,
1081
+ modelFinal: `${active.resolved.provider}/${active.resolved.id}`,
1082
+ tierFinal: active.resolved.role,
1083
+ escalations,
1084
+ }));
1085
+ // Online learning (spec §7.1 step 6, §8.1): a root run that was not interrupted gets a reflect job; it runs later, in a
1086
+ // worker. Optimization rollouts are never learned from.
1087
+ if (!parent && !optimRunId && config.learning.enabled && status !== "aborted") {
1088
+ attempt("enqueueing the learn job", () => enqueueLearnJob(db, { runId, trigger: "run_end" }, now().toISOString()));
1089
+ }
1090
+ attempt("run_end event", () => deps.onEvent?.({ type: "run_end", runId, depth, status, costUsd: totalCost }));
1091
+ logger.info("run finished", { status, cost_usd: totalCost, approval_cost_usd: approvalCost });
1092
+ const messages = agent ? newMessages(agent.state.messages, seededCount) : [];
1093
+ return {
1094
+ trajectoryId: runId,
1095
+ runDir: runDir.root,
1096
+ status,
1097
+ output,
1098
+ costUsd: totalCost,
1099
+ costUnknown,
1100
+ approvalCostUsd: approvalCost,
1101
+ ...(safeError ? { error: safeError } : {}),
1102
+ messages,
1103
+ model: modelInfo(active.model, active.resolved),
1104
+ ...(scoreRows.length > 0 ? { scores: latestScores } : {}),
1105
+ escalations,
1106
+ ...(continuationFailure ? { continuationError: continuationFailure } : {}),
1107
+ };
1108
+ }
1109
+ function modelInfo(model, resolved) {
1110
+ return { provider: model.provider, id: model.id, effort: resolved.effort, contextWindow: model.contextWindow, role: resolved.role ?? null };
1111
+ }
1112
+ /** The pi messages appended after the seeded system prompt and history, without system messages. */
1113
+ function newMessages(messages, seededCount) {
1114
+ return messages.slice(seededCount).filter((m) => m.role === "user" || m.role === "assistant" || m.role === "toolResult");
1115
+ }