@asobacloud/nehanda 0.7.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # Nehanda Command-Line Interface (`nehanda-cli`)
 
-An agentic terminal REPL and single-process engine built for energy systems research and software development. `nehanda-cli` connects directly to our flagship [Nehanda v3](https://huggingface.co/asoba/nehanda-v3-27b), normalizes multi-OEM energy telemetry through the ODSE protocol, and enforces a governed development workflow across the full research-to-production lifecycle. It also connects to local or cloud-based Ollama models, LM Studio instances, or any OpenAI-compatible API.
+An agentic terminal REPL and single-process engine built for energy systems research and software development. `nehanda-cli` works with Ollama, LM Studio, OpenRouter, Anthropic Claude, ZhipuAI, or any OpenAI-compatible API — local or cloud. It normalizes multi-OEM energy telemetry through the ODSE protocol and enforces a governed development workflow across the full research-to-production lifecycle.
 
 Every conversation turn, tool call, phase transition, and permission check is stored in a local, queryable SQLite database you own, ensuring complete transcripts exist for auditing and debugging.
 
@@ -94,7 +94,7 @@ Local Ollama / LM Studio: pick that provider in `/model`, accept or edit the hos
 
 * **Dynamic Tool Rescue (`[TOOL_CALL]`):** Native support for endpoints that strip OpenAI tool schemas (such as `nehandaMlProxy`). The engine dynamically injects active tool schemas directly into system prompts as `[TOOL_CALL]` blocks, parsing and executing tools locally without server-side function-calling support. Uses `[TOOL_CALL]` delimiters instead of `<tool_call>` XML to prevent vLLM's `--tool-call-parser qwen3_xml` stop-token interception.
 
-* **Deterministic SDLC Workflow:** Enforces a 6-phase state machine (`idle` → `plan` → `implement` → `test` → `verify` → `done`) to prevent unapproved code changes, hallucinated test passes, or unverified implementations.
+* **Deterministic SDLC Workflow:** Enforces a 7-phase state machine (`idle` → `explore` → `planning` → `test` → `implement` → `test` → `verify` → `done`) following the AGENTS.md TDD mandate. Transitions are gated: `planning → implement` is blocked until an approved plan exists and at least one RED behavioral test is recorded; `test → verify` requires all tests passing and safety checkers clean.
 
 * **Interactive Safety Interventions:** When execution checkers flag a command — opening local sockets, inspecting HIL testbed hardware paths, or writing outside the working directory — the engine raises a structured `{ status, reason, risk_score, proposed_remediation }` payload rather than crashing. In the TUI, blocked operations surface a `BlockConfirmMenu` (`[A] Approve for Session | [S] Run in Laya Sandbox | [C] Cancel`) wired directly into the Ink event loop. Session approvals are cached so the same operation is not re-prompted within a session. Headless pipe mode auto-denies without prompting.
 
@@ -102,7 +102,7 @@ Local Ollama / LM Studio: pick that provider in `/model`, accept or edit the hos
 
 * **Runtime Visibility:** `RuntimeHealthMonitor` probes active inference endpoints (1s HEAD request) and checks Laya sidecar liveness before each session. The TUI status header shows active model, endpoint health and latency, sidecar PID, and context usage percentage — so researchers have immediate visual confirmation of whether the target backend is an internal local host or an external cloud endpoint before uploading grid telemetry.
 
-* **Process Legibility:** Every tool call is visible while it runs. Tool-start lines show argument summaries (`⚙ Read(ui.mjs)`, `⚙ Bash(git status)`), a live spinner with plain-English verbs tracks activity between outputs (`⠋ Analyzing…`, `⠙ Reading ui.mjs…`), and tool results carry honest context suffixes (`✓ Read: … (N lines)`, `✓ Bash: … (240ms)`, `✓ Write: … (N chars)`) — never fabricated data. A dim `esc to cancel` hint stays available while a turn runs, and result previews are capped at 120 characters so raw output never floods the screen. Backed by `summarizeToolArgs`, `verbForTool`, `formatToolResultSuffix`, and `TOOL_VERBS` in `lib/ui.mjs`, with a live spinner channel (`bridge.updateSpinner`) in the Ink TUI.
+* **Process Legibility:** Every tool call is visible while it runs. Tool-start lines show argument summaries (`⚙ Read(ui.mjs)`, `⚙ Bash(git status)`), a live spinner with plain-English verbs tracks activity between outputs (`⠋ Analyzing…`, `⠙ Reading ui.mjs…`), and tool results carry honest context suffixes (`✓ Read: … (N lines)`, `✓ Bash: … (240ms)`, `✓ Write: … (N chars)`) — never fabricated data. When a reasoning model (Qwen3, Gemma) is thinking, the spinner shows live token progress (`⠋ Thinking (42 tokens)…`) rather than a frozen screen. Pressing Esc immediately updates the spinner to `Cancelling…` before the in-flight request is torn down. A dim `esc to cancel` hint stays available while a turn runs, and result previews are capped at 120 characters so raw output never floods the screen. Backed by `summarizeToolArgs`, `verbForTool`, `formatToolResultSuffix`, and `TOOL_VERBS` in `lib/ui.mjs`, with a live spinner channel (`bridge.updateSpinner`) in the Ink TUI.
 
 * **Interactive TUI & Pipe Support:** Rich Ink-based TUI (`bin/nehanda-ui.mjs`) for interactive development sessions, with headless pipe-mode support (`bin/agent.mjs`) for acceptance testing and automation.
 
@@ -343,10 +343,10 @@ Place the script at `lib/scripts/my-new-tool.py`. It will receive arguments inte
 | `/mcp list` | Connect to each server and enumerate available tools |
 | `/mcp reload [server]` | Re-read `mcp.json` and bust the tool cache (optionally for one server) |
 | `/mcp add <name> <command> [args…]` | Register a new server and save it to `~/.config/nehanda/mcp.json` |
-| `/mcp env` | Show environment variables for all configured servers |
+| `/mcp env` | Show environment variables for all configured servers (values masked) |
 | `/mcp env <server>` | Show environment variables for a specific server |
-| `/mcp env <server> <KEY> <value>` | Set an environment variable (e.g. an API key) |
-| `/mcp env <server> <KEY>` | Clear an environment variable |
+| `/mcp env <server> <NAME> <VALUE>` | Set an environment variable (e.g. an API key) |
+| `/mcp env unset <server> <NAME>` | Remove an environment variable (`clear` is also accepted) |
 
 ---
 
@@ -388,18 +388,18 @@ Many MCP servers require an API key or other secrets. Rather than editing `mcp.j
 ```
 ❯ /mcp env                    # show env vars for all servers
 ❯ /mcp env asoba              # show env vars for 'asoba' server
-❯ /mcp env asoba ASOBA_API_KEY sk-abc123...   # set the key
+❯ /mcp env asoba ASOBA_API_KEY sk-abc123...   # set the key (NAME + VALUE)
 ✓ Set ASOBA_API_KEY = ******** on asoba
   Config file: ~/.config/nehanda/mcp.json
 ```
 
 This writes the value to the `mcp.json` file where the server is defined (project-local `./mcp.json` takes priority over global `~/.config/nehanda/mcp.json`), then automatically reloads the server so the change takes effect immediately.
 
-To clear a key:
+To remove a key (explicit unset — omitting VALUE no longer clears):
 
 ```
-❯ /mcp env asoba ASOBA_API_KEY
-✓ Cleared ASOBA_API_KEY on asoba
+❯ /mcp env unset asoba ASOBA_API_KEY
+✓ Unset ASOBA_API_KEY on asoba
 ```
 
 **Tip:** Keys are masked in `/mcp env` output. Only the first 6 and last 4 characters are shown.
@@ -430,19 +430,23 @@ Numeric values are auto-converted. Changes persist in the local settings databas
 
 ## SDLC Workflow
 
-The engine enforces state transitions across six distinct phases:
+The engine enforces state transitions across seven distinct phases, aligned with the AGENTS.md TDD mandate:
 
-1. **`idle`**: Discovery and triage. Mutating file tools are physically masked out. Safety and analysis tools are available on-demand.
+1. **`idle`**: Discovery and triage. Mutating file tools are available. Safety and analysis tools are available on-demand.
 
-2. **`plan`**: Model formulates success criteria and implementation steps (`EnterPlanMode`). No tools available.
+2. **`explore`**: Codebase exploration only. `lib/explore.mjs` drives this phase — the model uses Glob, Grep, and Read to aggregate file summaries before entering planning. Ends when the model outputs `Exploration complete.`
 
-3. **`implement`**: Code changes applied using file editing and shell execution (`ExitPlanMode`).
+3. **`planning`**: Model formulates a plan using exploration summaries (`EnterPlanMode`). Mutating tools are blocked until a plan is approved. No code changes permitted.
 
-4. **`test`**: Automated test generation and execution (`SubmitImplementation`). **After tests pass, all tools marked `mandatory_in: ["test"]` must be run.** The system prompt enforces this — the model cannot declare success until all mandatory safety checkers pass.
+4. **`test`**: Behavioral test creation and RED confirmation. The model writes tests and runs them to confirm they fail for the diagnosed reason. **Gated:** `planning → implement` is blocked until at least one RED test result is recorded here.
 
-5. **`verify`**: Inspection of test outputs and coverage verification (`SubmitTest`).
+5. **`implement`**: Code changes applied using file editing and shell execution (`ExitPlanMode`). Only reachable after a confirmed RED test exists and a plan is approved.
 
-6. **`done`**: Final sign-off and git commit creation.
+6. **`test`**: Automated test execution to verify GREEN (`SubmitImplementation`). **All tools marked `mandatory_in: ["test"]` must run and pass** before this phase can advance — the system prompt enforces this.
+
+7. **`verify`**: Inspection of test outputs and coverage verification (`SubmitTest`). **Gated:** requires all test results passing and at least one safety checker event recorded.
+
+8. **`done`**: Final sign-off and git commit creation.
 
 ---
 
@@ -494,11 +498,40 @@ node tests/unit/gap4_pinned_compaction_behavioral.mjs
 node tests/unit/ui_legibility_behavioral.mjs
 ```
 
+Run the Ollama, spinner, and Laya behavioral suites:
+
+```bash
+node tests/unit/test-ollama-llm-call-behavioral.mjs
+node tests/unit/test-ollama-permission-prompt-behavioral.mjs
+node tests/unit/laya_warm_load_behavioral.mjs
+node tests/unit/issue22_query_context_behavioral.mjs
+```
+
 ---
 
 ## Changelog
 
-### 0.7.0
+### 0.9.0
+
+- **AGENTS.md SDLC workflow + local issue tracking (`lib/workflow.mjs`, `lib/issues.mjs`, `lib/explore.mjs`):** The orchestrator now enforces the full E-P-C-V-D workflow defined in AGENTS.md — Explore, Plan, Confirm, Code, Validate. A local `.issues/` directory tracks open and closed issues with structured metadata (observed behavior, diagnosis, acceptance criteria). `lib/explore.mjs` drives the EXPLORE phase, aggregating file summaries before entering PLANNING. Closes #15.
+
+- **Generic agent config restored to `~/.config/nehanda` (`lib/settings.mjs`, `scripts/postinstall.mjs`):** Removed the `.aimee` dependency and all references to the legacy agent registry. Agent configuration now lives exclusively at `~/.config/nehanda/agents.json`, consistent with the documented config file locations. Closes #16.
+
+- **Working directory in welcome banner and footer (`bin/nehanda-ui.mjs`):** The TUI banner displayed on startup and the status footer both now show the current working directory, giving researchers immediate confirmation of which project root is active before issuing any commands. Closes #17.
+
+- **Spinner stabilization: AskPrompt, spitfire suppression, null-safe `askHuman` (`bin/nehanda-ui.mjs`):** Fixed three related spinner regressions: (1) the spinner was visible and cycling behind interactive `io.ask` permission prompts, obscuring the question; (2) rapid `bridge.updateSpinner` calls between tool results caused visible label flicker (spitfire); (3) `askHuman` threw on a null `io` reference in headless contexts. Closes #18.
+
+- **Ollama LLM call path: behavioral coverage + documentation (`lib/orchestrate.mjs`, `tests/unit/test-ollama-llm-call-behavioral.mjs`, `docs/MAP.md`):** Full behavioral RED/GREEN test suite for the Ollama call path — `detectOllamaToolSupport` probe logic (capabilities, template, modelfile fields, HTTP error fail-open), native vs. manual tool injection dispatch, `Authorization: Bearer ollama` header, `OLLAMA_BASE_URL` env var resolution, and `buildSystemPrompt` injection format. `docs/MAP.md` documents the full call path contract. Closes #19.
+
+- **Turn-start and probe spinner stabilization (`bin/nehanda-ui.mjs`, `lib/orchestrate.mjs`):** Prior to this fix, the spinner had no label during the gap between turn submission and the first model event — cycling generic `TOOL_VERBS` while Laya intent classification and the Ollama `detectOllamaToolSupport` probe (up to 3 s) ran silently. Fixed by pre-seeding `bridge.updateSpinner('Analyzing')` immediately on submit and `io.spinner.start('Analyzing')` at `runSdlcOpenAICompat` entry. Behavioral coverage in `tests/unit/test-ollama-permission-prompt-behavioral.mjs`. Closes #20.
+
+- **Laya sidecar startup warming (`lib/laya_sidecar.mjs`):** `ensureLayaReady()` now calls `loadLaya()` (`method: 'load'`) instead of `pingLaya()` (`method: 'ping'`). The `ping` path responded immediately without loading model weights, leaving the first user-turn `classifyUserIntent` call to cold-load the 322M-parameter checkpoint mid-turn (200–400 ms stall). `load` invokes `_ensure_loaded()` in `laya_worker.py`, priming both `noul` and `choice` criteria into MPS/CPU RAM before the first turn. Behavioral coverage in `tests/unit/laya_warm_load_behavioral.mjs`. Closes #21.
+
+- **Grounded query context, Ollama `think:false`, reasoning token streaming, instant Esc cancel (`lib/orchestrate.mjs`, `lib/openaiCompat.mjs`, `bin/nehanda-ui.mjs`):** Four improvements to reduce reasoning model overhead and improve cancellation UX: (1) `buildSystemPrompt` appends an explicit `[GROUNDED FACTS]` block (date, cwd, platform, shell) to every phase prompt so models never spend tokens debating their own awareness; (2) `streamOpenAIChatCompletion` now parses `delta.reasoning` and `delta.reasoning_content` SSE fields and updates the spinner live — `⠋ Thinking (42 tokens)…` — rather than sitting frozen during the thinking phase; (3) a `think: false` option is forwarded to the Ollama API request body when `model_config.thinking === false`, disabling chain-of-thought for supported models; (4) `detectOllamaToolSupport` now accepts `rt.signal` composed via `AbortSignal.any([signal, AbortSignal.timeout(3000)])` so Esc cancels the capability probe immediately rather than waiting the full 3 s timeout, and `bridge.abortCurrent` updates the spinner to `Cancelling…` before invoking `controller.abort()`. Behavioral coverage in `tests/unit/issue22_query_context_behavioral.mjs`. Closes #22.
+
+### 0.8.0
+
+- **Full `/help` + explicit MCP env unset (`lib/slashCommands.mjs`, `bin/nehanda-ui.mjs`):** `/help` lists every command and subcommand (`/key` variants, full `/mcp` surface). Omitting a VALUE no longer silently clears env vars — use `/mcp env unset <server> <NAME>` (or `clear`). Autocomplete stays top-level unless you type `/mcp` or `/key`. Behavioral coverage in `tests/unit/help_commands_behavioral.mjs`. Closes #9.
 
 - **Unified `/model` configure wizard with keyed discovery (`lib/configureProvider.mjs`, `lib/modelDiscovery.mjs`, `bin/nehanda-ui.mjs`):** Provider setup is a single Goose-style flow — provider → API key → host → live model catalog → select → persist. OpenRouter / OpenAI-compat / Zhipu / Nehanda / LM Studio discover via authenticated `GET {base}/models`; Ollama keeps `/api/tags`. Discovery failure falls back to custom model name. `/key <provider>` chains into the same wizard tail. `/config` is read-only status. Behavioral coverage in `tests/unit/configure_provider_behavioral.mjs`. Closes #8.
 
@@ -539,7 +572,7 @@ node tests/unit/ui_legibility_behavioral.mjs
 ### 0.2.0
 - Jev-Mem memory architecture (System-1 Laya control plane)
 - Dynamic Tool Rescue (`[TOOL_CALL]` delimiter path)
-- Deterministic 6-phase SDLC workflow
+- Deterministic SDLC workflow (expanded to 7 phases in 0.9.0)
 - Multi-provider switching
 
 ---

package/bin/agent.mjs

@@ -21,6 +21,7 @@ import { executeBuiltinTool, invalidateMcpToolCache } from '../lib/tools.mjs'
 import { appendEntry, makeUserPayload, makeToolResultPayload } from '../lib/transcript.mjs'
 import { loadInstructions } from '../lib/instructions.mjs'
 import { discoverModelsForProvider, formatModelList } from '../lib/modelDiscovery.mjs'
+import { parseMcpEnvParts } from '../lib/slashCommands.mjs'
 import { compactConversation } from '../lib/compact.mjs'
 import { createTeam, getTeam, listTeams, deleteTeam } from '../lib/team.mjs'
 import { ensureLayaReady } from '../lib/laya_sidecar.mjs'
@@ -165,16 +166,19 @@ Tools:
   /team         Manage teams
 
 Session:
-  /model [name] Change model
-  /models       Discover available models
+  /model        Configure provider → key → host → model
+  /models       Discover available models for active provider
+  /key          Provider API keys (see /help in nehanda TUI for variants)
   /login        Authenticate
   /logout       Clear credentials
   /status       Auth status
   /config       Settings (try /config set <key> <value>)
-  /mcp          MCP server management & guide
-  /mcp list     List all discovered tools & descriptions
-  /mcp status   Show configured MCP servers
-  /mcp env      Set MCP env vars (API keys)
+  /mcp          MCP guide (list · status · reload · add · env)
+  /mcp list     List tools from configured MCP servers
+  /mcp status   Show configured servers
+  /mcp env      Show env vars (masked)
+  /mcp env <server> <NAME> <VALUE>   Set env var
+  /mcp env unset <server> <NAME>     Remove env var
   /clear        New conversation
   /exit         Quit`)
       return
@@ -531,11 +535,14 @@ Session:
       if (!sub || sub === 'help') {
         const lines = [
           'MCP Server & Tool Commands:',
-          '  /mcp list                  Discover and list all available MCP tools',
-          '  /mcp status                Show configured servers and command paths',
-          '  /mcp reload [server]       Reload mcp.json configs into session',
-          '  /mcp add <name> <cmd> […]  Register a new MCP server',
-          '  /mcp env [server] [K] [V]  View or set server environment variables',
+          '  /mcp list                              List tools from configured MCP servers',
+          '  /mcp status                            Show configured servers',
+          '  /mcp reload [server]                   Reload mcp.json into this session',
+          '  /mcp add <name> <command> [args…]      Register a server',
+          '  /mcp env                               Show env vars for every server (values masked)',
+          '  /mcp env <server>                      Show env vars for one server',
+          '  /mcp env <server> <NAME> <VALUE>       Set env var  e.g. /mcp env jupyter JUPYTER_TOKEN sk-…',
+          '  /mcp env unset <server> <NAME>         Remove an env var',
           '',
           `Configured servers: ${serverNames.length ? serverNames.join(', ') : 'none'}`,
           'Tip: Run /mcp list to inspect tools injected into the assistant.',
@@ -619,10 +626,12 @@ Session:
       }
 
       if (sub === 'env') {
-        const srvName = parts[2]
-        const envKey = parts[3]
-        if (!srvName) {
-          // Show env for all servers
+        const parsed = parseMcpEnvParts(parts.slice(1))
+        if (parsed.action === 'usage_error') {
+          app.addSystemMessage(parsed.error)
+          return
+        }
+        if (parsed.action === 'list_all') {
           const mcpServers = settings?.mcp_servers || {}
           const names = Object.keys(mcpServers)
           if (!names.length) { app.addSystemMessage('No MCP servers configured.'); return }
@@ -645,13 +654,15 @@ Session:
           app.addSystemMessage(lines.join('\n'))
           return
         }
-        if (!envKey) {
-          // Show env for a specific server
-          const cfg = (settings?.mcp_servers || {})[srvName]
-          if (!cfg) { app.addSystemMessage(`Server "${srvName}" not found. Use /mcp status to see configured servers.`); return }
+        if (parsed.action === 'list_server') {
+          const cfg = (settings?.mcp_servers || {})[parsed.server]
+          if (!cfg) { app.addSystemMessage(`Server "${parsed.server}" not found. Use /mcp status to see configured servers.`); return }
           const envKeys = Object.keys(cfg.env || {})
-          if (!envKeys.length) { app.addSystemMessage(`${srvName}: no env vars set\nUse /mcp env ${srvName} <KEY> <value> to set one.`); return }
-          const lines = [`${srvName} environment variables:`]
+          if (!envKeys.length) {
+            app.addSystemMessage(`${parsed.server}: no env vars set\nUse /mcp env ${parsed.server} <NAME> <VALUE> to set one.`)
+            return
+          }
+          const lines = [`${parsed.server} environment variables:`]
           for (const k of envKeys) {
             const v = cfg.env[k]
             const masked = v ? v.slice(0, 6) + '…' + v.slice(-4) : '(empty)'
@@ -660,25 +671,25 @@ Session:
           app.addSystemMessage(lines.join('\n'))
           return
         }
-        // Set or clear an env var
-        const value = parts.slice(4).join(' ')
-        const result = updateMcpServerEnv(srvName, envKey, value, cwd)
-        if (!result.ok) {
-          app.addSystemMessage(`✗ ${result.error}`)
+        if (parsed.action === 'set' || parsed.action === 'unset') {
+          const value = parsed.action === 'unset' ? '' : parsed.value
+          const result = updateMcpServerEnv(parsed.server, parsed.name, value, cwd)
+          if (!result.ok) {
+            app.addSystemMessage(`✗ ${result.error}`)
+            return
+          }
+          settings.mcp_servers = {}
+          applyMcpConfig(settings, cwd)
+          invalidateMcpToolCache()
+          const action = parsed.action === 'set' ? 'Set' : 'Unset'
+          const display = parsed.action === 'set' ? ' = ********' : ''
+          const relPath = path.relative(os.homedir(), result.path).startsWith('..') ? result.path : '~/' + path.relative(os.homedir(), result.path)
+          app.addSystemMessage(`✓ ${action} ${parsed.name}${display} on ${parsed.server}\n  Config file: ${relPath}`)
           return
         }
-        // Reload to pick up the change
-        settings.mcp_servers = {}
-        applyMcpConfig(settings, cwd)
-        invalidateMcpToolCache()
-        const action = result.set ? 'Set' : 'Cleared'
-        const display = result.set ? ' = ********' : ''
-        const relPath = path.relative(os.homedir(), result.path).startsWith('..') ? result.path : '~/' + path.relative(os.homedir(), result.path)
-        app.addSystemMessage(`✓ ${action} ${envKey}${display} on ${srvName}\n  Config file: ${relPath}`)
-        return
       }
 
-      app.addSystemMessage('/mcp sub-commands: status · list · reload [server] · add <name> <command> [args…] · env [server] [KEY] [value]')
+      app.addSystemMessage('/mcp sub-commands: status · list · reload · add · env · env unset — type /help for full list')
       return
     }
 
@@ -1070,7 +1081,10 @@ function resolveModelArg(arg) {
   
   // First, try exact match in hardcoded WIRE map (backward compatibility)
   if (arg.includes('/')) {
-    const [p, m] = arg.split('/', 2)
+    // Split on the FIRST "/" only — the model name may itself contain slashes (#12)
+    const slashIdx = arg.indexOf('/')
+    const p = arg.slice(0, slashIdx)
+    const m = arg.slice(slashIdx + 1)
     
     // Validate provider and model_id are non-empty
     if (!p || !p.trim()) {