hoomanjs 1.29.1 → 1.30.0

package/README.md

@@ -36,10 +36,10 @@ It gives you a practical toolkit to build and run agent workflows:
 - MCP server support via `stdio`, `streamable-http`, and `sse`
 - MCP server `instructions` support: server-provided instructions are appended to the agent system prompt
 - MCP channel notifications: `hooman daemon` subscribes to servers that advertise `hooman/channel`
-- Skill discovery from local `~/.hooman/skills` folders
+- 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
-- Toolkit-oriented architecture with configurable tools, prompts, memory, and transports
+- Toolkit-oriented architecture with configurable tools, prompts, and transports
 - Interactive terminal UI for chat and configuration
 
 ## Requirements
@@ -54,7 +54,7 @@ Fastest way to get started without cloning the repo:
 
 ```bash
 npx hoomanjs configure
-npx hoomanjs chat
+npx hoomanjs
 
 # or install globally
 npm i -g hoomanjs
@@ -64,13 +64,13 @@ Or with Bun:
 
 ```bash
 bunx hoomanjs configure
-bunx hoomanjs chat
+bunx hoomanjs
 ```
 
 Recommended first run:
 
 1. Run `hooman configure` to choose your LLM provider and model.
-2. Start chatting with `hooman chat`.
+2. Start chatting with `hooman` (same as `hooman chat`).
 3. Use `hooman exec "your prompt"` for one-off tasks.
 
 ## Must have
@@ -148,6 +148,12 @@ hooman exec "Map the architecture" --mode ask
 
 Start an interactive stateful chat session.
 
+```bash
+hooman
+```
+
+Equivalent explicit form:
+
 ```bash
 hooman chat
 ```
@@ -180,10 +186,11 @@ hooman chat --mode ask
 
 `exec`, `chat`, and `daemon` accept **`-m` / `--mode`** with:
 
-- **`default`** (default): normal tool surface and approvals.
+- **`agent`** (default): normal tool surface and approvals.
+- **`plan`**: planning workflow with a reduced tool surface plus `enter_plan_mode` / `exit_plan_mode`.
 - **`ask`**: read-oriented, narrower surface (similar to interactive **plan** mode) but **without** `enter_plan_mode` / `exit_plan_mode`.
 
-In **`chat`**, `/mode` can also switch to **plan** (includes plan tools and a plan document workflow). **ACP** sessions can set `hooman.sessionMode` to `default`, `plan`, or `ask`.
+In **`chat`**, `/mode` can switch between **agent**, **ask**, and **plan**. **ACP** sessions can set `hooman.sessionMode` to `agent`, `plan`, or `ask`.
 
 ### `hooman daemon`
 
@@ -233,17 +240,9 @@ Runtime tool and prompt switches are controlled from `config.json`:
 - `tools.filesystem.enabled`
 - `tools.shell.enabled`
 - `tools.sleep.enabled`
-- `tools.memory.enabled`
-- Memory and wiki embedding model URI is fixed in code as `DEFAULT_EMBED_MODEL` in `src/core/config.ts` (not configurable in `config.json`).
-- Local embed GPU selection uses **`HOOMAN_LLAMA_GPU`**: unset defaults to **`auto`** (CI forces CPU off); use `false`, `off`, `none`, `disable`, `disabled`, or `0` for CPU-only; or `metal`, `vulkan`, or `cuda` for an explicit backend. Optional **`HOOMAN_EMBED_CONTEXT_SIZE`** caps embedding context length (tokens).
-- `tools.wiki.enabled`
-- `tools.agents.enabled` (enables built-in `run_agents` tool)
+- `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`)
 
-Long-term memory uses **SQLite + sqlite-vec** at `$HOOMAN_HOME/memory.sqlite` and **local GGUF embeddings** via `node-llama-cpp` (model cache under `$HOOMAN_HOME/.models`). The same **sqlite-vec** native extension requirements apply (see the `sqlite-vec` package and your platform notes).
-
-With **`tools.wiki.enabled`**, the agent gets **`wiki_search`** only: semantic retrieval over the indexed knowledge base. Data lives under `$HOOMAN_HOME/wiki/` with chunks and vectors in **`$HOOMAN_HOME/wiki/content.sqlite`**. The first embed may download the configured GGUF model into `$HOOMAN_HOME/.models`. Documents are ingested as **PDF** (via **OpenDataLoader PDF**, which needs **Java 11+** on `PATH`) or **DOCX** (via **mammoth**).
-
 ### `hooman configure`
 
 Open the Ink configuration workflow.
@@ -275,7 +274,7 @@ ACP notes:
 - 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
-- session configuration includes `hooman.sessionMode` (`default`, `plan`, or `ask`); see [Session mode](#session-mode)
+- session configuration includes `hooman.sessionMode` (`agent`, `plan`, or `ask`); see [Session mode](#session-mode)
 
 ## Configuration Layout
 
@@ -287,10 +286,7 @@ Hooman stores its data in:
 
 Important files and folders:
 
-- `config.json` - app name, LLM provider/model, tool flags, memory/wiki settings, compaction
-- `memory.sqlite` - long-term memory vectors + rows (created when memory tools are used)
-- `.models/` - downloaded GGUF embedding weights (memory + wiki embedders)
-- `wiki/content.sqlite` - wiki document store and semantic chunk index (when wiki is used)
+- `config.json` - app name, reusable provider configs, model configs, tool flags, and compaction
 - `instructions.md` - system instructions used to build the agent prompt
 - `mcp.json` - MCP server definitions
 - `skills/` - installed skills
@@ -299,16 +295,25 @@ Important files and folders:
 
 ## Example `config.json`
 
-The on-disk shape uses a non-empty **`llms`** array: each item has `name`, `options` (`provider`, `model`, `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 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.
 
 ```json
 {
   "name": "Hooman",
+  "providers": [
+    {
+      "name": "ollama-local",
+      "options": {
+        "provider": "ollama",
+        "params": {}
+      }
+    }
+  ],
   "llms": [
     {
       "name": "Default",
       "options": {
-        "provider": "ollama",
+        "provider": "ollama-local",
         "model": "gemma4:e4b",
         "params": {}
       },
@@ -346,12 +351,6 @@ The on-disk shape uses a non-empty **`llms`** array: each item has `name`, `opti
     "sleep": {
       "enabled": true
     },
