@hexdecimal16/nexo 0.0.0-stage → 0.2.1

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 (209) 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 +78 -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 +266 -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/cli/src/version.js +19 -0
  20. package/core/src/approval/classifier.js +152 -0
  21. package/core/src/config/load.js +283 -0
  22. package/core/src/config/schema.js +186 -0
  23. package/core/src/cost/admission.js +90 -0
  24. package/core/src/cost/budget.js +67 -0
  25. package/core/src/cost/pricing.js +53 -0
  26. package/core/src/engine/charged-completion.js +79 -0
  27. package/core/src/engine/errors.js +77 -0
  28. package/core/src/engine/mcp.js +11 -0
  29. package/core/src/engine/messages.js +86 -0
  30. package/core/src/engine/prompts.js +32 -0
  31. package/core/src/engine/provider-gate.js +33 -0
  32. package/core/src/engine/recorder.js +61 -0
  33. package/core/src/engine/run.js +1115 -0
  34. package/core/src/engine/semaphore.js +45 -0
  35. package/core/src/engine/spawn-tool.js +119 -0
  36. package/core/src/engine/task-graph.js +153 -0
  37. package/core/src/index.js +32 -0
  38. package/core/src/learn/caller.js +171 -0
  39. package/core/src/learn/context.js +112 -0
  40. package/core/src/learn/embedder.js +216 -0
  41. package/core/src/learn/job.js +196 -0
  42. package/core/src/learn/wiki.js +116 -0
  43. package/core/src/learn/worker.js +141 -0
  44. package/core/src/optimize/adapter.js +250 -0
  45. package/core/src/optimize/climb.js +338 -0
  46. package/core/src/optimize/mine.js +95 -0
  47. package/core/src/optimize/optimize.js +377 -0
  48. package/core/src/optimize/optimizer-run.js +67 -0
  49. package/core/src/optimize/reflect.js +100 -0
  50. package/core/src/optimize/scratchpad-wiki.js +69 -0
  51. package/core/src/providers/claude-p.js +363 -0
  52. package/core/src/providers/kiro-p.js +408 -0
  53. package/core/src/providers/models.js +10 -0
  54. package/core/src/scoring/calibration.js +31 -0
  55. package/core/src/scoring/continuation.js +24 -0
  56. package/core/src/scoring/runner.js +322 -0
  57. package/core/src/scoring/sources.js +88 -0
  58. package/core/src/session/lock.js +88 -0
  59. package/core/src/session/session.js +647 -0
  60. package/core/src/session/shell.js +26 -0
  61. package/core/src/session/transcript.js +86 -0
  62. package/core/src/settings/config-edit.js +472 -0
  63. package/core/src/settings/credentials.js +120 -0
  64. package/core/src/settings/doctor.js +103 -0
  65. package/core/src/settings/settings.js +265 -0
  66. package/mcp/src/hub.js +184 -0
  67. package/mcp/src/index.js +1 -0
  68. package/memory/src/curate.js +121 -0
  69. package/memory/src/index.js +4 -0
  70. package/memory/src/prompts.js +143 -0
  71. package/memory/src/retrieval.js +91 -0
  72. package/memory/src/similarity.js +47 -0
  73. package/optimize/src/engine.js +206 -0
  74. package/optimize/src/index.js +8 -0
  75. package/optimize/src/merge.js +73 -0
  76. package/optimize/src/novelty.js +37 -0
  77. package/optimize/src/pareto.js +83 -0
  78. package/optimize/src/proposer.js +148 -0
  79. package/optimize/src/report.js +107 -0
  80. package/optimize/src/rng.js +34 -0
  81. package/optimize/src/target.js +34 -0
  82. package/package.json +47 -4
  83. package/router/src/effort.js +5 -0
  84. package/router/src/escalation.js +171 -0
  85. package/router/src/index.js +4 -0
  86. package/router/src/registry.js +21 -0
  87. package/router/src/resolve.js +117 -0
  88. package/scorers/src/deterministic.js +194 -0
  89. package/scorers/src/family.js +48 -0
  90. package/scorers/src/index.js +6 -0
  91. package/scorers/src/judge.js +284 -0
  92. package/scorers/src/regex-worker.js +3 -0
  93. package/scorers/src/spec.js +147 -0
  94. package/scorers/src/trajectory.js +22 -0
  95. package/scorers/src/types.js +1 -0
  96. package/sdk/src/index.js +3 -0
  97. package/sdk/src/nexo.js +94 -0
  98. package/sdk/src/runtime.js +39 -0
  99. package/skills/bundled/browser/SKILL.md +57 -0
  100. package/skills/bundled/wiki/SKILL.md +73 -0
  101. package/skills/src/frontmatter.js +25 -0
  102. package/skills/src/index.js +3 -0
  103. package/skills/src/load-skill-tool.js +41 -0
  104. package/skills/src/loader.js +95 -0
  105. package/store/src/artifacts.js +124 -0
  106. package/store/src/budget-ledger.js +18 -0
  107. package/store/src/cost-report.js +46 -0
  108. package/store/src/cursor.js +35 -0
  109. package/store/src/db.js +83 -0
  110. package/store/src/errors.js +9 -0
  111. package/store/src/eval-cases.js +255 -0
  112. package/store/src/feedback.js +154 -0
  113. package/store/src/goldens.js +61 -0
  114. package/store/src/ids.js +6 -0
  115. package/store/src/index.js +25 -0
  116. package/store/src/judge-calibration.js +182 -0
  117. package/store/src/learn-jobs.js +145 -0
  118. package/store/src/memories.js +261 -0
  119. package/store/src/migrations/001_init.sql +81 -0
  120. package/store/src/migrations/002_feedback.sql +9 -0
  121. package/store/src/migrations/003_sessions.sql +19 -0
  122. package/store/src/migrations/004_scoring.sql +22 -0
  123. package/store/src/migrations/005_judge_calibration.sql +27 -0
  124. package/store/src/migrations/006_learning.sql +77 -0
  125. package/store/src/migrations/007_optimize.sql +55 -0
  126. package/store/src/migrations/008_mined_cases_and_climb.sql +46 -0
  127. package/store/src/mine.js +51 -0
  128. package/store/src/optim.js +291 -0
  129. package/store/src/paths.js +22 -0
  130. package/store/src/playbooks.js +199 -0
  131. package/store/src/reindex.js +143 -0
  132. package/store/src/run-dir.js +151 -0
  133. package/store/src/runs.js +310 -0
  134. package/store/src/scores.js +92 -0
  135. package/store/src/sessions.js +304 -0
  136. package/store/src/span-tree.js +98 -0
  137. package/store/src/spans.js +84 -0
  138. package/store/src/sql.js +13 -0
  139. package/store/src/workspace-copy.js +80 -0
  140. package/telemetry/src/errors.js +32 -0
  141. package/telemetry/src/index.js +3 -0
  142. package/telemetry/src/logger.js +39 -0
  143. package/telemetry/src/redact.js +106 -0
  144. package/tools/src/builtin.js +269 -0
  145. package/tools/src/change-tracker.js +57 -0
  146. package/tools/src/confine.js +101 -0
  147. package/tools/src/index.js +7 -0
  148. package/tools/src/leases.js +57 -0
  149. package/tools/src/policy.js +162 -0
  150. package/tools/src/read-only.js +338 -0
  151. package/tools/src/session-rules.js +140 -0
  152. package/tui/src/app.js +965 -0
  153. package/tui/src/approvals.js +96 -0
  154. package/tui/src/commands.js +38 -0
  155. package/tui/src/components.js +248 -0
  156. package/tui/src/index.js +5 -0
  157. package/tui/src/picker.js +78 -0
  158. package/tui/src/session-picker.js +100 -0
  159. package/tui/src/settings-screen.js +346 -0
  160. package/tui/src/text.js +70 -0
  161. package/tui/src/theme.js +44 -0
  162. package/web/public/cost.html +25 -0
  163. package/web/public/fonts/GeistMono-400.woff2 +0 -0
  164. package/web/public/fonts/GeistMono-600.woff2 +0 -0
  165. package/web/public/fonts/InstrumentSans-400.woff2 +0 -0
  166. package/web/public/fonts/InstrumentSans-600.woff2 +0 -0
  167. package/web/public/index.html +39 -0
  168. package/web/public/judge.html +21 -0
  169. package/web/public/learning.html +46 -0
  170. package/web/public/lib/api-types.ts +616 -0
  171. package/web/public/lib/common-view.ts +47 -0
  172. package/web/public/lib/cost-view.ts +35 -0
  173. package/web/public/lib/files-view.ts +90 -0
  174. package/web/public/lib/format.ts +35 -0
  175. package/web/public/lib/html.ts +51 -0
  176. package/web/public/lib/judge-view.ts +62 -0
  177. package/web/public/lib/learning-view.ts +102 -0
  178. package/web/public/lib/optim-view.ts +148 -0
  179. package/web/public/lib/pager.ts +56 -0
  180. package/web/public/lib/poller.ts +79 -0
  181. package/web/public/lib/run-view.ts +61 -0
  182. package/web/public/lib/runs-view.ts +87 -0
  183. package/web/public/lib/score-view.ts +94 -0
  184. package/web/public/lib/sessions-view.ts +28 -0
  185. package/web/public/lib/span-view.ts +90 -0
  186. package/web/public/lib/theme.ts +60 -0
  187. package/web/public/lib/timeline.ts +97 -0
  188. package/web/public/lib/wikis-view.ts +257 -0
  189. package/web/public/optim.html +30 -0
  190. package/web/public/pages/api.ts +60 -0
  191. package/web/public/pages/cost.ts +36 -0
  192. package/web/public/pages/judge.ts +15 -0
  193. package/web/public/pages/learning.ts +92 -0
  194. package/web/public/pages/optim.ts +68 -0
  195. package/web/public/pages/paging.ts +18 -0
  196. package/web/public/pages/run.ts +221 -0
  197. package/web/public/pages/runs.ts +91 -0
  198. package/web/public/pages/sessions.ts +25 -0
  199. package/web/public/pages/wikis.ts +103 -0
  200. package/web/public/run.html +36 -0
  201. package/web/public/sessions.html +28 -0
  202. package/web/public/style.css +288 -0
  203. package/web/public/wikis.html +25 -0
  204. package/web/src/api.js +682 -0
  205. package/web/src/http-errors.js +60 -0
  206. package/web/src/index.js +5 -0
  207. package/web/src/server.js +292 -0
  208. package/web/src/static.js +86 -0
  209. package/web/src/strip.js +22 -0
