@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
@@ -1,4 +1,5 @@
1
1
  import { findEnvKeys, getEnvApiKey } from "@earendil-works/pi-ai/compat";
2
+ import { isSearchProvider, SEARCH_PROVIDER_IDS, SEARCH_PROVIDERS } from "../../../tools/src/index.js";
2
3
  import { createMutableRedactor, createRedactor, createSecretSet, containsSecret, MIN_SECRET_LENGTH, NexoError, toErrorPayload, } from "../../../telemetry/src/index.js";
3
4
  import { configErrors, deepMerge, loadConfig } from "../config/load.js";
4
5
  import { EDITABLE_SETTINGS, findSetting, mergedLayers, parseSettingInput, readConfigLayers, resetSetting, settingView, writeSetting, } from "./config-edit.js";
@@ -42,6 +43,8 @@ function configuredProviders(merged) {
42
43
  return out;
43
44
  }
44
45
  export function keyStatusLabel(status) {
46
+ if (status.state === "option")
47
+ return "set (passed in code)";
45
48
  if (status.state === "env")
46
49
  return "set (env)";
47
50
  if (status.state === "file")
@@ -51,6 +54,10 @@ export function keyStatusLabel(status) {
51
54
  export function createSettings(options) {
52
55
  const { paths, cwd } = options;
53
56
  const env = providerEnv(options.env ?? process.env);
57
+ const optionKeys = new Map();
58
+ for (const [provider, value] of Object.entries(options.apiKeys ?? {}))
59
+ if (typeof value === "string" && value.trim() !== "")
60
+ optionKeys.set(provider, value.trim());
54
61
  const secrets = createSecretSet();
55
62
  let patterns = [];
56
63
  const redact = createMutableRedactor(createRedactor(patterns, { secrets }));
@@ -84,10 +91,16 @@ export function createSettings(options) {
84
91
  registerSecret(provider, "file", entry.apiKey);
85
92
  };
86
93
  const envKey = (provider) => {
87
- const value = getEnvApiKey(provider, env)?.trim();
94
+ const value = (isSearchProvider(provider) ? env[SEARCH_PROVIDERS[provider].envVar] : getEnvApiKey(provider, env))?.trim();
88
95
  return value ? value : undefined;
89
96
  };
97
+ const envVarOf = (provider) => (isSearchProvider(provider) ? SEARCH_PROVIDERS[provider].envVar : (findEnvKeys(provider, env)?.[0] ?? null));
90
98
  const resolveApiKey = (provider) => {
99
+ const fromOption = optionKeys.get(provider);
100
+ if (fromOption !== undefined) {
101
+ registerSecret(provider, "option", fromOption);
102
+ return fromOption;
103
+ }
91
104
  const fromEnv = envKey(provider);
92
105
  if (fromEnv !== undefined) {
93
106
  if (fromEnv === AMBIENT_CREDENTIALS)
@@ -111,9 +124,9 @@ export function createSettings(options) {
111
124
  */
112
125
  const validateProvider = (provider, strict) => {
113
126
  const known = !containsSecret(provider) &&
114
- (options.models?.getProvider(provider) !== undefined || configured().includes(provider) || (!strict && provider in credentials));
127
+ (options.models?.getProvider(provider) !== undefined || isSearchProvider(provider) || configured().includes(provider) || (!strict && provider in credentials));
115
128
  if (!known) {
116
- const ids = [...new Set([...(options.models?.getProviders().map((p) => p.id) ?? []), ...configured()])].sort();
129
+ const ids = [...new Set([...(options.models?.getProviders().map((p) => p.id) ?? []), ...configured(), ...SEARCH_PROVIDER_IDS])].sort();
117
130
  throw invalidRequest("Unknown provider: not in the model registry or the nexo config", ids.length > 0 ? `Use a provider id such as ${ids.slice(0, 12).join(", ")}${ids.length > 12 ? ", …" : ""}` : "Configure models.s1/models.s2 first");
118
131
  }
119
132
  };
@@ -121,14 +134,17 @@ export function createSettings(options) {
121
134
  const keyStatus = (provider) => {
122
135
  const stored = credentials[provider];
123
136
  const inFile = stored !== undefined;
137
+ const purpose = isSearchProvider(provider) ? "search" : "model";
138
+ if (optionKeys.has(provider))
139
+ return { provider, purpose, state: "option", envVar: null, last4: null, inFile };
124
140
  // claude-p and kiro-p run a local CLI that brings its own login: ambient credentials, like AWS or Google ADC.
125
141
  if (provider === CLAUDE_P_PROVIDER || provider === KIRO_P_PROVIDER)
126
- return { provider, state: "env", envVar: null, last4: null, inFile };
142
+ return { provider, purpose, state: "env", envVar: null, last4: null, inFile };
127
143
  if (envKey(provider) !== undefined)
128
- return { provider, state: "env", envVar: findEnvKeys(provider, env)?.[0] ?? null, last4: null, inFile };
144
+ return { provider, purpose, state: "env", envVar: envVarOf(provider), last4: null, inFile };
129
145
  if (stored?.apiKey)
130
- return { provider, state: "file", envVar: null, last4: stored.apiKey.slice(-4), inFile };
131
- return { provider, state: "unset", envVar: null, last4: null, inFile };
146
+ return { provider, purpose, state: "file", envVar: null, last4: stored.apiKey.slice(-4), inFile };
147
+ return { provider, purpose, state: "unset", envVar: null, last4: null, inFile };
132
148
  };
133
149
  const loadEffective = () => {
134
150
  const loaded = loadConfig({ paths, cwd, overrides: options.overrides });
@@ -136,8 +152,10 @@ export function createSettings(options) {
136
152
  redact.replace(createRedactor(patterns, { secrets }));
137
153
  return loaded;
138
154
  };
139
- /** Redacts env keys of the providers in use, since bash children inherit the environment and could print them. */
155
+ /** Redacts env keys of the providers in use and of the search providers, since bash children inherit the environment and could print them. */
140
156
  const registerEnvKeys = () => {
157
+ for (const provider of SEARCH_PROVIDER_IDS)
158
+ resolveApiKey(provider);
141
159
  try {
142
160
  for (const provider of modelProviders(deepMerge(mergedLayers(layers()), options.overrides)))
143
161
  resolveApiKey(provider);
@@ -178,10 +196,11 @@ export function createSettings(options) {
178
196
  catch {
179
197
  fromModels = [];
180
198
  }
199
+ const fromSearch = SEARCH_PROVIDER_IDS.filter((p) => !fromModels.includes(p));
181
200
  const fromFile = Object.keys(credentials)
182
- .filter((p) => !fromModels.includes(p))
201
+ .filter((p) => !fromModels.includes(p) && !isSearchProvider(p))
183
202
  .sort();
184
- return [...fromModels, ...fromFile].map(keyStatus);
203
+ return [...fromModels, ...fromSearch, ...fromFile].map(keyStatus);
185
204
  },
186
205
  setKey(provider, apiKey) {
187
206
  validateProvider(provider, true);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hexdecimal16/nexo",
3
- "version": "0.3.5",
3
+ "version": "0.4.1",
4
4
  "description": "nexo agent engine",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "repository": {
package/sdk/src/nexo.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { createSession, createSettings, nexoModels, resumeSession, runDoctor, } from "../../core/src/index.js";
2
- import { resolveNexoPaths } from "../../store/src/index.js";
2
+ import { resolveNexoPaths, reviewQueue } from "../../store/src/index.js";
3
3
  import { NexoError } from "../../telemetry/src/index.js";
4
- import { nonInteractivePrompter } from "../../tools/src/index.js";
4
+ import { nonInteractivePrompter, SEARCH_PROVIDER_IDS, webSearch } from "../../tools/src/index.js";
5
5
  import { createRuntime } from "./runtime.js";
6
6
  function withHome(options) {
7
7
  const env = options.env ?? process.env;
@@ -15,7 +15,7 @@ export function checkSetup(options = {}) {
15
15
  const env = withHome(options);
16
16
  const cwd = options.cwd ?? process.cwd();
17
17
  const paths = resolveNexoPaths(env);
18
- const settings = createSettings({ paths, cwd, env, models: options.models ?? nexoModels() });
18
+ const settings = createSettings({ paths, cwd, env, models: options.models ?? nexoModels(), apiKeys: options.apiKeys });
19
19
  return runDoctor({ paths, settings, env, cwd });
20
20
  }
21
21
  /** Builds the runtime and returns the programmatic entry point. Throws CONFIG_INVALID when the config is not usable. */
@@ -30,6 +30,8 @@ export function createNexo(options = {}) {
30
30
  prompter,
31
31
  models: options.models,
32
32
  overrides: options.config,
33
+ apiKeys: options.apiKeys,
34
+ ...(options.fetch ? { fetch: options.fetch } : {}),
33
35
  onEvent: (event) => {
34
36
  for (const listener of [...listeners])
35
37
  listener(event);
@@ -76,9 +78,37 @@ export function createNexo(options = {}) {
76
78
  live();
77
79
  return resumeSession(sessionDeps(), id);
78
80
  },
81
+ reviewQueue(queueOptions) {
82
+ live();
83
+ return reviewQueue(runtime.db, queueOptions);
84
+ },
79
85
  doctor() {
80
86
  return runDoctor({ paths: runtime.paths, settings: runtime.settings, env, cwd });
81
87
  },
88
+ async webSearch(query, searchOptions = {}) {
89
+ live();
90
+ const keys = Object.fromEntries(SEARCH_PROVIDER_IDS.map((id) => [id, runtime.settings.resolveApiKey(id)]));
91
+ try {
92
+ return await webSearch(query, { keys, count: searchOptions.count ?? runtime.config.tools.webSearch.count, ...(options.fetch ? { fetch: options.fetch } : {}) }, searchOptions.signal);
93
+ }
94
+ catch (error) {
95
+ if (searchOptions.signal?.aborted || error instanceof NexoError)
96
+ throw error;
97
+ // An empty query or no key: the message names `nexo settings set-key` and the environment variables.
98
+ throw new NexoError({ code: "INVALID_REQUEST", message: error instanceof Error ? error.message : String(error), hint: "Pass apiKeys: { brave: \"…\" } or { tavily: \"…\" } to createNexo, or call setKey" });
99
+ }
100
+ },
101
+ keys() {
102
+ return runtime.settings.keyProviders();
103
+ },
104
+ setKey(provider, apiKey) {
105
+ live();
106
+ return runtime.settings.setKey(provider, apiKey);
107
+ },
108
+ removeKey(provider) {
109
+ live();
110
+ return runtime.settings.removeKey(provider);
111
+ },
82
112
  async close() {
83
113
  if (closed)
84
114
  return;
@@ -27,6 +27,7 @@ export function trackRunTree(onChange) {
27
27
  status: "running",
28
28
  costUsd: 0,
29
29
  toolCalls: 0,
30
+ loopGuards: 0,
30
31
  currentTool: null,
31
32
  error: null,
32
33
  startedAt: Date.now(),
@@ -48,6 +49,11 @@ export function trackRunTree(onChange) {
48
49
  n.currentTool = event.toolName;
49
50
  });
50
51
  break;
52
+ case "loop_guard":
53
+ update(event.runId, (n) => {
54
+ n.loopGuards++;
55
+ });
56
+ break;
51
57
  case "tool_end":
52
58
  update(event.runId, (n) => {
53
59
  n.currentTool = null;
@@ -12,7 +12,7 @@ export function createRuntime(options) {
12
12
  const paths = resolveNexoPaths(options.env);
13
13
  ensureNexoDirs(paths);
14
14
  const models = options.models ?? nexoModels();
15
- const settings = createSettings({ paths, cwd: options.cwd, env: options.env, models, overrides: options.overrides });
15
+ const settings = createSettings({ paths, cwd: options.cwd, env: options.env, models, overrides: options.overrides, apiKeys: options.apiKeys });
16
16
  const { config, hash } = settings.loadConfig();
17
17
  const redact = settings.redact;
18
18
  const logger = openLogger(settings, paths, "cli");
@@ -33,6 +33,7 @@ export function createRuntime(options) {
33
33
  skills,
34
34
  onEvent: options.onEvent,
35
35
  resolveApiKey: settings.resolveApiKey,
36
+ ...(options.fetch ? { fetch: options.fetch } : {}),
36
37
  ...(mcp ? { mcp } : {}),
37
38
  });
38
39
  return { paths, config, configHash: hash, models, db, skills, engine, redact, logger, settings, mcp, learner: new LearnWorker(engine.env, options.onLearnEvent ? { onEvent: options.onLearnEvent } : {}) };
@@ -15,6 +15,7 @@ export * from "./mine.js";
15
15
  export * from "./optim.js";
16
16
  export * from "./paths.js";
17
17
  export * from "./playbooks.js";
18
+ export * from "./review-queue.js";
18
19
  export * from "./runs.js";
19
20
  export * from "./scores.js";
20
21
  export * from "./sessions.js";
@@ -0,0 +1,46 @@
1
+ export const DEFAULT_REVIEW_QUEUE_SIZE = 15;
2
+ const LOW_SCORE = 0.6;
3
+ /**
4
+ * Recent finished root runs that have no human verdict, worst first: failed, over-budget and aborted runs, then low
5
+ * scores, then unscored runs, then the rest by cost. A person reviews the head of this list each week and labels it.
6
+ */
7
+ export function reviewQueue(db, options = {}) {
8
+ const limit = Math.max(1, Math.min(100, options.limit ?? DEFAULT_REVIEW_QUEUE_SIZE));
9
+ const since = new Date((options.now ?? new Date()).getTime() - (options.days ?? 7) * 86_400_000).toISOString();
10
+ const rows = db
11
+ .prepare(`SELECT r.id, r.instruction, r.status, r.started_at, r.cost_usd, r.error_json,
12
+ (SELECT AVG(s.value) FROM scores s WHERE s.run_id = r.id AND s.status = 'ok' AND s.round = (SELECT MAX(s2.round) FROM scores s2 WHERE s2.run_id = r.id)) AS score
13
+ FROM runs r
14
+ WHERE r.parent_run_id IS NULL AND r.status != 'running' AND r.started_at >= ?
15
+ AND NOT EXISTS (SELECT 1 FROM feedback f WHERE f.run_id = r.id)`)
16
+ .all(since);
17
+ const items = rows.map((row) => {
18
+ const status = String(row.status);
19
+ const score = row.score === null ? null : Number(row.score);
20
+ const failureMode = status === "failed" || status === "budget_exceeded" || status === "aborted" ? status : score === null ? "unscored" : score < LOW_SCORE ? "low_score" : "ok";
21
+ let errorCode = null;
22
+ if (typeof row.error_json === "string") {
23
+ try {
24
+ const code = JSON.parse(row.error_json).code;
25
+ errorCode = typeof code === "string" ? code : null;
26
+ }
27
+ catch {
28
+ errorCode = null;
29
+ }
30
+ }
31
+ const first = String(row.instruction).split("\n")[0] ?? "";
32
+ return {
33
+ runId: String(row.id),
34
+ instruction: first.length > 120 ? `${first.slice(0, 119)}…` : first,
35
+ status,
36
+ failureMode,
37
+ errorCode,
38
+ score,
39
+ costUsd: Number(row.cost_usd),
40
+ startedAt: String(row.started_at),
41
+ };
42
+ });
43
+ const rank = { failed: 0, budget_exceeded: 1, aborted: 2, low_score: 3, unscored: 4, ok: 5 };
44
+ items.sort((a, b) => rank[a.failureMode] - rank[b.failureMode] || (a.score ?? 1) - (b.score ?? 1) || b.costUsd - a.costUsd || b.startedAt.localeCompare(a.startedAt));
45
+ return items.slice(0, limit);
46
+ }
@@ -43,6 +43,16 @@ function ensureExitHandler() {
43
43
  exitHandlerRegistered = true;
44
44
  process.on("exit", killLiveBashGroups);
45
45
  }
46
+ const SECRET_ENV_NAME = /(^|_)(API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|PRIVATE_KEY|ACCESS_KEY|SESSION_KEY)(_|$)|^(AWS|AZURE|GCP|GOOGLE|OPENAI|ANTHROPIC|GITHUB|GH|NPM|SSH_AUTH)_.*(KEY|TOKEN|SECRET|SOCK)/i;
47
+ /** The process environment without variables whose names look like secrets (API keys, tokens, passwords), for commands the agent runs. */
48
+ export function bashEnv(source = process.env) {
49
+ const out = {};
50
+ for (const [name, value] of Object.entries(source)) {
51
+ if (value !== undefined && !SECRET_ENV_NAME.test(name))
52
+ out[name] = value;
53
+ }
54
+ return out;
55
+ }
46
56
  /** Runs `command` with `bash -c` in its own process group, killed on timeout, abort or host exit. Never rejects. */
47
57
  export function runBash(run) {
48
58
  const { signal } = run;
@@ -239,11 +249,11 @@ export function createBuiltinTools(ctx) {
239
249
  const bash = {
240
250
  name: "bash",
241
251
  label: "Run command",
242
- description: "Run a bash command in the workspace directory.",
252
+ description: "Run a bash command in the workspace directory (bash -c, no TTY, no stdin). Returns `exit code: N` followed by combined stdout and stderr; output beyond the limit is truncated, so filter with grep, head or tail. Chain related steps with && in one call. A command that may outlive the timeout belongs in the background: nohup <command> > job.log 2>&1 &, then poll job.log. Pass timeoutMs to raise the default. The environment is filtered, so secrets such as API keys are not available.",
243
253
  parameters: BashParams,
244
254
  execute: async (_id, params, signal) => {
245
255
  const timeoutMs = params.timeoutMs ?? ctx.bashTimeoutMs;
246
- const r = await runBash({ command: params.command, cwd: root, timeoutMs, signal });
256
+ const r = await runBash({ command: params.command, cwd: root, timeoutMs, signal, env: bashEnv() });
247
257
  const body = `${r.output}${r.truncated ? "\n[output truncated]" : ""}`;
248
258
  switch (r.ended) {
249
259
  case "failed":
@@ -260,7 +270,7 @@ export function createBuiltinTools(ctx) {
260
270
  const webFetch = {
261
271
  name: "web_fetch",
262
272
  label: "Fetch URL",
263
- description: `Fetch an http(s) URL and return readable text. HTML pages are converted to plain text with links kept as [text](url); scripts, styles, navigation and footers are dropped. Markdown is requested first, so sites that serve it return it unchanged. Output is capped at ${MAX_FETCH_CHARS} characters. Binary files are refused. If a site blocks the fetch (for example a Cloudflare challenge), load the browser skill and read the page there.`,
273
+ description: `Fetch an http(s) URL and return readable text. To find URLs, use web_search when it is available. HTML pages are converted to plain text with links kept as [text](url); scripts, styles, navigation and footers are dropped. Markdown is requested first, so sites that serve it return it unchanged. Output is capped at ${MAX_FETCH_CHARS} characters. Binary files are refused. If a site blocks the fetch (for example a Cloudflare challenge), load the browser skill and read the page there.`,
264
274
  parameters: FetchParams,
265
275
  execute: async (_id, params, signal) => {
266
276
  const url = new URL(params.url);
@@ -1,11 +1,12 @@
1
1
  import { tmpdir } from "node:os";
2
2
  import { createBuiltinTools } from "./builtin.js";
3
3
  import { FileLeases } from "./leases.js";
4
+ import { WEB_SEARCH_DESCRIPTION } from "./web-search.js";
4
5
  /**
5
6
  * The built-in tools' own descriptions by tool name: the text an optimization of `tool:<name>` starts from and a run
6
7
  * uses when no promoted or candidate description replaces it. Read from the tools themselves, so there is one copy.
7
8
  */
8
9
  export function builtinToolDescriptions() {
9
10
  const tools = createBuiltinTools({ workspaceRoot: tmpdir(), holder: "descriptions", leases: new FileLeases(), bashTimeoutMs: 1 });
10
- return Object.fromEntries(tools.map((t) => [t.name, t.description]));
11
+ return { ...Object.fromEntries(tools.map((t) => [t.name, t.description])), web_search: WEB_SEARCH_DESCRIPTION };
11
12
  }
@@ -6,3 +6,4 @@ export * from "./leases.js";
6
6
  export * from "./policy.js";
7
7
  export * from "./read-only.js";
8
8
  export * from "./session-rules.js";
9
+ export * from "./web-search.js";
@@ -17,7 +17,7 @@ export function stripCdPrefix(command) {
17
17
  function escapeControl(text) {
18
18
  return text.replace(/[\u0000-\u001f\u007f]/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`);
19
19
  }
20
- const SUBJECT_KEY = { bash: "command", read: "path", write: "path", edit: "path", web_fetch: "url" };
20
+ const SUBJECT_KEY = { bash: "command", read: "path", write: "path", edit: "path", web_fetch: "url", web_search: "query" };
21
21
  function subjectOf(toolName, args) {
22
22
  const key = SUBJECT_KEY[toolName];
23
23
  if (key && typeof args === "object" && args !== null && typeof args[key] === "string") {
@@ -0,0 +1,251 @@
1
+ import { Type } from "typebox";
2
+ /** The web search APIs `web_search` can query. Each one is used when its key is set. */
3
+ export const SEARCH_PROVIDER_IDS = ["brave", "tavily"];
4
+ export const SEARCH_PROVIDERS = {
5
+ brave: { id: "brave", name: "Brave Search", envVar: "BRAVE_API_KEY", signupUrl: "https://api-dashboard.search.brave.com" },
6
+ tavily: { id: "tavily", name: "Tavily", envVar: "TAVILY_API_KEY", signupUrl: "https://app.tavily.com" },
7
+ };
8
+ export function isSearchProvider(id) {
9
+ return SEARCH_PROVIDER_IDS.includes(id);
10
+ }
11
+ export const MAX_SEARCH_RESULTS = 20;
12
+ const DEFAULT_TIMEOUT_MS = 15_000;
13
+ /** Reciprocal rank fusion constant; 60 is the value from the original paper and needs no tuning per provider. */
14
+ const RRF_K = 60;
15
+ const MAX_SNIPPET_CHARS = 400;
16
+ class ProviderError extends Error {
17
+ }
18
+ const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
19
+ /** Snippet text without tags and with entities decoded, whitespace collapsed and length capped. */
20
+ export function cleanSnippet(text) {
21
+ const decoded = text
22
+ .replace(/<[^>]*>/g, "")
23
+ .replace(/&(#x[0-9a-f]+|#\d+|[a-z]+\d*);/gi, (whole, name) => {
24
+ const lower = name.toLowerCase();
25
+ if (lower.startsWith("#x"))
26
+ return String.fromCodePoint(Number.parseInt(lower.slice(2), 16));
27
+ if (lower.startsWith("#"))
28
+ return String.fromCodePoint(Number.parseInt(lower.slice(1), 10));
29
+ return ENTITIES[lower] ?? whole;
30
+ })
31
+ .replace(/\s+/g, " ")
32
+ .trim();
33
+ return decoded.length > MAX_SNIPPET_CHARS ? `${decoded.slice(0, MAX_SNIPPET_CHARS - 1)}…` : decoded;
34
+ }
35
+ const TRACKING_PARAM = /^(utm_.+|gclid|fbclid|msclkid|mc_cid|mc_eid|ref|ref_src|_hsenc|_hsmi|igshid)$/i;
36
+ /**
37
+ * The key two results are deduplicated by: host lowercased without `www.`, scheme and fragment dropped, tracking
38
+ * parameters removed, the rest sorted, and no trailing slash. Unparsable URLs are their own key.
39
+ */
40
+ export function normalizeUrl(raw) {
41
+ let url;
42
+ try {
43
+ url = new URL(raw);
44
+ }
45
+ catch {
46
+ return raw.trim();
47
+ }
48
+ const host = url.hostname.toLowerCase().replace(/^www\./, "");
49
+ const port = url.port && url.port !== "80" && url.port !== "443" ? `:${url.port}` : "";
50
+ const params = [...url.searchParams.entries()].filter(([name]) => !TRACKING_PARAM.test(name)).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
51
+ const query = params.length > 0 ? `?${new URLSearchParams(params).toString()}` : "";
52
+ const path = url.pathname.replace(/\/+$/, "");
53
+ return `${host}${port}${path}${query}`;
54
+ }
55
+ /**
56
+ * Merges ranked lists with reciprocal rank fusion: a result scores the sum of 1/(60 + rank) over the lists that
57
+ * contain it, so agreement between providers lifts it. Duplicates (by `normalizeUrl`) keep the first title and URL
58
+ * and the longest snippet. Ties keep the order of first appearance.
59
+ */
60
+ export function fuseResults(lists, count) {
61
+ const merged = new Map();
62
+ let order = 0;
63
+ for (const { provider, hits } of lists) {
64
+ const seen = new Set();
65
+ hits.forEach((hit, index) => {
66
+ const key = normalizeUrl(hit.url);
67
+ if (seen.has(key))
68
+ return;
69
+ seen.add(key);
70
+ const add = 1 / (RRF_K + index + 1);
71
+ const existing = merged.get(key);
72
+ if (!existing) {
73
+ merged.set(key, { ...hit, providers: [provider], score: add, order: order++ });
74
+ return;
75
+ }
76
+ existing.score += add;
77
+ existing.providers.push(provider);
78
+ if (hit.snippet.length > existing.snippet.length)
79
+ existing.snippet = hit.snippet;
80
+ if (!existing.date && hit.date)
81
+ existing.date = hit.date;
82
+ });
83
+ }
84
+ return [...merged.values()]
85
+ .sort((a, b) => b.score - a.score || a.order - b.order)
86
+ .slice(0, count)
87
+ .map(({ order: _order, ...result }) => result);
88
+ }
89
+ function statusMessage(status) {
90
+ if (status === 401 || status === 403)
91
+ return `HTTP ${status}: the API key was rejected`;
92
+ if (status === 402)
93
+ return "HTTP 402: the plan's quota or credits are used up";
94
+ if (status === 429)
95
+ return "HTTP 429: rate limited";
96
+ return `HTTP ${status}`;
97
+ }
98
+ /** Error codes a provider puts in its JSON error body that mean the key itself is bad. */
99
+ const KEY_ERROR_CODES = new Set(["SUBSCRIPTION_TOKEN_INVALID"]);
100
+ async function getJson(fetchImpl, url, init) {
101
+ const response = await fetchImpl(url, init);
102
+ if (!response.ok) {
103
+ // Brave answers a bad key with 422 and an error code; only that code is read, never the rest of the body.
104
+ let code;
105
+ try {
106
+ code = record(record(await response.json()).error).code;
107
+ }
108
+ catch {
109
+ code = undefined;
110
+ }
111
+ throw new ProviderError(typeof code === "string" && KEY_ERROR_CODES.has(code) ? `HTTP ${response.status}: the API key was rejected` : statusMessage(response.status));
112
+ }
113
+ try {
114
+ return await response.json();
115
+ }
116
+ catch {
117
+ throw new ProviderError("the response was not JSON");
118
+ }
119
+ }
120
+ function record(value) {
121
+ return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
122
+ }
123
+ function str(value) {
124
+ return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
125
+ }
126
+ function toHits(items, map) {
127
+ if (!Array.isArray(items))
128
+ throw new ProviderError("the response had no result list");
129
+ return items.map((item) => map(record(item))).filter((hit) => hit !== null);
130
+ }
131
+ const PROVIDER_SEARCH = {
132
+ brave: async (query, count, key, fetchImpl, signal) => {
133
+ const url = `https://api.search.brave.com/res/v1/web/search?${new URLSearchParams({ q: query, count: String(count) })}`;
134
+ const body = record(await getJson(fetchImpl, url, { signal, headers: { Accept: "application/json", "X-Subscription-Token": key } }));
135
+ // A query with no web results has no `web` section at all.
136
+ if (body.web === undefined)
137
+ return [];
138
+ return toHits(record(body.web).results, (item) => {
139
+ const link = str(item.url);
140
+ if (!link)
141
+ return null;
142
+ const date = str(item.page_age) ?? str(item.age);
143
+ return { title: cleanSnippet(str(item.title) ?? link), url: link, snippet: cleanSnippet(str(item.description) ?? ""), ...(date ? { date } : {}) };
144
+ });
145
+ },
146
+ tavily: async (query, count, key, fetchImpl, signal) => {
147
+ const body = record(await getJson(fetchImpl, "https://api.tavily.com/search", {
148
+ method: "POST",
149
+ signal,
150
+ headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
151
+ body: JSON.stringify({ query, max_results: count, search_depth: "basic" }),
152
+ }));
153
+ return toHits(body.results, (item) => {
154
+ const link = str(item.url);
155
+ if (!link)
156
+ return null;
157
+ const date = str(item.published_date);
158
+ return { title: cleanSnippet(str(item.title) ?? link), url: link, snippet: cleanSnippet(str(item.content) ?? ""), ...(date ? { date } : {}) };
159
+ });
160
+ },
161
+ };
162
+ /** The providers `web_search` would query: the ones with a key, in SEARCH_PROVIDER_IDS order. */
163
+ export function configuredSearchProviders(keys) {
164
+ return SEARCH_PROVIDER_IDS.filter((id) => (keys[id] ?? "").trim() !== "");
165
+ }
166
+ /**
167
+ * Queries every provider that has a key in parallel and fuses their results. A failing provider is reported in
168
+ * `failures` and does not fail the search. Throws only on an empty query, without any key, or when aborted.
169
+ */
170
+ export async function webSearch(query, options, signal) {
171
+ const q = query.trim();
172
+ if (q === "")
173
+ throw new Error("The search query is empty");
174
+ const providers = configuredSearchProviders(options.keys);
175
+ if (providers.length === 0)
176
+ throw new Error(noKeyMessage());
177
+ const count = Math.min(Math.max(1, Math.floor(options.count)), MAX_SEARCH_RESULTS);
178
+ const fetchImpl = options.fetch ?? fetch;
179
+ const settled = await Promise.allSettled(providers.map((provider) => {
180
+ const combined = AbortSignal.any([AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS), ...(signal ? [signal] : [])]);
181
+ return PROVIDER_SEARCH[provider](q, count, options.keys[provider].trim(), fetchImpl, combined);
182
+ }));
183
+ if (signal?.aborted)
184
+ throw new Error("Search aborted");
185
+ const lists = [];
186
+ const failures = [];
187
+ settled.forEach((outcome, i) => {
188
+ const provider = providers[i];
189
+ if (outcome.status === "fulfilled")
190
+ lists.push({ provider, hits: outcome.value });
191
+ else
192
+ failures.push({ provider, message: failureMessage(outcome.reason) });
193
+ });
194
+ return { results: fuseResults(lists, count), failures, answered: lists.map((l) => l.provider) };
195
+ }
196
+ function failureMessage(reason) {
197
+ if (reason instanceof ProviderError)
198
+ return reason.message;
199
+ if (reason instanceof Error && (reason.name === "TimeoutError" || reason.name === "AbortError"))
200
+ return "timed out";
201
+ // Network errors from fetch carry no key; anything else is reported by type only.
202
+ if (reason instanceof TypeError)
203
+ return `network error (${reason.message})`;
204
+ return "request failed";
205
+ }
206
+ export function noKeyMessage() {
207
+ const lines = SEARCH_PROVIDER_IDS.map((id) => `${SEARCH_PROVIDERS[id].name}: nexo settings set-key ${id} (or ${SEARCH_PROVIDERS[id].envVar}); get a key at ${SEARCH_PROVIDERS[id].signupUrl}`);
208
+ return `Web search has no API key. Set one of:\n${lines.join("\n")}`;
209
+ }
210
+ /** The outcome as the text the agent reads: numbered markdown links with snippets, then any provider failures. */
211
+ export function formatSearchOutcome(query, outcome) {
212
+ const failed = outcome.failures.map((f) => `${f.provider} (${f.message})`).join("; ");
213
+ if (outcome.answered.length === 0)
214
+ return `Web search failed: ${failed}`;
215
+ const lines = [];
216
+ if (outcome.results.length === 0)
217
+ lines.push(`No results for "${query}".`);
218
+ outcome.results.forEach((r, i) => {
219
+ lines.push(`${i + 1}. [${r.title.replace(/[[\]]/g, "")}](${r.url})`);
220
+ if (r.snippet)
221
+ lines.push(` ${r.snippet}`);
222
+ lines.push(` (${[r.providers.join(", "), r.date].filter(Boolean).join(" · ")})`);
223
+ });
224
+ if (outcome.failures.length > 0) {
225
+ lines.push("", `Not included: ${failed}`);
226
+ }
227
+ return lines.join("\n");
228
+ }
229
+ export const WEB_SEARCH_DESCRIPTION = `Search the web and return ranked results as [title](url) with a snippet. Queries every configured search API (Brave, Tavily) in parallel and merges their results; results found by several providers rank higher. Use it to find current information, documentation, error messages and URLs, then read the best hits with web_fetch and cite them. Write specific queries (names, versions, exact error text). count: results to return (default from config, at most ${MAX_SEARCH_RESULTS}).`;
230
+ const SearchParams = Type.Object({
231
+ query: Type.String({ minLength: 1, description: "What to search for" }),
232
+ count: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_SEARCH_RESULTS, description: "Number of results" })),
233
+ });
234
+ function textResult(text, isError = false) {
235
+ return isError ? { content: [{ type: "text", text }], details: undefined, isError: true } : { content: [{ type: "text", text }], details: undefined };
236
+ }
237
+ /** The `web_search` tool, or null when no provider has a key (the agent then never sees it). */
238
+ export function createWebSearchTool(options) {
239
+ if (configuredSearchProviders(options.keys).length === 0)
240
+ return null;
241
+ return {
242
+ name: "web_search",
243
+ label: "Search web",
244
+ description: WEB_SEARCH_DESCRIPTION,
245
+ parameters: SearchParams,
246
+ execute: async (_id, params, signal) => {
247
+ const outcome = await webSearch(params.query, { ...options, count: params.count ?? options.count }, signal);
248
+ return textResult(formatSearchOutcome(params.query.trim(), outcome), outcome.answered.length === 0);
249
+ },
250
+ };
251
+ }
package/tui/src/app.js CHANGED
@@ -2,7 +2,7 @@ import { homedir } from "node:os";
2
2
  import { sep } from "node:path";
3
3
  import { CombinedAutocompleteProvider, Container, Editor, isKeyRelease, isKeyRepeat, Loader, matchesKey, ProcessTerminal, setCapabilityOverrides, TuiMainScreen, } from "@earendil-works/pi-tui";
4
4
  import { listSessions, projectRoots } from "../../core/src/index.js";
5
- import { getSessionRow, sessionNotFound } from "../../store/src/index.js";
5
+ import { getSessionRow, reviewQueue, sessionNotFound } from "../../store/src/index.js";
6
6
  import { toErrorPayload } from "../../telemetry/src/index.js";
7
7
  import { describeSessionRule } from "../../tools/src/index.js";
8
8
  import { createApprovalPrompter } from "./approvals.js";
@@ -643,6 +643,20 @@ class InteractiveApp {
643
643
  this.chat.addChild(new Block(`score ${escapeControl(oneLine(event.scorer, 60))}: ${scoreVerdict(event)}`, style.gray, " "));
644
644
  break;
645
645
  }
646
+ case "loop_guard": {
647
+ this.currentText = null;
648
+ const what = event.kind === "max_tool_calls"
649
+ ? `tool-call cap reached (loop.maxToolCalls ${event.limit}); the agent was asked to report`
650
+ : `blocked ${escapeControl(oneLine(event.toolName, 40))}: ${event.count} identical calls in a row (loop.repeatLimit ${event.limit})`;
651
+ this.chat.addChild(new Block(`⚠ ${what}`, style.yellow, " "));
652
+ break;
653
+ }
654
+ case "context_trim":
655
+ if (event.depth !== 0)
656
+ return;
657
+ this.currentText = null;
658
+ this.chat.addChild(new Block(`context nearly full: cleared ${event.cleared} old tool outputs (~${event.tokensBefore} → ~${event.tokensAfter} tokens)`, style.gray, " "));
659
+ break;
646
660
  case "compaction_start":
647
661
  this.currentText = null;
648
662
  this.chat.addChild(new Block("compacting earlier turns…", style.gray, " "));
@@ -769,6 +783,13 @@ class InteractiveApp {
769
783
  this.say("── conversation cleared ── (same session; earlier turns stay in its history)");
770
784
  this.tui.requestRender(true);
771
785
  break;
786
+ case "queue": {
787
+ const items = reviewQueue(this.options.db, { limit: 10 });
788
+ this.say(items.length === 0
789
+ ? "no unreviewed runs in the last 7 days"
790
+ : items.map((i) => `${i.runId.slice(-6)} ${i.failureMode} ${i.score === null ? "–" : i.score.toFixed(2)} ${escapeControl(i.instruction)}`).join("\n"));
791
+ break;
792
+ }
772
793
  case "sessions":
773
794
  this.say(this.sessionsText(session));
774
795
  break;
@@ -17,6 +17,7 @@ export const SLASH_COMMANDS = [
17
17
  { name: "done", description: "Mark the last turn done" },
18
18
  { name: "notdone", description: "Mark the last turn not done", argumentHint: "[comment]" },
19
19
  { name: "cost", description: "Show the session's cost and budget" },
20
+ { name: "queue", description: "List recent runs without a verdict, worst first" },
20
21
  { name: "budget", description: "Set this session's budget cap", argumentHint: "<usd>" },
21
22
  { name: "model", description: "Set this session's model (default clears it)", argumentHint: "<s1|s2|provider/id|default>", getArgumentCompletions: items(["s1", "s2", "default"]) },
22
23
  { name: "effort", description: "Set this session's effort (default clears it)", argumentHint: "<level|default>", getArgumentCompletions: items([...EFFORTS, "default"]) },