@hexdecimal16/nexo 0.4.0 → 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.
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,9 +10,13 @@ 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|reflectionTier|maxCaseDrop, loop.maxToolCalls|repeatLimit
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
package/cli/src/main.js CHANGED
@@ -18,6 +18,7 @@ import { doctorCommand } from "./doctor.js";
18
18
  import { initCommand } from "./init.js";
19
19
  import { updateCommand } from "./update.js";
20
20
  import { nexoVersion } from "./version.js";
21
+ import { searchCommand } from "./search.js";
21
22
  import { settingsCommand } from "./settings.js";
22
23
  import { escapeControl } from "../../tui/src/index.js";
23
24
  import { runUi } from "./ui.js";
@@ -244,6 +245,8 @@ export async function runCli(argv, io, options = {}) {
244
245
  return playbookCommand(rest, io, options);
245
246
  case "doctor":
246
247
  return doctorCommand(rest, io, options);
248
+ case "search":
249
+ return await searchCommand(rest, io, options);
247
250
  case "init":
248
251
  return await initCommand(rest, io, options, stdio);
249
252
  case "update":
@@ -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) {
@@ -94,6 +94,8 @@ export const ConfigSchema = Type.Object({
94
94
  nonInteractiveAsk: NonInteractiveAskSchema,
95
95
  autoApprove: Type.Union([Type.Literal("off"), Type.Literal("on")]),
96
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 }),
97
99
  }, { additionalProperties: false }),
