hoomanjs 1.40.1 → 1.41.0

package/README.md

@@ -1,4 +1,5 @@
 <div align="center">
+  <img src=".github/logo.svg" alt="Hooman logo" width="128" />
   <h1>Hooman</h1>
   <p>
     Hooman is a hackable 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>.
@@ -40,6 +41,8 @@ It gives you a practical toolkit to build and run agent workflows:
 - Bundled prompt harness toggles (`behaviour`, `communication`, `execution`, `guardrails`); coding guidance ships as the built-in `hooman-coding` skill
 - 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
+- Built-in `ask_user` tool: the agent can ask you a multiple-choice question mid-task and wait for the answer — inline picker in `chat`, numbered prompt in `exec`, question card in ACP clients (Zed, the VS Code extension); environments without a human (daemon, non-TTY `exec`, subagents) report "no user available" so the agent proceeds on its own
+- Context-window utilization and session-cost tracking backed by [models.dev](https://models.dev) (daily-cached catalog, optional per-model `billing` overrides) — shown in the chat status bar, the VS Code extension footer, and sent to ACP clients via `usage_update`
 - Toolkit-oriented architecture with configurable tools, prompts, and transports
 - Interactive terminal UI for chat and configuration
 
@@ -181,16 +184,20 @@ Start in ask mode:
 hooman chat --mode ask
 ```
 
+The status bar under the composer shows the active model, effort, mode, and yolo state; a usage row with `context: N% (used/size)`, cumulative `tokens` (`in`/`cin`/`out`), and session `cost: $…` (each segment appears once it has data — context and cost require resolvable billing metadata, see the [`billing` block](#provider-notes)); and an mcp/tools/skills row with a live `elapsed` timer while a turn runs.
+
 ### Chat commands
 
 Inside an interactive `chat` session, type `/` to discover slash commands:
 
 - `/model` - pick or set the chat model for this session.
+- `/effort` - pick or set the reasoning effort for the active model's provider (`off`, `minimal`, `low`, `medium`, `high`); Shift+Tab cycles it.
 - `/mode` - switch the session mode (`agent`, `ask`, `plan`); see [Session mode](#session-mode).
 - `/yolo` - toggle auto-approve of tool calls (`on` / `off`).
 - `/init` - generate or refresh `AGENTS.md` for the current project.
 - `/compact` - compact the conversation history now and persist the result.
 - `/new` - start a fresh chat session.
+- `/sessions` - browse and resume saved sessions.
 - `/config` - launch the configuration workflow (see below).
 
 ### Session mode
@@ -290,10 +297,31 @@ hooman acp
 
 ACP notes:
 
-- ACP sessions are stored under the active project's session directory in `sessions/acp/` (see [Configuration Layout](#configuration-layout))
+- ACP session metadata is indexed in the active project's `sessions/acp/sessions.jsonl`; conversation history lives in the regular per-session snapshots (see [Configuration Layout](#configuration-layout))
 - 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`
 - session configuration includes `hooman.sessionMode` (`agent`, `plan`, or `ask`); see [Session mode](#session-mode)
+- each turn ends with a `usage_update` carrying context-window utilization (`used`/`size`), cumulative session `cost`, and cumulative token totals under `_meta["hoomanjs/tokens"]` — `size` and `cost` come from the model's [`billing` metadata](#provider-notes) (models.dev-backed) and are omitted (`size: 0`, no `cost`) when unresolved; a model switch pushes a fresh `usage_update` so clients can rescale immediately
+
+## VS Code Extension
+
+`src/vscode/` ships a self-contained VS Code extension (`hooman-vscode`) that bridges `hooman acp` into the editor with a **Hooman chat panel** — its own webview view in the activity bar with streaming markdown, collapsible thinking, tool-call cards, plan checklists, usage, session list/load, mode/model/effort pickers, slash-command autocomplete, and inline permission prompts. Works in **stable VS Code, Insiders, and compatible forks** — no proposed APIs and no special subscription required.
+
+It's not published to the marketplace yet. Quick start:
+
+```bash
+# from the repo root
+npm install && npm run build && npm link
+
+# from src/vscode
+cd src/vscode
+npm install && npm run compile
+code .          # open src/vscode as its own workspace, then press F5
+```
+
+Or package and install a `.vsix` into any VS Code-compatible editor: `npm run package` in `src/vscode`, then `code --install-extension hooman-vscode-<version>.vsix`.
+
+Full setup, settings, and architecture notes: [`src/vscode/README.md`](src/vscode/README.md).
 
 ## Configuration Layout
 
@@ -313,7 +341,8 @@ Important files and folders:
 - `cache/` - runtime caches used by tools and subsystems
 - `projects.json` - registry mapping each project root to a stable UUID
 - `projects/<uuid>/` - per-project storage, scoped to the project (git root, falling back to cwd) the session runs in:
-  - `sessions/` - persisted session data (including ACP sessions under `sessions/acp/` and offloaded tool output under `sessions/offloaded-content/`)
+  - `sessions/` - persisted session data (per-session snapshots and the ACP session index at `sessions/acp/sessions.jsonl`)
+  - `offloaded-content/` - offloaded tool output (large tool results retrievable via `retrieve_offloaded_content`)
   - `memory/` - durable extracted memory store
   - `attachments/` - saved attachments (e.g. clipboard images)
   - `plans/` - plan-mode markdown documents
@@ -411,7 +440,7 @@ The on-disk shape uses a reusable **`providers`** array plus a non-empty **`llms
 
 Tool approvals are session-scoped and are not persisted in `config.json`.
 
-Hooman enables Strands `ContextOffloader` by default with file-backed storage under the project-scoped `~/.hooman/projects/<uuid>/sessions/offloaded-content`, so large tool results can be previewed in-context and retrieved later without bloating the active conversation window.
+Hooman enables Strands `ContextOffloader` by default with file-backed storage under the project-scoped `~/.hooman/projects/<uuid>/offloaded-content`, so large tool results can be previewed in-context and retrieved later without bloating the active conversation window.
 
 Supported `providers[].provider` values registered in this release (see `src/core/models/index.ts`):
 
@@ -486,6 +515,24 @@ Normalized LLM option fields:
 - optional `temperature`
 - optional `maxTokens`
 
+Each LLM entry may also carry an optional **`billing`** block used to display context-window utilization and cumulative session cost (in the chat TUI status bar and the VS Code extension footer, and sent to ACP clients via `usage_update`):
+
+```json
+{
+  "name": "Haiku 4.5",
+  "provider": "LiteLLM Anthropic",
+  "billing": {
+    "name": "claude-haiku-4.5",
+    "context": 200000,
+    "costs": { "input/m": 1, "cache/m": 0.1, "output/m": 5 }
+  },
+  "options": { "model": "claude-haiku-4.5" },
+  "default": true
+}
+```
+
+`billing.name` is required when the block is present and is the identifier looked up in the [models.dev](https://models.dev) catalog (cached under `~/.hooman/cache/` and refreshed at most once daily); when `billing` is omitted, `options.model` is used as the lookup name. `context` (window size in tokens) and `costs` (USD per million tokens; `"cache/m"` prices cached-input reads) override whatever models.dev resolves. If neither the config nor models.dev yields the data, context usage and cost are simply not shown.
+
 Notes:
 
 - Google maps normalized `maxTokens` to the SDK's `maxOutputTokens` internally.

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

@@ -1,4 +1,4 @@
-import { type AgentApp, type AgentConnection, type AgentContext, type CancelNotification, type DeleteSessionRequest, type InitializeRequest, type InitializeResponse, type ListSessionsRequest, type ListSessionsResponse, type LoadSessionRequest, type LoadSessionResponse, type NewSessionRequest, type NewSessionResponse, type PromptRequest, type PromptResponse, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SetSessionModeRequest, type SetSessionModeResponse } from "@agentclientprotocol/sdk";
+import { type AgentApp, type AgentConnection, type AgentContext, type CancelNotification, type CloseSessionRequest, type CloseSessionResponse, type DeleteSessionRequest, type InitializeRequest, type InitializeResponse, type ListSessionsRequest, type ListSessionsResponse, type LoadSessionRequest, type LoadSessionResponse, type NewSessionRequest, type NewSessionResponse, type PromptRequest, type PromptResponse, type ResumeSessionRequest, type ResumeSessionResponse, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SetSessionModeRequest, type SetSessionModeResponse } from "@agentclientprotocol/sdk";
 /** Name + version reported to the client in `agentInfo`. */
 type AgentIdentity = {
     name: string;
@@ -21,16 +21,29 @@ export declare class HoomanAcpAgent {
     deleteSession(params: DeleteSessionRequest): Promise<void>;
     newSession(params: NewSessionRequest): Promise<NewSessionResponse>;
     loadSession(params: LoadSessionRequest, client: AgentContext): Promise<LoadSessionResponse>;
+    /**
+     * Handle `session/resume`: reactivate a persisted session's in-memory state
+     * (including its conversation history, so the turn continues correctly)
+     * without replaying that history to the client — the spec reserves the full
+     * transcript replay for `session/load`.
+     */
+    resumeSession(params: ResumeSessionRequest, client: AgentContext): Promise<ResumeSessionResponse>;
+    /**
+     * Handle `session/close`: cancel any in-flight turn and free the in-memory
+     * session state, without deleting the persisted session from disk (unlike
+     * `session/delete`).
+     */
+    closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse>;
     /**
      * Handle `session/set_mode`: switch the active mode for a running session,
      * re-applying the tool surface and persisting the choice.
      */
-    setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse>;
+    setSessionMode(params: SetSessionModeRequest, client: AgentContext): Promise<SetSessionModeResponse>;
     /**
      * Handle `session/set_config_option`: apply a model or mode selection and
      * return the complete, up-to-date configuration state (as the spec requires).
      */
-    setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
+    setSessionConfigOption(params: SetSessionConfigOptionRequest, client: AgentContext): Promise<SetSessionConfigOptionResponse>;
     /** Cancel an in-flight prompt turn. Silent no-op for unknown sessions. */
     cancel(params: CancelNotification): Promise<void>;
     /** Run one prompt turn: stream model output, tool calls, and a stop reason. */