@hexdecimal16/nexo 0.4.0 → 0.4.2
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 +15 -0
- package/cli/src/common.js +5 -1
- package/cli/src/main.js +3 -0
- package/cli/src/search.js +50 -0
- package/cli/src/settings.js +20 -1
- package/core/src/config/schema.js +4 -1
- package/core/src/engine/prompts.js +4 -0
- package/core/src/engine/run.js +11 -2
- package/core/src/engine/spawn-tool.js +1 -1
- package/core/src/settings/config-edit.js +7 -0
- package/core/src/settings/doctor.js +15 -2
- package/core/src/settings/settings.js +29 -10
- package/package.json +3 -3
- package/sdk/src/nexo.js +28 -2
- package/sdk/src/runtime.js +2 -1
- package/tools/src/builtin.js +1 -1
- package/tools/src/descriptions.js +2 -1
- package/tools/src/index.js +1 -0
- package/tools/src/policy.js +1 -1
- package/tools/src/web-search.js +251 -0
- package/tui/src/index.js +1 -1
- package/tui/src/settings-screen.js +8 -2
- package/tui/src/text.js +1 -1
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
|
+
}
|
package/cli/src/settings.js
CHANGED
|
@@ -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
|
|
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)
|
package/core/src/engine/run.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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:
|
|
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.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"description": "nexo agent engine",
|
|
5
5
|
"license": "PolyForm-Noncommercial-1.0.0",
|
|
6
6
|
"repository": {
|
|
@@ -36,8 +36,8 @@
|
|
|
36
36
|
"node": ">=22.19.0"
|
|
37
37
|
},
|
|
38
38
|
"dependencies": {
|
|
39
|
-
"@earendil-works/pi-agent-core": "1.
|
|
40
|
-
"@earendil-works/pi-ai": "1.
|
|
39
|
+
"@earendil-works/pi-agent-core": "1.5.0",
|
|
40
|
+
"@earendil-works/pi-ai": "1.5.0",
|
|
41
41
|
"@earendil-works/pi-tui": "1.1.0",
|
|
42
42
|
"@google/genai": "2.21.0",
|
|
43
43
|
"@modelcontextprotocol/sdk": "1.31.0",
|
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;
|
package/sdk/src/runtime.js
CHANGED
|
@@ -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 } : {}) };
|
package/tools/src/builtin.js
CHANGED
|
@@ -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
|
}
|
package/tools/src/index.js
CHANGED
package/tools/src/policy.js
CHANGED
|
@@ -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) => ({
|
|
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
|
|
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;
|