@@ -0,0 +1,647 @@
1
+ import { realpathSync, statSync } from "node:fs";
2
+ import { resolve } from "node:path";
3
+ import { EFFORTS, isEffort, parseModelRef } from "../../../router/src/index.js";
4
+ import { getSpent, latestSessionRunId, latestSessionRunWorkspace, deleteSessionRow, listSessionRows, maxSessionTurn, newId, recordFeedback, SessionDir, sessionRowFromJson, upsertSessionRow, } from "../../../store/src/index.js";
5
+ import { runBash, sameSessionRule } from "../../../tools/src/index.js";
6
+ import { createRedactor, NexoError, toErrorPayload } from "../../../telemetry/src/index.js";
7
+ import { checkAdmission, runBudgetLimit, sessionScope } from "../cost/admission.js";
8
+ import { RunBudget } from "../cost/budget.js";
9
+ import { estimateCallCostUsd } from "../cost/pricing.js";
10
+ import { createEngineEnv, executeRun, } from "../engine/run.js";
11
+ import { LearnWorker } from "../learn/worker.js";
12
+ import { activeMessageLines, buildHistory, COMPACTION_SYSTEM_PROMPT, KEEP_VERBATIM_TURNS, latestCompaction, renderForSummary, titleFrom, } from "./transcript.js";
13
+ import { SessionLock } from "./lock.js";
14
+ import { capShellOutput, withShellNotes } from "./shell.js";
15
+ const EPSILON = 1e-9;
16
+ /** Share of the s1 model's context window the compaction input may fill (at about 4 characters per token). */
17
+ const COMPACTION_INPUT_WINDOW_SHARE = 0.5;
18
+ /** Constructor guard: only this module's factories can build a Session. */
19
+ const INIT = Symbol("Session.init");
20
+ function invalid(message, hint) {
21
+ return new NexoError({ code: "INVALID_REQUEST", message, ...(hint ? { hint } : {}) });
22
+ }
23
+ function resolveWorkspace(cwd, workspace) {
24
+ const dir = resolve(cwd, workspace);
25
+ let isDir = false;
26
+ try {
27
+ isDir = statSync(dir).isDirectory();
28
+ }
29
+ catch {
30
+ isDir = false;
31
+ }
32
+ if (!isDir) {
33
+ throw new NexoError({
34
+ code: "CONFIG_INVALID",
35
+ message: `Workspace ${dir} is not an existing directory`,
36
+ hint: "Pass an existing directory to --workspace",
37
+ context: { workspace: dir },
38
+ });
39
+ }
40
+ return realpathSync(dir);
41
+ }
42
+ function refusedResult(error) {
43
+ return { trajectoryId: null, runDir: null, status: "budget_exceeded", output: "", costUsd: 0, costUnknown: false, error, messages: [], model: null };
44
+ }
45
+ /** Request size of the turn's last call: what the model saw plus what it wrote. */
46
+ function contextTokens(messages) {
47
+ for (let i = messages.length - 1; i >= 0; i--) {
48
+ const m = messages[i];
49
+ if (m?.role !== "assistant")
50
+ continue;
51
+ const u = m.usage;
52
+ const total = u.input + u.cacheRead + u.cacheWrite + u.output;
53
+ if (total > 0)
54
+ return total;
55
+ }
56
+ return null;
57
+ }
58
+ /**
59
+ * A persistent conversation: each `turn` is one engine run that continues the session's transcript. State is saved to
60
+ * `session.json`, `transcript.jsonl` and the `sessions` row after every change.
61
+ */
62
+ export class Session {
63
+ id;
64
+ deps;
65
+ dir;
66
+ lock;
67
+ env;
68
+ configHash;
69
+ state;
70
+ lines;
71
+ lastModelInfo = null;
72
+ busy = false;
73
+ compactRequested = false;
74
+ /** The latest turn's workspace for `shellDir`, looked up once per turn; undefined until then, null for none. */
75
+ latestWorkspace;
76
+ onEvent;
77
+ /** Runs this process's learn jobs in the background after each turn and verdict (spec §8.1). */
78
+ learner;
79
+ /**
80
+ * The memories retrieved at this process's first turn, injected unchanged into every later turn (also after /clear
81
+ * and compaction), so the system prompt and its prompt cache stay the same (spec §8.3).
82
+ */
83
+ memoryContext = null;
84
+ /** Use `createSession` or `resumeSession`. Saves the state and takes ownership of `lock`. */
85
+ constructor(init, deps, dir, state, lines, lock) {
86
+ if (init !== INIT)
87
+ throw new NexoError({ code: "INTERNAL", message: "Use createSession or resumeSession" });
88
+ this.id = state.id;
89
+ this.deps = deps;
90
+ this.dir = dir;
91
+ this.state = state;
92
+ this.lines = lines;
93
+ this.lock = lock;
94
+ this.configHash = deps.configHash;
95
+ this.env = this.buildEnv(deps);
96
+ this.learner = new LearnWorker(this.env);
97
+ this.save();
98
+ }
99
+ get dirPath() {
100
+ return this.dir.root;
101
+ }
102
+ get title() {
103
+ return this.state.title;
104
+ }
105
+ get cwd() {
106
+ return this.state.cwd;
107
+ }
108
+ /** The `--workspace` directory every turn shares; null when each turn works in its own run folder's `workspace/`. */
109
+ get workspace() {
110
+ return this.state.workspace;
111
+ }
112
+ /** Where run folders are created; a run-folder session's turn files are in `<runsDir>/<run id>/workspace`. */
113
+ get runsDir() {
114
+ return this.deps.paths.runs;
115
+ }
116
+ /**
117
+ * Where `!` commands run: the `--workspace` directory, else the latest turn's workspace (whose files the next turn
118
+ * starts from), else the directory nexo was started in.
119
+ */
120
+ get shellDir() {
121
+ if (this.state.workspace !== null)
122
+ return this.state.workspace;
123
+ this.latestWorkspace ??= latestSessionRunWorkspace(this.deps.db, this.id)?.dir ?? null;
124
+ return this.latestWorkspace ?? this.state.cwd;
125
+ }
126
+ get status() {
127
+ return this.state.status;
128
+ }
129
+ get turns() {
130
+ return this.state.turns;
131
+ }
132
+ get costUsd() {
133
+ return this.state.costUsd;
134
+ }
135
+ /** The session cap: the `/budget` override, else `budgets.perSessionUsd` of the current config. */
136
+ get budgetUsd() {
137
+ return this.state.budgetOverrideUsd ?? this.env.deps.config.budgets.perSessionUsd;
138
+ }
139
+ /** The `/budget` override, or null when the cap follows the config. */
140
+ get budgetOverrideUsd() {
141
+ return this.state.budgetOverrideUsd ?? null;
142
+ }
143
+ /** "Always allow … this session" rules, applied to every turn and its subagents. */
144
+ get sessionRules() {
145
+ return this.state.sessionRules ?? [];
146
+ }
147
+ addSessionRule(rule) {
148
+ const rules = this.state.sessionRules ?? [];
149
+ if (rules.some((r) => sameSessionRule(r, rule)))
150
+ return;
151
+ this.state.sessionRules = [...rules, rule];
152
+ this.save();
153
+ }
154
+ /** Removes rule `index` (1-based, as /permissions lists them). */
155
+ removeSessionRule(index) {
156
+ const rules = this.state.sessionRules ?? [];
157
+ const rule = Number.isInteger(index) ? rules[index - 1] : undefined;
158
+ if (!rule)
159
+ throw invalid(`There is no rule ${index}`, `Use a number from /permissions (1 to ${rules.length})`);
160
+ this.state.sessionRules = rules.filter((_, i) => i !== index - 1);
161
+ this.save();
162
+ return rule;
163
+ }
164
+ clearSessionRules() {
165
+ const count = this.state.sessionRules?.length ?? 0;
166
+ this.state.sessionRules = [];
167
+ this.save();
168
+ return count;
169
+ }
170
+ /** Auto mode for the next turns: the /auto override, else tools.autoApprove. */
171
+ get autoApprove() {
172
+ return this.state.autoApprove ?? this.env.deps.config.tools.autoApprove === "on";
173
+ }
174
+ get autoApproveOverride() {
175
+ return this.state.autoApprove ?? null;
176
+ }
177
+ setAutoApprove(on) {
178
+ this.state.autoApprove = on;
179
+ this.save();
180
+ }
181
+ get remainingUsd() {
182
+ return Math.max(0, this.budgetUsd - this.state.costUsd);
183
+ }
184
+ /** The `/model` override, or null. */
185
+ get model() {
186
+ return this.state.model;
187
+ }
188
+ /** The `/model` override as `provider/id` (a role such as "s2" resolved against the config), or null. */
189
+ get modelOverride() {
190
+ const ref = this.state.model;
191
+ if (ref === null)
192
+ return null;
193
+ try {
194
+ const { config } = this.env.deps;
195
+ const parsed = parseModelRef(ref, { s1: config.models.s1, s2: config.models.s2 });
196
+ return `${parsed.provider}/${parsed.id}`;
197
+ }
198
+ catch {
199
+ return ref;
200
+ }
201
+ }
202
+ /** True when the next turn starts on S2 because the latest one stopped on S2 unfinished (and no `/model` override is set). */
203
+ get continuesOnS2() {
204
+ return this.state.continueOnS2 === true && this.state.model === null;
205
+ }
206
+ /** The `/effort` override, or null. */
207
+ get effort() {
208
+ return isEffort(this.state.effort) ? this.state.effort : null;
209
+ }
210
+ /** Model and effort the latest turn ran with (this process only); null before the first turn. */
211
+ get lastModel() {
212
+ return this.lastModelInfo;
213
+ }
214
+ /** The latest turn's request size as a fraction of its model's context window; null before the first turn. */
215
+ get contextFraction() {
216
+ const c = this.state.context;
217
+ return c && c.window > 0 ? c.tokens / c.window : null;
218
+ }
219
+ get lastRunId() {
220
+ return this.state.lastRunId;
221
+ }
222
+ get running() {
223
+ return this.busy;
224
+ }
225
+ /** `!` commands waiting to go to the model with the next turn. */
226
+ get pendingShellCount() {
227
+ return this.state.pendingShell?.length ?? 0;
228
+ }
229
+ /** True after `compact()` until the next turn compacts. */
230
+ get compactPending() {
231
+ return this.compactRequested;
232
+ }
233
+ /** The transcript in order: message lines and compaction markers. Lines read from disk are redacted. */
234
+ transcript() {
235
+ return this.lines;
236
+ }
237
+ /** Messages steered before the run's agent exists; handed to it once it does. */
238
+ steerPending = [];
239
+ steerCtl = null;
240
+ /** Sends a message into the running turn, injected before the agent's next model call. False when no turn runs. */
241
+ steer(text) {
242
+ if (!this.busy || !text.trim())
243
+ return false;
244
+ if (this.steerCtl)
245
+ this.steerCtl.steer(text);
246
+ else
247
+ this.steerPending.push(text);
248
+ return true;
249
+ }
250
+ /** Drops steered messages the running turn has not taken yet. */
251
+ clearSteering() {
252
+ this.steerPending = [];
253
+ this.steerCtl?.clear();
254
+ }
255
+ /**
256
+ * Runs one turn. Refusals (session cap, daily or monthly cap) return a `budget_exceeded` result without a run.
257
+ * Throws INVALID_REQUEST for an empty instruction, a closed session or while another turn is running, and STORE_IO
258
+ * when the session cannot be saved.
259
+ */
260
+ async turn(instruction, options = {}) {
261
+ if (!instruction.trim())
262
+ throw invalid("The message is empty");
263
+ if (this.state.status === "closed")
264
+ throw invalid(`Session ${this.id} is closed`, "Resume it with `nexo --resume`");
265
+ if (this.busy)
266
+ throw invalid("A turn is already running", "Wait for it to finish or abort it");
267
+ this.busy = true;
268
+ try {
269
+ this.reloadConfig();
270
+ const { config } = this.env.deps;
271
+ const remaining = this.remainingUsd;
272
+ if (remaining <= EPSILON) {
273
+ return refusedResult(new NexoError({
274
+ code: "BUDGET_EXCEEDED",
275
+ message: `Session budget of $${this.budgetUsd.toFixed(2)} is exhausted ($${this.state.costUsd.toFixed(4)} spent)`,
276
+ hint: "Raise it for this session with /budget <usd>, or raise budgets.perSessionUsd in your nexo config",
277
+ context: { sessionId: this.id, limitUsd: this.budgetUsd, spentUsd: this.state.costUsd },
278
+ }).toPayload());
279
+ }
280
+ try {
281
+ checkAdmission(this.deps.db, config.budgets, this.env.now());
282
+ }
283
+ catch (error) {
284
+ return refusedResult(this.env.deps.redact(toErrorPayload(error)));
285
+ }
286
+ const limit = runBudgetLimit(this.deps.db, config.budgets, this.env.now(), { run: config.budgets.perRunUsd, session: remaining });
287
+ const turnIndex = this.state.turns + 1;
288
+ this.onEvent = options.onEvent;
289
+ const sent = withShellNotes(this.state.pendingShell ?? [], instruction);
290
+ const workspace = this.state.workspace;
291
+ const previous = workspace === null ? latestSessionRunWorkspace(this.deps.db, this.id) : undefined;
292
+ const result = await executeRun(this.env, {
293
+ request: {
294
+ instruction: sent,
295
+ history: buildHistory(this.lines, this.env.now().getTime()),
296
+ prepareHistory: this.compactionHook(turnIndex, limit.usd),
297
+ sessionId: this.id,
298
+ turnIndex,
299
+ ...(workspace !== null ? { workspace } : {}),
300
+ ...(previous ? { workspaceFrom: previous } : {}),
301
+ ...(this.state.model ? { model: this.state.model } : {}),
302
+ ...(this.continuesOnS2 ? { startOnS2: true } : {}),
303
+ ...(this.effort ? { effort: this.effort } : {}),
304
+ sessionRules: () => this.state.sessionRules ?? [],
305
+ addSessionRule: (rule) => this.addSessionRule(rule),
306
+ autoApprove: this.autoApprove,
307
+ onSteeringReady: (control) => {
308
+ this.steerCtl = control;
309
+ for (const text of this.steerPending.splice(0))
310
+ control.steer(text);
311
+ },
312
+ },
313
+ budget: new RunBudget(limit.usd),
314
+ budgetLimit: limit.by,
315
+ signal: options.signal,
316
+ ...(this.memoryContext
317
+ ? { memoryContext: this.memoryContext }
318
+ : {
319
+ onMemoryContext: (context) => {
320
+ this.memoryContext = context;
321
+ },
322
+ }),
323
+ });
324
+ if (result.trajectoryId !== null)
325
+ this.recordTurn(turnIndex, instruction, sent, result);
326
+ this.learner.kick();
327
+ return result;
328
+ }
329
+ finally {
330
+ this.latestWorkspace = undefined;
331
+ this.onEvent = undefined;
332
+ this.steerCtl = null;
333
+ this.steerPending = [];
334
+ this.busy = false;
335
+ }
336
+ }
337
+ /**
338
+ * Runs a `!` command in the workspace with the bash tool's timeout, outside any run (no model call, cost or approval).
339
+ * Its command and output go to the model in front of the next turn's message. Throws INVALID_REQUEST for an empty
340
+ * command, a closed session or while a turn or another command is running.
341
+ */
342
+ async shell(command, options = {}) {
343
+ const trimmed = command.trim();
344
+ if (!trimmed)
345
+ throw invalid("The command is empty", "Example: !git status");
346
+ if (this.state.status === "closed")
347
+ throw invalid(`Session ${this.id} is closed`, "Resume it with `nexo --resume`");
348
+ this.assertIdle();
349
+ this.busy = true;
350
+ try {
351
+ this.reloadConfig();
352
+ const { config, redact } = this.env.deps;
353
+ const outcome = await runBash({ command: trimmed, cwd: this.shellDir, timeoutMs: config.tools.bashTimeoutMs, signal: options.signal });
354
+ const result = { ...outcome, output: redact(outcome.output) };
355
+ const note = { command: redact(trimmed), ended: result.ended, exitCode: result.exitCode, output: capShellOutput(result.output, result.truncated) };
356
+ this.state.pendingShell = [...(this.state.pendingShell ?? []), note];
357
+ this.save();
358
+ return result;
359
+ }
360
+ finally {
361
+ this.busy = false;
362
+ }
363
+ }
364
+ /** Sets this session's cap in USD (overrides `budgets.perSessionUsd`). */
365
+ setBudget(usd) {
366
+ if (!Number.isFinite(usd) || usd <= 0)
367
+ throw invalid(`Budget must be a positive number of USD, got ${usd}`, "Example: /budget 10");
368
+ this.state.budgetOverrideUsd = usd;
369
+ this.save();
370
+ }
371
+ /** Sets the session's model override ("s1", "s2" or "provider/model-id"); null clears it. */
372
+ setModel(ref) {
373
+ if (ref !== null) {
374
+ try {
375
+ const { config } = this.env.deps;
376
+ const parsed = parseModelRef(ref, { s1: config.models.s1, s2: config.models.s2 });
377
+ this.env.registry.get(parsed.provider, parsed.id);
378
+ }
379
+ catch (error) {
380
+ const e = error instanceof NexoError ? error : undefined;
381
+ throw new NexoError({
382
+ code: "INVALID_REQUEST",
383
+ message: e?.message ?? `Unknown model "${ref}"`,
384
+ hint: 'Use "s1", "s2" or "provider/model-id" from pi-ai\'s catalog',
385
+ context: { ref },
386
+ cause: error,
387
+ });
388
+ }
389
+ }
390
+ this.state.model = ref;
391
+ this.save();
392
+ }
393
+ /** Sets the session's effort override; null clears it. */
394
+ setEffort(level) {
395
+ if (level !== null && !isEffort(level))
396
+ throw invalid(`Effort must be one of ${EFFORTS.join(", ")}, got "${String(level)}"`);
397
+ this.state.effort = level;
398
+ this.save();
399
+ }
400
+ /** Compacts older turns at the start of the next turn, whatever the context size. */
401
+ compact() {
402
+ this.assertIdle();
403
+ this.compactRequested = true;
404
+ }
405
+ /** Starts a new conversation in the same session: a compaction marker with an empty summary. */
406
+ clear() {
407
+ this.assertIdle();
408
+ this.appendLines([{ type: "compaction", turnIndex: this.state.turns, summary: "", replacedThroughTurn: this.state.turns }]);
409
+ this.compactRequested = false;
410
+ this.state.context = null;
411
+ this.state.pendingShell = [];
412
+ this.state.continueOnS2 = false;
413
+ this.save();
414
+ }
415
+ /** Records a verdict on the latest turn (spec §7.1 feedback). Throws INVALID_REQUEST before the first turn. */
416
+ review(verdict, comment) {
417
+ const runId = this.state.lastRunId;
418
+ if (!runId)
419
+ throw invalid("There is no turn to review yet");
420
+ const row = recordFeedback(this.deps.db, {
421
+ runId,
422
+ verdict,
423
+ comment,
424
+ nowIso: this.env.now().toISOString(),
425
+ redact: this.env.deps.redact,
426
+ learn: this.env.deps.config.learning.enabled,
427
+ });
428
+ this.learner.kick();
429
+ return row;
430
+ }
431
+ /** Resolves when the learn jobs started in the background have finished. */
432
+ learnIdle() {
433
+ return this.learner.idle();
434
+ }
435
+ /** Marks the session closed and releases its lock; a session that never ran a turn is deleted instead; `resumeSession` reopens it. Throws CONFLICT while a turn runs. */
436
+ close() {
437
+ if (this.busy) {
438
+ throw new NexoError({ code: "CONFLICT", message: "A turn is running", hint: "Abort the turn (its signal) and wait for it to finish before closing" });
439
+ }
440
+ if (this.state.status === "closed")
441
+ return;
442
+ // A job cut short goes back to pending (or is reclaimed as stale if the process exits first).
443
+ void this.learner.stop();
444
+ this.state.status = "closed";
445
+ if (this.isEmpty()) {
446
+ // Nothing happened: leave no empty session behind. The lock goes last, so nobody can resume a half-deleted session.
447
+ this.dir.remove();
448
+ deleteSessionRow(this.deps.db, this.id);
449
+ this.lock.release();
450
+ return;
451
+ }
452
+ this.save();
453
+ this.lock.release();
454
+ }
455
+ /** No turn, cost or run: in memory and in the database, which stays the source of truth after a failed save. */
456
+ isEmpty() {
457
+ return (this.state.turns === 0 &&
458
+ this.state.costUsd === 0 &&
459
+ !this.state.lastRunId &&
460
+ latestSessionRunId(this.deps.db, this.id) === undefined &&
461
+ getSpent(this.deps.db, sessionScope(this.id)) === 0);
462
+ }
463
+ assertIdle() {
464
+ if (this.busy)
465
+ throw invalid("A turn is running", "Wait for it to finish or abort it");
466
+ }
467
+ buildEnv(deps) {
468
+ const { reloadConfig: _reload, ...engineDeps } = deps;
469
+ return createEngineEnv({ ...engineDeps, onEvent: (event) => this.onEvent?.(event) });
470
+ }
471
+ /** Re-reads the config now (a turn does this itself), so `budgetUsd` reflects settings changed between turns. Throws while a turn is running. */
472
+ refreshConfig() {
473
+ this.assertIdle();
474
+ this.reloadConfig();
475
+ }
476
+ reloadConfig() {
477
+ if (!this.deps.reloadConfig)
478
+ return;
479
+ const next = this.deps.reloadConfig();
480
+ if (next.configHash === this.configHash)
481
+ return;
482
+ this.configHash = next.configHash;
483
+ const redact = next.redact ?? createRedactor(next.config.redaction.patterns);
484
+ this.deps = { ...this.deps, config: next.config, configHash: next.configHash, redact };
485
+ this.dir = new SessionDir(this.dir.root, this.id, redact);
486
+ this.env = this.buildEnv(this.deps);
487
+ const previous = this.learner;
488
+ this.learner = new LearnWorker(this.env);
489
+ void previous.stop();
490
+ }
491
+ /**
492
+ * Compacts before the turn's first request when forced, when the request would pass `session.compactAt` of the
493
+ * context window, or when one S2 request with this history would cost more than `session.compactAtBudgetShare` of
494
+ * the turn's budget (every follow-up sends the whole history, and any turn may escalate to S2).
495
+ */
496
+ compactionHook(turnIndex, turnBudgetUsd) {
497
+ return async (ctx) => {
498
+ const { config } = this.env.deps;
499
+ const tokens = ctx.estimateTokens(ctx.history);
500
+ const overWindow = tokens > config.session.compactAt * ctx.model.contextWindow;
501
+ const s2 = this.env.registry.get(config.models.s2.provider, config.models.s2.id);
502
+ const share = config.session.compactAtBudgetShare;
503
+ const overBudget = share > 0 && estimateCallCostUsd(s2, config.pricingOverrides, tokens * 4, config.budgets.estimateOutputTokens) > share * turnBudgetUsd;
504
+ if (!this.compactRequested && !overWindow && !overBudget)
505
+ return ctx.history;
506
+ const active = activeMessageLines(this.lines);
507
+ const turnIndexes = [...new Set(active.map((l) => l.turnIndex))].sort((a, b) => a - b);
508
+ const replacedThroughTurn = turnIndexes[turnIndexes.length - KEEP_VERBATIM_TURNS - 1];
509
+ if (replacedThroughTurn === undefined) {
510
+ this.compactRequested = false;
511
+ return ctx.history;
512
+ }
513
+ const old = active.filter((l) => l.turnIndex <= replacedThroughTurn).map((l) => l.message);
514
+ const s1 = this.env.registry.get(config.models.s1.provider, config.models.s1.id);
515
+ const maxChars = Math.floor(s1.contextWindow * COMPACTION_INPUT_WINDOW_SHARE * 4) - COMPACTION_SYSTEM_PROMPT.length;
516
+ const text = renderForSummary(latestCompaction(this.lines)?.summary ?? "", old, maxChars);
517
+ let summary;
518
+ try {
519
+ summary = await ctx.summarize({ system: COMPACTION_SYSTEM_PROMPT, text });
520
+ }
521
+ catch (error) {
522
+ if (ctx.signal?.aborted)
523
+ throw error;
524
+ this.deps.logger.warn("compaction failed; continuing with the full history", { session_id: this.id, error });
525
+ return ctx.history;
526
+ }
527
+ this.compactRequested = false;
528
+ this.appendLines([{ type: "compaction", turnIndex, summary, replacedThroughTurn }]);
529
+ return buildHistory(this.lines, this.env.now().getTime());
530
+ };
531
+ }
532
+ /** `instruction` is what the user typed; `sent` is the message the run started from (with any `!` command notes). */
533
+ recordTurn(turnIndex, instruction, sent, result) {
534
+ // A run that ended before its first request returns no messages; the message is kept so it is not lost.
535
+ const messages = result.messages.length > 0 ? result.messages : [{ role: "user", content: [{ type: "text", text: sent }], timestamp: this.env.now().getTime() }];
536
+ this.appendLines(messages.map((message) => ({ type: "message", turnIndex, message })));
537
+ this.state.turns = turnIndex;
538
+ this.state.costUsd += result.costUsd;
539
+ // S2 work that stopped unfinished (out of budget, failed, aborted, or a failed S2 continuation) goes on on S2 in
540
+ // the next turn; a finished S2 turn, or one on a model the user chose, does not carry.
541
+ const stoppedOnS2 = result.model?.role === "s2" && result.status !== "succeeded";
542
+ this.state.continueOnS2 = this.state.model === null && (stoppedOnS2 || result.continuationError !== undefined);
543
+ this.state.lastRunId = result.trajectoryId;
544
+ this.state.pendingShell = [];
545
+ if (!this.state.title)
546
+ this.state.title = titleFrom(this.env.deps.redact(instruction));
547
+ if (result.model) {
548
+ this.lastModelInfo = result.model;
549
+ const tokens = contextTokens(result.messages);
550
+ if (tokens !== null)
551
+ this.state.context = { tokens, window: result.model.contextWindow };
552
+ }
553
+ this.save();
554
+ }
555
+ appendLines(lines) {
556
+ this.dir.appendTranscript(lines);
557
+ this.lines.push(...lines);
558
+ }
559
+ save() {
560
+ this.state.updatedAt = this.env.now().toISOString();
561
+ this.state.budgetUsd = this.budgetUsd;
562
+ this.state.budgetOverrideUsd = this.state.budgetOverrideUsd ?? null;
563
+ this.dir.writeSessionJson(this.state);
564
+ upsertSessionRow(this.deps.db, sessionRowFromJson(this.env.deps.redact(this.state), this.dir.root));
565
+ }
566
+ }
567
+ /** Builds a session under `lock`, releasing the lock if construction fails. */
568
+ function openSession(deps, dir, state, lines, lock) {
569
+ try {
570
+ return new Session(INIT, deps, dir, state, lines, lock);
571
+ }
572
+ catch (error) {
573
+ lock.release();
574
+ throw error;
575
+ }
576
+ }
577
+ /**
578
+ * Starts a new session with the cap from `budgets.perSessionUsd`. Its turns work in `options.workspace` when given, else
579
+ * each in its own run folder.
580
+ */
581
+ export function createSession(deps, options) {
582
+ const workspace = options.workspace === undefined ? null : resolveWorkspace(options.cwd, options.workspace);
583
+ const id = newId();
584
+ const nowIso = (deps.now ?? (() => new Date()))().toISOString();
585
+ const state = {
586
+ id,
587
+ title: "",
588
+ cwd: resolve(options.cwd),
589
+ workspace,
590
+ model: null,
591
+ effort: null,
592
+ budgetUsd: deps.config.budgets.perSessionUsd,
593
+ budgetOverrideUsd: null,
594
+ costUsd: 0,
595
+ turns: 0,
596
+ status: "active",
597
+ createdAt: nowIso,
598
+ updatedAt: nowIso,
599
+ lastRunId: null,
600
+ context: null,
601
+ };
602
+ const dir = SessionDir.create(deps.paths.sessions, id, deps.redact);
603
+ const session = openSession(deps, dir, state, [], SessionLock.acquire(dir.root, id));
604
+ try {
605
+ if (options.model !== undefined)
606
+ session.setModel(options.model);
607
+ if (options.effort !== undefined)
608
+ session.setEffort(options.effort);
609
+ }
610
+ catch (error) {
611
+ session.close();
612
+ throw error;
613
+ }
614
+ return session;
615
+ }
616
+ /**
617
+ * Reopens a session from its directory as `active`, rebuilding the history from the transcript. Throws NOT_FOUND for an
618
+ * unknown id, CONFLICT when another live process has it open, and STORE_IO for an unreadable session.json.
619
+ */
620
+ export function resumeSession(deps, id) {
621
+ const dir = SessionDir.open(deps.paths.sessions, id, deps.redact);
622
+ const lock = SessionLock.acquire(dir.root, id);
623
+ let state;
624
+ try {
625
+ state = dir.readSessionJson();
626
+ // A turn that crashed before session.json was saved still has its spend in the ledger and its run in the index.
627
+ state.costUsd = Math.max(state.costUsd, getSpent(deps.db, sessionScope(id)));
628
+ const indexedTurns = maxSessionTurn(deps.db, id);
629
+ if (indexedTurns > state.turns) {
630
+ state.turns = indexedTurns;
631
+ state.lastRunId = latestSessionRunId(deps.db, id) ?? state.lastRunId;
632
+ }
633
+ state.status = "active";
634
+ }
635
+ catch (error) {
636
+ lock.release();
637
+ throw error;
638
+ }
639
+ return openSession(deps, dir, state, dir.readTranscript(), lock);
640
+ }
641
+ /** Indexed sessions that ran at least one turn, most recently updated first. Throws INVALID_REQUEST for a limit outside 1..1000. */
642
+ export function listSessions(db, options = {}) {
643
+ const limit = options.limit ?? 20;
644
+ if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
645
+ throw invalid(`limit must be an integer from 1 to 1000, got ${limit}`);
646
+ return listSessionRows(db, { limit, withTurns: true });
647
+ }
@@ -0,0 +1,26 @@
1
+ /** Most characters of one command's output the model reads; the end is kept, where errors and summaries usually are. */
2
+ export const SHELL_NOTE_CHARS = 20_000;
3
+ /** Keeps the last SHELL_NOTE_CHARS characters of `output`, marking the cut. */
4
+ export function capShellOutput(output, truncated = false) {
5
+ const kept = output.length > SHELL_NOTE_CHARS ? `[…${output.length - SHELL_NOTE_CHARS} characters cut]\n${output.slice(-SHELL_NOTE_CHARS)}` : output;
6
+ return truncated ? `${kept}\n[output truncated]` : kept;
7
+ }
8
+ function outcome(note) {
9
+ switch (note.ended) {
10
+ case "exited":
11
+ return `exit code ${note.exitCode ?? -1}`;
12
+ case "timeout":
13
+ return "timed out";
14
+ case "aborted":
15
+ return "stopped by the user";
16
+ case "failed":
17
+ return "failed to start";
18
+ }
19
+ }
20
+ /** The user message for a turn that follows `!` commands: the commands with their output, then what the user typed. */
21
+ export function withShellNotes(notes, instruction) {
22
+ if (notes.length === 0)
23
+ return instruction;
24
+ const blocks = notes.map((n) => `$ ${n.command}\n[${outcome(n)}]\n${n.output.replace(/\n$/, "")}`);
25
+ return `[nexo] Before this message the user ran shell commands in the workspace:\n\n${blocks.join("\n\n")}\n\n[nexo] The user's message:\n${instruction}`;
26
+ }