hoomanjs 1.46.0 → 1.55.0

package/README.md

@@ -2,18 +2,22 @@
   <img src="docs/src/assets/logo.svg" alt="Hooman logo" width="128" />
   <h1>Hooman</h1>
   <p>
-    Hooman is a hackable, local-first AI agent toolkit for local workflows. It is built with TypeScript, <a href="https://www.npmjs.com/package/@strands-agents/sdk">Strands Agents SDK</a>, and <a href="https://github.com/vadimdemedes/ink">Ink</a>.
+    <strong>The full-stack open-source agentic ecosystem.</strong><br />
+    Local-first with llama.cpp &amp; MLX. BYOK or your own inference endpoints.<br />
+    CLI · VS Code · ACP · daemon channels · Design mode — one MIT-licensed runtime.
   </p>
   <p>
     <a href="https://nodejs.org"><img src="https://img.shields.io/badge/runtime-Node.js-5FA04E?logo=nodedotjs&logoColor=white" alt="Node.js" /></a>
     <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/language-TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" /></a>
-    <a href="https://github.com/vadimdemedes/ink"><img src="https://img.shields.io/badge/ui-Ink-6f42c1" alt="Ink" /></a>
-    <a href="https://github.com/vaibhavpandeyvpz/hooman/actions/workflows/publish-npm.yml"><img src="https://img.shields.io/github/actions/workflow/status/vaibhavpandeyvpz/hooman/publish-npm.yml?branch=main&label=build" alt="Build" /></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-0091cd" alt="MIT" /></a>
+    <a href="https://github.com/vaibhavpandeyvpz/hooman/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/vaibhavpandeyvpz/hooman/ci.yml?branch=main&label=ci" alt="CI" /></a>
+    <a href="https://github.com/vaibhavpandeyvpz/hooman/actions/workflows/docs.yml"><img src="https://img.shields.io/github/actions/workflow/status/vaibhavpandeyvpz/hooman/docs.yml?branch=main&label=docs" alt="Docs" /></a>
     <a href="https://github.com/vaibhavpandeyvpz/hooman/stargazers"><img src="https://img.shields.io/github/stars/vaibhavpandeyvpz/hooman?style=flat" alt="GitHub Repo stars" /></a>
     <a href="https://github.com/vaibhavpandeyvpz/hooman/commits/main"><img src="https://img.shields.io/github/last-commit/vaibhavpandeyvpz/hooman" alt="GitHub last commit" /></a>
   </p>
   <p>
-    <img src="docs/src/assets/screenshots-hero.png" alt="Hooman screenshot" />
+    <img src="docs/public/screenshots/ask-mode.png" alt="Hooman CLI" width="480" />
+    <img src="docs/public/screenshots/agent-mode.png" alt="Hooman in VS Code" width="640" />
   </p>
   <p>
     <strong><a href="https://vaibhavpandey.com/hooman/">Website</a></strong> ·
@@ -22,31 +26,51 @@
   </p>
 </div>
 
