@hexdecimal16/nexo 0.3.5 → 0.4.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 (40) hide show
  1. package/README.md +15 -0
  2. package/cli/src/common.js +6 -1
  3. package/cli/src/main.js +12 -0
  4. package/cli/src/review-queue.js +31 -0
  5. package/cli/src/search.js +50 -0
  6. package/cli/src/settings.js +20 -1
  7. package/core/src/config/schema.js +12 -2
  8. package/core/src/engine/context-trim.js +26 -0
  9. package/core/src/engine/prompts.js +5 -0
  10. package/core/src/engine/run.js +68 -2
  11. package/core/src/engine/spawn-tool.js +5 -1
  12. package/core/src/optimize/holdout-gate.js +19 -0
  13. package/core/src/optimize/optimize.js +13 -2
  14. package/core/src/optimize/reflect.js +1 -1
  15. package/core/src/settings/config-edit.js +31 -0
  16. package/core/src/settings/doctor.js +15 -2
  17. package/core/src/settings/settings.js +29 -10
  18. package/package.json +1 -1
  19. package/sdk/src/nexo.js +33 -3
  20. package/sdk/src/run-tree.js +6 -0
  21. package/sdk/src/runtime.js +2 -1
  22. package/store/src/index.js +1 -0
  23. package/store/src/review-queue.js +46 -0
  24. package/tools/src/builtin.js +13 -3
  25. package/tools/src/descriptions.js +2 -1
  26. package/tools/src/index.js +1 -0
  27. package/tools/src/policy.js +1 -1
  28. package/tools/src/web-search.js +251 -0
  29. package/tui/src/app.js +22 -1
  30. package/tui/src/commands.js +1 -0
  31. package/tui/src/index.js +1 -1
  32. package/tui/src/settings-screen.js +8 -2
  33. package/tui/src/text.js +1 -1
  34. package/web/public/lib/api-types.ts +18 -0
  35. package/web/public/lib/run-view.ts +19 -1
  36. package/web/public/pages/run.ts +3 -1
  37. package/web/public/run.html +2 -1
  38. package/web/src/api.js +32 -0
  39. package/web/src/review-queue-api.js +18 -0
  40. package/web/src/server.js +7 -0
package/README.md CHANGED
@@ -45,6 +45,19 @@ For scripts, `nexo init --yes --s1 <provider/id> --s2 <provider/id>` runs withou
45
45
 
46
46
  Data lives in `~/.nexo` (set `NEXO_HOME` to change it).
47
47
 