98
100
  mcp: Type.Object({
99
101
  /** Stdio MCP servers by name; their tools reach the agent as `mcp__<name>__<tool>`. */
@@ -184,11 +186,12 @@ export const DEFAULT_CONFIG = {
184
186
  instructions: [],
185
187
  skills: { dirs: ["$NEXO_HOME/skills", "./.nexo/skills"], pins: {} },
186
188
  tools: {
187
- 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" },
188
190
  rules: [],
189
191
  nonInteractiveAsk: "deny",
190
192
  autoApprove: "off",
191
193
  bashTimeoutMs: 120_000,
194
+ webSearch: { count: 8 },
192
195
  },
193
196
  mcp: { servers: {} },
194
197
  pricingOverrides: {},
@@ -13,6 +13,8 @@ export const DEFAULT_PLANNER_PROMPT = `Parallel work:
13
13
  - When the instruction has independent parts, call spawn once with all independent tasks so they run in parallel.
14
14
  - Use dependsOn only when a task needs another task's output; dependency outputs are appended to the dependent task's instruction.
15
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.`;
16
18
  /** The line that points the agent at the wikis directory; the wiki skill holds the rules for using it. */
17
19
  export function wikiPrompt(wikisDir) {
18
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.`;
@@ -21,6 +23,8 @@ export function renderSystemPrompt(parts) {
21
23
  const sections = [parts.systemPrompt.replaceAll("{{workspace}}", parts.workspace)];
22
24
  if (parts.plannerPrompt)
23
25
  sections.push(parts.plannerPrompt);
26
+ if (parts.webSearch)
27
+ sections.push(WEB_SEARCH_PROMPT);
24
28
  if (parts.wikisDir)
25
29
  sections.push(wikiPrompt(parts.wikisDir));
26
30
  if (parts.skillIndex)
@@ -4,7 +4,7 @@ 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";
@@ -35,7 +35,7 @@ function toolOutputExcerpt(text, pointer) {
35
35
  /** Longest tool result text carried by a `tool_end` preview (`output` carries all of it). */
36
36
  export const TOOL_END_PREVIEW_CHARS = 2_000;
37
37
  /** The tools an explore-mode subagent keeps: read-only research. */
38
- const EXPLORE_TOOLS = new Set(["read", "web_fetch", "load_skill"]);
38
+ const EXPLORE_TOOLS = new Set(["read", "web_fetch", "web_search", "load_skill"]);
39
39
  /** JSON with object keys sorted at every level, so the same arguments in another key order compare equal. */
40
40
  function stableJson(value) {
41
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);
@@ -564,6 +564,14 @@ export async function executeRun(env, input) {
564
564
  },
565
565
  }),
566
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);
567
575
  const toolCtx = {
568
576
  env,
569
577
  runId,
@@ -625,6 +633,7 @@ export async function executeRun(env, input) {
625
633
  const systemPrompt = renderSystemPrompt({
626
634
  systemPrompt: systemPromptText,
627
635
  plannerPrompt: tools.some((t) => t.name === "spawn") ? plannerPromptText : null,
636
+ webSearch: tools.some((t) => t.name === "web_search"),
628
637
  workspace,
629
638
  ...(rollout ? {} : { wikisDir: deps.paths.wikis }),
630
639
  skillIndex: formatSkillIndex(deps.skills),
@@ -13,7 +13,7 @@ const SpawnTaskSchema = Type.Object({
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
15
  mode: Type.Optional(Type.Union([Type.Literal("explore"), Type.Literal("work")], {
16
- description: '"explore": read-only research (read, web_fetch, 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.',
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
17
  })),
18
18
  });
19
19
  const SpawnParams = Type.Object({ tasks: Type.Array(SpawnTaskSchema, { minItems: 1 }) });
@@ -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",
@@ -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" }
@@ -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.4.0",
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
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);
@@ -83,6 +85,30 @@ export function createNexo(options = {}) {
83
85
  doctor() {
84
86
  return runDoctor({ paths: runtime.paths, settings: runtime.settings, env, cwd });
85
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
+ },
86
112
  async close() {
87
113
  if (closed)
88
114
  return;
@@ -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 } : {}) };
@@ -270,7 +270,7 @@ export function createBuiltinTools(ctx) {
270
270
  const webFetch = {
271
271
  name: "web_fetch",
272
272
  label: "Fetch URL",
273
- 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.`,
274
274
  parameters: FetchParams,
275
275
  execute: async (_id, params, signal) => {
276
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/index.js CHANGED
@@ -2,4 +2,4 @@ export { restoreTerminal, runInteractive, runSettingsScreen } from "./app.js";
2
2
  export { createApprovalPrompter } from "./approvals.js";
3
3
  export { runSessionPicker, sessionPickerItems } from "./session-picker.js";
4
4
  export { helpText, parseSlashCommand, SLASH_COMMANDS } from "./commands.js";
5
- export { escapeControl, oneLine } from "./text.js";
5
+ export { escapeControl, escapeControlKeepLines, oneLine } from "./text.js";
@@ -1,6 +1,7 @@
1
1
  import { Input, truncateToWidth } from "@earendil-works/pi-tui";
2
2
  import { keyStatusLabel, ON_OFF } from "../../core/src/index.js";
3
3
  import { toErrorPayload } from "../../telemetry/src/index.js";
4
+ import { isSearchProvider, SEARCH_PROVIDERS } from "../../tools/src/index.js";
4
5
  import { fitLines, MaskedInput } from "./components.js";
5
6
  import { PickerView } from "./picker.js";
6
7
  import { escapeControl, formatError } from "./text.js";
@@ -98,7 +99,11 @@ export class SettingsScreen {
98
99
  this.setError(error);
99
100
  }
100
101
  const items = [
101
- ...keys.map((k) => ({ value: `key:${k.provider}`, label: `${escapeControl(k.provider)} key`, description: escapeControl(keyStatusLabel(k)) })),
102
+ ...keys.map((k) => ({
103
+ value: `key:${k.provider}`,
104
+ label: `${escapeControl(k.provider)} key${k.purpose === "search" ? " (web search)" : ""}`,
105
+ description: escapeControl(keyStatusLabel(k)),
106
+ })),
102
107
  ...views.map((v) => ({ value: `set:${v.key}`, label: escapeControl(v.label), description: settingDescription(v) })),
103
108
  ];
104
109
  return new PickerView({
@@ -129,7 +134,8 @@ export class SettingsScreen {
129
134
  this.setError(error);
130
135
  return this.menuView();
131
136
  }
132
- const items = [{ value: "set", label: "Set key", description: "masked entry; stored in credentials.json (mode 600)" }];
137
+ const signup = isSearchProvider(provider) ? `; get one at ${SEARCH_PROVIDERS[provider].signupUrl}` : "";
138
+ const items = [{ value: "set", label: "Set key", description: `masked entry; stored in credentials.json (mode 600)${signup}` }];
133
139
  if (status.inFile)
134
140
  items.push({ value: "remove", label: "Remove key", description: "delete it from credentials.json" });
135
141
  items.push({ value: BACK, label: "Back" });
package/tui/src/text.js CHANGED
@@ -19,7 +19,7 @@ export function oneLine(text, max) {
19
19
  const flat = text.replace(/\s+/g, " ").trim();
20
20
  return flat.length > max ? `${flat.slice(0, Math.max(0, max - 1))}…` : flat;
21
21
  }
22
- const SUBJECT_KEY = { bash: "command", read: "path", write: "path", edit: "path", web_fetch: "url", load_skill: "name" };
22
+ const SUBJECT_KEY = { bash: "command", read: "path", write: "path", edit: "path", web_fetch: "url", web_search: "query", load_skill: "name" };
23
23
  /** `tool(args)` summary: the tool's subject argument when it has one, otherwise compact JSON; control-escaped. */
24
24
  export function toolSummary(toolName, args, max = 80) {
25
25
  let subject;