@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 CHANGED
@@ -3,60 +3,60 @@
3
3
  [![npm version](https://img.shields.io/npm/v/@hexdecimal16/nexo)](https://www.npmjs.com/package/@hexdecimal16/nexo)
4
4
  [![test](https://github.com/hexdecimal16/nexo/actions/workflows/test.yml/badge.svg?event=push)](https://github.com/hexdecimal16/nexo/actions/workflows/test.yml)
5
5
 
6
- An AI agent engine that runs on your machine. It tracks what each run costs, scores the results, and keeps every run inspectable. Use it from the terminal, from a web run inspector, or from Node code.
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
- From source:
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
- git clone https://github.com/hexdecimal16/nexo.git
22
- cd nexo
23
- npm ci
24
- npm run nexo -- init
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
- To install a `nexo` command globally from your checkout:
29
+ `nexo --help` lists every command. Data lives in `~/.nexo`. Set `NEXO_HOME` to move it.
28
30
 
29
- ```sh
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
- ## First run
33
+ Every option is in `/settings` inside a chat, or in `nexo settings` from the shell:
35
34
 
36
35
  ```sh
37
- nexo init # pick models, store API keys, make one small test call
38
- nexo doctor # check Node, config, keys and the data directory
39
- nexo # start a chat
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
- For scripts, `nexo init --yes --s1 <provider/id> --s2 <provider/id>` runs without prompts and reads keys from the provider's environment variable. `nexo doctor --json` prints the checks for automation.
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
- Data lives in `~/.nexo` (set `NEXO_HOME` to change it).
43
+ ## Optional tools
47
44
 
48
- ### Web search
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
- 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.
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
- 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
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
- `BRAVE_API_KEY` and `TAVILY_API_KEY` work too, and they take precedence over the credentials file. In a chat, `/settings` lists both keys.
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
- 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
-
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.
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 # release build into dist/
89
- npm run bump -- minor
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
@@ -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
- return resumeId ? resumeSession(deps, resumeId) : createSession(deps, { cwd, workspace: parsed.workspace, model: parsed.model, effort: parsed.effort });
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 {
@@ -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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hexdecimal16/nexo",
3
- "version": "0.4.3",
3
+ "version": "0.4.4",
4
4
  "description": "nexo agent engine",
5
5
  "license": "PolyForm-Noncommercial-1.0.0",
6
6
  "repository": {
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();
@@ -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;
@@ -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" },