@hexdecimal16/nexo 0.3.5 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -0
- package/cli/src/common.js +6 -1
- package/cli/src/main.js +12 -0
- package/cli/src/review-queue.js +31 -0
- package/cli/src/search.js +50 -0
- package/cli/src/settings.js +20 -1
- package/core/src/config/schema.js +12 -2
- package/core/src/engine/context-trim.js +26 -0
- package/core/src/engine/prompts.js +5 -0
- package/core/src/engine/run.js +68 -2
- package/core/src/engine/spawn-tool.js +5 -1
- package/core/src/optimize/holdout-gate.js +19 -0
- package/core/src/optimize/optimize.js +13 -2
- package/core/src/optimize/reflect.js +1 -1
- package/core/src/settings/config-edit.js +31 -0
- package/core/src/settings/doctor.js +15 -2
- package/core/src/settings/settings.js +29 -10
- package/package.json +1 -1
- package/sdk/src/nexo.js +33 -3
- package/sdk/src/run-tree.js +6 -0
- package/sdk/src/runtime.js +2 -1
- package/store/src/index.js +1 -0
- package/store/src/review-queue.js +46 -0
- package/tools/src/builtin.js +13 -3
- 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/app.js +22 -1
- package/tui/src/commands.js +1 -0
- package/tui/src/index.js +1 -1
- package/tui/src/settings-screen.js +8 -2
- package/tui/src/text.js +1 -1
- package/web/public/lib/api-types.ts +18 -0
- package/web/public/lib/run-view.ts +19 -1
- package/web/public/pages/run.ts +3 -1
- package/web/public/run.html +2 -1
- package/web/src/api.js +32 -0
- package/web/src/review-queue-api.js +18 -0
- package/web/src/server.js +7 -0
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { findEnvKeys, getEnvApiKey } from "@earendil-works/pi-ai/compat";
|
|
2
|
+
import { isSearchProvider, SEARCH_PROVIDER_IDS, SEARCH_PROVIDERS } from "../../../tools/src/index.js";
|
|
2
3
|
import { createMutableRedactor, createRedactor, createSecretSet, containsSecret, MIN_SECRET_LENGTH, NexoError, toErrorPayload, } from "../../../telemetry/src/index.js";
|
|
3
4
|
import { configErrors, deepMerge, loadConfig } from "../config/load.js";
|
|
4
5
|
import { EDITABLE_SETTINGS, findSetting, mergedLayers, parseSettingInput, readConfigLayers, resetSetting, settingView, writeSetting, } from "./config-edit.js";
|
|
@@ -42,6 +43,8 @@ function configuredProviders(merged) {
|
|
|
42
43
|
return out;
|
|
43
44
|
}
|
|
44
45
|
export function keyStatusLabel(status) {
|
|
46
|
+
if (status.state === "option")
|
|
47
|
+
return "set (passed in code)";
|
|
45
48
|
if (status.state === "env")
|
|
46
49
|
return "set (env)";
|
|
47
50
|
if (status.state === "file")
|
|
@@ -51,6 +54,10 @@ export function keyStatusLabel(status) {
|
|
|
51
54
|
export function createSettings(options) {
|
|
52
55
|
const { paths, cwd } = options;
|
|
53
56
|
const env = providerEnv(options.env ?? process.env);
|
|
57
|
+
const optionKeys = new Map();
|
|
58
|
+
for (const [provider, value] of Object.entries(options.apiKeys ?? {}))
|
|
59
|
+
if (typeof value === "string" && value.trim() !== "")
|
|
60
|
+
optionKeys.set(provider, value.trim());
|
|
54
61
|
const secrets = createSecretSet();
|
|
55
62
|
let patterns = [];
|
|
56
63
|
const redact = createMutableRedactor(createRedactor(patterns, { secrets }));
|
|
@@ -84,10 +91,16 @@ export function createSettings(options) {
|
|
|
84
91
|
registerSecret(provider, "file", entry.apiKey);
|
|
85
92
|
};
|
|
86
93
|
const envKey = (provider) => {
|
|
87
|
-
const value = getEnvApiKey(provider, env)?.trim();
|
|
94
|
+
const value = (isSearchProvider(provider) ? env[SEARCH_PROVIDERS[provider].envVar] : getEnvApiKey(provider, env))?.trim();
|
|
88
95
|
return value ? value : undefined;
|
|
89
96
|
};
|
|
97
|
+
const envVarOf = (provider) => (isSearchProvider(provider) ? SEARCH_PROVIDERS[provider].envVar : (findEnvKeys(provider, env)?.[0] ?? null));
|
|
90
98
|
const resolveApiKey = (provider) => {
|
|
99
|
+
const fromOption = optionKeys.get(provider);
|
|
100
|
+
if (fromOption !== undefined) {
|
|
101
|
+
registerSecret(provider, "option", fromOption);
|
|
102
|
+
return fromOption;
|
|
103
|
+
}
|
|
91
104
|
const fromEnv = envKey(provider);
|
|
92
105
|
if (fromEnv !== undefined) {
|
|
93
106
|
if (fromEnv === AMBIENT_CREDENTIALS)
|
|
@@ -111,9 +124,9 @@ export function createSettings(options) {
|
|
|
111
124
|
*/
|
|
112
125
|
const validateProvider = (provider, strict) => {
|
|
113
126
|
const known = !containsSecret(provider) &&
|
|
114
|
-
(options.models?.getProvider(provider) !== undefined || configured().includes(provider) || (!strict && provider in credentials));
|
|
127
|
+
(options.models?.getProvider(provider) !== undefined || isSearchProvider(provider) || configured().includes(provider) || (!strict && provider in credentials));
|
|
115
128
|
if (!known) {
|
|
116
|
-
const ids = [...new Set([...(options.models?.getProviders().map((p) => p.id) ?? []), ...configured()])].sort();
|
|
129
|
+
const ids = [...new Set([...(options.models?.getProviders().map((p) => p.id) ?? []), ...configured(), ...SEARCH_PROVIDER_IDS])].sort();
|
|
117
130
|
throw invalidRequest("Unknown provider: not in the model registry or the nexo config", ids.length > 0 ? `Use a provider id such as ${ids.slice(0, 12).join(", ")}${ids.length > 12 ? ", …" : ""}` : "Configure models.s1/models.s2 first");
|
|
118
131
|
}
|
|
119
132
|
};
|
|
@@ -121,14 +134,17 @@ export function createSettings(options) {
|
|
|
121
134
|
const keyStatus = (provider) => {
|
|
122
135
|
const stored = credentials[provider];
|
|
123
136
|
const inFile = stored !== undefined;
|
|
137
|
+
const purpose = isSearchProvider(provider) ? "search" : "model";
|
|
138
|
+
if (optionKeys.has(provider))
|
|
139
|
+
return { provider, purpose, state: "option", envVar: null, last4: null, inFile };
|
|
124
140
|
// claude-p and kiro-p run a local CLI that brings its own login: ambient credentials, like AWS or Google ADC.
|
|
125
141
|
if (provider === CLAUDE_P_PROVIDER || provider === KIRO_P_PROVIDER)
|
|
126
|
-
return { provider, state: "env", envVar: null, last4: null, inFile };
|
|
142
|
+
return { provider, purpose, state: "env", envVar: null, last4: null, inFile };
|
|
127
143
|
if (envKey(provider) !== undefined)
|
|
128
|
-
return { provider, state: "env", envVar:
|
|
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
package/sdk/src/nexo.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { createSession, createSettings, nexoModels, resumeSession, runDoctor, } from "../../core/src/index.js";
|
|
2
|
-
import { resolveNexoPaths } from "../../store/src/index.js";
|
|
2
|
+
import { resolveNexoPaths, reviewQueue } from "../../store/src/index.js";
|
|
3
3
|
import { NexoError } from "../../telemetry/src/index.js";
|
|
4
|
-
import { nonInteractivePrompter } from "../../tools/src/index.js";
|
|
4
|
+
import { nonInteractivePrompter, SEARCH_PROVIDER_IDS, webSearch } from "../../tools/src/index.js";
|
|
5
5
|
import { createRuntime } from "./runtime.js";
|
|
6
6
|
function withHome(options) {
|
|
7
7
|
const env = options.env ?? process.env;
|
|
@@ -15,7 +15,7 @@ export function checkSetup(options = {}) {
|
|
|
15
15
|
const env = withHome(options);
|
|
16
16
|
const cwd = options.cwd ?? process.cwd();
|
|
17
17
|
const paths = resolveNexoPaths(env);
|
|
18
|
-
const settings = createSettings({ paths, cwd, env, models: options.models ?? nexoModels() });
|
|
18
|
+
const settings = createSettings({ paths, cwd, env, models: options.models ?? nexoModels(), apiKeys: options.apiKeys });
|
|
19
19
|
return runDoctor({ paths, settings, env, cwd });
|
|
20
20
|
}
|
|
21
21
|
/** Builds the runtime and returns the programmatic entry point. Throws CONFIG_INVALID when the config is not usable. */
|
|
@@ -30,6 +30,8 @@ export function createNexo(options = {}) {
|
|
|
30
30
|
prompter,
|
|
31
31
|
models: options.models,
|
|
32
32
|
overrides: options.config,
|
|
33
|
+
apiKeys: options.apiKeys,
|
|
34
|
+
...(options.fetch ? { fetch: options.fetch } : {}),
|
|
33
35
|
onEvent: (event) => {
|
|
34
36
|
for (const listener of [...listeners])
|
|
35
37
|
listener(event);
|
|
@@ -76,9 +78,37 @@ export function createNexo(options = {}) {
|
|
|
76
78
|
live();
|
|
77
79
|
return resumeSession(sessionDeps(), id);
|
|
78
80
|
},
|
|
81
|
+
reviewQueue(queueOptions) {
|
|
82
|
+
live();
|
|
83
|
+
return reviewQueue(runtime.db, queueOptions);
|
|
84
|
+
},
|
|
79
85
|
doctor() {
|
|
80
86
|
return runDoctor({ paths: runtime.paths, settings: runtime.settings, env, cwd });
|
|
81
87
|
},
|
|
88
|
+
async webSearch(query, searchOptions = {}) {
|
|
89
|
+
live();
|
|
90
|
+
const keys = Object.fromEntries(SEARCH_PROVIDER_IDS.map((id) => [id, runtime.settings.resolveApiKey(id)]));
|
|
91
|
+
try {
|
|
92
|
+
return await webSearch(query, { keys, count: searchOptions.count ?? runtime.config.tools.webSearch.count, ...(options.fetch ? { fetch: options.fetch } : {}) }, searchOptions.signal);
|
|
93
|
+
}
|
|
94
|
+
catch (error) {
|
|
95
|
+
if (searchOptions.signal?.aborted || error instanceof NexoError)
|
|
96
|
+
throw error;
|
|
97
|
+
// An empty query or no key: the message names `nexo settings set-key` and the environment variables.
|
|
98
|
+
throw new NexoError({ code: "INVALID_REQUEST", message: error instanceof Error ? error.message : String(error), hint: "Pass apiKeys: { brave: \"…\" } or { tavily: \"…\" } to createNexo, or call setKey" });
|
|
99
|
+
}
|
|
100
|
+
},
|
|
101
|
+
keys() {
|
|
102
|
+
return runtime.settings.keyProviders();
|
|
103
|
+
},
|
|
104
|
+
setKey(provider, apiKey) {
|
|
105
|
+
live();
|
|
106
|
+
return runtime.settings.setKey(provider, apiKey);
|
|
107
|
+
},
|
|
108
|
+
removeKey(provider) {
|
|
109
|
+
live();
|
|
110
|
+
return runtime.settings.removeKey(provider);
|
|
111
|
+
},
|
|
82
112
|
async close() {
|
|
83
113
|
if (closed)
|
|
84
114
|
return;
|
package/sdk/src/run-tree.js
CHANGED
|
@@ -27,6 +27,7 @@ export function trackRunTree(onChange) {
|
|
|
27
27
|
status: "running",
|
|
28
28
|
costUsd: 0,
|
|
29
29
|
toolCalls: 0,
|
|
30
|
+
loopGuards: 0,
|
|
30
31
|
currentTool: null,
|
|
31
32
|
error: null,
|
|
32
33
|
startedAt: Date.now(),
|
|
@@ -48,6 +49,11 @@ export function trackRunTree(onChange) {
|
|
|
48
49
|
n.currentTool = event.toolName;
|
|
49
50
|
});
|
|
50
51
|
break;
|
|
52
|
+
case "loop_guard":
|
|
53
|
+
update(event.runId, (n) => {
|
|
54
|
+
n.loopGuards++;
|
|
55
|
+
});
|
|
56
|
+
break;
|
|
51
57
|
case "tool_end":
|
|
52
58
|
update(event.runId, (n) => {
|
|
53
59
|
n.currentTool = null;
|
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/store/src/index.js
CHANGED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
export const DEFAULT_REVIEW_QUEUE_SIZE = 15;
|
|
2
|
+
const LOW_SCORE = 0.6;
|
|
3
|
+
/**
|
|
4
|
+
* Recent finished root runs that have no human verdict, worst first: failed, over-budget and aborted runs, then low
|
|
5
|
+
* scores, then unscored runs, then the rest by cost. A person reviews the head of this list each week and labels it.
|
|
6
|
+
*/
|
|
7
|
+
export function reviewQueue(db, options = {}) {
|
|
8
|
+
const limit = Math.max(1, Math.min(100, options.limit ?? DEFAULT_REVIEW_QUEUE_SIZE));
|
|
9
|
+
const since = new Date((options.now ?? new Date()).getTime() - (options.days ?? 7) * 86_400_000).toISOString();
|
|
10
|
+
const rows = db
|
|
11
|
+
.prepare(`SELECT r.id, r.instruction, r.status, r.started_at, r.cost_usd, r.error_json,
|
|
12
|
+
(SELECT AVG(s.value) FROM scores s WHERE s.run_id = r.id AND s.status = 'ok' AND s.round = (SELECT MAX(s2.round) FROM scores s2 WHERE s2.run_id = r.id)) AS score
|
|
13
|
+
FROM runs r
|
|
14
|
+
WHERE r.parent_run_id IS NULL AND r.status != 'running' AND r.started_at >= ?
|
|
15
|
+
AND NOT EXISTS (SELECT 1 FROM feedback f WHERE f.run_id = r.id)`)
|
|
16
|
+
.all(since);
|
|
17
|
+
const items = rows.map((row) => {
|
|
18
|
+
const status = String(row.status);
|
|
19
|
+
const score = row.score === null ? null : Number(row.score);
|
|
20
|
+
const failureMode = status === "failed" || status === "budget_exceeded" || status === "aborted" ? status : score === null ? "unscored" : score < LOW_SCORE ? "low_score" : "ok";
|
|
21
|
+
let errorCode = null;
|
|
22
|
+
if (typeof row.error_json === "string") {
|
|
23
|
+
try {
|
|
24
|
+
const code = JSON.parse(row.error_json).code;
|
|
25
|
+
errorCode = typeof code === "string" ? code : null;
|
|
26
|
+
}
|
|
27
|
+
catch {
|
|
28
|
+
errorCode = null;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
const first = String(row.instruction).split("\n")[0] ?? "";
|
|
32
|
+
return {
|
|
33
|
+
runId: String(row.id),
|
|
34
|
+
instruction: first.length > 120 ? `${first.slice(0, 119)}…` : first,
|
|
35
|
+
status,
|
|
36
|
+
failureMode,
|
|
37
|
+
errorCode,
|
|
38
|
+
score,
|
|
39
|
+
costUsd: Number(row.cost_usd),
|
|
40
|
+
startedAt: String(row.started_at),
|
|
41
|
+
};
|
|
42
|
+
});
|
|
43
|
+
const rank = { failed: 0, budget_exceeded: 1, aborted: 2, low_score: 3, unscored: 4, ok: 5 };
|
|
44
|
+
items.sort((a, b) => rank[a.failureMode] - rank[b.failureMode] || (a.score ?? 1) - (b.score ?? 1) || b.costUsd - a.costUsd || b.startedAt.localeCompare(a.startedAt));
|
|
45
|
+
return items.slice(0, limit);
|
|
46
|
+
}
|
package/tools/src/builtin.js
CHANGED
|
@@ -43,6 +43,16 @@ function ensureExitHandler() {
|
|
|
43
43
|
exitHandlerRegistered = true;
|
|
44
44
|
process.on("exit", killLiveBashGroups);
|
|
45
45
|
}
|
|
46
|
+
const SECRET_ENV_NAME = /(^|_)(API_?KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIALS?|PRIVATE_KEY|ACCESS_KEY|SESSION_KEY)(_|$)|^(AWS|AZURE|GCP|GOOGLE|OPENAI|ANTHROPIC|GITHUB|GH|NPM|SSH_AUTH)_.*(KEY|TOKEN|SECRET|SOCK)/i;
|
|
47
|
+
/** The process environment without variables whose names look like secrets (API keys, tokens, passwords), for commands the agent runs. */
|
|
48
|
+
export function bashEnv(source = process.env) {
|
|
49
|
+
const out = {};
|
|
50
|
+
for (const [name, value] of Object.entries(source)) {
|
|
51
|
+
if (value !== undefined && !SECRET_ENV_NAME.test(name))
|
|
52
|
+
out[name] = value;
|
|
53
|
+
}
|
|
54
|
+
return out;
|
|
55
|
+
}
|
|
46
56
|
/** Runs `command` with `bash -c` in its own process group, killed on timeout, abort or host exit. Never rejects. */
|
|
47
57
|
export function runBash(run) {
|
|
48
58
|
const { signal } = run;
|
|
@@ -239,11 +249,11 @@ export function createBuiltinTools(ctx) {
|
|
|
239
249
|
const bash = {
|
|
240
250
|
name: "bash",
|
|
241
251
|
label: "Run command",
|
|
242
|
-
description: "Run a bash command in the workspace directory.",
|
|
252
|
+
description: "Run a bash command in the workspace directory (bash -c, no TTY, no stdin). Returns `exit code: N` followed by combined stdout and stderr; output beyond the limit is truncated, so filter with grep, head or tail. Chain related steps with && in one call. A command that may outlive the timeout belongs in the background: nohup <command> > job.log 2>&1 &, then poll job.log. Pass timeoutMs to raise the default. The environment is filtered, so secrets such as API keys are not available.",
|
|
243
253
|
parameters: BashParams,
|
|
244
254
|
execute: async (_id, params, signal) => {
|
|
245
255
|
const timeoutMs = params.timeoutMs ?? ctx.bashTimeoutMs;
|
|
246
|
-
const r = await runBash({ command: params.command, cwd: root, timeoutMs, signal });
|
|
256
|
+
const r = await runBash({ command: params.command, cwd: root, timeoutMs, signal, env: bashEnv() });
|
|
247
257
|
const body = `${r.output}${r.truncated ? "\n[output truncated]" : ""}`;
|
|
248
258
|
switch (r.ended) {
|
|
249
259
|
case "failed":
|
|
@@ -260,7 +270,7 @@ export function createBuiltinTools(ctx) {
|
|
|
260
270
|
const webFetch = {
|
|
261
271
|
name: "web_fetch",
|
|
262
272
|
label: "Fetch URL",
|
|
263
|
-
description: `Fetch an http(s) URL and return readable text. HTML pages are converted to plain text with links kept as [text](url); scripts, styles, navigation and footers are dropped. Markdown is requested first, so sites that serve it return it unchanged. Output is capped at ${MAX_FETCH_CHARS} characters. Binary files are refused. If a site blocks the fetch (for example a Cloudflare challenge), load the browser skill and read the page there.`,
|
|
273
|
+
description: `Fetch an http(s) URL and return readable text. To find URLs, use web_search when it is available. HTML pages are converted to plain text with links kept as [text](url); scripts, styles, navigation and footers are dropped. Markdown is requested first, so sites that serve it return it unchanged. Output is capped at ${MAX_FETCH_CHARS} characters. Binary files are refused. If a site blocks the fetch (for example a Cloudflare challenge), load the browser skill and read the page there.`,
|
|
264
274
|
parameters: FetchParams,
|
|
265
275
|
execute: async (_id, params, signal) => {
|
|
266
276
|
const url = new URL(params.url);
|
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
import { tmpdir } from "node:os";
|
|
2
2
|
import { createBuiltinTools } from "./builtin.js";
|
|
3
3
|
import { FileLeases } from "./leases.js";
|
|
4
|
+
import { WEB_SEARCH_DESCRIPTION } from "./web-search.js";
|
|
4
5
|
/**
|
|
5
6
|
* The built-in tools' own descriptions by tool name: the text an optimization of `tool:<name>` starts from and a run
|
|
6
7
|
* uses when no promoted or candidate description replaces it. Read from the tools themselves, so there is one copy.
|
|
7
8
|
*/
|
|
8
9
|
export function builtinToolDescriptions() {
|
|
9
10
|
const tools = createBuiltinTools({ workspaceRoot: tmpdir(), holder: "descriptions", leases: new FileLeases(), bashTimeoutMs: 1 });
|
|
10
|
-
return Object.fromEntries(tools.map((t) => [t.name, t.description]));
|
|
11
|
+
return { ...Object.fromEntries(tools.map((t) => [t.name, t.description])), web_search: WEB_SEARCH_DESCRIPTION };
|
|
11
12
|
}
|
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/app.js
CHANGED
|
@@ -2,7 +2,7 @@ import { homedir } from "node:os";
|
|
|
2
2
|
import { sep } from "node:path";
|
|
3
3
|
import { CombinedAutocompleteProvider, Container, Editor, isKeyRelease, isKeyRepeat, Loader, matchesKey, ProcessTerminal, setCapabilityOverrides, TuiMainScreen, } from "@earendil-works/pi-tui";
|
|
4
4
|
import { listSessions, projectRoots } from "../../core/src/index.js";
|
|
5
|
-
import { getSessionRow, sessionNotFound } from "../../store/src/index.js";
|
|
5
|
+
import { getSessionRow, reviewQueue, sessionNotFound } from "../../store/src/index.js";
|
|
6
6
|
import { toErrorPayload } from "../../telemetry/src/index.js";
|
|
7
7
|
import { describeSessionRule } from "../../tools/src/index.js";
|
|
8
8
|
import { createApprovalPrompter } from "./approvals.js";
|
|
@@ -643,6 +643,20 @@ class InteractiveApp {
|
|
|
643
643
|
this.chat.addChild(new Block(`score ${escapeControl(oneLine(event.scorer, 60))}: ${scoreVerdict(event)}`, style.gray, " "));
|
|
644
644
|
break;
|
|
645
645
|
}
|
|
646
|
+
case "loop_guard": {
|
|
647
|
+
this.currentText = null;
|
|
648
|
+
const what = event.kind === "max_tool_calls"
|
|
649
|
+
? `tool-call cap reached (loop.maxToolCalls ${event.limit}); the agent was asked to report`
|
|
650
|
+
: `blocked ${escapeControl(oneLine(event.toolName, 40))}: ${event.count} identical calls in a row (loop.repeatLimit ${event.limit})`;
|
|
651
|
+
this.chat.addChild(new Block(`⚠ ${what}`, style.yellow, " "));
|
|
652
|
+
break;
|
|
653
|
+
}
|
|
654
|
+
case "context_trim":
|
|
655
|
+
if (event.depth !== 0)
|
|
656
|
+
return;
|
|
657
|
+
this.currentText = null;
|
|
658
|
+
this.chat.addChild(new Block(`context nearly full: cleared ${event.cleared} old tool outputs (~${event.tokensBefore} → ~${event.tokensAfter} tokens)`, style.gray, " "));
|
|
659
|
+
break;
|
|
646
660
|
case "compaction_start":
|
|
647
661
|
this.currentText = null;
|
|
648
662
|
this.chat.addChild(new Block("compacting earlier turns…", style.gray, " "));
|
|
@@ -769,6 +783,13 @@ class InteractiveApp {
|
|
|
769
783
|
this.say("── conversation cleared ── (same session; earlier turns stay in its history)");
|
|
770
784
|
this.tui.requestRender(true);
|
|
771
785
|
break;
|
|
786
|
+
case "queue": {
|
|
787
|
+
const items = reviewQueue(this.options.db, { limit: 10 });
|
|
788
|
+
this.say(items.length === 0
|
|
789
|
+
? "no unreviewed runs in the last 7 days"
|
|
790
|
+
: items.map((i) => `${i.runId.slice(-6)} ${i.failureMode} ${i.score === null ? "–" : i.score.toFixed(2)} ${escapeControl(i.instruction)}`).join("\n"));
|
|
791
|
+
break;
|
|
792
|
+
}
|
|
772
793
|
case "sessions":
|
|
773
794
|
this.say(this.sessionsText(session));
|
|
774
795
|
break;
|
package/tui/src/commands.js
CHANGED
|
@@ -17,6 +17,7 @@ export const SLASH_COMMANDS = [
|
|
|
17
17
|
{ name: "done", description: "Mark the last turn done" },
|
|
18
18
|
{ name: "notdone", description: "Mark the last turn not done", argumentHint: "[comment]" },
|
|
19
19
|
{ name: "cost", description: "Show the session's cost and budget" },
|
|
20
|
+
{ name: "queue", description: "List recent runs without a verdict, worst first" },
|
|
20
21
|
{ name: "budget", description: "Set this session's budget cap", argumentHint: "<usd>" },
|
|
21
22
|
{ name: "model", description: "Set this session's model (default clears it)", argumentHint: "<s1|s2|provider/id|default>", getArgumentCompletions: items(["s1", "s2", "default"]) },
|
|
22
23
|
{ name: "effort", description: "Set this session's effort (default clears it)", argumentHint: "<level|default>", getArgumentCompletions: items([...EFFORTS, "default"]) },
|