-    "memory": {
-      "enabled": false
-    },
-    "wiki": {
-      "enabled": false
-    },
     "agents": {
       "enabled": true,
       "concurrency": 2
@@ -366,7 +365,9 @@ The on-disk shape uses a non-empty **`llms`** array: each item has `name`, `opti
 
 Tool approvals are session-scoped and are not persisted in `config.json`.
 
-Supported `llms[].options.provider` values registered in this release (see `src/core/models/index.ts`):
+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`):
 
 - `anthropic`
 - `bedrock`
@@ -395,9 +396,26 @@ Good default for local usage. Example:
 
 ```json
 {
-  "provider": "ollama",
-  "model": "gemma4:e4b",
-  "params": {}
+  "providers": [
+    {
+      "name": "ollama-local",
+      "options": {
+        "provider": "ollama",
+        "params": {}
+      }
+    }
+  ],
+  "llms": [
+    {
+      "name": "Default",
+      "options": {
+        "provider": "ollama-local",
+        "model": "gemma4:e4b",
+        "params": {}
+      },
+      "default": true
+    }
+  ]
 }
 ```
 
@@ -409,11 +427,28 @@ Example:
 
 ```json
 {
-  "provider": "openai",
-  "model": "gpt-5",
-  "params": {
-    "apiKey": "..."
-  }
+  "providers": [
+    {
+      "name": "openai",
+      "options": {
+        "provider": "openai",
+        "params": {
+          "apiKey": "..."
+        }
+      }
+    }
+  ],
+  "llms": [
+    {
+      "name": "GPT-5",
+      "options": {
+        "provider": "openai",
+        "model": "gpt-5",
+        "params": {}
+      },
+      "default": true
+    }
+  ]
 }
 ```
 
@@ -425,12 +460,30 @@ Uses Strands **AnthropicModel** (Anthropic Messages API). `apiKey` or `authToken
 
 ```json
 {
-  "provider": "anthropic",
-  "model": "claude-sonnet-4-20250514",
-  "params": {
-    "apiKey": "...",
-    "temperature": 0.7
-  }
+  "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
+    }
+  ]
 }
 ```
 
@@ -440,15 +493,33 @@ Uses Strands `GoogleModel` on top of `@google/genai`. Top-level options like `ap
 
 ```json
 {
-  "provider": "google",
-  "model": "gemini-2.5-flash",
-  "params": {
-    "apiKey": "...",
-    "temperature": 0.7,
-    "maxOutputTokens": 2048,
-    "topP": 0.9,
-    "topK": 40
-  }
+  "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
+    }
+  ]
 }
 ```
 
@@ -458,22 +529,40 @@ Supports `region`, `clientConfig`, and optional `apiKey`, with all other values
 
 ```json
 {
-  "provider": "bedrock",
-  "model": "anthropic.claude-sonnet-4-20250514-v1:0",
-  "params": {
-    "region": "us-east-1",
-    "clientConfig": {
-      "profile": "dev",
-      "maxAttempts": 3,
-      "credentials": {
-        "accessKeyId": "AKIA...",
-        "secretAccessKey": "...",
-        "sessionToken": "..."
+  "providers": [
+    {
+      "name": "bedrock-dev",
+      "options": {
+        "provider": "bedrock",
+        "params": {
+          "region": "us-east-1",
+          "clientConfig": {
+            "profile": "dev",
+            "maxAttempts": 3,
+            "credentials": {
+              "accessKeyId": "AKIA...",
+              "secretAccessKey": "...",
+              "sessionToken": "..."
+            }
+          }
+        }
       }
-    },
-    "temperature": 0.7,
-    "maxTokens": 1024
-  }
+    }
+  ],
+  "llms": [
+    {
+      "name": "Claude Sonnet",
+      "options": {
+        "provider": "bedrock-dev",
+        "model": "anthropic.claude-sonnet-4-20250514-v1:0",
+        "params": {
+          "temperature": 0.7,
+          "maxTokens": 1024
+        }
+      },
+      "default": true
+    }
+  ]
 }
 ```
 
