@hexdecimal16/nexo 0.4.3 → 0.4.4
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 +38 -34
- package/cli/src/common.js +2 -2
- package/cli/src/interactive.js +9 -3
- package/cli/src/main.js +2 -0
- package/core/src/engine/run.js +3 -1
- package/core/src/session/session.js +10 -0
- package/package.json +1 -1
- package/sdk/src/index.js +1 -0
- package/sdk/src/nexo.js +3 -2
- package/tools/src/policy.js +3 -0
- package/tui/src/app.js +14 -1
- package/tui/src/commands.js +1 -0
package/README.md
CHANGED
|
@@ -3,60 +3,60 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/@hexdecimal16/nexo)
|
|
4
4
|
[](https://github.com/hexdecimal16/nexo/actions/workflows/test.yml)
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
nexo is an AI agent that runs on your machine. It tracks what each run costs, scores the results, and keeps every run inspectable. You can use it from the terminal, from a web run inspector, or from Node code.
|
|
7
7
|
|
|
8
8
|
Requires Node 22.19 or newer.
|
|
9
9
|
|
|
10
10
|
## Install
|
|
11
11
|
|
|
12
|
-
From npm:
|
|
13
|
-
|
|
14
12
|
```sh
|
|
15
13
|
npm install -g @hexdecimal16/nexo
|
|
14
|
+
nexo init # pick two models (s1, s2), store their API keys, make one test call
|
|
16
15
|
```
|
|
17
16
|
|
|
18
|
-
|
|
17
|
+
Running `nexo` for the first time also opens this setup. `nexo update` tells you when a newer version is out.
|
|
18
|
+
|
|
19
|
+
## Everyday use
|
|
19
20
|
|
|
20
21
|
```sh
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
22
|
+
nexo # chat; type /settings to change anything
|
|
23
|
+
nexo run "summarize this folder" --budget 0.25 # one task, then exit
|
|
24
|
+
nexo ui # run inspector: traces, costs, scores
|
|
25
|
+
nexo cost --by day # what you spent
|
|
26
|
+
nexo doctor # check Node, config, keys and tools
|
|
25
27
|
```
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
`nexo --help` lists every command. Data lives in `~/.nexo`. Set `NEXO_HOME` to move it.
|
|
28
30
|
|
|
29
|
-
|
|
30
|
-
npm run build
|
|
31
|
-
(cd dist && npm pack --pack-destination /tmp) && npm install -g /tmp/nexo-*.tgz
|
|
32
|
-
```
|
|
31
|
+
## Settings and keys
|
|
33
32
|
|
|
34
|
-
|
|
33
|
+
Every option is in `/settings` inside a chat, or in `nexo settings` from the shell:
|
|
35
34
|
|
|
36
35
|
```sh
|
|
37
|
-
nexo
|
|
38
|
-
nexo
|
|
39
|
-
nexo
|
|
40
|
-
nexo run "summarize this folder" --budget 0.25
|
|
41
|
-
nexo ui # open the run inspector (traces, costs, scores)
|
|
36
|
+
nexo settings keys # which keys are set and where from (never the values)
|
|
37
|
+
nexo settings set-key anthropic # hidden prompt, or pipe the key on stdin
|
|
38
|
+
nexo settings set budgets.perRunUsd 0.5
|
|
42
39
|
```
|
|
43
40
|
|
|
44
|
-
|
|
41
|
+
Keys are stored in `~/.nexo/credentials.json` (mode 600) and redacted from logs. A provider's environment variable, such as `ANTHROPIC_API_KEY`, takes precedence over the stored key.
|
|
45
42
|
|
|
46
|
-
|
|
43
|
+
## Optional tools
|
|
47
44
|
|
|
48
|
-
|
|
45
|
+
**Web search.** Set a [Brave Search](https://api-dashboard.search.brave.com) or [Tavily](https://app.tavily.com) key and the agent gets a `web_search` tool. With both keys, it queries both and merges the results.
|
|
49
46
|
|
|
50
|
-
|
|
47
|
+
```sh
|
|
48
|
+
nexo settings set-key brave # or tavily
|
|
49
|
+
nexo search "node 22 release notes" # try it without a model
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**Browser control.** The agent can drive your own Chrome, with your signed-in sites, through [playwright-cli](https://github.com/microsoft/playwright-cli) and the Playwright Extension. It keeps page snapshots on disk and reads only the lines it needs, so browsing uses few tokens.
|
|
51
53
|
|
|
52
54
|
```sh
|
|
53
|
-
|
|
54
|
-
nexo settings
|
|
55
|
-
nexo search "node 22 release notes" # try it without a model (--count <n>, --json)
|
|
56
|
-
nexo settings set tools.webSearch.count 10
|
|
55
|
+
npm install -g @playwright/cli@latest
|
|
56
|
+
nexo settings set-key playwright-personal # paste the token from the Playwright Extension in that Chrome profile
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
`
|
|
59
|
+
Add one key per Chrome profile, such as `playwright-work`. First-run setup and `/settings` offer the same step. The browser skill tells the agent to ask before sending, posting, buying or deleting anything. Its wrapper also blocks the commands that run arbitrary code in your pages.
|
|
60
60
|
|
|
61
61
|
## Use it from Node
|
|
62
62
|
|
|
@@ -72,21 +72,25 @@ try {
|
|
|
72
72
|
}
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
The SDK denies every tool approval by default, so a backend never waits on a person.
|
|
75
|
+
- Pass keys in code without writing them to disk: `createNexo({ apiKeys: { anthropic: "…" } })`.
|
|
76
|
+
- `nexo.keys()`, `nexo.setKey()` and `nexo.removeKey()` manage stored keys. `nexo.webSearch(query)` searches without a model.
|
|
77
|
+
- The SDK denies every tool approval by default, so a backend never waits on a person. Pass `allowAll: true` to `createNexo` or `run` to auto-approve tool actions in sandboxed environments. Always pass `budgetUsd`.
|
|
78
|
+
- `checkSetup()` runs the doctor checks without starting the engine, for a start-up pre-flight.
|
|
78
79
|
|
|
79
80
|
## Security
|
|
80
81
|
|
|
81
|
-
nexo tools run shell commands and edit files. Path confinement is not a sandbox. If you run nexo for other people, give each request its own workspace and use a container for real isolation.
|
|
82
|
+
nexo's tools run shell commands and edit files. Path confinement is not a sandbox. If you run nexo for other people, give each request its own workspace and use a container for real isolation.
|
|
82
83
|
|
|
83
84
|
## Develop
|
|
84
85
|
|
|
85
86
|
```sh
|
|
87
|
+
git clone https://github.com/hexdecimal16/nexo.git && cd nexo
|
|
88
|
+
npm ci
|
|
89
|
+
npm run nexo -- init # run from source
|
|
86
90
|
npm run typecheck
|
|
87
91
|
npm test
|
|
88
|
-
npm run build
|
|
89
|
-
npm run bump --
|
|
92
|
+
npm run build # release build into dist/
|
|
93
|
+
npm run bump -- patch # set one version on every package
|
|
90
94
|
```
|
|
91
95
|
|
|
92
96
|
## License
|
package/cli/src/common.js
CHANGED
|
@@ -3,7 +3,7 @@ export const USAGE = `Usage:
|
|
|
3
3
|
nexo start an interactive session (needs a terminal)
|
|
4
4
|
nexo --resume [id] [--all] resume a session (a picker of this project's sessions when no id is given;
|
|
5
5
|
--all lists every project)
|
|
6
|
-
nexo [--workspace <dir>] [--model <s1|s2|provider/id>] [--effort <level>] options for a new session
|
|
6
|
+
nexo [--workspace <dir>] [--model <s1|s2|provider/id>] [--effort <level>] [--allow-all] options for a new session
|
|
7
7
|
without --workspace each turn works in its own run folder (files carried over
|
|
8
8
|
from the previous turn); --workspace . works in the current folder
|
|
9
9
|
nexo sessions [--limit <n>]
|
|
@@ -17,7 +17,7 @@ export const USAGE = `Usage:
|
|
|
17
17
|
nexo settings remove-key <provider> delete a key from the credentials file
|
|
18
18
|
nexo settings keys key status of the model and web search providers (never the keys)
|
|
19
19
|
nexo search <query...> [--count <n>] [--json] search the web with the configured Brave/Tavily keys
|
|
20
|
-
nexo run <instruction...> [--skill <name>] [--model <s1|s2|provider/id>] [--effort <level>] [--workspace <dir>] [--budget <usd>] [--no-review]
|
|
20
|
+
nexo run <instruction...> [--skill <name>] [--model <s1|s2|provider/id>] [--effort <level>] [--workspace <dir>] [--budget <usd>] [--no-review] [--allow-all]
|
|
21
21
|
nexo cost [--by model|tier|day|run|skill] [--since YYYY-MM-DD]
|
|
22
22
|
nexo reindex
|
|
23
23
|
nexo review-queue [--limit <n>] [--days <n>] recent runs without a verdict, worst first
|
package/cli/src/interactive.js
CHANGED
|
@@ -53,7 +53,7 @@ export function parseInteractiveArgs(args) {
|
|
|
53
53
|
else
|
|
54
54
|
rest.push(arg);
|
|
55
55
|
}
|
|
56
|
-
const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { workspace: { type: "string" }, model: { type: "string" }, effort: { type: "string" }, all: { type: "boolean" } } });
|
|
56
|
+
const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { workspace: { type: "string" }, model: { type: "string" }, effort: { type: "string" }, all: { type: "boolean" }, "allow-all": { type: "boolean" } } });
|
|
57
57
|
if (values.all && !resume)
|
|
58
58
|
throw usageError("--all applies to --resume only");
|
|
59
59
|
if (positionals.length > 0)
|
|
@@ -63,7 +63,7 @@ export function parseInteractiveArgs(args) {
|
|
|
63
63
|
if (resume && (values.workspace !== undefined || values.model !== undefined || values.effort !== undefined)) {
|
|
64
64
|
throw usageError("--resume reopens a session as it was; --workspace, --model and --effort apply to new sessions only");
|
|
65
65
|
}
|
|
66
|
-
return { resume, workspace: values.workspace, model: values.model, effort: values.effort, all: values.all === true };
|
|
66
|
+
return { resume, workspace: values.workspace, model: values.model, effort: values.effort, all: values.all === true, allowAll: values["allow-all"] === true };
|
|
67
67
|
}
|
|
68
68
|
const PICKER_LIMIT = 50;
|
|
69
69
|
/**
|
|
@@ -133,7 +133,13 @@ export async function interactiveCommand(args, io, options, stdio) {
|
|
|
133
133
|
signal: options.signal,
|
|
134
134
|
openSession: (prompter) => {
|
|
135
135
|
const deps = buildDeps(prompter);
|
|
136
|
-
|
|
136
|
+
if (resumeId) {
|
|
137
|
+
const s = resumeSession(deps, resumeId);
|
|
138
|
+
if (parsed.allowAll)
|
|
139
|
+
s.setAllowAll(true);
|
|
140
|
+
return s;
|
|
141
|
+
}
|
|
142
|
+
return createSession(deps, { cwd, workspace: parsed.workspace, model: parsed.model, effort: parsed.effort, allowAll: parsed.allowAll });
|
|
137
143
|
},
|
|
138
144
|
resumeSession: (id, prompter) => resumeSession(buildDeps(prompter), id),
|
|
139
145
|
});
|
package/cli/src/main.js
CHANGED
|
@@ -92,6 +92,7 @@ async function runCommand(args, io, options) {
|
|
|
92
92
|
workspace: { type: "string" },
|
|
93
93
|
budget: { type: "string" },
|
|
94
94
|
"no-review": { type: "boolean" },
|
|
95
|
+
"allow-all": { type: "boolean" },
|
|
95
96
|
},
|
|
96
97
|
});
|
|
97
98
|
const instruction = positionals.join(" ").trim();
|
|
@@ -144,6 +145,7 @@ async function runCommand(args, io, options) {
|
|
|
144
145
|
workspace: values.workspace,
|
|
145
146
|
projectDir: options.cwd ?? process.cwd(),
|
|
146
147
|
budgetUsd,
|
|
148
|
+
allowAll: values["allow-all"] === true,
|
|
147
149
|
}, options.signal);
|
|
148
150
|
}
|
|
149
151
|
finally {
|
package/core/src/engine/run.js
CHANGED
|
@@ -157,6 +157,7 @@ export async function executeRun(env, input) {
|
|
|
157
157
|
sessionRules: request.sessionRules ?? (() => []),
|
|
158
158
|
...(request.addSessionRule ? { addSessionRule: request.addSessionRule } : {}),
|
|
159
159
|
auto: request.autoApprove ?? config.tools.autoApprove === "on",
|
|
160
|
+
allowAll: request.allowAll ?? false,
|
|
160
161
|
userRequest: request.instruction,
|
|
161
162
|
};
|
|
162
163
|
// Resolve skill, model and workspace before creating anything on disk.
|
|
@@ -804,12 +805,13 @@ export async function executeRun(env, input) {
|
|
|
804
805
|
sessionRules: approvals.sessionRules,
|
|
805
806
|
...(approvals.addSessionRule ? { addSessionRule: approvals.addSessionRule } : {}),
|
|
806
807
|
...(classifier ? { classify: (name, a, s) => classifier(name, a, toolCall.id, s) } : {}),
|
|
808
|
+
allowAll: approvals.allowAll,
|
|
807
809
|
}
|
|
808
810
|
: undefined);
|
|
809
811
|
if (!auth.allowed)
|
|
810
812
|
return { block: true, reason: toolErrorText(auth.error) };
|
|
811
813
|
approvedBy.set(toolCall.id, auth.by);
|
|
812
|
-
if (auth.by === "auto")
|
|
814
|
+
if (auth.by === "auto" || auth.by === "allow_all")
|
|
813
815
|
deps.onEvent?.({ type: "approval", runId, depth, toolCallId: toolCall.id, toolName: toolCall.name, reason: deps.redact(auth.reason ?? "") });
|
|
814
816
|
return undefined;
|
|
815
817
|
},
|
|
@@ -178,6 +178,14 @@ export class Session {
|
|
|
178
178
|
this.state.autoApprove = on;
|
|
179
179
|
this.save();
|
|
180
180
|
}
|
|
181
|
+
/** Allow-all mode for this session: auto-approves all tool approval prompts without asking. */
|
|
182
|
+
get allowAll() {
|
|
183
|
+
return this.state.allowAll ?? false;
|
|
184
|
+
}
|
|
185
|
+
setAllowAll(on) {
|
|
186
|
+
this.state.allowAll = on;
|
|
187
|
+
this.save();
|
|
188
|
+
}
|
|
181
189
|
get remainingUsd() {
|
|
182
190
|
return Math.max(0, this.budgetUsd - this.state.costUsd);
|
|
183
191
|
}
|
|
@@ -305,6 +313,7 @@ export class Session {
|
|
|
305
313
|
sessionRules: () => this.state.sessionRules ?? [],
|
|
306
314
|
addSessionRule: (rule) => this.addSessionRule(rule),
|
|
307
315
|
autoApprove: this.autoApprove,
|
|
316
|
+
allowAll: this.allowAll,
|
|
308
317
|
onSteeringReady: (control) => {
|
|
309
318
|
this.steerCtl = control;
|
|
310
319
|
for (const text of this.steerPending.splice(0))
|
|
@@ -599,6 +608,7 @@ export function createSession(deps, options) {
|
|
|
599
608
|
updatedAt: nowIso,
|
|
600
609
|
lastRunId: null,
|
|
601
610
|
context: null,
|
|
611
|
+
allowAll: options.allowAll ?? null,
|
|
602
612
|
};
|
|
603
613
|
const dir = SessionDir.create(deps.paths.sessions, id, deps.redact);
|
|
604
614
|
const session = openSession(deps, dir, state, [], SessionLock.acquire(dir.root, id));
|
package/package.json
CHANGED
package/sdk/src/index.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
export { checkSetup, createNexo } from "./nexo.js";
|
|
2
|
+
export { allowAllPrompter, nonInteractivePrompter } from "../../tools/src/index.js";
|
|
2
3
|
export { createRuntime, openLogger } from "./runtime.js";
|
|
3
4
|
export { NexoError } from "../../telemetry/src/index.js";
|
|
4
5
|
export { trackRunTree } from "./run-tree.js";
|
package/sdk/src/nexo.js
CHANGED
|
@@ -23,6 +23,7 @@ export function createNexo(options = {}) {
|
|
|
23
23
|
const env = withHome(options);
|
|
24
24
|
const cwd = options.cwd ?? process.cwd();
|
|
25
25
|
const prompter = options.prompter ?? nonInteractivePrompter;
|
|
26
|
+
const allowAll = options.allowAll ?? false;
|
|
26
27
|
const listeners = new Set();
|
|
27
28
|
const runtime = createRuntime({
|
|
28
29
|
env,
|
|
@@ -63,7 +64,7 @@ export function createNexo(options = {}) {
|
|
|
63
64
|
if (onEvent)
|
|
64
65
|
listeners.add(onEvent);
|
|
65
66
|
try {
|
|
66
|
-
return await runtime.engine.run(request, runOptions.signal);
|
|
67
|
+
return await runtime.engine.run(allowAll && request.allowAll === undefined ? { ...request, allowAll: true } : request, runOptions.signal);
|
|
67
68
|
}
|
|
68
69
|
finally {
|
|
69
70
|
if (onEvent)
|
|
@@ -72,7 +73,7 @@ export function createNexo(options = {}) {
|
|
|
72
73
|
},
|
|
73
74
|
createSession(sessionOptions) {
|
|
74
75
|
live();
|
|
75
|
-
return createSession(sessionDeps(), sessionOptions);
|
|
76
|
+
return createSession(sessionDeps(), allowAll && sessionOptions.allowAll === undefined ? { ...sessionOptions, allowAll: true } : sessionOptions);
|
|
76
77
|
},
|
|
77
78
|
resumeSession(id) {
|
|
78
79
|
live();
|
package/tools/src/policy.js
CHANGED
|
@@ -2,6 +2,7 @@ import { NexoError } from "../../telemetry/src/index.js";
|
|
|
2
2
|
import { isReadOnlyCommand } from "./read-only.js";
|
|
3
3
|
import { describeSessionRule, matchesSessionRule, sessionRuleFor } from "./session-rules.js";
|
|
4
4
|
export const nonInteractivePrompter = { interactive: false, approve: async () => "deny" };
|
|
5
|
+
export const allowAllPrompter = { interactive: true, approve: async () => "once" };
|
|
5
6
|
/** The auto-allow reason for a bash command `isReadOnlyCommand` accepts; the approver is not called. */
|
|
6
7
|
export const READ_ONLY_REASON = "read-only command";
|
|
7
8
|
/** Shell metacharacters that chain or redirect commands; an allow rule never vouches for a command containing them. */
|
|
@@ -109,6 +110,8 @@ export function createPolicy(cfg) {
|
|
|
109
110
|
const ruleMatches = () => (options.sessionRules?.() ?? []).some((rule) => matchesSessionRule(rule, toolName, args));
|
|
110
111
|
if (ruleMatches())
|
|
111
112
|
return { allowed: true, by: "session_rule" };
|
|
113
|
+
if (options.allowAll)
|
|
114
|
+
return { allowed: true, by: "allow_all", reason: "allow-all" };
|
|
112
115
|
if (!prompter.interactive && cfg.nonInteractiveAsk === "allow")
|
|
113
116
|
return { allowed: true, by: "config" };
|
|
114
117
|
const aborted = () => ({
|
package/tui/src/app.js
CHANGED
|
@@ -327,7 +327,7 @@ class InteractiveApp {
|
|
|
327
327
|
const fraction = session.contextFraction;
|
|
328
328
|
const ctx = fraction === null ? "ctx –" : `ctx ${Math.round(fraction * 100)}%`;
|
|
329
329
|
const score = !this.running && this.lastScore ? [this.lastScore] : [];
|
|
330
|
-
const parts = [escapeControl(model), escapeControl(effort), ...(session.autoApprove ? ["auto"] : []), `turn ${usd(turn)}`, ...score, `session ${usd(spent)}/${usd(session.budgetUsd)}`, ctx];
|
|
330
|
+
const parts = [escapeControl(model), escapeControl(effort), ...(session.allowAll ? ["allow-all"] : session.autoApprove ? ["auto"] : []), `turn ${usd(turn)}`, ...score, `session ${usd(spent)}/${usd(session.budgetUsd)}`, ctx];
|
|
331
331
|
return style.gray(parts.join(" · ")) + (this.running ? style.cyan(" · running…") : "");
|
|
332
332
|
}
|
|
333
333
|
// Input
|
|
@@ -746,6 +746,19 @@ class InteractiveApp {
|
|
|
746
746
|
}
|
|
747
747
|
break;
|
|
748
748
|
}
|
|
749
|
+
case "allow-all": {
|
|
750
|
+
if (!args) {
|
|
751
|
+
this.say(`allow-all mode: ${session.allowAll ? "on" : "off"}`);
|
|
752
|
+
}
|
|
753
|
+
else if (args === "on" || args === "off") {
|
|
754
|
+
session.setAllowAll(args === "on");
|
|
755
|
+
this.say(`allow-all mode ${session.allowAll ? "on" : "off"} for this session`);
|
|
756
|
+
}
|
|
757
|
+
else {
|
|
758
|
+
this.sayError({ code: "INVALID_REQUEST", message: `Unknown /allow-all argument "${escapeControl(oneLine(args, 40))}"`, hint: "Use on or off" });
|
|
759
|
+
}
|
|
760
|
+
break;
|
|
761
|
+
}
|
|
749
762
|
case "permissions": {
|
|
750
763
|
if (!args) {
|
|
751
764
|
const rules = session.sessionRules;
|
package/tui/src/commands.js
CHANGED
|
@@ -22,6 +22,7 @@ export const SLASH_COMMANDS = [
|
|
|
22
22
|
{ name: "model", description: "Set this session's model (default clears it)", argumentHint: "<s1|s2|provider/id|default>", getArgumentCompletions: items(["s1", "s2", "default"]) },
|
|
23
23
|
{ name: "effort", description: "Set this session's effort (default clears it)", argumentHint: "<level|default>", getArgumentCompletions: items([...EFFORTS, "default"]) },
|
|
24
24
|
{ name: "auto", description: "Auto mode for this session: an approver model allows in-scope actions", argumentHint: "[on|off|default]", getArgumentCompletions: items(["on", "off", "default"]) },
|
|
25
|
+
{ name: "allow-all", description: "Allow-all mode for this session: auto-approves all tool prompts", argumentHint: "[on|off]", getArgumentCompletions: items(["on", "off"]) },
|
|
25
26
|
{ name: "permissions", description: "List this session's Always-allow rules", argumentHint: "[remove <n>|clear]", getArgumentCompletions: items(["remove", "clear"]) },
|
|
26
27
|
{ name: "compact", description: "Summarize older turns at the start of the next turn" },
|
|
27
28
|
{ name: "clear", description: "Start a new conversation in this session" },
|