hoomanjs 1.33.0 → 1.35.0

package/README.md

@@ -21,7 +21,7 @@ It gives you a practical toolkit to build and run agent workflows:
 - a one-shot `exec` command for single prompts
 - a stateful `chat` interface for iterative sessions
 - a `daemon` command for channel-driven MCP automation
-- an in-chat `/config` workflow (Ink-powered) for app config, prompts, MCP servers, and installed skills
+- an in-chat `/config` workflow (Ink-powered) for general settings, models, MCP servers, and installed skills
 - an `acp` command for running Hooman as an Agent Client Protocol (ACP) agent over stdio
 
 ## Related
@@ -30,7 +30,7 @@ It gives you a practical toolkit to build and run agent workflows:
 
 ## Features
 
-- Multiple LLM providers: `anthropic`, `bedrock`, `google`, `groq`, `moonshot`, `ollama`, `openai`, `xai`
+- Multiple LLM providers: `anthropic`, `azure`, `bedrock`, `google`, `groq`, `minimax`, `moonshot`, `ollama`, `openai`, `openrouter`, `xai`
 - Local configuration under `~/.hooman`
 - Optional web search tool with provider selection (`brave`, `exa`, `firecrawl`, `serper`, or `tavily`)
 - MCP server support via `stdio`, `streamable-http`, and `sse`
@@ -38,7 +38,7 @@ It gives you a practical toolkit to build and run agent workflows:
 - MCP channel notifications: `hooman daemon` subscribes to servers that advertise `hooman/channel`
 - Runtime skills via Strands `AgentSkills`, loading bundled built-in skills plus local `~/.hooman/skills`
 - Bundled prompt harness toggles (`behaviour`, `communication`, `execution`, `guardrails`); coding guidance ships as the built-in `hooman-coding` skill
-- Built-in research sub-agent runner (`research`) with configurable concurrency
+- Built-in read-only subagent tools (`subagent_research`, `subagent_review`, `subagent_test_investigator`)
 - Built-in `grep` tool backed by ripgrep (`rg`), with runtime bootstrap when `rg` is not available on PATH
 - Toolkit-oriented architecture with configurable tools, prompts, and transports
 - Interactive terminal UI for chat and configuration
@@ -231,6 +231,15 @@ Log raw notification payloads:
 hooman daemon --debug
 ```
 
+### `hooman config`
+
+Print the effective runtime `config.json` for the current working directory in
+the same shape as `config.json`, with credential-like values redacted.
+
+```bash
+hooman config
+```
+
 ### Feature Flags
 
 Runtime tool and prompt switches are controlled from `config.json`:
@@ -251,12 +260,11 @@ Runtime tool and prompt switches are controlled from `config.json`:
 - `tools.filesystem.enabled`
 - `tools.shell.enabled`
 - `tools.sleep.enabled`
-- `tools.agents.enabled` (enables built-in `run_subagents` tool)
-- `tools.agents.concurrency` (defaults to `3` when omitted on load; a freshly generated default `config.json` uses `2`)
+- `tools.subagents.enabled` (enables built-in subagent tools)
 
 ### `/config`
 
-The configuration workflow is launched from inside a `chat` session with the `/config` slash command (there is no separate top-level `configure` command). It takes over the terminal on the alternate screen buffer while open, and restores the chat session on exit. Any config changes are picked up when the session re-bootstraps.
+The interactive configuration workflow is launched from inside a `chat` session with the `/config` slash command (there is no separate top-level `configure` command). It takes over the terminal on the alternate screen buffer while open, and restores the chat session on exit. Any config changes are picked up when the session re-bootstraps.
 
 ```text
 /config