48
+ ### Web search
49
+
50
+ The agent gets a `web_search` tool once a [Brave Search](https://api-dashboard.search.brave.com) or [Tavily](https://app.tavily.com) key is set. With both keys, it queries both in parallel and merges the results. Results found by both rank higher, and a provider that fails is skipped. The tool is allowed without a prompt (`tools.policy.web_search`), including in unattended runs.
51
+
52
+ ```sh
53
+ nexo settings set-key brave # or tavily; hidden prompt, or pipe the key on stdin
54
+ nexo settings keys # which keys are set, and from where
55
+ nexo search "node 22 release notes" # try it without a model (--count <n>, --json)
56
+ nexo settings set tools.webSearch.count 10
57
+ ```
58
+
59
+ `BRAVE_API_KEY` and `TAVILY_API_KEY` work too, and they take precedence over the credentials file. In a chat, `/settings` lists both keys.
60
+
48
61
  ## Use it from Node
49
62
 
50
63
  ```ts
@@ -59,6 +72,8 @@ try {
59
72
  }
60
73
  ```
61
74
 
75
+ Keys can be passed in code without touching disk: `createNexo({ apiKeys: { anthropic: "…", brave: "…" } })`. `nexo.webSearch(query)` searches directly, without a model and at no model cost. `nexo.keys()`, `nexo.setKey()` and `nexo.removeKey()` manage stored keys.
76
+
62
77
  The SDK denies every tool approval by default, so a backend never waits on a person. Always pass `budgetUsd`. `checkSetup()` runs the doctor checks without starting the engine, which suits a start-up pre-flight.
63
78
 
64
79
  ## Security
package/cli/src/common.js CHANGED
@@ -10,12 +10,17 @@ export const USAGE = `Usage:
10
10
  nexo --version print the installed version
11
11
  nexo settings open the settings screen (needs a terminal)
12
12
  nexo settings get <key>
13
- nexo settings set <key> <value> keys: models.s1|s2|judge|reflector|embedding, budgets.*, tools.policy.*, tools.autoApprove, tools.nonInteractiveAsk, models.approver, scoring.judge, learning.*, memory.*, optimize.minCases|patience|minJudgeKappa|noveltySimilarity|offspringAlpha
13
+ nexo settings set <key> <value> keys: models.s1|s2|judge|reflector|embedding, budgets.*, tools.policy.*, tools.webSearch.count, tools.autoApprove, tools.nonInteractiveAsk, models.approver, scoring.judge, learning.*, memory.*, optimize.minCases|patience|minJudgeKappa|noveltySimilarity|offspringAlpha|reflectionTier|maxCaseDrop, loop.maxToolCalls|repeatLimit
14
14
  nexo settings reset <key> remove it from the user config
15
15
  nexo settings set-key <provider> reads the key from a hidden prompt, or from stdin when piped
16
+ (brave or tavily turns on the web_search tool)
17
+ nexo settings remove-key <provider> delete a key from the credentials file
18
+ nexo settings keys key status of the model and web search providers (never the keys)
19
+ nexo search <query...> [--count <n>] [--json] search the web with the configured Brave/Tavily keys
16
20
  nexo run <instruction...> [--skill <name>] [--model <s1|s2|provider/id>] [--effort <level>] [--workspace <dir>] [--budget <usd>] [--no-review]
17
21
  nexo cost [--by model|tier|day|run|skill] [--since YYYY-MM-DD]
18
22
  nexo reindex
23
+ nexo review-queue [--limit <n>] [--days <n>] recent runs without a verdict, worst first
19
24
  nexo eval judge [--judge <provider/id[+provider/id…]>] judge-vs-human agreement and Cohen's κ
20
25
  nexo eval add --target <target> --input <text> [--skill <name>] [--expected <text>] [--feedback <text>]
21
26
  nexo eval list --target <target>
package/cli/src/main.js CHANGED
@@ -9,6 +9,7 @@ import { evalCommand } from "./eval.js";
9
9
  import { learnCommand, learnEventLine, memoryCommand, playbookCommand } from "./learn.js";
10
10
  import { optimizeCommand } from "./optimize.js";
11
11
  import { createTtyPrompter } from "./prompter.js";
12
+ import { reviewQueueCommand } from "./review-queue.js";
12
13
  import { createTtyLineAsker, isInteractiveTerminal, promptReview } from "./review.js";
13
14
  import { createRuntime } from "./runtime.js";
14
15
  import { interactiveCommand, settingsScreenCommand } from "./interactive.js";
@@ -17,6 +18,7 @@ import { doctorCommand } from "./doctor.js";
17
18
  import { initCommand } from "./init.js";
18
19
  import { updateCommand } from "./update.js";
19
20
  import { nexoVersion } from "./version.js";
21
+ import { searchCommand } from "./search.js";
20
22
  import { settingsCommand } from "./settings.js";
21
23
  import { escapeControl } from "../../tui/src/index.js";
22
24
  import { runUi } from "./ui.js";
@@ -117,6 +119,12 @@ async function runCommand(args, io, options) {
117
119
  io.stderr.write(`\x1b[2m${" ".repeat(event.depth)} auto-allowed: ${escapeControl(event.reason)}\x1b[22m\n`);
118
120
  if (event.type === "escalation" && event.applied)
119
121
  io.stderr.write(escalationLine(event.depth, event.model, event.trigger, event.reason));
122
+ if (event.type === "loop_guard") {
123
+ const what = event.kind === "max_tool_calls" ? `tool-call cap reached (loop.maxToolCalls ${event.limit}); asked the agent to report` : `blocked ${escapeControl(event.toolName)}: ${event.count} identical calls in a row (loop.repeatLimit ${event.limit})`;
124
+ io.stderr.write(`${" ".repeat(event.depth)} ⚠ ${what}\n`);
125
+ }
126
+ if (event.type === "context_trim" && event.depth === 0)
127
+ io.stderr.write(` · context nearly full: cleared ${event.cleared} old tool outputs (~${event.tokensBefore} → ~${event.tokensAfter} tokens)\n`);
120
128
  },
121
129
  onLearnEvent: (event) => {
122
130
  const line = learnEventLine(event);
@@ -223,6 +231,8 @@ export async function runCli(argv, io, options = {}) {
223
231
  return costCommand(rest, io, options);
224
232
  case "reindex":
225
233
  return reindexCommand(io, options);
234
+ case "review-queue":
235
+ return reviewQueueCommand(rest, io, options);
226
236
  case "eval":
227
237
  return await evalCommand(rest, io, options);
228
238
  case "optimize":
@@ -235,6 +245,8 @@ export async function runCli(argv, io, options = {}) {
235
245
  return playbookCommand(rest, io, options);
236
246
  case "doctor":
237
247
  return doctorCommand(rest, io, options);
248
+ case "search":
249
+ return await searchCommand(rest, io, options);
238
250
  case "init":
239
251
  return await initCommand(rest, io, options, stdio);
240
252
  case "update":
@@ -0,0 +1,31 @@
1
+ import { parseArgs } from "node:util";
2
+ import { reviewQueue } from "../../store/src/index.js";
3
+ import { escapeControl } from "../../tui/src/index.js";
4
+ import { usageError } from "./common.js";
5
+ import { openStore } from "./learn.js";
6
+ /** `nexo review-queue [--limit <n>] [--days <n>]`: recent runs without a verdict, worst first. */
7
+ export function reviewQueueCommand(args, io, options) {
8
+ const { values } = parseArgs({ args, options: { limit: { type: "string" }, days: { type: "string" } } });
9
+ const limit = values.limit === undefined ? undefined : Number(values.limit);
10
+ const days = values.days === undefined ? undefined : Number(values.days);
11
+ if (limit !== undefined && !(Number.isInteger(limit) && limit > 0))
12
+ throw usageError("--limit must be a positive integer");
13
+ if (days !== undefined && !(Number.isInteger(days) && days > 0))
14
+ throw usageError("--days must be a positive integer");
15
+ const store = openStore(options);
16
+ try {
17
+ const items = reviewQueue(store.db, { ...(limit ? { limit } : {}), ...(days ? { days } : {}) });
18
+ if (items.length === 0)
19
+ io.stdout.write("No unreviewed runs in this period\n");
20
+ for (const i of items) {
21
+ const score = i.score === null ? "–" : i.score.toFixed(2);
22
+ io.stdout.write(`${i.runId} ${i.failureMode.padEnd(15)} score ${score} $${i.costUsd.toFixed(4)} ${escapeControl(i.instruction)}\n`);
23
+ }
24
+ if (items.length > 0)
25
+ io.stdout.write("Label a run in the UI or with /done and /notdone in a session\n");
26
+ return 0;
27
+ }
28
+ finally {
29
+ store.close();
30
+ }
31
+ }
@@ -0,0 +1,50 @@
1
+ import { parseArgs } from "node:util";
2
+ import { createSettings, DEFAULT_CONFIG, keyStatusLabel, nexoModels } from "../../core/src/index.js";
3
+ import { ensureNexoDirs, resolveNexoPaths } from "../../store/src/index.js";
4
+ import { escapeControlKeepLines } from "../../tui/src/index.js";
5
+ import { formatSearchOutcome, MAX_SEARCH_RESULTS, noKeyMessage, SEARCH_PROVIDER_IDS, webSearch } from "../../tools/src/index.js";
6
+ import { NexoError } from "../../telemetry/src/index.js";
7
+ import { EXIT_SIGINT, usageError } from "./common.js";
8
+ import { openLogger } from "./runtime.js";
9
+ /**
10
+ * `nexo search <query...> [--count <n>] [--json]`: the agent's web_search without a model, for checking keys and
11
+ * results. Exit 0 when at least one provider answered, 4 when none has a key, 1 when all failed.
12
+ */
13
+ export async function searchCommand(args, io, options) {
14
+ const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { count: { type: "string" }, json: { type: "boolean" } } });
15
+ const query = positionals.join(" ").trim();
16
+ if (!query)
17
+ throw usageError("nexo search needs a query");
18
+ const env = options.env ?? process.env;
19
+ const paths = resolveNexoPaths(env);
20
+ ensureNexoDirs(paths);
21
+ const settings = createSettings({ paths, cwd: options.cwd ?? process.cwd(), env, models: options.models ?? nexoModels() });
22
+ openLogger(settings, paths, "search");
23
+ let count = DEFAULT_CONFIG.tools.webSearch.count;
24
+ try {
25
+ count = settings.loadConfig().config.tools.webSearch.count;
26
+ }
27
+ catch {
28
+ // Searching needs no models: an incomplete config (first run) keeps the default count.
29
+ }
30
+ if (values.count !== undefined) {
31
+ count = Number(values.count);
32
+ if (!Number.isInteger(count) || count < 1 || count > MAX_SEARCH_RESULTS)
33
+ throw usageError(`--count must be an integer from 1 to ${MAX_SEARCH_RESULTS}`);
34
+ }
35
+ const keys = Object.fromEntries(SEARCH_PROVIDER_IDS.map((id) => [id, settings.resolveApiKey(id)]));
36
+ if (!SEARCH_PROVIDER_IDS.some((id) => keys[id])) {
37
+ throw new NexoError({ code: "PROVIDER_AUTH", message: "No web search key is set", hint: noKeyMessage() });
38
+ }
39
+ const outcome = await webSearch(query, { keys, count, ...(options.searchFetch ? { fetch: options.searchFetch } : {}) }, options.signal);
40
+ if (options.signal?.aborted)
41
+ return EXIT_SIGINT;
42
+ if (values.json)
43
+ io.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
44
+ else {
45
+ io.stdout.write(`${escapeControlKeepLines(formatSearchOutcome(query, outcome))}\n`);
46
+ const used = settings.keyProviders().filter((k) => k.purpose === "search" && k.state !== "unset");
47
+ io.stderr.write(`searched ${outcome.answered.join(", ") || "nothing"} · keys: ${used.map((k) => `${k.provider} ${keyStatusLabel(k)}`).join(", ")}\n`);
48
+ }
49
+ return outcome.answered.length > 0 ? 0 : 1;
50
+ }
@@ -131,6 +131,25 @@ export async function settingsCommand(args, io, options, stdio) {
131
131
  io.stderr.write(`note: ${view.notice}\n`);
132
132
  return 0;
133
133
  }
134
+ case "keys": {
135
+ if (rest.length !== 0)
136
+ throw usageError("nexo settings keys takes no arguments");
137
+ for (const status of build().keyProviders()) {
138
+ const tag = status.purpose === "search" ? " (web search)" : "";
139
+ const env = status.state === "env" && status.envVar ? ` via ${status.envVar}` : "";
140
+ io.stdout.write(`${status.provider}${tag}: ${keyStatusLabel(status)}${env}\n`);
141
+ }
142
+ return 0;
143
+ }
144
+ case "remove-key": {
145
+ if (rest.length !== 1)
146
+ throw usageError("nexo settings remove-key needs exactly one provider");
147
+ const settings = build();
148
+ redact = settings.redact;
149
+ const status = settings.removeKey(rest[0]);
150
+ io.stdout.write(`${status.provider}: ${keyStatusLabel(status)}\n`);
151
+ return 0;
152
+ }
134
153
  case "set-key": {
135
154
  if (rest.length > 1) {
136
155
  throw new NexoError({
@@ -158,7 +177,7 @@ export async function settingsCommand(args, io, options, stdio) {
158
177
  return 0;
159
178
  }
160
179
  default:
161
- throw usageError(sub === undefined ? "nexo settings needs get, set, reset or set-key (or a terminal for the screen)" : `Unknown settings command "${sub}"`);
180
+ throw usageError(sub === undefined ? "nexo settings needs get, set, reset, keys, set-key or remove-key (or a terminal for the screen)" : `Unknown settings command "${sub}"`);
162
181
  }
163
182
  }
164
183
  catch (error) {
@@ -79,6 +79,8 @@ export const ConfigSchema = Type.Object({
79
79
  /** Also compact when one S2 request with the history would cost more than this share of the turn's budget; 0 turns it off. */
80
80
  compactAtBudgetShare: Type.Number({ minimum: 0, maximum: 1 }),
81
81
  }, { additionalProperties: false }),
82
+ /** Guards against a run that loops: a cap on tool calls and a limit on identical consecutive calls; 0 turns a guard off. */
83
+ loop: Type.Object({ maxToolCalls: Type.Integer({ minimum: 0 }), repeatLimit: Type.Integer({ minimum: 0 }) }, { additionalProperties: false }),
82
84
  spawn: Type.Object({ maxParallelSubagents: Type.Integer({ minimum: 1 }), maxDepth: Type.Integer({ minimum: 0 }) }, { additionalProperties: false }),
83
85
  /** Extra instruction files (paths or globs inside the project) loaded into the prompt next to AGENTS.md / CLAUDE.md. */
84
86
  instructions: Type.Array(Type.String({ minLength: 1 })),
@@ -92,6 +94,8 @@ export const ConfigSchema = Type.Object({
92
94
  nonInteractiveAsk: NonInteractiveAskSchema,
93
95
  autoApprove: Type.Union([Type.Literal("off"), Type.Literal("on")]),
94
96
  bashTimeoutMs: Type.Integer({ minimum: 1000 }),
97
+ /** The `web_search` tool: on when a Brave or Tavily key is set; `count` results are returned after merging. */
98
+ webSearch: Type.Object({ count: Type.Integer({ minimum: 1, maximum: 20 }) }, { additionalProperties: false }),
95
99
  }, { additionalProperties: false }),
96
100
  mcp: Type.Object({
97
101
  /** Stdio MCP servers by name; their tools reach the agent as `mcp__<name>__<tool>`. */
@@ -131,6 +135,10 @@ export const ConfigSchema = Type.Object({
131
135
  patience: Type.Integer({ minimum: 1 }),
132
136
  /** Lowest judge Cohen's κ that lets judge-only evidence promote a candidate. */
133
137
  minJudgeKappa: Type.Number({ minimum: -1, maximum: 1 }),
138
+ /** Model tier that writes candidate edits. Edit quality barely depends on model size, so s1 is the default. */
139
+ reflectionTier: Type.Union([Type.Literal("s1"), Type.Literal("s2")]),
140
+ /** Largest drop in one holdout case's quality that a promoted candidate may have; a larger drop, or a lower holdout mean, reverts to the base version. */
141
+ maxCaseDrop: Type.Number({ minimum: 0, maximum: 1 }),
134
142
  /** Embedding cosine at or above which a reflected text counts as a near-duplicate of a candidate and is skipped before any rollout. */
135
143
  noveltySimilarity: Type.Number({ exclusiveMinimum: 0, maximum: 1 }),
136
144
  /** How strongly a parent's child count lowers its chance of being sampled again (0 turns the penalty off). */
@@ -173,20 +181,22 @@ export const DEFAULT_CONFIG = {
173
181
  estimateOutputTokens: 4096,
174
182
  },
175
183
  session: { compactAt: 0.8, compactAtBudgetShare: 0.2 },
184
+ loop: { maxToolCalls: 200, repeatLimit: 3 },
176
185
  spawn: { maxParallelSubagents: 4, maxDepth: 4 },
177
186
  instructions: [],
178
187
  skills: { dirs: ["$NEXO_HOME/skills", "./.nexo/skills"], pins: {} },
179
188
  tools: {
180
- policy: { read: "allow", write: "allow", edit: "allow", bash: "ask", web_fetch: "ask", load_skill: "allow", spawn: "allow" },
189
+ policy: { read: "allow", write: "allow", edit: "allow", bash: "ask", web_fetch: "ask", web_search: "allow", load_skill: "allow", spawn: "allow" },
181
190
  rules: [],
182
191
  nonInteractiveAsk: "deny",
183
192
  autoApprove: "off",
184
193
  bashTimeoutMs: 120_000,
194
+ webSearch: { count: 8 },
185
195
  },
186
196
  mcp: { servers: {} },
187
197
  pricingOverrides: {},
188
198
  redaction: { patterns: [] },
189
199
  memory: { enabled: true, maxTokens: 1500, weights: { relevance: 1, importance: 0.5, recency: 0.3 }, tauDays: 14, topK: 20, minRelevance: 0 },
190
200
  learning: { enabled: true, maxPlaybookItems: 50, perJobUsd: 0.15, staleMinutes: 10, drainAfterRunMs: 30_000 },
191
- optimize: { minCases: 10, patience: 5, minJudgeKappa: 0.6, noveltySimilarity: 0.98, offspringAlpha: 0.5, mine: { days: 30, maxRuns: 500, minCluster: 3, maxNew: 3, cosine: 0.8, jaccard: 0.5 }, climb: { guards: 2 } },
201
+ optimize: { minCases: 10, patience: 5, minJudgeKappa: 0.6, reflectionTier: "s1", maxCaseDrop: 0.2, noveltySimilarity: 0.98, offspringAlpha: 0.5, mine: { days: 30, maxRuns: 500, minCluster: 3, maxNew: 3, cosine: 0.8, jaccard: 0.5 }, climb: { guards: 2 } },
192
202
  };
@@ -0,0 +1,26 @@
1
+ export const CLEARED_TOOL_OUTPUT = "[nexo] Earlier tool output cleared to save context. Run the tool again if you need it.";
2
+ /** Tool results shorter than this are left alone: the stub would not save anything. */
3
+ const MIN_CLEARABLE_CHARS = 400;
4
+ function textLength(content) {
5
+ if (typeof content === "string")
6
+ return content.length;
7
+ if (!Array.isArray(content))
8
+ return 0;
9
+ return content.reduce((sum, block) => sum + (block?.type === "text" && typeof block.text === "string" ? block.text.length : 0), 0);
10
+ }
11
+ /**
12
+ * Replaces the content of every tool result except the newest `keepRecent` with a short stub. Used mid-run when a
13
+ * request nears the context window: it needs no model call, and the call and its arguments stay in the history.
14
+ */
15
+ export function clearOldToolResults(messages, keepRecent) {
16
+ const resultIndexes = messages.flatMap((m, i) => (m.role === "toolResult" ? [i] : []));
17
+ const candidates = new Set(resultIndexes.slice(0, Math.max(0, resultIndexes.length - keepRecent)));
18
+ let cleared = 0;
19
+ const out = messages.map((m, i) => {
20
+ if (!candidates.has(i) || textLength(m.content) < MIN_CLEARABLE_CHARS)
21
+ return m;
22
+ cleared++;
23
+ return { ...m, content: [{ type: "text", text: CLEARED_TOOL_OUTPUT }] };
24
+ });
25
+ return { messages: cleared > 0 ? out : messages, cleared };
26
+ }
@@ -7,11 +7,14 @@ Working rules:
7
7
  - Make independent tool calls in the same turn, and combine related shell steps into one command. To read several files, pass paths to one read call.
8
8
  - Scope searches to a directory, never find /. Start a command that may outlive the bash timeout in the background (nohup ... > job.log 2>&1 &) and poll the log.
9
9
  - A budget line is appended to your latest input each turn. Prefer fewer, larger steps when it is low. Never say you hit or ran out of budget unless the budget line shows $0.0000 remaining or a tool result says BUDGET_EXCEEDED; otherwise finish the task.
10
+ - Before you finish, check the result against the instruction: run the test, open the file you wrote, or re-read the output. Report what you verified and what you could not verify. If the same call fails twice with the same result, change your approach instead of repeating it.
10
11
  - End with a concise final answer that states what you did and where any output files are.`;
11
12
  export const DEFAULT_PLANNER_PROMPT = `Parallel work:
12
13
  - When the instruction has independent parts, call spawn once with all independent tasks so they run in parallel.
13
14
  - Use dependsOn only when a task needs another task's output; dependency outputs are appended to the dependent task's instruction.
14
15
  - Choose model "s1" and low effort for simple tasks; use "s2" or higher effort only for hard reasoning. Give each task a clear, self-contained instruction.`;
16
+ /** Added only when web_search is available, so runs without a search key are not told about a tool they lack. */
17
+ export const WEB_SEARCH_PROMPT = `Web research: your training data has a cutoff, so use web_search for anything that may have changed or that you are not sure of: current versions, APIs and docs, error messages, prices, news and other recent facts. Search with specific terms, read the best one to three hits with web_fetch, and cite the URLs you relied on in your answer. Do not search for things the workspace or a skill already answers.`;
15
18
  /** The line that points the agent at the wikis directory; the wiki skill holds the rules for using it. */
16
19
  export function wikiPrompt(wikisDir) {
17
20
  return `Wikis: the user keeps persistent knowledge bases as markdown folders under ${wikisDir}. When a task produces durable subject knowledge worth keeping (research findings, a source you read, a topic the user keeps returning to), load the wiki skill with load_skill and file it in the wiki that fits, creating a new wiki when none fits. Do not create or edit wikis for one-off questions, small talk or routine code changes. Load the wiki skill first whenever the task is about a wiki.`;
@@ -20,6 +23,8 @@ export function renderSystemPrompt(parts) {
20
23
  const sections = [parts.systemPrompt.replaceAll("{{workspace}}", parts.workspace)];
21
24
  if (parts.plannerPrompt)
22
25
  sections.push(parts.plannerPrompt);
26
+ if (parts.webSearch)
27
+ sections.push(WEB_SEARCH_PROMPT);
23
28
  if (parts.wikisDir)
24
29
  sections.push(wikiPrompt(parts.wikisDir));
25
30
  if (parts.skillIndex)
@@ -4,13 +4,14 @@ import { createModelRegistry, DEFAULT_ROUTER_POLICY, ESCALATION_BLOCK_REASONS, e
4
4
  import { createLoadSkillTool, formatSkillIndex, parseSkillFile } from "../../../skills/src/index.js";
5
5
  import { createArtifactSet, enqueueLearnJob, getActiveArtifact, insertRun, isPidAlive, listPlaybookItems, listSpans, newId, recoverCrashedRuns, resolveSourcedArtifact, RunDir, sessionRunDirs, updateRun, } from "../../../store/src/index.js";
6
6
  import { NexoError, toErrorPayload } from "../../../telemetry/src/index.js";
7
- import { builtinToolDescriptions, createBuiltinTools, createChangeTracker, createPolicy, FileLeases, TOOL_OUTPUT_PREFIX, } from "../../../tools/src/index.js";
7
+ import { builtinToolDescriptions, createBuiltinTools, createChangeTracker, createPolicy, createWebSearchTool, FileLeases, SEARCH_PROVIDER_IDS, TOOL_OUTPUT_PREFIX, } from "../../../tools/src/index.js";
8
8
  import { realpathSync, statSync } from "node:fs";
9
9
  import { join } from "node:path";
10
10
  import { createApprovalClassifier } from "../approval/classifier.js";
11
11
  import { budgetExhaustedError, checkAdmission, recordSpend, runBudgetLimit } from "../cost/admission.js";
12
12
  import { budgetLine, RunBudget } from "../cost/budget.js";
13
13
  import { estimateCallCostUsd, priceUsage } from "../cost/pricing.js";
14
+ import { clearOldToolResults } from "./context-trim.js";
14
15
  import { classifyProviderError, contextOverflowError, providerRetryDelayMs, toolErrorText, withToolErrorCodes } from "./errors.js";
15
16
  import { assistantText, contentText, estimatePromptChars, foreignToolCallsAsText, lastAssistant, recordedContent, withBudgetLine } from "./messages.js";
16
17
  import { DEFAULT_PLANNER_PROMPT, DEFAULT_SYSTEM_PROMPT, renderSystemPrompt } from "./prompts.js";
@@ -33,6 +34,12 @@ function toolOutputExcerpt(text, pointer) {
33
34
  }
34
35
  /** Longest tool result text carried by a `tool_end` preview (`output` carries all of it). */
35
36
  export const TOOL_END_PREVIEW_CHARS = 2_000;
37
+ /** The tools an explore-mode subagent keeps: read-only research. */
38
+ const EXPLORE_TOOLS = new Set(["read", "web_fetch", "web_search", "load_skill"]);
39
+ /** JSON with object keys sorted at every level, so the same arguments in another key order compare equal. */
40
+ function stableJson(value) {
41
+ return JSON.stringify(value, (_key, v) => v && typeof v === "object" && !Array.isArray(v) ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) : v);
42
+ }
36
43
  const extraToolFactories = [];
37
44
  /** Registers tools that every run receives in addition to the built-ins (used by the spawn tool). Returns an unregister function. */
38
45
  export function registerExtraTools(factory) {
@@ -557,6 +564,14 @@ export async function executeRun(env, input) {
557
564
  },
558
565
  }),
559
566
  ];
567
+ // web_search exists only when a search provider has a key; keys are read per run, so a key set mid-session applies to the next turn.
568
+ const webSearchTool = createWebSearchTool({
569
+ keys: Object.fromEntries(SEARCH_PROVIDER_IDS.map((id) => [id, deps.resolveApiKey?.(id)])),
570
+ count: config.tools.webSearch.count,
571
+ ...(deps.fetch ? { fetch: deps.fetch } : {}),
572
+ });
573
+ if (webSearchTool)
574
+ baseTools.push(webSearchTool);
560
575
  const toolCtx = {
561
576
  env,
562
577
  runId,
@@ -601,6 +616,7 @@ export async function executeRun(env, input) {
601
616
  if (deps.mcp)
602
617
  baseTools.push(...(await deps.mcp.tools()));
603
618
  const tools = baseTools
619
+ .filter((t) => !request.exploreOnly || EXPLORE_TOOLS.has(t.name))
604
620
  .map((t) => (toolDescriptionOverrides.has(t.name) ? { ...t, description: toolDescriptionOverrides.get(t.name) } : t))
605
621
  .map(withToolErrorCodes);
606
622
  if (input.memoryContext) {
@@ -617,6 +633,7 @@ export async function executeRun(env, input) {
617
633
  const systemPrompt = renderSystemPrompt({
618
634
  systemPrompt: systemPromptText,
619
635
  plannerPrompt: tools.some((t) => t.name === "spawn") ? plannerPromptText : null,
636
+ webSearch: tools.some((t) => t.name === "web_search"),
620
637
  workspace,
621
638
  ...(rollout ? {} : { wikisDir: deps.paths.wikis }),
622
639
  skillIndex: formatSkillIndex(deps.skills),
@@ -718,6 +735,13 @@ export async function executeRun(env, input) {
718
735
  }
719
736
  const approvedBy = new Map();
720
737
  let classify = null;
738
+ let lastTrimCleared = 0;
739
+ /** completedCalls when the tool-call cap was first passed; tool calls from a later model reply end the run. */
740
+ let loopCapWarnedAt = null;
741
+ let loopLimitHit = false;
742
+ let toolCallCount = 0;
743
+ let lastCallSignature = "";
744
+ let repeatCount = 0;
721
745
  const runAgent = new Agent({
722
746
  streamFn: env.streamFn,
723
747
  initialState: { systemPrompt, model, thinkingLevel: resolved.effort, tools, messages: history },
@@ -734,12 +758,46 @@ export async function executeRun(env, input) {
734
758
  return undefined;
735
759
  return { model: target, thinkingLevel: active.resolved.effort };
736
760
  },
737
- transformContext: async (messages) => withBudgetLine(foreignToolCallsAsText(messages, active.model), budgetLine(budget)),
761
+ transformContext: async (messages) => {
762
+ // Mid-turn relief: compaction runs only before a turn's first request, so a long tool-heavy turn clears old tool outputs instead.
763
+ let current = messages;
764
+ const tokens = Math.ceil(requestChars(current, tools) / 4);
765
+ if (tokens > config.session.compactAt * active.model.contextWindow) {
766
+ const trimmed = clearOldToolResults(current, 4);
767
+ if (trimmed.cleared > lastTrimCleared) {
768
+ const after = Math.ceil(requestChars(trimmed.messages, tools) / 4);
769
+ deps.onEvent?.({ type: "context_trim", runId, depth, cleared: trimmed.cleared, tokensBefore: tokens, tokensAfter: after });
770
+ }
771
+ lastTrimCleared = Math.max(lastTrimCleared, trimmed.cleared);
772
+ current = trimmed.messages;
773
+ }
774
+ return withBudgetLine(foreignToolCallsAsText(current, active.model), budgetLine(budget));
775
+ },
738
776
  beforeToolCall: async ({ toolCall, args }, signal) => {
739
777
  if (budget.isExhausted()) {
740
778
  budgetExceeded = true;
741
779
  return { block: true, reason: "BUDGET_EXCEEDED: the run budget is exhausted", terminate: true };
742
780
  }
781
+ const { maxToolCalls, repeatLimit } = config.loop;
782
+ toolCallCount++;
783
+ if (maxToolCalls > 0 && toolCallCount > maxToolCalls) {
784
+ if (loopCapWarnedAt !== null && completedCalls !== loopCapWarnedAt) {
785
+ loopLimitHit = true;
786
+ return { block: true, reason: `LOOP_LIMIT: the run kept calling tools after passing loop.maxToolCalls (${maxToolCalls}); it ends here.`, terminate: true };
787
+ }
788
+ if (loopCapWarnedAt === null) {
789
+ loopCapWarnedAt = completedCalls;
790
+ deps.onEvent?.({ type: "loop_guard", runId, depth, toolCallId: toolCall.id, toolName: toolCall.name, kind: "max_tool_calls", count: toolCallCount - 1, limit: maxToolCalls });
791
+ }
792
+ return { block: true, reason: `LOOP_LIMIT: this run made ${maxToolCalls} tool calls (loop.maxToolCalls). Do not call more tools: reply now with what you have done, what you verified and what remains.` };
793
+ }
794
+ const signature = `${toolCall.name}:${stableJson(args)}`;
795
+ repeatCount = signature === lastCallSignature ? repeatCount + 1 : 1;
796
+ lastCallSignature = signature;
797
+ if (repeatLimit > 0 && repeatCount > repeatLimit) {
798
+ deps.onEvent?.({ type: "loop_guard", runId, depth, toolCallId: toolCall.id, toolName: toolCall.name, kind: "repeat", count: repeatCount, limit: repeatLimit });
799
+ return { block: true, reason: `LOOP_REPEAT: ${toolCall.name} was called ${repeatCount} times in a row with identical arguments (loop.repeatLimit ${repeatLimit}). Change your approach or report the blocker.` };
800
+ }
743
801
  const classifier = classify;
744
802
  const auth = await env.policy.authorize(deps.prompter, toolCall.name, args, signal, depth > 0 ? `subagent ${runId.slice(-6)}` : undefined, approvals
745
803
  ? {
@@ -953,6 +1011,14 @@ export async function executeRun(env, input) {
953
1011
  status = "budget_exceeded";
954
1012
  error = budgetExhaustedError(budget, input.budgetLimit ?? "run", sessionId !== null && !parent).toPayload();
955
1013
  }
1014
+ else if (loopLimitHit) {
1015
+ status = "failed";
1016
+ error = new NexoError({
1017
+ code: "LOOP_LIMIT",
1018
+ message: `The run passed loop.maxToolCalls (${config.loop.maxToolCalls}) and kept calling tools after it was asked to report`,
1019
+ hint: "Raise loop.maxToolCalls (0 turns the cap off) or split the task into smaller ones",
1020
+ }).toPayload();
1021
+ }
956
1022
  else if (input.signal?.aborted || last?.stopReason === "aborted") {
957
1023
  status = "aborted";
958
1024
  }
@@ -12,6 +12,9 @@ const SpawnTaskSchema = Type.Object({
12
12
  effort: Type.Optional(EffortSchema),
13
13
  budgetUsd: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
14
14
  dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Task ids whose outputs this task needs" })),
15
+ mode: Type.Optional(Type.Union([Type.Literal("explore"), Type.Literal("work")], {
16
+ description: '"explore": read-only research (read, web_fetch, web_search, load_skill) that returns a short summary and keeps the parent context small; "work" (default): full tools. Run write-capable tasks one at a time.',
17
+ })),
15
18
  });
16
19
  const SpawnParams = Type.Object({ tasks: Type.Array(SpawnTaskSchema, { minItems: 1 }) });
17
20
  function withDependencyOutputs(instruction, outputs) {
@@ -50,7 +53,8 @@ async function runSpawn(ctx, toolCallId, tasks, signal) {
50
53
  const startedAt = env.now().toISOString();
51
54
  const runChild = (childBudgetUsd) => executeRun(env, {
52
55
  request: {
53
- instruction: withDependencyOutputs(task.instruction, input.dependencyOutputs),
56
+ instruction: task.mode === "explore" ? `${withDependencyOutputs(task.instruction, input.dependencyOutputs)}\n\nYou are an explorer: you cannot change anything. Finish with a summary of at most 300 words: findings, source paths or URLs, and what you could not verify.` : withDependencyOutputs(task.instruction, input.dependencyOutputs),
57
+ ...(task.mode === "explore" ? { exploreOnly: true } : {}),
54
58
  skill: task.skill,
55
59
  model: task.model,
56
60
  effort: task.effort,
@@ -0,0 +1,19 @@
1
+ /** Float noise below this is not a drop. */
2
+ const EPSILON = 1e-9;
3
+ /**
4
+ * Verify-or-rollback check on the holdout split: a candidate regresses when its holdout mean is lower than the base's,
5
+ * or when any one case drops by more than `maxCaseDrop`. A case with no score after counts as 0.
6
+ */
7
+ export function holdoutRegression(before, after, ids, maxCaseDrop) {
8
+ if (ids.length === 0)
9
+ return { regressed: false, meanDrop: 0, worstDrop: 0 };
10
+ let sumDrop = 0;
11
+ let worstDrop = 0;
12
+ for (const id of ids) {
13
+ const drop = (before[id]?.quality ?? 0) - (after[id]?.quality ?? 0);
14
+ sumDrop += drop;
15
+ worstDrop = Math.max(worstDrop, drop);
16
+ }
17
+ const meanDrop = sumDrop / ids.length;
18
+ return { regressed: meanDrop > EPSILON || worstDrop > maxCaseDrop + EPSILON, meanDrop, worstDrop };
19
+ }
@@ -1,3 +1,4 @@
1
+ import { holdoutRegression } from "./holdout-gate.js";
1
2
  import { existsSync, writeFileSync } from "node:fs";
2
3
  import { join } from "node:path";
3
4
  import { BudgetStop, buildReport, contentOf, MAX_CANDIDATE_CHARS, meanOf, MINIBATCH_SIZE, mulberry32, runGepa, targetComponents, textsOf, } from "../../../optimize/src/index.js";
@@ -298,8 +299,8 @@ export async function startOptimization(baseEnv, options) {
298
299
  // The report (spec §8.2.5): the base and the best candidate on the holdout split only.
299
300
  ctx.phase = "final";
300
301
  options.onEvent?.({ type: "phase", phase: "holdout" });
301
- const bestArtifactId = artifactOfCandidate.get(result.bestId) ?? base.id;
302
- const best = getArtifact(db, bestArtifactId);
302
+ let bestArtifactId = artifactOfCandidate.get(result.bestId) ?? base.id;
303
+ let best = getArtifact(db, bestArtifactId);
303
304
  const before = perCaseOf(cases.holdout, baseline.holdout);
304
305
  let after = before;
305
306
  let deterministic = baseline.holdout.deterministic.some(Boolean);
@@ -320,6 +321,16 @@ export async function startOptimization(baseEnv, options) {
320
321
  }
321
322
  }
322
323
  }
324
+ // Verify-or-rollback: a candidate that lowers the holdout mean, or drops any one case by more than maxCaseDrop, is not promoted.
325
+ if (bestArtifactId !== base.id) {
326
+ const gate = holdoutRegression(before, after, cases.holdout.map((c) => c.id), config.optimize.maxCaseDrop);
327
+ if (gate.regressed) {
328
+ logger.warn("optimization reverted to the base version: the best candidate regressed on the holdout", { optim_run_id: optimRunId, mean_drop: gate.meanDrop, worst_case_drop: gate.worstDrop });
329
+ bestArtifactId = base.id;
330
+ best = base;
331
+ after = before;
332
+ }
333
+ }
323
334
  const key = judgeKey(config);
324
335
  const judgeOnly = target.kind !== "judge_rubric" && !deterministic;
325
336
  const holdoutIds = cases.holdout.map((c) => c.id);
@@ -51,7 +51,7 @@ export async function stopOnRefusal(fn) {
51
51
  async function reflectionCompletion(payer, request) {
52
52
  const { env, budget } = payer;
53
53
  const { config } = env.deps;
54
- const spec = config.models.s2;
54
+ const spec = config.models[config.optimize.reflectionTier];
55
55
  const model = env.registry.get(spec.provider, spec.id);
56
56
  const effort = env.registry.clampEffort(model, spec.effort ?? "off");
57
57
  const { text } = await stopOnRefusal(() => runChargedCompletion({
@@ -15,6 +15,7 @@ const POLICY_DESCRIPTIONS = {
15
15
  edit: "edit files in the workspace",
16
16
  bash: "run shell commands",
17
17
  web_fetch: "fetch web pages",
18
+ web_search: "search the web (sends the query to Brave or Tavily)",
18
19
  load_skill: "load a skill's instructions",
19
20
  spawn: "start subagents",
20
21
  };
@@ -46,6 +47,12 @@ export const EDITABLE_SETTINGS = [
46
47
  description: `Whether the agent may ${POLICY_DESCRIPTIONS[tool] ?? `use the ${tool} tool`}: allow, ask first, or deny`,
47
48
  type: { kind: "enum", values: POLICY_VALUES },
48
49
  })),
50
+ {
51
+ key: "tools.webSearch.count",
52
+ label: "Web search results",
53
+ description: "Results web_search returns after merging Brave and Tavily (1 to 20); set a key for either to turn web search on",
54
+ type: { kind: "number", integer: true, min: 1, max: 20 },
55
+ },
49
56
  {
50
57
  key: "tools.nonInteractiveAsk",
51
58
  label: "Ask without a terminal",
@@ -70,6 +77,30 @@ export const EDITABLE_SETTINGS = [
70
77
  description: "Also compact when one S2 request with the history would cost more than this share of a turn's budget (0 to 1; 0 = off)",
71
78
  type: { kind: "number", integer: false, min: 0, max: 1 },
72
79
  },
80
+ {
81
+ key: "optimize.reflectionTier",
82
+ label: "Optimizer edit model",
83
+ description: "Which model tier writes candidate edits in `nexo optimize` (s1 is cheaper; edit quality barely depends on model size)",
84
+ type: { kind: "enum", values: ["s1", "s2"] },
85
+ },
86
+ {
87
+ key: "optimize.maxCaseDrop",
88
+ label: "Optimizer max case drop",
89
+ description: "Largest quality drop on one holdout case a promoted candidate may have (0 to 1); a larger drop or a lower holdout mean reverts to the base version",
90
+ type: { kind: "number", integer: false, min: 0, max: 1 },
91
+ },
92
+ {
93
+ key: "loop.maxToolCalls",
94
+ label: "Max tool calls",
95
+ description: "Most tool calls one run may make before it is stopped and told to report (0 = no cap)",
96
+ type: { kind: "number", integer: true, min: 0 },
97
+ },
98
+ {
99
+ key: "loop.repeatLimit",
100
+ label: "Repeat limit",
101
+ description: "Most identical consecutive tool calls (same tool and arguments) before the next one is blocked (0 = off)",
102
+ type: { kind: "number", integer: true, min: 0 },
103
+ },
73
104
  {
74
105
  key: "spawn.maxParallelSubagents",
75
106
  label: "Parallel subagents",
@@ -1,6 +1,8 @@
1
1
  import { accessSync, constants, existsSync } from "node:fs";
2
2
  import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
3
3
  import { toErrorPayload } from "../../../telemetry/src/index.js";
4
+ import { SEARCH_PROVIDERS } from "../../../tools/src/index.js";
5
+ const KEY_SOURCE = { option: "passed in code", env: "environment", file: "credentials file", unset: "not set" };
4
6
  /** Oldest Node release nexo supports; keep in step with `engines.node` in package.json. */
5
7
  export const MIN_NODE_VERSION = "22.19.0";
6
8
  function parseVersion(version) {
@@ -78,14 +80,25 @@ export function runDoctor(options) {
78
80
  else {
79
81
  add({ id: "models", status: "ok", message: "Models s1 and s2 are set" });
80
82
  }
81
- for (const key of settings.keyProviders()) {
83
+ const keys = settings.keyProviders();
84
+ for (const key of keys.filter((k) => k.purpose === "model")) {
82
85
  if (key.state === "unset") {
83
86
  add({ id: `key:${key.provider}`, status: "warn", message: `No API key for ${key.provider}`, fix: `Run \`nexo settings set-key ${key.provider}\` (not needed for keyless or local providers)` });
84
87
  }
85
88
  else {
86
- add({ id: `key:${key.provider}`, status: "ok", message: `API key for ${key.provider} found (${key.state === "env" ? "environment" : "credentials file"})` });
89
+ add({ id: `key:${key.provider}`, status: "ok", message: `API key for ${key.provider} found (${KEY_SOURCE[key.state]})` });
87
90
  }
88
91
  }
92
+ const search = keys.filter((k) => k.purpose === "search");
93
+ const searchOn = search.filter((k) => k.state !== "unset");
94
+ add(searchOn.length > 0
95
+ ? { id: "web_search", status: "ok", message: `Web search uses ${searchOn.map((k) => `${k.provider} (${KEY_SOURCE[k.state]})`).join(", ")}` }
96
+ : {
97
+ id: "web_search",
98
+ status: "warn",
99
+ message: "No web search key (the web_search tool is off)",
100
+ fix: `Run \`nexo settings set-key ${search.map((k) => k.provider).join("` or `nexo settings set-key ")}\`, or set ${search.map((k) => SEARCH_PROVIDERS[k.provider]?.envVar).join(" or ")}`,
101
+ });
89
102
  if (config) {
90
103
  add((config.models.judge ?? []).length > 0
91
104
  ? { id: "judge", status: "ok", message: "Judge model is set" }