@serkanalgur/opencode-nexus 1.4.0 → 1.5.0

package/README.md

@@ -147,14 +147,14 @@ await ctx.session.prompt({ sessionID: session.id, text: 'You are a senior softwa
 
 Each agent role gets a specialized prompt:
 
-| Role | Focus |
-|------|-------|
-| **Architect** | System design, architecture patterns, high-level decisions |
-| **Coder** | Clean, efficient code following best practices |
-| **Reviewer** | Code review for correctness, security, performance |
-| **Tester** | Comprehensive tests, edge cases, quality assurance |
-| **Explorer** | Codebase navigation, architecture analysis |
-| **Documenter** | Clear technical documentation |
+| Role | OpenCode Agent | Focus |
+|------|----------------|-------|
+| **Architect** | `architect` | System design, architecture patterns, high-level decisions |
+| **Coder** | `build-orchestrator` | Clean, efficient code following best practices |
+| **Reviewer** | `code-reviewer` | Code review for correctness, security, performance |
+| **Tester** | `build-orchestrator` | Comprehensive tests, edge cases, quality assurance |
+| **Explorer** | `explore` | Codebase navigation, architecture analysis |
+| **Documenter** | `doc-writer` | Clear technical documentation |
 
 ### Cost-Aware Model Selection
 
@@ -278,6 +278,68 @@ NexusPlugin.register({
 })
 ```
 
+### Custom Agent Roles
+
+Define your own agent roles with custom prompts:
+
+```jsonc
+// .opencode/nexus.jsonc
+{
+  "customRoles": [
+    {
+      "name": "security-auditor",
+      "displayName": "Security Auditor",
+      "emoji": "🔐",
+      "prompt": "You are a security auditor. Focus on OWASP Top 10, vulnerability scanning, and security best practices.",
+      "model": "anthropic/claude-sonnet-4-6"
+    }
+  ]
+}
+```
+
+Or register dynamically via tools: `nexus.roles.add(name="security-auditor", displayName="Security Auditor", prompt="...")`
+
+### Execution History
+
+Track all task executions with costs, durations, and outcomes:
+
+```
+nexus.history.list(count=10)  — Recent executions
+nexus.history.stats()         — Success rate, avg cost, breakdown by role
+```
+
+### Cost Forecasting
+
+Predict costs before executing tasks:
+
+```typescript
+const forecast = orchestrator.forecaster.forecastAll([
+  { task: myTask, role: 'coder', model: 'claude-sonnet-4-6', complexity: score }
+], budgetRemaining)
+// → { totalEstimatedCost: 0.0234, withinBudget: true }
+```
+
+### Agent Performance Scoring
+
+Track which model/role combinations work best:
+
+```
+nexus.performance.scores()           — All model/role scores
+nexus.performance.best(role="coder") — Best model for a role
+```
+
+Score = 40% success rate + 30% speed + 30% cost efficiency.
+
+### Git Worktree Per Agent
+
+Each agent works in its own isolated git worktree:
+
+```
+nexus.worktree.enable()   — Enable isolation
+nexus.worktree.list()     — List active worktrees
+nexus.worktree.disable()  — Clean up all
+```
+
 ---
 
 ## TUI Commands
@@ -313,6 +375,18 @@ Register these tools in your agent prompts:
 | `nexus.dashboard.stop` | Stop web dashboard | `{}` |
 | `nexus.preset` | Apply preset config | `{ name: string }` |
 | `nexus.template` | List/instantiate templates | `{ name?: string, baseDir?: string }` |
+| `nexus.model.costs` | Show/set model pricing | `{ model?: string, setInput?: number, setOutput?: number }` |
+| `nexus.security.scan` | Scan code for security issues | `{ content: string, filename?: string }` |
+| `nexus.roles.list` | List custom agent roles | `{}` |
+| `nexus.roles.add` | Add a custom role | `{ name, displayName, prompt, emoji?, model? }` |
+| `nexus.history.list` | List execution history | `{ count?: number }` |
+| `nexus.history.stats` | Execution statistics | `{}` |
+| `nexus.forecast` | Predict costs before execution | `{ tasks: string }` |
+| `nexus.performance.scores` | Model/role performance scores | `{}` |
+| `nexus.performance.best` | Best model for a role | `{ role: string }` |
+| `nexus.worktree.enable` | Enable git worktree isolation | `{ repoRoot?: string }` |
+| `nexus.worktree.list` | List active worktrees | `{}` |
+| `nexus.worktree.disable` | Disable and clean up | `{}` |
 
 ### Tool Examples
 

package/dist/index.js

@@ -8817,6 +8817,7 @@ class StateBroadcaster {
 }
 
 // src/dashboard.ts
+import { join as join2 } from "node:path";
 var CORS_HEADERS = {
   "Access-Control-Allow-Origin": "*",
   "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
@@ -8845,7 +8846,7 @@ class DashboardModule {
       this.server = Bun.serve({
         port,
         hostname: host,
-        fetch(req, server) {
+        async fetch(req, server) {
           const url = new URL(req.url);
           if (req.method === "OPTIONS") {
             return new Response(null, { headers: CORS_HEADERS });
@@ -8871,6 +8872,22 @@ class DashboardModule {
           if (url.pathname === "/api/health") {
             return jsonResponse({ ok: true, uptime: process.uptime() });
           }
+          try {
+            const spaPath = join2(process.cwd(), "dashboard", "index.html");
+            const spaContent = await Bun.file(spaPath).text();
+            if (spaContent.length > 100) {
+              return new Response(spaContent, {
+                headers: { "Content-Type": "text/html; charset=utf-8", ...CORS_HEADERS }
+              });
+            }
+            return new Response(`SPA not found at ${spaPath} (content: ${spaContent.length} bytes)`, {
+              headers: { "Content-Type": "text/plain", ...CORS_HEADERS }
+            });
+          } catch (e) {
+            return new Response(`SPA error: ${e}`, {
+              headers: { "Content-Type": "text/plain", ...CORS_HEADERS }
+            });
+          }
           return new Response("Nexus Dashboard API", {
             headers: {
               "Content-Type": "text/plain",
@@ -8973,9 +8990,9 @@ function detectCycles(nodes) {
 
 // src/message-store.ts
 import { appendFileSync, readFileSync as readFileSync2, existsSync, mkdirSync as mkdirSync2 } from "node:fs";
-import { join as join2, dirname as dirname2 } from "node:path";
+import { join as join3, dirname as dirname2 } from "node:path";
 var DEFAULT_CONFIG2 = {
-  storagePath: join2(process.env.HOME || "~", ".local", "share", "opencode-nexus", "messages.jsonl"),
+  storagePath: join3(process.env.HOME || "~", ".local", "share", "opencode-nexus", "messages.jsonl"),
   maxMessages: 1e4,
   rotationSize: 1000
 };
@@ -9063,10 +9080,10 @@ class MessageStore {
 
 // src/memory-store.ts
 import { Database } from "bun:sqlite";
-import { join as join3, dirname as dirname3 } from "node:path";
+import { join as join4, dirname as dirname3 } from "node:path";
 import { mkdirSync as mkdirSync3 } from "node:fs";
 var DEFAULT_CONFIG3 = {
-  dbPath: join3(process.env.HOME || "~", ".local", "share", "opencode-nexus", "memory.db"),
+  dbPath: join4(process.env.HOME || "~", ".local", "share", "opencode-nexus", "memory.db"),
   defaultTTL: 0,
   maxEntries: 1e4
 };
@@ -9880,7 +9897,7 @@ class CostForecaster {
 // src/worktree.ts
 import { execSync } from "node:child_process";
 import { existsSync as existsSync2 } from "node:fs";
-import { join as join4 } from "node:path";
+import { join as join5 } from "node:path";
 
 class WorktreeManager {
   worktrees = new Map;
@@ -9888,11 +9905,11 @@ class WorktreeManager {
   repoRoot;
   constructor(repoRoot, baseDir) {
     this.repoRoot = repoRoot;
-    this.baseDir = baseDir || join4(repoRoot, ".worktrees", "nexus-agents");
+    this.baseDir = baseDir || join5(repoRoot, ".worktrees", "nexus-agents");
   }
   create(agentId) {
     const branch = `nexus-agent-${agentId}`;
-    const path = join4(this.baseDir, agentId);
+    const path = join5(this.baseDir, agentId);
     try {
       if (!existsSync2(this.baseDir)) {
         execSync(`mkdir -p "${this.baseDir}"`, { cwd: this.repoRoot });
@@ -11083,9 +11100,84 @@ function getTemplate(name) {
 }
 
 // src/index.ts
+import { writeFileSync as writeFileSync2, mkdirSync as mkdirSync4, existsSync as existsSync3 } from "node:fs";
+import { join as join6 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+var NEXUS_AGENT_CONTENT = `---
+description: Nexus multi-agent orchestrator — manages parallel sub-agents with cost-aware routing, self-healing, and intelligent task decomposition.
+mode: primary
+---
+
+# Nexus Orchestrator Agent
+
+You are the Nexus Orchestrator — an intelligent multi-agent coordinator. You manage parallel sub-agents with cost-aware model selection, self-healing on failures, and DAG-based task execution.
+
+## Core Capabilities
+
+- **Spawn specialized sub-agents** for each task (architect, coder, reviewer, tester, explorer, documenter)
+- **Cost-aware routing** — automatically selects optimal models based on task complexity and budget
+- **Self-healing** — retries failed tasks, transfers context to new agents, escalates if needed
+- **Performance tracking** — learns which model/role combinations work best
+- **Execution history** — tracks all past executions for analysis
+
+## How to Use Nexus Tools
+
+### Spawning Agents
+Use the \`spawn\` tool to create specialized agents:
+\`\`\`
+nexus.spawn(role="coder", task="Implement JWT authentication middleware")
+nexus.spawn(role="reviewer", task="Review the auth implementation for security")
+\`\`\`
+
+Available roles: architect, coder, reviewer, tester, explorer, documenter
+
+### Checking Status
+\`\`\`
+nexus.status(detailed=true)    — Full orchestrator state
+nexus.agents(filter="working") — List active agents
+nexus.costs()                  — Cost report and budget status
+\`\`\`
+
+### Cost Management
+\`\`\`
+nexus.forecast(tasks='[...]')  — Predict costs
+nexus.model.costs()            — Show real model pricing
+nexus.preset(name="balanced")  — Apply a cost preset
+\`\`\`
+
+### Performance & History
+\`\`\`
+nexus.performance.scores()     — Model/role performance scores
+nexus.history.list(count=10)   — Recent execution history
+\`\`\`
+
+## Task Decomposition Strategy
+
+When given a development request:
+1. **Analyze** — Break the request into discrete tasks
+2. **Estimate** — Use nexus.forecast to predict costs
+3. **Execute** — Spawn agents in parallel where possible
+4. **Review** — Use nexus.spawn(role="reviewer") for each delivery
+5. **Report** — Summarize what was done, costs, and outcomes
+
+## Quality Gates
+
+Never skip these steps:
+- Every code change must be reviewed by nexus.spawn(role="reviewer")
+- Run nexus.security.scan() on new code
+- Verify with nexus.spawn(role="tester") before marking complete
+`;
 var src_default = define({
   id: "nexus",
   async setup(ctx) {
+    try {
+      const agentDir = join6(homedir2(), ".config", "opencode", "agents");
+      const agentFile = join6(agentDir, "nexus-orchestrator.md");
+      if (!existsSync3(agentFile)) {
+        mkdirSync4(agentDir, { recursive: true });
+        writeFileSync2(agentFile, NEXUS_AGENT_CONTENT, "utf-8");
+      }
+    } catch {}
     const orchestrator = new NexusOrchestrator;
     await orchestrator.initialize(ctx, () => {
       const state = orchestrator.getState();

package/dist/tui.js

@@ -34532,6 +34532,25 @@ var tui_default = define({
                     case "d":
                       await handleDashboard();
                       break;
+                    case "web":
+                    case "w":
+                      try {
+                        const port = parts[1] ? parseInt(parts[1]) : 4747;
+                        context.ui.toast.show({
+                          title: "Nexus Dashboard",
+                          message: `Starting web dashboard on port ${port}...
+Open http://localhost:${port} in your browser`,
+                          variant: "success",
+                          duration: 5000
+                        });
+                      } catch (e) {
+                        context.ui.toast.show({
+                          title: "Nexus",
+                          message: `Failed to start dashboard: ${e.message}`,
+                          variant: "error"
+                        });
+                      }
+                      break;
                     case "model":
                     case "m":
                       if (parts[1]) {
@@ -34568,7 +34587,7 @@ var tui_default = define({
                     default:
                       context.ui.toast.show({
                         title: "Nexus",
-                        message: "Commands: config, status, dashboard, model <role>, reset",
+                        message: "Commands: config, status, dashboard, web [port], model <role>, reset",
                         variant: "info"
                       });
                   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serkanalgur/opencode-nexus",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Adaptive Multi-Agent Orchestration with Cost Intelligence for OpenCode V2",
   "keywords": [
     "opencode",