@@ -264,11 +272,12 @@ The configuration workflow is launched from inside a `chat` session with the `/c
 
 The configuration UI currently lets you:
 
-- edit app configuration values
+- manage general settings such as name, prompts, tools, and compaction
+- manage models and providers with field-by-field editors
 - choose search provider and set its API key
 - toggle bundled harness prompts (`behaviour`, `communication`, `execution`, `guardrails`)
 - edit `instructions.md` in your `$VISUAL` / `$EDITOR` (cross-platform fallback included)
-- add, edit, and delete MCP servers with confirmation
+- add, edit, and delete MCP servers with field-by-field editors and confirmation
 - search, install, refresh, and remove skills
 
 ### `hooman acp`
@@ -283,8 +292,7 @@ ACP notes:
 
 - ACP sessions are stored under the active Hooman data directory in `acp-sessions/`
 - ACP loads MCP servers passed on `session/new` and `session/load`, in addition to Hooman's local `mcp.json`
-- ACP `session/new` and `session/load` support `_meta.userId` and `_meta.systemPrompt`
-- when `_meta.systemPrompt` is provided, it is appended to the agent system prompt with a section break
+- ACP `session/new` and `session/load` support `_meta.userId`
 - session configuration includes `hooman.sessionMode` (`agent`, `plan`, or `ask`); see [Session mode](#session-mode)
 
 ## Configuration Layout
@@ -306,6 +314,33 @@ Important files and folders:
 - `sessions/` - persisted session data
 - `acp-sessions/` - persisted ACP session metadata and message snapshots
 
+### Repo-local runtime overlays
+
+At runtime, Hooman resolves configuration in this order:
+
+1. `~/.hooman/config.json` and `~/.hooman/mcp.json`
+2. `<git-root>/config.json` and `<git-root>/mcp.json` (if present)
+3. matching files in nested directories from git root to current working directory
+
+Nearest files win when keys overlap.
+
+For app config (`config.json`):
+
+- plain objects are deep-merged
+- scalar values are overridden by the nearest file
+- `providers` and `llms` are merged by `name` (nearest entry with the same name replaces inherited entries)
+
+For MCP config (`mcp.json`):
+
+- `mcpServers` is merged by server name (nearest entry with the same name wins)
+
+Notes:
+
+- Runtime overlays apply to `chat`, `exec`, `daemon`, and `acp` bootstraps.
+- `hooman config` prints only the merged effective `config.json` shape with credential-like values redacted.
+- The `/config` UI and `hooman mcp auth/logout/auth-status` still target home config (`~/.hooman/*`) directly.
+- Keep secrets in home config unless you explicitly want project-scoped credentials.
+
 `grep` tool binary resolution order:
 
 1. Use system `rg` when available.
@@ -314,27 +349,24 @@ Important files and folders:
 
 ## Example `config.json`
 
-The on-disk shape uses a reusable **`providers`** array plus a non-empty **`llms`** array. Each provider stores the shared runtime type and params once; each LLM references a provider by name, sets its `model`, optional model-specific `params`, and `default`. The bundled **hooman-config** skill documents the full schema.
+The on-disk shape uses a reusable **`providers`** array plus a non-empty **`llms`** array. Each provider stores a runtime `provider` id plus provider-specific `options`; each LLM references a provider by name, stores its model `options`, and marks one entry as the default. The bundled **hooman-config** skill documents the full schema.
 
 ```json
 {
   "name": "Hooman",
   "providers": [
     {
-      "name": "ollama-local",
-      "options": {
-        "provider": "ollama",
-        "params": {}
-      }
+      "name": "Ollama",
+      "provider": "ollama",
+      "options": {}
     }
   ],
   "llms": [
     {
       "name": "Default",
+      "provider": "Ollama",
       "options": {
-        "provider": "ollama-local",
-        "model": "gemma4:e4b",
-        "params": {}
+        "model": "gemma4:e4b"
       },
       "default": true
     }
@@ -355,25 +387,12 @@ The on-disk shape uses a reusable **`providers`** array plus a non-empty **`llms
     "guardrails": true
   },
   "tools": {
-    "todo": {
-      "enabled": true
-    },
-    "fetch": {
-      "enabled": true
-    },
-    "filesystem": {
-      "enabled": true
-    },
-    "shell": {
-      "enabled": true
-    },
-    "sleep": {
-      "enabled": true
-    },
-    "agents": {
-      "enabled": true,
-      "concurrency": 2
-    }
+    "todo": { "enabled": true },
+    "fetch": { "enabled": true },
+    "filesystem": { "enabled": true },
+    "shell": { "enabled": true },
+    "sleep": { "enabled": true },
+    "subagents": { "enabled": true }
   },
   "compaction": {
     "ratio": 0.75,
@@ -386,19 +405,20 @@ Tool approvals are session-scoped and are not persisted in `config.json`.
 
 Hooman enables Strands `ContextOffloader` by default with file-backed storage under `~/.hooman/sessions/offloaded-content`, so large tool results can be previewed in-context and retrieved later without bloating the active conversation window.
 
-Supported `providers[].options.provider` values registered in this release (see `src/core/models/index.ts`):
+Supported `providers[].provider` values registered in this release (see `src/core/models/index.ts`):
 
 - `anthropic`
+- `azure`
 - `bedrock`
 - `google`
 - `groq`
+- `minimax`
 - `moonshot`
 - `ollama`
 - `openai`
+- `openrouter`
 - `xai`
 
-The `LlmProvider` enum in `src/core/config.ts` may list additional strings for forwards compatibility; unknown providers are not loaded at runtime.
-
 Supported `search.provider` values:
 
 - `brave`
@@ -409,253 +429,62 @@ Supported `search.provider` values:
 
 ## Provider Notes
 
-### Ollama
-
-Good default for local usage. Example:
-
-```json
-{
-  "providers": [
-    {
-      "name": "ollama-local",
-      "options": {
-        "provider": "ollama",
-        "params": {}
-      }
-    }
-  ],
-  "llms": [
-    {
-      "name": "Default",
-      "options": {
-        "provider": "ollama-local",
-        "model": "gemma4:e4b",
-        "params": {}
-      },
-      "default": true
-    }
-  ]
-}
-```
-
-### OpenAI
-
-Uses Strands **OpenAIModel** (Chat Completions). `apiKey` is optional if `OPENAI_API_KEY` is set. Use `clientConfig` for a custom base URL or other OpenAI client options (OpenAI-compatible proxies and gateways).
-
-Example:
-
-```json
-{
-  "providers": [
-    {
-      "name": "openai",
-      "options": {
-        "provider": "openai",
-        "params": {
-          "apiKey": "..."
-        }
-      }
-    }
-  ],
-  "llms": [
-    {
-      "name": "GPT-5",
-      "options": {
-        "provider": "openai",
-        "model": "gpt-5",
-        "params": {}
-      },
-      "default": true
-    }
-  ]
-}
-```
-
-OpenAI-compatible gateways that put token `usage` on the last streamed chunk together with `choices` are handled via a small stream shim so usage still surfaces in the UI.
-
-### Anthropic
-
-Uses Strands **AnthropicModel** (Anthropic Messages API). `apiKey` or `authToken`, optional `baseURL` and `headers` (merged into `clientConfig`), optional `clientConfig`, and model fields such as `temperature` and `maxTokens`. A prebuilt `client` is not configurable from JSON.
-
-```json
-{
-  "providers": [
-    {
-      "name": "anthropic",
-      "options": {
-        "provider": "anthropic",
-        "params": {
-          "apiKey": "..."
-        }
-      }
-    }
-  ],
-  "llms": [
-    {
-      "name": "Claude Sonnet",
-      "options": {
-        "provider": "anthropic",
-        "model": "claude-sonnet-4-20250514",
-        "params": {
-          "temperature": 0.7
-        }
-      },
-      "default": true
-    }
-  ]
-}
-```
-
-### Google
-
-Uses Strands `GoogleModel` on top of `@google/genai`. Top-level options like `apiKey`, `client`, `clientConfig`, and `builtInTools` are supported; other values go into Google generation params.
-
-```json
-{
-  "providers": [
-    {
-      "name": "google",
-      "options": {
-        "provider": "google",
-        "params": {
-          "apiKey": "..."
-        }
-      }
-    }
-  ],
-  "llms": [
-    {
-      "name": "Gemini Flash",
-      "options": {
-        "provider": "google",
-        "model": "gemini-2.5-flash",
-        "params": {
-          "temperature": 0.7,
-          "maxOutputTokens": 2048,
-          "topP": 0.9,
-          "topK": 40
-        }
-      },
-      "default": true
-    }
-  ]
-}
-```
-
-### Bedrock
-
-Supports `region`, `clientConfig`, and optional `apiKey`, with all other values forwarded as Bedrock model options.
-
-```json
-{
-  "providers": [
-    {
-      "name": "bedrock-dev",
-      "options": {
-        "provider": "bedrock",
-        "params": {
-          "region": "us-east-1",
-          "clientConfig": {
-            "profile": "dev",
-            "maxAttempts": 3,
-            "credentials": {
-              "accessKeyId": "AKIA...",
-              "secretAccessKey": "...",
-              "sessionToken": "..."
-            }
-          }
-        }
-      }
-    }
-  ],
-  "llms": [
-    {
-      "name": "Claude Sonnet",
-      "options": {
-        "provider": "bedrock-dev",
-        "model": "anthropic.claude-sonnet-4-20250514-v1:0",
-        "params": {
-          "temperature": 0.7,
-          "maxTokens": 1024
-        }
-      },
-      "default": true
-    }
-  ]
-}
-```
-
-You can also rely on the AWS default credential chain (recommended) by setting environment variables such as `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SESSION_TOKEN`.
-
-### Groq
-
-### Anthropic
-
-Uses Strands `AnthropicModel` on top of `@anthropic-ai/sdk`. Provider-specific settings `apiKey`/`authToken`, `baseURL`, `headers`, `clientConfig`, `betas`, and `useNativeTokenCount` are picked up directly. Standard model config such as `temperature`, `topP`, `maxTokens`, and `stopSequences` stays top-level. Any other keys are forwarded to the Anthropic Messages request body, which is useful for Anthropic-compatible providers such as MiniMax.
-
-For MiniMax specifically:
-
-- Use `baseURL: "https://api.minimax.io/anthropic"`.
-- `MiniMax-M3` can emit visible thinking blocks when you set `thinking: { "type": "adaptive" }`.
-- `MiniMax-M2.7` / `M2.5` / `M2.1` / `M2` do internal reasoning, but MiniMax’s Anthropic-compatible API does not expose those as `thinking` content blocks, so Hooman has nothing to render in the transcript.
+Provider entries now look like:
 
 ```json
 {
-  "provider": "anthropic",
-  "model": "MiniMax-M3",
-  "params": {
-    "apiKey": "...",
-    "baseURL": "https://api.minimax.io/anthropic",
-    "thinking": { "type": "adaptive" },
-    "temperature": 1
+  "name": "MiniMax",
+  "provider": "minimax",
+  "options": {
+    "apiKey": "..."
   }
 }
 ```
 
-### Groq
-
-Uses the Vercel AI SDK Groq provider (`@ai-sdk/groq`) on top of Strands `VercelModel`. Provider-specific settings `apiKey`, `baseURL`, and `headers` are picked up; other values are forwarded into the model config (`temperature`, `maxTokens`, etc.). Defaults to `GROQ_API_KEY` from the environment when no `apiKey` is supplied.
+LLM entries reference a provider by name and carry normalized model options:
 
 ```json
 {
-  "provider": "groq",
-  "model": "gemma2-9b-it",
-  "params": {
-    "apiKey": "...",
-    "temperature": 0.7
-  }
+  "name": "MiniMax M3",
+  "provider": "MiniMax",
+  "options": {
+    "model": "MiniMax-M3",
+    "temperature": 1,
+    "maxTokens": 4096
+  },
+  "default": true
 }
 ```
 
-### Moonshot
+Supported provider option fields:
 
-Uses the Vercel AI SDK Moonshot provider (`@ai-sdk/moonshotai`) on top of Strands `VercelModel`. Provider-specific settings `apiKey`, `baseURL`, `headers`, and `fetch` are picked up; other values are forwarded into the model config (`temperature`, `maxTokens`, `providerOptions`, etc.). Defaults to `MOONSHOT_API_KEY` from the environment when no `apiKey` is supplied. Moonshot reasoning models such as `kimi-k2-thinking` can be configured through `params.providerOptions.moonshotai`.
+- `anthropic`: `apiKey`, optional `baseURL`, optional `headers`, optional `thinking`
+- `azure`: optional `resourceName`, optional `baseURL`, optional `apiKey`, optional `headers`, optional `apiVersion`, optional `useDeploymentBasedUrls`
+- `bedrock`: `region`, `accessKeyId`, `secretAccessKey`, optional `sessionToken`, optional `apiKey`
+- `google`: `apiKey`
+- `groq`: `apiKey`, optional `baseURL`, optional `headers`
+- `minimax`: `apiKey`, optional `headers`, optional `thinking`
+- `moonshot`: `apiKey`, optional `baseURL`, optional `headers`
+- `ollama`: optional `baseURL`, optional `thinking`
+- `openai`: `apiKey`, optional `baseURL`, optional `headers`
+- `openrouter`: `apiKey`, optional `baseURL`, optional `headers`
+- `xai`: `apiKey`, optional `baseURL`, optional `headers`
 
-```json
-{
-  "provider": "moonshot",
-  "model": "kimi-k2.5",
-  "params": {
-    "apiKey": "...",
-    "temperature": 0.7
-  }
-}
-```
+Normalized LLM option fields:
 
-### xAI
+- `model`
+- optional `temperature`
+- optional `maxTokens`
 
-Uses the Vercel AI SDK xAI provider (`@ai-sdk/xai`) on top of Strands `VercelModel`. Provider-specific settings `apiKey`, `baseURL`, and `headers` are picked up; other values are forwarded into the model config (`temperature`, `maxTokens`, etc.). Defaults to `XAI_API_KEY` from the environment when no `apiKey` is supplied.
+Notes:
 
-```json
-{
-  "provider": "xai",
-  "model": "grok-4.20-non-reasoning",
-  "params": {
-    "apiKey": "...",
-    "temperature": 0.7
-  }
-}
-```
+- Google maps normalized `maxTokens` to the SDK's `maxOutputTokens` internally.
+- Azure uses the Vercel AI SDK `@ai-sdk/azure` provider. Set the LLM `model` to your Azure deployment name, not the raw OpenAI model id.
+- Ollama maps normalized `temperature` into Ollama `options.temperature`.
+- MiniMax uses the Anthropic-compatible endpoint `https://api.minimax.io/anthropic` automatically.
+- Moonshot defaults `baseURL` to `https://api.moonshot.ai/v1` when it is omitted.
+- OpenRouter defaults `baseURL` to `https://openrouter.ai/api/v1` when it is omitted, and model names are usually provider-qualified ids such as `anthropic/claude-3.5-sonnet`.
+- Bedrock can rely on the AWS default credential chain when explicit credentials are not provided.
 
 ## MCP Configuration
 
@@ -669,6 +498,8 @@ Detailed design notes for planned OAuth-enabled remote MCP support live in [docs
 }
 ```
 
+At runtime, project-local `mcp.json` files are merged on top of `~/.hooman/mcp.json` from git root to current directory. On name conflicts, the nearest `mcpServers.<name>` entry wins.
+
 ### Example stdio server
 
 ```json
@@ -797,6 +628,19 @@ Run typecheck:
 npm run typecheck
 ```
 
+Build the project:
+
+```bash
+npm run build
+```
+
+After making any code change, run both verification steps:
+
+```bash
+npm run typecheck
+npm run build
+```
+
 ## License
 
 MIT. See `LICENSE`.

package/dist/acp/acp-agent.js

@@ -17,7 +17,6 @@ import { copyAgentAppState } from "../core/state/agent-app-state.js";
 import { getModeState } from "../core/state/session-mode.js";
 import { ENTER_PLAN_MODE_TOOL, EXIT_PLAN_MODE_TOOL, } from "../core/state/tool-approvals.js";
 import { isYoloEnabled } from "../core/state/yolo.js";
-import { extractAcpClientSystemPrompt } from "./meta/system-prompt.js";
 import { extractAcpClientUserId } from "./meta/user-id.js";
 import { deriveSessionTitleFromEcho } from "./sessions/title.js";
 import { acpPromptEchoText, acpPromptToInvokeArgs } from "./prompt-invoke.js";
@@ -230,7 +229,6 @@ export class AcpAgent {
         assertAbsolutePath(params.cwd, "cwd");
         const sessionId = crypto.randomUUID();
         const clientUserId = extractAcpClientUserId(params._meta) ?? null;
-        const clientSystemPrompt = extractAcpClientSystemPrompt(params._meta) ?? null;
         const bootstrapUserId = clientUserId ?? sessionId;
         const mcpServers = normalizeAcpSessionMcpServers(params.mcpServers);
         const now = new Date().toISOString();
@@ -240,7 +238,6 @@ export class AcpAgent {
             updatedAt: now,
             title: null,
             userId: clientUserId,
-            systemPrompt: clientSystemPrompt,
             mcpServers,
         };
         await writeSessionMeta(this.#acpRoot, sessionId, meta);
@@ -253,7 +250,6 @@ export class AcpAgent {
             ],
             acp: {
                 mcpServers,
-                ...(clientSystemPrompt ? { systemPrompt: clientSystemPrompt } : {}),
             },
         }, false, createSessionConfig());
         const config = bootConfig;
@@ -308,13 +304,8 @@ export class AcpAgent {
         }
         assertAbsolutePath(params.cwd, "cwd");
         const fromRequest = extractAcpClientUserId(params._meta);
-        const requestedSystemPrompt = extractAcpClientSystemPrompt(params._meta);
         const storedUserId = existing.userId ?? null;
-        const storedSystemPrompt = existing.systemPrompt ?? null;
         const clientUserId = fromRequest !== undefined ? fromRequest : storedUserId;
-        const clientSystemPrompt = requestedSystemPrompt !== undefined
-            ? requestedSystemPrompt
-            : storedSystemPrompt;
         const bootstrapUserId = clientUserId ?? params.sessionId;
         const mcpServers = params.mcpServers.length > 0
             ? normalizeAcpSessionMcpServers(params.mcpServers)
@@ -323,14 +314,13 @@ export class AcpAgent {
             userId: bootstrapUserId,
             sessionId: params.sessionId,
             yolo: existing.yolo === true,
-            sessionMode: existing.sessionMode ?? "agent",
+            mode: existing.sessionMode ?? "agent",
             createInterventions: () => [
                 createAcpToolApprovalIntervention(this.#connection, params.sessionId, () => this.#sessions.get(params.sessionId)?.streamedToolCallIds ??
                     EMPTY_STREAMED_TOOL_CALL_IDS),
             ],
             acp: {
                 mcpServers,
-                ...(clientSystemPrompt ? { systemPrompt: clientSystemPrompt } : {}),
             },
         }, false, createSessionConfig());
         const config = bootConfig;
@@ -366,9 +356,6 @@ export class AcpAgent {
             cwd: params.cwd,
             updatedAt: new Date().toISOString(),
             ...(fromRequest !== undefined ? { userId: fromRequest || null } : {}),
-            ...(requestedSystemPrompt !== undefined
-                ? { systemPrompt: requestedSystemPrompt || null }
-                : {}),
             mcpServers,
         });
         return {
@@ -415,14 +402,13 @@ export class AcpAgent {
             userId: bootstrapUserId,
             sessionId,
             yolo: isYoloEnabled(rec.agent),
-            sessionMode: getModeState(rec.agent).mode,
+            mode: getModeState(rec.agent).mode,
             createInterventions: () => [
                 createAcpToolApprovalIntervention(this.#connection, sessionId, () => this.#sessions.get(sessionId)?.streamedToolCallIds ??
                     EMPTY_STREAMED_TOOL_CALL_IDS),
             ],
             acp: {
                 mcpServers,
-                ...(meta.systemPrompt ? { systemPrompt: meta.systemPrompt } : {}),
             },
         }, false, rec.config);
         const config = bootConfig;