@akon-labs/nexus-cli 0.1.8 → 0.1.10

package/docs/mcp.md

@@ -0,0 +1,178 @@
+# MCP
+
+Nexus includes a native Model Context Protocol client. No extension package is required.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/mcp` | Open the server, connection, authentication, and direct-tool panel |
+| `/mcp status` | Show text server status |
+| `/mcp setup` | Discover existing configurations, import them, or add a known server |
+| `/mcp reconnect [server]` | Reconnect one server or every server |
+| `/mcp tools` | List discovered MCP tools |
+| `/mcp prompts` | List MCP prompts and their generated slash commands |
+| `/mcp enable <server>` | Enable a server through a project override |
+| `/mcp disable <server>` | Disable a server through a project override |
+| `/mcp logout <server>` | Remove stored OAuth credentials |
+| `/mcp token status\|remove <server>` | Inspect or remove an OS-stored bearer token |
+| `/mcp-auth [server]` | Open OAuth management or authenticate one server |
+
+Project configuration and project overrides are available only in trusted projects. Global MCP remains available in untrusted projects.
+
+## Configuration
+
+Nexus loads configuration in this order; later definitions override earlier definitions with the same server name:
+
+1. `~/.config/nexus/mcp.json`
+2. `.nexus/mcp.json` for trusted projects
+
+Both files use an `mcpServers` object and optional `settings` and `imports` fields.
+
+### Local stdio server
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+      "env": {
+        "LOG_LEVEL": "info"
+      },
+      "lifecycle": "lazy"
+    }
+  }
+}
+```
+
+### Hosted HTTP server with OAuth
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "url": "https://mcp.notion.com/mcp",
+      "auth": "oauth",
+      "protocolVersion": "auto"
+    }
+  }
+}
+```
+
+### Bearer authentication
+
+Prefer an environment variable instead of storing a token in JSON:
+
+```json
+{
+  "mcpServers": {
+    "internal": {
+      "url": "https://mcp.example.com/mcp",
+      "auth": "bearer",
+      "bearerTokenEnv": "INTERNAL_MCP_TOKEN"
+    }
+  }
+}
+```
+
+Header and environment values support `${NAME}`, `$env:NAME`, and `{env:NAME}` interpolation. A value beginning with `!` executes a trusted command and uses its output as the secret; `!!` escapes a literal leading `!`.
+
+### Import another client’s configuration
+
+```json
+{
+  "imports": ["cursor", "claude-code", "codex", "opencode", "vscode"],
+  "mcpServers": {}
+}
+```
+
+Imports are explicit. Nexus never requires another client or package at runtime.
+
+## Server options
+
+Common server fields include:
+
+- Transport: `command`, `args`, `env`, `cwd`, `url`, `headers`, or `socket`
+- Authentication: `auth`, `oauth`, `bearerTokenEnv`, `bearerTokenStore`, `requestHeadersCommand`
+- Lifecycle: `lazy`, `eager`, `keep-alive`, or `lazy-keep-alive`
+- Discovery: `includeTools`, `excludeTools`, `exposeResources`, `searchKeywords`
+- Tool surface: `directTools`, `toolPrefix`, `approveTools`
+- Runtime: `idleTimeout`, `requestTimeoutMs`, `protocolVersion`, `debug`, `trace`
+- State: `disabled: true`
+
+Only one transport—`command`, `url`, or `socket`—may be configured per server.
+
+## Tool surfaces
+
+Nexus always provides the `mcp` gateway tool for status, discovery, descriptions, authentication, connections, and individual calls. It also provides `mcpScript`, a bounded worker for multi-call JavaScript orchestration.
+
+Frequently used MCP tools can be registered directly:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "url": "https://example.com/mcp",
+      "directTools": ["search_issues", "get_issue"]
+    }
+  },
+  "settings": {
+    "toolPrefix": "server"
+  }
+}
+```
+
+Direct-tool metadata is cached and refreshed when servers reconnect or publish list-change notifications. The `/mcp` panel can enable direct tools without restarting the current session.
+
+## Protocol capabilities
+
+The native runtime supports:
+
+- stdio, Streamable HTTP, legacy SSE fallback, and Unix-domain sockets
+- modern protocol negotiation with legacy compatibility
+- tools, resources, prompts, server instructions, and list-change notifications
+- OAuth 2.1 with PKCE, dynamic client registration, client credentials, and manual remote completion
+- secure OS credential storage for OAuth and optional bearer tokens
+- MCP sampling with user approval
+- form and URL elicitation
+- MCP Apps/AppBridge resources in a sandboxed local viewer
+- bounded output with private spill files
+- lazy startup, idle shutdown, keep-alive recovery, and stale-session reconnection
+- per-tool approval gates and metadata-only protocol tracing
+
+Connection failures are non-fatal: Nexus reports the failed server and continues with the remaining tools.
+
+## Settings
+
+Useful top-level settings include:
+
+```json
+{
+  "settings": {
+    "directTools": false,
+    "scriptMode": true,
+    "autoAuth": false,
+    "sampling": true,
+    "elicitation": true,
+    "idleTimeout": 10,
+    "mcpFooterStatus": "full",
+    "outputGuard": true,
+    "toolResultRendering": "compact"
+  },
+  "mcpServers": {}
+}
+```
+
+## Environment controls
+
+| Variable | Purpose |
+|----------|---------|
+| `MCP_DIRECT_TOOLS` | Override direct-tool selection; use `__none__` to disable it |
+| `MCP_OUTPUT_GUARD` | Enable or disable bounded MCP output |
+| `MCP_OAUTH_CALLBACK_PORT` | Set the local OAuth callback port |
+| `MCP_OAUTH_DIR` | Legacy plaintext credential import directory only |
+| `MCP_UI_VIEWER` | Select `browser`, `glimpse`, or `none` |
+| `MCP_UI_DEBUG` | Enable MCP UI debug logging |
+
+Nexus consumes MCP servers; it does not expose Nexus itself as an MCP server.