-Hooman reads your codebase, edits files, and runs commands — from a terminal, VS Code, or any [Agent Client Protocol](https://agentclientprotocol.com) client. Bring your own model; your config, keys, and sessions never leave `~/.hooman`.
+Hooman is a mature, local-first AI agent runtime for teams that want the full stack — not a thin chat wrapper. It reads your codebase, edits files, runs commands, automates channels, and ships design artifacts — from a terminal, VS Code, or any [Agent Client Protocol](https://agentclientprotocol.com) client.
 
-- a one-shot `exec` command for single prompts
-- a stateful `chat` interface for iterative sessions, with an in-chat `/config` workflow for models, MCP servers, and skills
-- a `daemon` command for channel-driven MCP automation
-- an `acp` command for running Hooman as an Agent Client Protocol agent over stdio (used by the [VS Code extension](https://vaibhavpandey.com/hooman/guides/vscode/) and editors like Zed)
+**Open source (MIT). No account. No telemetry.** Bring your own keys, point at private inference endpoints, or run fully offline with llama.cpp / MLX. Config, secrets, and sessions stay in `~/.hooman`.
+
+| Surface         | What it is                                                                                                                  |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `hooman chat`   | Stateful Ink TUI with modes, slash commands, and live cost/context                                                          |
+| `hooman exec`   | One-shot agent runs for scripts and CI                                                                                      |
+| `hooman daemon` | Channel-driven MCP automation (Slack, Telegram, cron, …)                                                                    |
+| `hooman acp`    | ACP agent over stdio — powers the [VS Code extension](https://vaibhavpandey.com/hooman/guides/vscode/) and editors like Zed |
+| Design mode     | HTML → preview → Figma / Sketch / PDF / PPTX                                                                                |
 
 ## Quick start
 
+macOS & Linux:
+
 ```bash
-npx hoomanjs
+curl -fsSL https://raw.githubusercontent.com/vaibhavpandeyvpz/hooman/main/install.sh | bash
+```
+
+Windows (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/vaibhavpandeyvpz/hooman/main/install.ps1 | iex
 ```
 
-Or install globally (`npm i -g hoomanjs`), or via Bun (`bunx hoomanjs`). Then run `/config` inside the chat to pick a provider and model. Full walkthrough: [Getting Started](https://vaibhavpandey.com/hooman/getting-started/).
+Or skip the installer and run `npx hoomanjs` / `bunx hoomanjs`, or install with `npm i -g hoomanjs` / `bun add -g hoomanjs`. On first run (when `~/.hooman/config.json` is missing), a **setup** wizard asks for an inference provider and search; then chat starts. Re-run anytime with `hooman setup`. Full walkthrough: [Getting Started](https://vaibhavpandey.com/hooman/getting-started/).
+
+## Why Hooman
+
+- **Full-stack, not single-surface** — CLI, VS Code, ACP, daemon channels, and Design mode share one runtime and one local config.
+- **Local-first by default** — first-run setup offers llama.cpp (GGUF) and Apple Silicon MLX; weights download on demand; no API key required to start.
+- **Enterprise-friendly** — MIT license, BYOK, OpenAI-compatible custom base URLs, no telemetry, data residency under your control.
+- **Most-featured agent toolkit** — Agent / Plan / Ask / Design modes, MCP + OAuth, skills, subagents, approvals, background shell jobs, context & cost tracking.
 
 ## Features
 
-- Multiple LLM providers: `anthropic`, `azure`, `bedrock`, `google`, `groq`, `llama-cpp` (local GGUF, the default), `minimax`, `mlx` (local, Apple Silicon), `moonshot`, `ollama`, `openai`, `openrouter`, `xai` — see [Models](https://vaibhavpandey.com/hooman/guides/configuration/models/)
-- MCP server support (`stdio`, `streamable-http`, `sse`) with OAuth (DCR + CIMD), lazy MCP tool discovery via `search_tools` / `activate_tools`, and channel-driven automation via `hooman daemon` — see [MCP](https://vaibhavpandey.com/hooman/guides/mcp/)
-- Runtime [Skills](https://vaibhavpandey.com/hooman/guides/skills/): bundled built-ins plus a local `~/.hooman/skills` catalog
-- Built-in read-only subagents, a ripgrep-backed `grep` tool, and an `ask_user` tool for mid-task questions — see [Tools](https://vaibhavpandey.com/hooman/guides/tools/)
-- Context-window utilization and session-cost tracking backed by [models.dev](https://models.dev), shown live in every surface
-- Interactive terminal UI for chat and configuration, plus a native [VS Code chat panel](https://vaibhavpandey.com/hooman/guides/vscode/)
+- **Providers:** `anthropic`, `azure`, `bedrock`, `google`, `groq`, `llama-cpp`, `minimax`, `mlx`, `moonshot`, `ollama`, `openai`, `openrouter`, `xai` — see [Models](https://vaibhavpandey.com/hooman/guides/configuration/models/)
+- **Modes:** `agent` / `plan` / `ask` / `design` plus a separate Yolo auto-approve toggle — see [Modes](https://vaibhavpandey.com/hooman/guides/modes/) and [Design](https://vaibhavpandey.com/hooman/guides/modes/design/)
+- **MCP:** `stdio`, `streamable-http`, `sse` with OAuth (DCR + CIMD), lazy tool discovery, optional Playwright browser MCP, and `hooman daemon` channels — see [MCP](https://vaibhavpandey.com/hooman/guides/mcp/)
+- **Skills:** bundled built-ins (including `hooman-design`), `~/.hooman/skills`, and project-local `.hooman/skills` — see [Skills](https://vaibhavpandey.com/hooman/guides/skills/)
+- **Tools:** filesystem (respects `.gitignore`), ripgrep `grep`, background shell (`run_in_background` / `shell_output` / `shell_stop`), `ask_user`, and read-only `launch_subagent` kinds — see [Tools](https://vaibhavpandey.com/hooman/guides/tools/)
+- **VS Code:** native chat panel with Mermaid, plan checklists, Changes keep/undo, fork/copy, turn revert, and background-terminals strip — see [VS Code](https://vaibhavpandey.com/hooman/guides/vscode/)
 
-See the [full documentation](https://vaibhavpandey.com/hooman/) for CLI commands, configuration layout, provider setup, and more.
+See the [full documentation](https://vaibhavpandey.com/hooman/) for CLI commands, configuration, provider setup, and more.
 
 ## Related
 
@@ -66,3 +90,5 @@ After making any code change, run both `npm run typecheck` and `npm run build`.
 ## License
 
 MIT. See [`LICENSE`](LICENSE).
+
+Built by [Vaibhav Pandey](https://vaibhavpandey.com/) · [GitHub](https://github.com/vaibhavpandeyvpz) · [LinkedIn](https://www.linkedin.com/in/vaibhavpandeyvpz/)

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

@@ -4,6 +4,30 @@ type AgentIdentity = {
     name: string;
     version: string;
 };
+/**
+ * Params/response for the custom `_hoomanjs/rewind_session` method (turn
+ * revert). Not part of the ACP spec — registered as a custom request
+ * via `AgentApp.onRequest(method: string, parser, handler)`. `messageId` is
+ * the agent-generated ACP id (see the MessageId RFD) of the turn's user
+ * message, captured by the client from that message's `user_message_chunk`
+ * echo — never minted by the client itself.
+ */
+export interface RewindSessionRequest {
+    sessionId: string;
+    messageId: string;
+}
+export interface RewindSessionResponse {
+    /** False when `messageId` has no recorded boundary (e.g. session reloaded since that turn ran). */
+    reverted: boolean;
+}
+/** Params/response for the custom `_hoomanjs/stop_shell_job` method. */
+export interface StopShellJobRequest {
+    sessionId: string;
+    jobId: string;
+}
+export interface StopShellJobResponse {
+    stopped: boolean;
+}
 /**
  * Hooman's ACP agent, built on the app-style SDK API.
  *
@@ -21,6 +45,24 @@ export declare class HoomanAcpAgent {
     deleteSession(params: DeleteSessionRequest): Promise<void>;
     newSession(params: NewSessionRequest): Promise<NewSessionResponse>;
     forkSession(params: ForkSessionRequest, _client: AgentContext): Promise<ForkSessionResponse>;
+    /**
+     * Turn revert (custom `_hoomanjs/rewind_session` method, not part
+     * of the ACP spec): splice `agent.messages` back to the message index
+     * bookmarked for `messageId` (see {@link recordTurnBoundary}), dropping
+     * that turn and every turn after it, then persist the trimmed history.
+     *
+     * Returns `reverted: false` instead of erroring when `messageId` has no
+     * recorded boundary — e.g. the session was reloaded since that turn ran,
+     * so its in-memory bookmark (and the client's matching file-edit
+     * baselines) no longer exist.
+     */
+    rewindSession(params: RewindSessionRequest): Promise<RewindSessionResponse>;
+    /**
+     * Custom `_hoomanjs/stop_shell_job`: stop a background shell job by id.
+     * Routes through {@link ShellJobManager.stop}, which kills the host terminal
+     * (process group) and emits the completion notification the UI listens for.
+     */
+    stopShellJob(params: StopShellJobRequest): Promise<StopShellJobResponse>;
     loadSession(params: LoadSessionRequest, client: AgentContext): Promise<LoadSessionResponse>;
     /**
      * Handle `session/resume`: reactivate a persisted session's in-memory state