hoomanjs 1.45.4 → 1.47.0

package/README.md

@@ -8,7 +8,8 @@
     <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://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>
@@ -40,11 +41,12 @@ Or install globally (`npm i -g hoomanjs`), or via Bun (`bunx hoomanjs`). Then ru
 ## 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/)
+- Session modes (`agent` / `plan` / `ask`) plus a separate Yolo auto-approve toggle — see [CLI](https://vaibhavpandey.com/hooman/guides/cli/#session-mode)
+- MCP server support (`stdio`, `streamable-http`, `sse`) with OAuth (DCR + CIMD), lazy MCP tool discovery via `search_tools` / `activate_tools`, optional browser automation via Playwright MCP (`tools.browser.enabled`), 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, a local `~/.hooman/skills` catalog, and optional project-local `.hooman/skills`
+- Built-in read-only subagents, a ripgrep-backed `grep` tool, filesystem tools that respect `.gitignore`, background shell jobs (`run_in_background` / `shell_output` / `shell_stop`), 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/)
+- Interactive terminal UI for chat and configuration, plus a native [VS Code chat panel](https://vaibhavpandey.com/hooman/guides/vscode/) with Mermaid diagrams, plan checklists, Changes keep/undo, fork/copy, Cursor-style revert, and a background-terminals strip
 
 See the [full documentation](https://vaibhavpandey.com/hooman/) for CLI commands, configuration layout, provider setup, and more.
 

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 (Cursor-
+ * style 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>;
+    /**
+     * Cursor-style 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

package/dist/acp/acp-agent.js

@@ -9,15 +9,16 @@ import { MODE_DEFINITIONS } from "../core/modes/definitions.js";
 import { DEFAULT_SESSION_MODE, isKnownSessionMode, } from "../core/modes/schema.js";
 import { getModeState, setSessionMode } from "../core/state/session-mode.js";
 import { isYoloEnabled, setYoloEnabled } from "../core/state/yolo.js";
+import { dropTurnBoundariesFrom, getTurnBoundary, recordTurnBoundary, } from "../core/state/turn-boundaries.js";
 import { ChatTurnSteeringController, createChatTurnSteeringIntervention, } from "../core/agent/turn-steering.js";
 import { getAgentConversationManager, getAgentSessionManager, } from "../core/agent/index.js";
 import { readBundledPrompt } from "../core/prompts/bundled.js";
 import { modelProviders } from "../core/models/index.js";
-import { subscribeModelDownloadProgress, } from "../core/models/download-progress.js";
+import { subscribeModelDownloadProgress, } from "../core/utils/download-progress.js";
 import { subscribeModelRetryProgress, } from "../core/agent/retry-progress.js";
-import { toAdditiveUsage } from "../core/models/usage.js";
-import { computeUsageCostUsd, configuredLlmContext, contextTokensFromUsage, resolveLlmBilling, } from "../core/utils/billing.js";
-import { buildSessionConfigOptions, currentModelName, CONFIG_ID_EFFORT, CONFIG_ID_MODE, CONFIG_ID_MODEL, MODE_VALUE_YOLO, } from "./session-config.js";
+import { toAdditiveUsage } from "../core/utils/usage.js";
+import { computeUsageCostUsd, configuredLlmContext, contextTokensFromUsage, resolveLlmMetadata, } from "../core/utils/metadata.js";
+import { buildSessionConfigOptions, currentModelName, CONFIG_ID_EFFORT, CONFIG_ID_MODE, CONFIG_ID_MODEL, CONFIG_ID_YOLO, } from "./session-config.js";
 import { activeProviderName, parseReasoningEffortArg, withReasoningEffort, } from "../core/utils/reasoning-effort.js";
 import { ACP_SLASH_COMMANDS, parseAcpSlashCommand, } from "./commands.js";
 import { ENTER_PLAN_MODE_TOOL, EXIT_PLAN_MODE_TOOL, } from "../core/state/tool-approvals.js";
@@ -33,7 +34,7 @@ import { getTodoViewState } from "../core/state/todos.js";
 import { UPDATE_TODOS_TOOL_NAME } from "../core/tools/todo.js";
 import { setAskUserBackend } from "../core/tools/ask-user.js";
 import { setTextFsBackend } from "../core/tools/filesystem.js";
-import { setTerminalBackend, } from "../core/tools/shell.js";
+import { setTerminalBackend, clearShellJobManager, getShellJobManager, } from "../core/shell/index.js";
 import { createAcpToolApprovalIntervention } from "./approvals.js";
 import { createAcpAskUserBackend } from "./questions.js";
 import { extractAcpClientUserId } from "./meta/user-id.js";
@@ -338,6 +339,7 @@ export class HoomanAcpAgent {
         if (record) {
             this.#sessions.delete(params.sessionId);
             record.turnAbort?.abort();
+            await this.#teardownShellJobs(params.sessionId, record);
             await record.mcpDisconnect();
         }
         await deleteSessionEntry(this.#acpRoot, params.sessionId);
@@ -369,6 +371,7 @@ export class HoomanAcpAgent {
         await writeSessionEntry(this.#acpRoot, entry);
         const record = await this.#bootstrapSession(sessionId, params.cwd, clientUserId ?? sessionId, mcpServers, mode, undefined, vscode);
         this.#sessions.set(sessionId, record);
+        this.#subscribeShellJobs(record.agent, this.#requireClient(), sessionId);
         await this.#advertiseCommands(this.#requireClient(), sessionId);
         return {
             sessionId,
@@ -449,6 +452,58 @@ export class HoomanAcpAgent {
             configOptions: buildSessionConfigOptions(forkConfig, mode, sourceEntry.yolo === true),
         };
     }
+    /**
+     * Cursor-style 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.
+     */
+    async rewindSession(params) {
+        const rec = this.#sessions.get(params.sessionId);
+        if (!rec) {
+            throw RequestError.invalidParams({ sessionId: params.sessionId });
+        }
+        if (this.#isTurnActive(rec)) {
+            throw RequestError.invalidParams({
+                sessionId: params.sessionId,
+                message: "Cannot rewind a session while a turn is still running.",
+            });
+        }
+        const boundary = getTurnBoundary(rec.agent, params.messageId);
+        if (boundary === undefined) {
+            return { reverted: false };
+        }
+        rec.agent.messages.length = boundary;
+        dropTurnBoundariesFrom(rec.agent, params.messageId);
+        await getAgentSessionManager(rec.agent)?.saveSnapshot({
+            target: rec.agent,
+            isLatest: true,
+        });
+        return { reverted: true };
+    }
+    /**
+     * 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.
+     */
+    async stopShellJob(params) {
+        const rec = this.#sessions.get(params.sessionId);
+        if (!rec) {
+            throw RequestError.invalidParams({ sessionId: params.sessionId });
+        }
+        const manager = getShellJobManager(rec.agent);
+        const existing = manager.get(params.jobId);
+        if (!existing) {
+            return { stopped: false };
+        }
+        await manager.stop(params.jobId);
+        return { stopped: true };
+    }
     async loadSession(params, client) {
         const { record, mode } = await this.#reactivateSession({
             sessionId: params.sessionId,
@@ -489,6 +544,7 @@ export class HoomanAcpAgent {
         if (record) {
             this.#sessions.delete(params.sessionId);
             record.turnAbort?.abort();
+            await this.#teardownShellJobs(params.sessionId, record);
             await record.mcpDisconnect();
         }
         return {};
@@ -529,6 +585,7 @@ export class HoomanAcpAgent {
             await replayConversationHistory(client, params.sessionId, record.agent.messages);
         }
         this.#sessions.set(params.sessionId, record);
+        this.#subscribeShellJobs(record.agent, client, params.sessionId);
         await patchSessionEntry(this.#acpRoot, params.sessionId, {
             cwd: params.cwd,
             ...(fromRequest !== undefined ? { userId: fromRequest || null } : {}),
@@ -581,6 +638,27 @@ export class HoomanAcpAgent {
         if (!rec) {
             throw RequestError.invalidParams({ sessionId: params.sessionId });
         }
+        // Yolo is a boolean toggle (auto-approve all tool calls), so it carries a
+        // boolean value rather than a string one; handle it before the string
+        // guard below that the select-style options rely on.
+        if (params.configId === CONFIG_ID_YOLO) {
+            if (typeof params.value !== "boolean") {
+                throw RequestError.invalidParams({
+                    configId: params.configId,
+                    message: `Config option "${params.configId}" expects a boolean value`,
+                });
+            }
+            const enabled = params.value;
+            if (isYoloEnabled(rec.agent) !== enabled) {
+                setYoloEnabled(rec.agent, enabled);
+                await patchSessionEntry(this.#acpRoot, params.sessionId, {
+                    yolo: enabled,
+                });
+            }
+            return {
+                configOptions: buildSessionConfigOptions(rec.config, resolveSessionMode(getModeState(rec.agent).mode), isYoloEnabled(rec.agent)),
+            };
+        }
         if (typeof params.value !== "string") {
             throw RequestError.invalidParams({
                 configId: params.configId,
@@ -589,39 +667,16 @@ export class HoomanAcpAgent {
         }
         const value = params.value;
         if (params.configId === CONFIG_ID_MODE) {
-            if (value === MODE_VALUE_YOLO) {
-                // Yolo is agent mode with auto-approval on, not a distinct SessionMode.
-                if (this.#transitionMode(rec, "agent")) {
-                    // Keep the legacy `modes` surface in sync too (see Session Config
-                    // Options spec: "Agents SHOULD keep both in sync").
-                    await this.#syncCurrentMode(client, params.sessionId, rec);
-                }
-                if (!isYoloEnabled(rec.agent)) {
-                    setYoloEnabled(rec.agent, true);
-                    await patchSessionEntry(this.#acpRoot, params.sessionId, {
-                        yolo: true,
-                    });
-                }
+            if (!isKnownSessionMode(value)) {
+                throw RequestError.invalidParams({
+                    value,
+                    message: `Unknown mode "${value}"`,
+                });
             }
-            else {
-                if (!isKnownSessionMode(value)) {
-                    throw RequestError.invalidParams({
-                        value,
-                        message: `Unknown mode "${value}"`,
-                    });
-                }
-                if (this.#transitionMode(rec, value)) {
-                    // Keep the legacy `modes` surface in sync too (see Session Config
-                    // Options spec: "Agents SHOULD keep both in sync").
-                    await this.#syncCurrentMode(client, params.sessionId, rec);
-                }
-                // Selecting a plain mode always turns yolo back off.
-                if (isYoloEnabled(rec.agent)) {
-                    setYoloEnabled(rec.agent, false);
-                    await patchSessionEntry(this.#acpRoot, params.sessionId, {
-                        yolo: false,
-                    });
-                }
+            if (this.#transitionMode(rec, value)) {
+                // Keep the legacy `modes` surface in sync too (see Session Config
+                // Options spec: "Agents SHOULD keep both in sync").
+                await this.#syncCurrentMode(client, params.sessionId, rec);
             }
         }
         else if (params.configId === CONFIG_ID_MODEL) {
@@ -632,7 +687,7 @@ export class HoomanAcpAgent {
             // The conversation (and thus the context tokens in use) carries over to
             // the new model, so rescale the client's context gauge against the new
             // window immediately instead of leaving the old one up until the next
-            // turn ends. Skipped mid-turn: the rebuild (and billing re-resolution)
+            // turn ends. Skipped mid-turn: the rebuild (and metadata re-resolution)
             // is deferred to the turn boundary, and the running turn's own
             // `usage_update` is still correctly priced against the old model.
             if (!this.#isTurnActive(rec)) {
@@ -787,7 +842,7 @@ export class HoomanAcpAgent {
             const resolved = rec.config.llm;
             const provider = await modelProviders[resolved.provider]();
             rec.agent.model = provider.create(resolved.providerOptions, resolved.llmOptions);
-            rec.billing = await resolveLlmBilling(resolved.billing, resolved.llmOptions.model, resolved.provider, configuredLlmContext(resolved)).catch(() => null);
+            rec.metadata = await resolveLlmMetadata(resolved.metadata, resolved.llmOptions.model, resolved.provider, configuredLlmContext(resolved)).catch(() => null);
         }
         catch (error) {
             if (previous) {
@@ -825,7 +880,7 @@ export class HoomanAcpAgent {
                 if (persistEffort) {
                     this.#persistProviderEffort(rec, persistEffort.provider, persistEffort.effort);
                 }
-                // The rebuild re-resolved billing; rescale the client's context gauge
+                // The rebuild re-resolved metadata; rescale the client's context gauge
                 // against the new model's window (the turn's earlier `usage_update`
                 // carried the previous model's size). Best-effort: the turn result
                 // must not fail over a lost notification.
@@ -937,11 +992,13 @@ export class HoomanAcpAgent {
         let stopReason = "end_turn";
         try {
             const echo = acpPromptEchoText(params.prompt);
+            let turnMessageId;
             if (echo.length > 0) {
+                turnMessageId = crypto.randomUUID();
                 await this.#sendUpdate(client, params.sessionId, {
                     sessionUpdate: "user_message_chunk",
                     content: { type: "text", text: echo },
-                    messageId: crypto.randomUUID(),
+                    messageId: turnMessageId,
                 });
                 await this.#maybeDeriveTitle(client, params.sessionId, echo);
             }
@@ -967,8 +1024,16 @@ export class HoomanAcpAgent {
                             ? `${INIT_AGENTS_PROMPT}\n\n${command.args}`
                             : INIT_AGENTS_PROMPT,
                     },
-                ])
-                : acpPromptToInvokeArgs(params.prompt);
+                ], rec.metadata)
+                : acpPromptToInvokeArgs(params.prompt, rec.metadata);
+            // The `messageId` we just generated for this turn's user_message_chunk
+            // echo (see the ACP MessageId RFD) doubles as a durable handle for
+            // Cursor-style revert: bookmark where this turn's messages start,
+            // before `agent.stream(...)` appends them, so a later `rewindSession`
+            // can splice history back to exactly this point.
+            if (turnMessageId) {
+                recordTurnBoundary(rec.agent, turnMessageId, rec.agent.messages.length);
+            }
             const signals = [turnAbort.signal];
             if (this.#connectionSignal) {
                 signals.push(this.#connectionSignal);
@@ -1001,7 +1066,18 @@ export class HoomanAcpAgent {
                                 // live output with a JSON result blob. The structured result
                                 // still travels to the model via `rawOutput`.
                                 const terminalId = rec.terminalByToolCall.get(ev.toolUse.toolUseId);
-                                rec.terminalByToolCall.delete(ev.toolUse.toolUseId);
+                                // Keep terminalByToolCall for background jobs so live polling
+                                // can continue; only drop the mapping for foreground shells.
+                                const bgJob = extractBackgroundShellFromResult(ev.result);
+                                if (!bgJob) {
+                                    rec.terminalByToolCall.delete(ev.toolUse.toolUseId);
+                                }
+                                else if (terminalId) {
+                                    rec.shellJobs.set(bgJob.jobId, {
+                                        terminalId,
+                                        toolCallId: ev.toolUse.toolUseId,
+                                    });
+                                }
                                 const content = terminalId !== undefined
                                     ? [{ type: "terminal", terminalId }]
                                     : (diff ?? toolResultToAcpContent(ev.result));
@@ -1012,6 +1088,20 @@ export class HoomanAcpAgent {
                                     rawOutput: ev.result.toJSON(),
                                     content,
                                     ...(locations ? { locations } : {}),
+                                    ...(bgJob
+                                        ? {
+                                            _meta: {
+                                                "hoomanjs/shell_job": {
+                                                    event: "started",
+                                                    job_id: bgJob.jobId,
+                                                    description: bgJob.description,
+                                                    status: bgJob.jobStatus ?? "running",
+                                                    terminal_id: terminalId,
+                                                    tool_call_id: ev.toolUse.toolUseId,
+                                                },
+                                            },
+                                        }
+                                        : {}),
                                 });
                                 if (ev.toolUse.name === UPDATE_TODOS_TOOL_NAME &&
                                     ev.result.status === "success") {
@@ -1076,7 +1166,7 @@ export class HoomanAcpAgent {
      * Emit a `usage_update` at the end of a turn:
      * - `used`: context tokens of the latest request (additive prompt total,
      *   so cache reads/writes count regardless of provider reporting style).
-     * - `size`: the context window resolved from the model's `billing` config /
+     * - `size`: the context window resolved from the model's `metadata` config /
      *   the models.dev catalog; `0` ("unknown") when unresolved, in which case
      *   clients should not render a used/size percentage.
      * - `cost`: cumulative session USD, only while every priced request had
@@ -1091,11 +1181,11 @@ export class HoomanAcpAgent {
             return Promise.resolve();
         }
         const tokens = rec.lastTurnUsage;
-        const includeCost = rec.billing?.costs !== undefined && !rec.costUnpriced;
+        const includeCost = rec.metadata?.costs !== undefined && !rec.costUnpriced;
         return this.#sendUpdate(client, sessionId, {
             sessionUpdate: "usage_update",
             used: contextUsed,
-            size: rec.billing?.context ?? 0,
+            size: rec.metadata?.context ?? 0,
             ...(includeCost && {
                 cost: { amount: rec.cumulativeCostUsd, currency: "USD" },
             }),
@@ -1281,8 +1371,8 @@ export class HoomanAcpAgent {
                     // served it; once a request with usage runs unpriced, the total is
                     // incomplete and cost reporting stops for the session.
                     if ((additive.totalTokens ?? 0) > 0) {
-                        if (rec.billing?.costs) {
-                            rec.cumulativeCostUsd += computeUsageCostUsd(additive, rec.billing.costs);
+                        if (rec.metadata?.costs) {
+                            rec.cumulativeCostUsd += computeUsageCostUsd(additive, rec.metadata.costs);
                         }
                         else {
                             rec.costUnpriced = true;
@@ -1380,7 +1470,7 @@ export class HoomanAcpAgent {
         this.#registerTerminalBackend(agent, client, sessionId);
         setAskUserBackend(agent, createAcpAskUserBackend(client, sessionId));
         const activeLlm = config.llm;
-        const billing = await resolveLlmBilling(activeLlm.billing, activeLlm.llmOptions.model, activeLlm.provider, configuredLlmContext(activeLlm)).catch(() => null);
+        const metadata = await resolveLlmMetadata(activeLlm.metadata, activeLlm.llmOptions.model, activeLlm.provider, configuredLlmContext(activeLlm)).catch(() => null);
         return {
             cwd,
             agent,
@@ -1393,13 +1483,15 @@ export class HoomanAcpAgent {
             streamingToolInputJson: new Map(),
             lastStreamToolUseId: null,
             terminalByToolCall: new Map(),
+            shellJobs: new Map(),
+            shellJobUnsub: null,
             currentAssistantMessageId: null,
             pendingModeReapply: false,
             pendingModelRebuild: false,
             pendingPersistModel: null,
             pendingPersistEffort: null,
             lastTurnUsage: createEmptyUsage(),
-            billing,
+            metadata,
             cumulativeCostUsd: 0,
             costUnpriced: false,
             lastContextTokens: undefined,
@@ -1447,7 +1539,134 @@ export class HoomanAcpAgent {
         }
         setTerminalBackend(agent, {
             run: (request) => this.#runClientTerminal(client, sessionId, request),
+            spawn: (request) => this.#spawnClientTerminal(client, sessionId, request),
+            readOutput: (terminalId) => this.#readClientTerminal(client, sessionId, terminalId),
+            kill: (terminalId) => this.#killClientTerminal(client, sessionId, terminalId),
+        });
+    }
+    /** Call after the SessionRecord is stored in `#sessions`. */
+    #subscribeShellJobs(agent, client, sessionId) {
+        const record = this.#sessions.get(sessionId);
+        if (!record) {
+            return;
+        }
+        record.shellJobUnsub?.();
+        const manager = getShellJobManager(agent);
+        record.shellJobUnsub = manager.on((event) => {
+            void this.#onShellJobEvent(client, sessionId, event);
+        });
+    }
+    async #onShellJobEvent(client, sessionId, event) {
+        if (event.type !== "completed" &&
+            event.type !== "stopped" &&
+            event.type !== "failed") {
+            return;
+        }
+        const job = event.job;
+        const meta = {
+            "hoomanjs/shell_job": {
+                event: event.type,
+                job_id: job.id,
+                description: job.description,
+                status: job.status,
+                ready: job.ready,
+                exit_code: job.exitCode,
+                signal: job.signal,
+                terminal_id: job.terminalId,
+                tool_call_id: job.toolUseId,
+            },
+        };
+        // Meta-only update for the jobs bar — empty text so nothing lands in the
+        // transcript. Fire-and-forget release: awaiting a nested terminal/* RPC
+        // from inside stop_shell_job deadlocks the ACP connection.
+        void this.#sendUpdate(client, sessionId, {
+            sessionUpdate: "agent_message_chunk",
+            content: {
+                type: "text",
+                text: "",
+            },
+            _meta: meta,
+        }).catch(() => undefined);
+        const record = this.#sessions.get(sessionId);
+        const hosted = record?.shellJobs.get(job.id);
+        if (hosted) {
+            record?.shellJobs.delete(job.id);
+            void client
+                .request(methods.client.terminal.release, {
+                sessionId,
+                terminalId: hosted.terminalId,
+            })
+                .catch(() => undefined);
+        }
+    }
+    async #spawnClientTerminal(client, sessionId, request) {
+        const created = await client.request(methods.client.terminal.create, {
+            sessionId,
+            command: request.command,
+            args: request.args,
+            cwd: request.cwd,
+            ...(request.outputByteLimit !== undefined
+                ? { outputByteLimit: request.outputByteLimit }
+                : {}),
+        }, { cancellationSignal: request.cancelSignal });
+        const terminalId = created.terminalId;
+        const record = this.#sessions.get(sessionId);
+        if (request.jobId && record) {
+            record.shellJobs.set(request.jobId, {
+                terminalId,
+                toolCallId: request.toolUseId,
+            });
+        }
+        if (request.toolUseId) {
+            record?.terminalByToolCall.set(request.toolUseId, terminalId);
+            await this.#sendUpdate(client, sessionId, {
+                sessionUpdate: "tool_call_update",
+                toolCallId: request.toolUseId,
+                status: "in_progress",
+                content: [{ type: "terminal", terminalId }],
+            });
+        }
+        return { terminalId };
+    }
+    async #readClientTerminal(client, sessionId, terminalId) {
+        const output = await client.request(methods.client.terminal.output, {
+            sessionId,
+            terminalId,
         });
+        return {
+            output: output.output,
+            truncated: output.truncated,
+            exitCode: output.exitStatus?.exitCode ?? null,
+            signal: output.exitStatus?.signal ?? null,
+        };
+    }
+    async #killClientTerminal(client, sessionId, terminalId) {
+        await client
+            .request(methods.client.terminal.kill, { sessionId, terminalId })
+            .catch(() => undefined);
+    }
+    async #teardownShellJobs(sessionId, record) {
+        record.shellJobUnsub?.();
+        record.shellJobUnsub = null;
+        const client = this.#client;
+        for (const [jobId, hosted] of record.shellJobs) {
+            if (client) {
+                await client
+                    .request(methods.client.terminal.kill, {
+                    sessionId,
+                    terminalId: hosted.terminalId,
+                })
+                    .catch(() => undefined);
+                await client
+                    .request(methods.client.terminal.release, {
+                    sessionId,
+                    terminalId: hosted.terminalId,
+                })
+                    .catch(() => undefined);
+            }
+            record.shellJobs.delete(jobId);
+        }
+        await clearShellJobManager(record.agent).catch(() => undefined);
     }
     async #runClientTerminal(client, sessionId, request) {
         const created = await client.request(methods.client.terminal.create, {
@@ -1545,10 +1764,11 @@ export class HoomanAcpAgent {
         }
     }
     async #disposeAll() {
-        const records = [...this.#sessions.values()];
+        const entries = [...this.#sessions.entries()];
         this.#sessions.clear();
-        for (const record of records) {
+        for (const [sessionId, record] of entries) {
             record.turnAbort?.abort();
+            await this.#teardownShellJobs(sessionId, record);
             await record.mcpDisconnect();
         }
     }
@@ -1565,6 +1785,8 @@ export function createAcpApp(agent) {
         .onRequest(methods.agent.session.list, (ctx) => agent.listSessions(ctx.params))
         .onRequest(methods.agent.session.delete, (ctx) => agent.deleteSession(ctx.params))
         .onRequest(methods.agent.session.fork, (ctx) => agent.forkSession(ctx.params, ctx.client))
+        .onRequest("_hoomanjs/rewind_session", (params) => params, (ctx) => agent.rewindSession(ctx.params))
+        .onRequest("_hoomanjs/stop_shell_job", (params) => params, (ctx) => agent.stopShellJob(ctx.params))
         .onRequest(methods.agent.session.setMode, (ctx) => agent.setSessionMode(ctx.params, ctx.client))
         .onRequest(methods.agent.session.setConfigOption, (ctx) => agent.setSessionConfigOption(ctx.params, ctx.client))
         .onRequest(methods.agent.session.prompt, (ctx) => agent.prompt(ctx.params))
@@ -1577,4 +1799,66 @@ export async function runAcpStdio() {
     const connection = createAcpApp(new HoomanAcpAgent(identity)).connect(stream);
     await connection.closed;
 }
+/**
+ * Pull a background shell job payload out of a Strands tool result.
+ * The tool returns `{ status: "background", job_id, ... }` which the SDK wraps
+ * as a ToolResultBlock with a json content block.
+ */
+function extractBackgroundShellFromResult(result) {
+    const fromValue = (value) => {
+        if (!value || typeof value !== "object") {
+            return null;
+        }
+        const record = value;
+        if (record.status === "background" && typeof record.job_id === "string") {
+            return {
+                jobId: record.job_id,
+                description: typeof record.description === "string"
+                    ? record.description
+                    : undefined,
+                jobStatus: typeof record.job_status === "string" ? record.job_status : undefined,
+            };
+        }
+        return null;
+    };
+    if (Array.isArray(result.content)) {
+        for (const block of result.content) {
+            if (!block || typeof block !== "object") {
+                continue;
+            }
+            const json = block.json;
+            const nested = fromValue(json ?? block);
+            if (nested) {
+                return nested;
+            }
+        }
+    }
+    try {
+        const serialized = result.toJSON?.();
+        if (serialized && typeof serialized === "object") {
+            const wrapped = serialized;
+            const content = wrapped.toolResult?.content ?? wrapped.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (!block || typeof block !== "object") {
+                        continue;
+                    }
+                    const json = block.json;
+                    const nested = fromValue(json ?? block);
+                    if (nested) {
+                        return nested;
+                    }
+                }
+            }
+            const direct = fromValue(serialized);
+            if (direct) {
+                return direct;
+            }
+        }
+    }
+    catch {
+        // ignore serialization errors
+    }
+    return null;
+}
 //# sourceMappingURL=acp-agent.js.map