hoomanjs 1.17.1 → 1.17.3

package/README.md

@@ -28,10 +28,13 @@ It gives you a practical toolkit to build and run agent workflows:
 
 - Multiple LLM providers: `ollama`, `openai`, `anthropic`, `google`, `bedrock`, `groq`, `moonshot`, `xai`
 - Local configuration under `./.hooman` when that folder exists in the current working directory, otherwise `~/.hooman`
+- Optional web search tool with provider selection (`brave` or `tavily`)
 - 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 notification support through `hooman daemon --channels`
 - Skill discovery / install / removal through the integrated configure flow
+- Bundled prompt harness toggles (`behaviour`, `communication`, `execution`, `engineering`, `guardrails`)
+- Built-in subagent runner tools (`research`, `plan`) with configurable concurrency
 - Toolkit-oriented architecture with configurable tools, prompts, memory, and transports
 - Interactive terminal UI for chat and configuration
 
@@ -46,15 +49,21 @@ It gives you a practical toolkit to build and run agent workflows:
 Fastest way to get started without cloning the repo:
 
 ```bash
-npx hoomanjs configure
-npx hoomanjs chat
+bunx hoomanjs configure
+bunx hoomanjs chat
+
+# or install globally
+bun i -g hoomanjs
 ```
 
-Or with Bun:
+Or with npm:
 
 ```bash
-bunx hoomanjs configure
-bunx hoomanjs chat
+npx hoomanjs configure
+npx hoomanjs chat
+
+# or install globally
+npm i -g hoomanjs
 ```
 
 Recommended first run:
@@ -63,6 +72,23 @@ Recommended first run:
 2. Start chatting with `hooman chat`.
 3. Use `hooman exec "your prompt"` for one-off tasks.
 