package/docs/pi-subagents.md

@@ -0,0 +1,75 @@
+# Subagents (bundled pi-subagents) with worker-scope billing
+
+Nexus ships [pi-subagents](https://github.com/nicobailon/pi-subagents) inside the CLI.
+Nothing to install: every session has the `subagent` tool, the built-in agents
+(`scout`, `researcher`, `worker`, `reviewer`, `oracle`, `delegate`), the fleet view,
+and the `/parallel-research`, `/review-loop` and `/council` workflows.
+
+## Two-tier billing, automatically
+
+The orchestrator (your session) bills the Hub's **orchestrator** deployment. Every
+subagent child bills the **worker** deployment, because the CLI marks each child
+spawned by pi-subagents as a delegated worker: the child self-mints a one-time worker
+grant per model turn (`POST /llm/worker-grants`) and the gateway consumes it and
+reserves the request as `worker`. Minting is fail-closed — a child whose grant is
+missing sends an invalid sentinel and the gateway rejects the request, so a child can
+never silently bill as orchestrator.
+
+Agents listed in `NEXUS_BIG_MODEL_AGENTS` (default `oracle`) are deliberately left
+unmarked and bill the orchestrator deployment. That is the escalation path: ask
+`oracle` when a subagent needs the big model.
+
+Model identity stays server-side in the Hub's experiment groups; swapping deployments
+never touches agent configuration.
+
+## Orchestrator policy
+
+With bundled subagents active, the orchestrator session:
+
+- **cannot run `bash`, `write`, or `edit` directly** — implementation, shell, tests and
+  long tool loops go through `subagent` (this is the cost guarantee);
+- keeps **unlimited** direct reads, greps and GitNexus graph queries;
+- is told to fan out `scout`/`researcher` subagents (or `/parallel-research`) for
+  broad research and to run long investigations in the background.
+
+`NEXUS_PARENT_POLICY=off` restores direct mutating tools for one session.
+
+## Limits follow pi-subagents
+
+No concurrency, spawn, or timeout limits are layered on top of pi-subagents: its own
+defaults apply (20 concurrent children per run, 4 per parallel group, 64 spawns per
+run, 30-minute run deadline). Capacity is the Hub's concern — the gateway caps in-flight
+requests per user by role (orchestrator and worker separately), so a fan-out of cheap
+workers never competes with the orchestrator's own turn.
+
+The web search tool is registered under pi-web-access's canonical name `web_search`,
+so pi-subagents' builtin `researcher` and any other pi package that expects it work
+unmodified.
+
+## Legacy `delegate_task`
+
+The Hub-driven `delegate_task` worker is no longer registered by default. Set
+`NEXUS_DELEGATION_MODE=internal` to get it back (its 5-minute worker timeout and
+single-worker cap apply there).
+
+## Environment knobs
+
+| Variable | Default | Effect |
+|---|---|---|
+| `NEXUS_DELEGATION_MODE` | `external` | `internal` re-enables `delegate_task` instead of bundled subagents. |
+| `NEXUS_BUNDLED_PACKAGES` | on | `off` stops loading CLI-bundled packages (pi-subagents) and flips delegation to internal. |
+| `NEXUS_BIG_MODEL_AGENTS` | `oracle` | Comma-separated agents that bill the orchestrator deployment. Empty string puts every agent on the worker deployment. |
+| `NEXUS_WORKER_SCOPE` | on | `off` leaves all children on the orchestrator deployment. |
+| `NEXUS_PARENT_POLICY` | on | `off` lets the orchestrator run bash/write/edit directly. |
+| `NEXUS_SUBAGENT_BINARY` | this CLI | Executable pi-subagents spawns for children (alias of `PI_SUBAGENT_PI_BINARY`). Any `NEXUS_SUBAGENT_X` maps to `PI_SUBAGENT_X`; explicit `PI_*` wins. |
+
+A user-installed `npm:pi-subagents` package (project or global) replaces the bundled
+copy, so pinning a different version still works.
+
+## Verification
+
+`test/suite/bundled-subagents.test.ts` covers child marking, tiering, the binary
+default and the orchestrator policy; `test/suite/worker-scope-stub-hub.test.ts` drives
+a stub Hub end to end and asserts the exact grant/scope headers per persona.
+`scripts/nexus-subagent-worker` remains as an optional wrapper for builds that cannot
+mark children in-process.

package/docs/quickstart.md

@@ -47,7 +47,7 @@ GitNexus credentials are stored in `~/.config/nexus/auth.json`.
 
 ## Configure a model provider
 
-Nexus supports provider subscriptions, API keys, and local Ollama models through `/byok`.
+Nexus supports other provider subscriptions and API keys through `/byok`.
 
 ### Option 1: subscription or stored API key
 

package/docs/usage.md

@@ -37,10 +37,11 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | Command | Description |
 |---------|-------------|
 | `/login` | Sign in to GitNexus |
-| `/byok [provider\|ollama]` | Configure a cloud provider, API key, or local Ollama model |
+| `/byok [provider]` | Use another subscription or cloud provider |
 | `/logout` | Remove stored model-provider credentials |
 | `/gitnexus-status` | Show the GitNexus connection status |
 | [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
+| `/nexus-agent` | Switch back to Nexus Agent |
 | `/model` | Switch models |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Thinking level, theme, message delivery, transport |

package/examples/extensions/pi-subagents-worker-policy.ts

@@ -0,0 +1,86 @@
+/**
+ * worker-policy — parent-session delegation policy for the pi-subagents swap.
+ *
+ * Replaces the old delegate_task parent gating (review-only allowlist + 8-call
+ * read budget) with the tuning we settled on:
+ *   - HARD-block mutating tools on the orchestrator (bash/write/edit): all
+ *     implementation goes through the `subagent` tool.
+ *   - NO read budget: reads, greps and gitnexus graph calls are cheap on
+ *     cached input and capping them measurably hurt output quality.
+ *   - Prompt-level steering for everything else.
+ *
+ * Scope guards: the policy applies only to the top-level orchestrator session
+ * on the gitnexus/auto model. It must never fire inside delegated workers or
+ * pi-subagents children (they do the mutating work), and NEXUS_PARENT_POLICY=off
+ * disables it entirely.
+ */
+
+// Nexus-branded env aliases: users configure NEXUS_SUBAGENT_*; we map them
+// onto the PI_SUBAGENT_* names the upstream pi-subagents package reads.
+// Explicit PI_* values win (they are the wire format, aliases are sugar).
+if (process.env.NEXUS_SUBAGENT_BINARY?.trim() && !process.env.PI_SUBAGENT_PI_BINARY?.trim()) {
+	process.env.PI_SUBAGENT_PI_BINARY = process.env.NEXUS_SUBAGENT_BINARY;
+}
+for (const [key, value] of Object.entries(process.env)) {
+	if (!key.startsWith("NEXUS_SUBAGENT_") || key === "NEXUS_SUBAGENT_BINARY" || !value?.trim()) continue;
+	const target = `PI_SUBAGENT_${key.slice("NEXUS_SUBAGENT_".length)}`;
+	if (!process.env[target]?.trim()) process.env[target] = value;
+}
+
+// Self-contained activation: plain `nexus` in this repo gets worker-scope
+// billing with no shell setup. Explicit env always wins over these defaults.
+const WORKER_WRAPPER = `${process.env.HOME}/.local/bin/nexus-subagent-worker`;
+if (!process.env.PI_SUBAGENT_PI_BINARY?.trim()) {
+	process.env.PI_SUBAGENT_PI_BINARY = WORKER_WRAPPER;
+}
+if (!process.env.NEXUS_BIG_MODEL_AGENTS?.trim()) {
+	process.env.NEXUS_BIG_MODEL_AGENTS = "oracle";
+}
+if (!process.env.NEXUS_DELEGATION_MODE?.trim()) {
+	process.env.NEXUS_DELEGATION_MODE = "external";
+}
+
+const BLOCKED_PARENT_TOOLS = new Set(["bash", "write", "edit", "delegate_task"]);
+
+const POLICY_PROMPT = [
+	"",
+	"Delegation policy: you are the orchestrator. Perform implementation, mutation,",
+	"shell commands, tests, and long repetitive tool loops through the `subagent`",
+	"tool (worker/reviewer/scout agents). Direct bash/write/edit are disabled in",
+	"this session. Reading files and querying the GitNexus graph directly is fine",
+	"and unlimited — prefer graph queries (gitnexus_query/context/impact) to locate",
+	"code before delegating. Keep planning, user communication, and final review here.",
+].join("\n");
+
+function isAuto(model: { provider?: string; id?: string } | undefined): boolean {
+	return model?.provider === "gitnexus" && model?.id === "auto";
+}
+
+function policyDisabled(): boolean {
+	return (
+		process.env.NEXUS_PARENT_POLICY === "off" ||
+		process.env.NEXUS_INTERNAL_DELEGATED_WORKER === "1" ||
+		Boolean(process.env.PI_SUBAGENT_CHILD_AGENT?.trim())
+	);
+}
+
+export default function workerPolicy(pi: any) {
+	if (policyDisabled()) return;
+
+	pi.on("before_agent_start", (event: any) => {
+		if (policyDisabled()) return;
+		return { systemPrompt: `${event.systemPrompt}\n${POLICY_PROMPT}` };
+	});
+
+	pi.on("tool_call", (event: any, ctx: any) => {
+		if (policyDisabled() || !isAuto(ctx?.model)) return;
+		if (!BLOCKED_PARENT_TOOLS.has(event.toolName)) return;
+		return {
+			block: true,
+			reason:
+				"This orchestrator session does not run mutating tools directly. " +
+				"Use the `subagent` tool (worker for implementation, reviewer for checks, " +
+				"scout for exploration) to execute this, then review its report.",
+		};
+	});
+}