@@ -481,6 +570,31 @@ You can also rely on the AWS default credential chain (recommended) by setting e
 
 ### 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.
+
+```json
+{
+  "provider": "anthropic",
+  "model": "MiniMax-M3",
+  "params": {
+    "apiKey": "...",
+    "baseURL": "https://api.minimax.io/anthropic",
+    "thinking": { "type": "adaptive" },
+    "temperature": 1
+  }
+}
+```
+
+### 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.
 
 ```json
@@ -526,6 +640,8 @@ Uses the Vercel AI SDK xAI provider (`@ai-sdk/xai`) on top of Strands `VercelMod
 
 ## MCP Configuration
 
+Detailed design notes for planned OAuth-enabled remote MCP support live in [docs/mcp-oauth-design.md](docs/mcp-oauth-design.md).
+
 `mcp.json` is stored as:
 
 ```json
@@ -568,6 +684,25 @@ Uses the Vercel AI SDK xAI provider (`@ai-sdk/xai`) on top of Strands `VercelMod
 }
 ```
 
+### Example OAuth-capable remote server
+
+```json
+{
+  "mcpServers": {
+    "linear": {
+      "type": "streamable-http",
+      "url": "https://example.com/mcp",
+      "oauth": {
+        "enabled": true,
+        "clientId": "optional-pre-registered-client",
+        "scopes": ["read", "write"],
+        "callbackPort": 19876
+      }
+    }
+  }
+}
+```
+
 ### Example SSE server
 
 ```json
@@ -588,6 +723,10 @@ Uses the Vercel AI SDK xAI provider (`@ai-sdk/xai`) on top of Strands `VercelMod
 
 - MCP server `instructions` from the protocol `initialize` response are appended to Hooman's system prompt, after local `instructions.md` and session-specific prompt overrides.
 - Hooman reads these instructions automatically from connected MCP servers when building the agent.
+- Remote MCP OAuth helpers are available via:
+  - `hooman mcp auth <server>`
+  - `hooman mcp logout <server>`
+  - `hooman mcp auth-status`
 - `hooman daemon` subscribes to MCP servers that advertise the experimental `hooman/channel` capability (always on; there is no opt-out flag).
 - Hooman also reads `hooman/user`, `hooman/session`, and `hooman/thread` capability paths so daemon turns preserve origin metadata from the source channel.
 - When a matching notification is received, Hooman uses `params.content` as the prompt if it is a string; otherwise it JSON-stringifies the notification params and sends that to the agent.
@@ -603,7 +742,15 @@ Skills are installed under:
 ~/.hooman/skills
 ```
 
-Skills are discovered by scanning direct child directories for `SKILL.md`.
+At runtime, Hooman uses the Strands `AgentSkills` plugin to load:
+
+- bundled built-in skills shipped with Hooman
+- user-installed skills under `~/.hooman/skills`
+
+The local skills folder is treated as a parent directory of skill subdirectories, where each installed skill should live in its own folder containing `SKILL.md`.
+
+When a session starts, the plugin injects available skill metadata into the system prompt and exposes the `skills` tool so the model can activate a skill and load its full instructions on demand.
+
 The configure workflow can:
 
 - search the public skills catalog

package/dist/acp/acp-agent.d.ts

@@ -39,9 +39,9 @@ export declare class AcpAgent implements AgentContract {
     newSession(params: Parameters<AgentContract["newSession"]>[0]): Promise<{
         sessionId: `${string}-${string}-${string}-${string}-${string}`;
         modes: {
-            currentModeId: "default";
+            currentModeId: "agent";
             availableModes: {
-                id: "default";
+                id: "agent";
                 name: string;
                 description: string;
             }[];
@@ -51,9 +51,9 @@ export declare class AcpAgent implements AgentContract {
     }>;
     loadSession(params: Parameters<NonNullable<AgentContract["loadSession"]>>[0]): Promise<{
         modes: {
-            currentModeId: "default";
+            currentModeId: "agent";
             availableModes: {
-                id: "default";
+                id: "agent";
                 name: string;
                 description: string;
             }[];
@@ -63,7 +63,7 @@ export declare class AcpAgent implements AgentContract {
     }>;
     cancel(params: Parameters<AgentContract["cancel"]>[0]): Promise<void>;
     prompt(params: Parameters<AgentContract["prompt"]>[0]): Promise<{
-        stopReason: "cancelled" | "end_turn" | "refusal";
+        stopReason: "cancelled" | "refusal" | "end_turn";
     }>;
 }
 export declare function runAcpStdio(): Promise<void>;