+## Must have
+
+For the best experience, set up both:
+
+1. **MCP servers** for on-demand tools in `chat` / `exec` (task APIs, messaging, schedulers, etc.).
+2. **MCP channels** for event-driven automation with `hooman daemon --channels` (notifications become agent prompts).
+
+Suggested MCP servers from this ecosystem:
+
+- [`cronmcp`](https://github.com/vaibhavpandeyvpz/cronmcp) - lets Hooman schedule recurring prompts and automations, so routine checks and follow-ups run on time.
+- [`jiraxmcp`](https://github.com/vaibhavpandeyvpz/jiraxmcp) - gives Hooman direct Jira Cloud access to search issues, update tickets, and help drive sprint workflows.
+- [`slackxmcp`](https://github.com/vaibhavpandeyvpz/slackxmcp) - connects Hooman to Slack so it can read channel context, draft updates, and post actions where your team already works.
+- [`tgfmcp`](https://github.com/vaibhavpandeyvpz/tgfmcp) - enables Telegram bot workflows, making it easy to route notifications and respond from agent-driven chats.
+- [`wappmcp`](https://github.com/vaibhavpandeyvpz/wappmcp) - brings WhatsApp Web messaging into Hooman for customer or team communication automations.
+
+For production deployments, still review permissions and use least-privilege credentials/tokens for each integration.
+
 ## Install
 
 ```bash
@@ -158,16 +184,28 @@ hooman daemon --channels --yolo
 
 ### Feature Flags
 
-Runtime tools and prompt sections are controlled from `config.json` under `tools`:
-
+Runtime tool and prompt switches are controlled from `config.json`:
+
+- `search.enabled`
+- `search.provider` (`brave` or `tavily`)
+- `search.brave.apiKey`
+- `search.tavily.apiKey`
+- `prompts.behaviour`
+- `prompts.communication`
+- `prompts.execution`
+- `prompts.engineering`
+- `prompts.guardrails`
 - `tools.todo.enabled`
 - `tools.fetch.enabled`
 - `tools.filesystem.enabled`
 - `tools.shell.enabled`
+- `tools.sleep.enabled`
 - `tools.ltm.enabled`
 - `tools.wiki.enabled`
 - `tools.mcp.enabled` (enables MCP management tools + prefixed MCP server tools/instructions)
 - `tools.skills.enabled` (enables skills management tools + skills prompt sections)
+- `tools.agents.enabled` (enables built-in `run_agents` tool)
+- `tools.agents.concurrency`
 
 Both `ltm` and `wiki` include dedicated Chroma settings under:
 
@@ -185,6 +223,8 @@ hooman configure
 The configure UI currently lets you:
 
 - edit app configuration values
+- choose search provider and set its API key
+- toggle bundled harness prompts (`behaviour`, `communication`, `execution`, `engineering`, `guardrails`)
 - edit `instructions.md` in your `$VISUAL` / `$EDITOR` (cross-platform fallback included)
 - add, edit, and delete MCP servers with confirmation
 - search, install, refresh, and remove skills
@@ -224,7 +264,7 @@ Important files and folders:
 
 ## Example `config.json`
 
-This is the shape managed by `hooman configure`:
+This is the config shape loaded by Hooman:
 
 ```json
 {
@@ -234,6 +274,19 @@ This is the shape managed by `hooman configure`:
     "model": "gemma4:e4b",
     "params": {}
   },
+  "search": {
+    "enabled": false,
+    "provider": "brave",
+    "brave": {},
+    "tavily": {}
+  },
+  "prompts": {
+    "behaviour": true,
+    "communication": true,
+    "execution": true,
+    "engineering": false,
+    "guardrails": true
+  },
   "tools": {
     "todo": {
       "enabled": true
@@ -247,6 +300,9 @@ This is the shape managed by `hooman configure`:
     "shell": {
       "enabled": true
     },
+    "sleep": {
+      "enabled": true
+    },
     "ltm": {
       "enabled": false,
       "chroma": {
@@ -270,6 +326,10 @@ This is the shape managed by `hooman configure`:
     },
     "skills": {
       "enabled": false
+    },
+    "agents": {
+      "enabled": true,
+      "concurrency": 3
     }
   },
   "compaction": {
@@ -292,6 +352,11 @@ Supported `llm.provider` values:
 - `moonshot`
 - `xai`
 
+Supported `search.provider` values:
+
+- `brave`
+- `tavily`
+
 ## Provider Notes
 
 ### Ollama
@@ -357,6 +422,29 @@ Uses Strands `GoogleModel` on top of `@google/genai`. Top-level options like `ap
 
 Supports `region`, `clientConfig`, and optional `apiKey`, with all other values forwarded as Bedrock model options.
 
+```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": "..."
+      }
+    },
+    "temperature": 0.7,
+    "maxTokens": 1024
+  }
+}
+```
+
+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
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hoomanjs",
-  "version": "1.17.1",
+  "version": "1.17.3",
   "description": "Hackable Bun-powered AI agent toolkit for building local CLI, ACP, MCP, and channel-driven workflows.",
   "author": {
     "name": "Vaibhav Pandey",

package/src/core/prompts/harness/engineering.md

@@ -4,14 +4,22 @@ Use senior engineering judgment, but let the repository guide the solution. Pref
 
 ### Code Changes
 
+- Treat generic or underspecified requests as software engineering tasks in the current repo context. Prefer making the real code change over replying with a superficial text transformation.
+- Defer to the user's judgment on scope. Do not reject work only because it is large or ambitious.
 - Understand the surrounding module before changing it.
+- Read a file before proposing edits to that file.
 - Preserve public behavior unless the user asked to change it or the existing behavior is clearly a bug.
 - Keep edits narrow, coherent, and easy to review.
 - Choose simple code that fully solves the problem over clever or over-generalized code.
 - Add abstractions only when they remove real duplication, clarify a real concept, or match an established local pattern.
 - Avoid compatibility shims for unshipped branch work. Replace in-progress code cleanly when that is the right fix.
+- Avoid backwards-compatibility hacks (placeholder re-exports, "removed" comments, legacy aliases) when old code is truly no longer needed.
 - Do not add comments by default. Add a comment only when it explains a non-obvious constraint, invariant, workaround, or surprising behavior.
 - Do not add docstrings, types, formatting churn, or refactors to unrelated code.
+- Do not create files unless they are necessary to complete the requested task. Prefer editing existing files.
+- Do not add features, configurability, refactors, or cleanup beyond the user's request.
+- Do not add speculative validation, fallbacks, feature flags, or defensive branches for scenarios that cannot happen.
+- Do not introduce one-off helpers or abstractions for hypothetical future requirements.
 
 ### Safety And Correctness
 
@@ -20,6 +28,9 @@ Use senior engineering judgment, but let the repository guide the solution. Pref
 - Treat generated files, lockfiles, migrations, and configuration as shared contracts. Update them only when the task requires it.
 - Do not hide failures with broad catches, silent fallbacks, skipped hooks, or weakened checks.
 - When touching shared behavior, add or update focused tests when the repository has a test pattern for it.
+- Avoid time estimates. Focus on what needs to happen and what is done.
+- If an approach fails, diagnose the failure before switching tactics. Do not blindly retry the same step.
+- Escalate with a focused user question only after investigation when safe progress is blocked.
 
 ### Repository Hygiene
 

package/src/core/prompts/harness/guardrails.md

@@ -7,10 +7,15 @@ Act with care around security, user data, irreversible operations, and shared sy
 - Local, reversible inspection and focused edits are usually acceptable.
 - Ask for confirmation before destructive, hard-to-reverse, externally visible, or shared-state actions unless the user has clearly authorized that exact scope.
 - Risky actions include deleting files or records, dropping data, killing unknown processes, overwriting user work, changing permissions, sending messages, posting comments, publishing artifacts, or uploading sensitive content to third-party services.
+- Hard-to-reverse examples include force-push, hard reset, amending published commits, removing or downgrading dependencies, and modifying CI/CD pipelines.
 - Approval for one risky action does not authorize different future risky actions.
+- Treat authorization as scope-limited: do only what was approved, not adjacent risky actions.
+- If the user explicitly asks for more autonomous execution, you may proceed without per-step confirmation but still apply risk checks.
 - Treat approval prompts, permission denials, hook feedback, and automated policy checks as authoritative user or system feedback for the current action.
 - If hook or approval feedback explains a required change, incorporate that feedback into the next safe step instead of ignoring it or working around it.
 - Do not bypass checks, hooks, permissions, or approval flows just to make progress.
+- If you discover unexpected state (unknown files, branches, lockfiles, process state, or config), investigate before deleting or overwriting it.
+- Prefer root-cause fixes over destructive shortcuts when blocked.
 
 ### Security Requests