hoomanjs 1.40.2 → 1.41.0

package/dist/acp/acp-agent.js

@@ -3,20 +3,22 @@ import { readFile } from "node:fs/promises";
 import { Readable, Writable } from "node:stream";
 import { stdin, stdout } from "node:process";
 import { agent as acpAgent, methods, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
-import { isModelStreamEvent, Message, } from "@strands-agents/sdk";
+import { isModelStreamEvent, } from "@strands-agents/sdk";
 import { bootstrap } from "../core/index.js";
 import { applySessionMode } from "../core/agent/sync-tool-registry-mode.js";
 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 { ChatTurnSteeringController, createChatTurnSteeringIntervention, } from "../core/agent/turn-steering.js";
 import { getAgentConversationManager, getAgentSessionManager, } from "../core/agent/index.js";
 import { readBundledPrompt } from "../core/prompts/bundled.js";
-import { formatModeNames } from "../core/modes/definitions.js";
 import { modelProviders } from "../core/models/index.js";
-import { buildSessionConfigOptions, currentModelName, CONFIG_ID_EFFORT, CONFIG_ID_MODE, CONFIG_ID_MODEL, } from "./session-config.js";
-import { activeProviderName, currentReasoningEffort, parseReasoningEffortArg, REASONING_EFFORT_LEVELS, REASONING_EFFORT_OFF, withReasoningEffort, } from "../core/models/reasoning-effort.js";
-import { ACP_SLASH_COMMANDS, parseAcpSlashCommand, parseYoloToggle, } from "./commands.js";
+import { toAdditiveUsage } from "../core/models/usage.js";
+import { computeUsageCostUsd, 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 { 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";
 import { runWithCwd } from "../core/utils/cwd-context.js";
 import { runWithAgentMemoryScope } from "../core/memory/index.js";
@@ -28,15 +30,20 @@ import { toolCallLocationsFromInput } from "./utils/tool-locations.js";
 import { takeFileToolDisplay } from "../core/state/file-tool-display.js";
 import { getTodoViewState } from "../core/state/todos.js";
 import { UPDATE_TODOS_TOOL_NAME } from "../core/tools/todo.js";
-import { setTextFsBackend } from "../core/tools/text-fs-backend.js";
-import { setTerminalBackend, } from "../core/tools/terminal-backend.js";
+import { setAskUserBackend } from "../core/tools/ask-user.js";
+import { setTextFsBackend } from "../core/tools/filesystem.js";
+import { setTerminalBackend, } from "../core/tools/shell.js";
 import { createAcpToolApprovalIntervention } from "./approvals.js";
+import { createAcpAskUserBackend } from "./questions.js";
 import { extractAcpClientUserId } from "./meta/user-id.js";
+import { extractAcpVscodeFlag } from "./meta/vscode.js";
 import { deriveSessionTitleFromEcho } from "./sessions/title.js";
 import { acpPromptEchoText, acpPromptToInvokeArgs } from "./prompt-invoke.js";
 import { normalizeAcpSessionMcpServers } from "./mcp-servers.js";
 import { replayConversationHistory } from "./sessions/replay.js";
-import { deleteStoredSession, listStoredSessionIds, loadSessionMessages, patchSessionMeta, readSessionMeta, saveSessionMessages, toSessionInfo, writeSessionMeta, } from "./sessions/store.js";
+import { compactSessionIndex, deleteSessionEntry, migrateLegacySessionStore, patchSessionEntry, readSessionEntry, readSessionIndex, touchSessionEntry, writeSessionEntry, } from "./sessions/store.js";
+import { FlatFileStorage } from "../core/sessions/flat-file-storage.js";
+import { sessionsPath } from "../core/utils/paths.js";
 /** Max sessions returned per `session/list` page. */
 const LIST_PAGE_SIZE = 40;
 /** Fallback when a session record is missing (never mutate). */
@@ -83,6 +90,36 @@ function decodeCursor(cursor) {
         message: "Invalid pagination cursor",
     });
 }
+/** Zeroed `Usage` accumulator for a fresh session's cumulative billing meter. */
+function createEmptyUsage() {
+    return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+}
+/**
+ * Accumulate `source` into `target` in place, mirroring the CLI TUI's
+ * cumulative billing meter (`src/chat/app.tsx`): sum every request's token
+ * usage over the session, including cache reads/writes which recur (and are
+ * billed) on every request. `source` must already be in the additive shape
+ * (see `toAdditiveUsage`), where cache reads are not part of `inputTokens`.
+ */
+function accumulateUsage(target, source) {
+    target.inputTokens += source.inputTokens ?? 0;
+    target.outputTokens += source.outputTokens ?? 0;
+    if (source.cacheReadInputTokens !== undefined ||
+        target.cacheReadInputTokens !== undefined) {
+        target.cacheReadInputTokens =
+            (target.cacheReadInputTokens ?? 0) + (source.cacheReadInputTokens ?? 0);
+    }
+    if (source.cacheWriteInputTokens !== undefined ||
+        target.cacheWriteInputTokens !== undefined) {
+        target.cacheWriteInputTokens =
+            (target.cacheWriteInputTokens ?? 0) + (source.cacheWriteInputTokens ?? 0);
+    }
+    target.totalTokens =
+        target.inputTokens +
+            target.outputTokens +
+            (target.cacheReadInputTokens ?? 0) +
+            (target.cacheWriteInputTokens ?? 0);
+}
 function assertAbsolutePath(value, field) {
     const trimmed = value?.trim() ?? "";
     if (!trimmed) {
@@ -122,23 +159,26 @@ function isCancellationError(err, cancelSignals) {
 function toAcpStopReason(reason) {
     switch (reason) {
         case "cancelled":
+        case "interrupt":
             return "cancelled";
         case "maxTokens":
         case "modelContextWindowExceeded":
+        case "limitOutputTokens":
+        case "limitTotalTokens":
             return "max_tokens";
+        case "limitTurns":
+            return "max_turn_requests";
         case "contentFiltered":
         case "guardrailIntervened":
             return "refusal";
         case "endTurn":
         case "toolUse":
         case "stopSequence":
+        case "pauseTurn":
         default:
             return "end_turn";
     }
 }
-function serializeAgentMessages(agent) {
-    return agent.messages.map((m) => m.toJSON());
-}
 /** Normalize a persisted/requested mode to a known id, else the default. */
 function resolveSessionMode(mode) {
     return mode && isKnownSessionMode(mode) ? mode : DEFAULT_SESSION_MODE;
@@ -164,6 +204,10 @@ function buildSessionModeState(currentModeId) {
 export class HoomanAcpAgent {
     #identity;
     #acpRoot = acpSessionsRootPath();
+    /** Strands snapshot storage root (`<project>/sessions`); message source of truth. */
+    #snapshotsRoot = sessionsPath();
+    /** Resolves once the legacy store migration + index compaction have run. */
+    #storeReady;
     #sessions = new Map();
     /** Connection-scoped outbound context, captured in {@link onConnect}. */
     #client = null;
@@ -174,6 +218,9 @@ export class HoomanAcpAgent {
     #clientTerminalCap = false;
     constructor(identity) {
         this.#identity = identity;
+        this.#storeReady = migrateLegacySessionStore(this.#acpRoot, this.#snapshotsRoot)
+            .then(() => compactSessionIndex(this.#acpRoot))
+            .catch(() => undefined);
     }
     /** Bind connection-scoped lifecycle: capture the client + dispose on close. */
     onConnect(connection) {
@@ -202,7 +249,6 @@ export class HoomanAcpAgent {
                 loadSession: true,
                 promptCapabilities: {
                     image: true,
-                    audio: true,
                     embeddedContext: true,
                 },
                 mcpCapabilities: {
@@ -212,17 +258,24 @@ export class HoomanAcpAgent {
                 sessionCapabilities: {
                     list: {},
                     delete: {},
+                    resume: {},
+                    close: {},
                 },
             },
         };
     }
     async listSessions(params) {
-        const ids = await listStoredSessionIds(this.#acpRoot);
+        await this.#storeReady;
+        const entries = await readSessionIndex(this.#acpRoot);
         const sessions = [];
-        for (const id of ids) {
-            const info = await toSessionInfo(this.#acpRoot, id);
-            if (info && (!params.cwd || info.cwd === params.cwd)) {
-                sessions.push(info);
+        for (const entry of entries.values()) {
+            if (!params.cwd || entry.cwd === params.cwd) {
+                sessions.push({
+                    sessionId: entry.sessionId,
+                    cwd: entry.cwd,
+                    title: entry.title ?? null,
+                    updatedAt: entry.updatedAt,
+                });
             }
         }
         sessions.sort((a, b) => String(b.updatedAt ?? "").localeCompare(String(a.updatedAt ?? "")));
@@ -233,70 +286,135 @@ export class HoomanAcpAgent {
         return { sessions: page, nextCursor };
     }
     async deleteSession(params) {
+        await this.#storeReady;
         const record = this.#sessions.get(params.sessionId);
         if (record) {
             this.#sessions.delete(params.sessionId);
             record.turnAbort?.abort();
             await record.mcpDisconnect();
         }
-        await deleteStoredSession(this.#acpRoot, params.sessionId);
+        await deleteSessionEntry(this.#acpRoot, params.sessionId);
+        // Also drop the Strands snapshot (the conversation history itself).
+        await new FlatFileStorage(this.#snapshotsRoot).deleteSession({
+            sessionId: params.sessionId,
+        });
     }
     async newSession(params) {
+        await this.#storeReady;
         assertAbsolutePath(params.cwd, "cwd");
         const sessionId = crypto.randomUUID();
         const clientUserId = extractAcpClientUserId(params._meta) ?? null;
         const mcpServers = normalizeAcpSessionMcpServers(params.mcpServers);
+        const vscode = extractAcpVscodeFlag(params._meta);
         const mode = DEFAULT_SESSION_MODE;
         const now = new Date().toISOString();
-        const meta = {
+        const entry = {
+            sessionId,
             cwd: params.cwd,
             createdAt: now,
             updatedAt: now,
             title: null,
             userId: clientUserId,
             mcpServers,
+            ...(vscode ? { vscode } : {}),
             sessionMode: mode,
         };
-        await writeSessionMeta(this.#acpRoot, sessionId, meta);
-        const record = await this.#bootstrapSession(sessionId, params.cwd, clientUserId ?? sessionId, mcpServers, mode);
+        await writeSessionEntry(this.#acpRoot, entry);
+        const record = await this.#bootstrapSession(sessionId, params.cwd, clientUserId ?? sessionId, mcpServers, mode, undefined, vscode);
         this.#sessions.set(sessionId, record);
         await this.#advertiseCommands(this.#requireClient(), sessionId);
         return {
             sessionId,
             modes: buildSessionModeState(mode),
-            configOptions: buildSessionConfigOptions(record.config, mode),
+            configOptions: buildSessionConfigOptions(record.config, mode, isYoloEnabled(record.agent)),
         };
     }
     async loadSession(params, client) {
+        const { record, mode } = await this.#reactivateSession({
+            sessionId: params.sessionId,
+            cwd: params.cwd,
+            mcpServers: params.mcpServers,
+            meta: params._meta,
+        }, client, { replayHistory: true });
+        return {
+            modes: buildSessionModeState(mode),
+            configOptions: buildSessionConfigOptions(record.config, mode, isYoloEnabled(record.agent)),
+        };
+    }
+    /**
+     * 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`.
+     */
+    async resumeSession(params, client) {
+        const { record, mode } = await this.#reactivateSession({
+            sessionId: params.sessionId,
+            cwd: params.cwd,
+            mcpServers: params.mcpServers ?? [],
+            meta: params._meta,
+        }, client, { replayHistory: false });
+        return {
+            modes: buildSessionModeState(mode),
+            configOptions: buildSessionConfigOptions(record.config, mode, isYoloEnabled(record.agent)),
+        };
+    }
+    /**
+     * 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`).
+     */
+    async closeSession(params) {
+        const record = this.#sessions.get(params.sessionId);
+        if (record) {
+            this.#sessions.delete(params.sessionId);
+            record.turnAbort?.abort();
+            await record.mcpDisconnect();
+        }
+        return {};
+    }
+    /** Shared setup for `session/load` and `session/resume`. */
+    async #reactivateSession(params, client, options) {
         if (this.#sessions.has(params.sessionId)) {
             throw RequestError.invalidParams({
                 sessionId: params.sessionId,
                 message: "Session is already active in this agent process.",
             });
         }
-        const existing = await readSessionMeta(this.#acpRoot, params.sessionId);
+        await this.#storeReady;
+        const existing = await readSessionEntry(this.#acpRoot, params.sessionId);
         if (!existing) {
             throw RequestError.resourceNotFound(`session:${params.sessionId}`);
         }
         assertAbsolutePath(params.cwd, "cwd");
-        const fromRequest = extractAcpClientUserId(params._meta);
+        const fromRequest = extractAcpClientUserId(params.meta);
         const clientUserId = fromRequest !== undefined ? fromRequest : (existing.userId ?? null);
         const mcpServers = params.mcpServers.length > 0
             ? normalizeAcpSessionMcpServers(params.mcpServers)
             : (existing.mcpServers ?? []);
+        const vscode = extractAcpVscodeFlag(params.meta) || existing.vscode === true;
         const mode = resolveSessionMode(existing.sessionMode);
-        const record = await this.#bootstrapSession(params.sessionId, params.cwd, clientUserId ?? params.sessionId, mcpServers, mode, existing.model);
-        const saved = await loadSessionMessages(this.#acpRoot, params.sessionId);
-        record.agent.messages.length = 0;
-        for (const md of saved) {
-            record.agent.messages.push(Message.fromJSON(md));
+        // Bootstrapping restores the Strands snapshot (messages + appState) during
+        // `agent.initialize()` — the snapshot is the conversation source of truth.
+        const record = await this.#bootstrapSession(params.sessionId, params.cwd, clientUserId ?? params.sessionId, mcpServers, mode, existing.model, vscode);
+        // The snapshot restore replaces appState wholesale, so re-apply the
+        // connection-scoped values that must win over persisted state: the
+        // client's user id, and the index-persisted yolo/mode settings.
+        record.agent.appState.set("userId", clientUserId ?? params.sessionId);
+        setYoloEnabled(record.agent, existing.yolo === true);
+        if (resolveSessionMode(getModeState(record.agent).mode) !== mode) {
+            setSessionMode(record.agent, mode);
+            applySessionMode(record.agent);
+        }
+        if (options.replayHistory) {
+            await replayConversationHistory(client, params.sessionId, record.agent.messages);
         }
-        await replayConversationHistory(client, params.sessionId, record.agent.messages);
         this.#sessions.set(params.sessionId, record);
-        await patchSessionMeta(this.#acpRoot, params.sessionId, {
+        await patchSessionEntry(this.#acpRoot, params.sessionId, {
             cwd: params.cwd,
             ...(fromRequest !== undefined ? { userId: fromRequest || null } : {}),
             mcpServers,
+            ...(vscode ? { vscode } : {}),
             sessionMode: mode,
         });
         await this.#advertiseCommands(client, params.sessionId);
@@ -304,10 +422,7 @@ export class HoomanAcpAgent {
         if (getTodoViewState(record.agent).total > 0) {
             await this.#sendPlanUpdate(client, params.sessionId, record);
         }
-        return {
-            modes: buildSessionModeState(mode),
-            configOptions: buildSessionConfigOptions(record.config, mode),
-        };
+        return { record, mode };
     }
     /** Advertise the available slash commands for a freshly set-up session. */
     #advertiseCommands(client, sessionId) {
@@ -320,7 +435,7 @@ export class HoomanAcpAgent {
      * Handle `session/set_mode`: switch the active mode for a running session,
      * re-applying the tool surface and persisting the choice.
      */
-    async setSessionMode(params) {
+    async setSessionMode(params, client) {
         const rec = this.#sessions.get(params.sessionId);
         if (!rec) {
             throw RequestError.invalidParams({ sessionId: params.sessionId });
@@ -332,9 +447,9 @@ export class HoomanAcpAgent {
             });
         }
         if (this.#transitionMode(rec, params.modeId)) {
-            await patchSessionMeta(this.#acpRoot, params.sessionId, {
-                sessionMode: params.modeId,
-            });
+            // Keep the (superseding) config-options `mode` value in sync too, since
+            // Clients may read either surface (see Session Config Options spec).
+            await this.#syncCurrentMode(client, params.sessionId, rec);
         }
         return {};
     }
@@ -342,7 +457,7 @@ export class HoomanAcpAgent {
      * Handle `session/set_config_option`: apply a model or mode selection and
      * return the complete, up-to-date configuration state (as the spec requires).
      */
-    async setSessionConfigOption(params) {
+    async setSessionConfigOption(params, client) {
         const rec = this.#sessions.get(params.sessionId);
         if (!rec) {
             throw RequestError.invalidParams({ sessionId: params.sessionId });
@@ -355,21 +470,55 @@ export class HoomanAcpAgent {
         }
         const value = params.value;
         if (params.configId === CONFIG_ID_MODE) {
-            if (!isKnownSessionMode(value)) {
-                throw RequestError.invalidParams({
-                    value,
-                    message: `Unknown mode "${value}"`,
-                });
+            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 (this.#transitionMode(rec, value)) {
-                await patchSessionMeta(this.#acpRoot, params.sessionId, {
-                    sessionMode: 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,
+                    });
+                }
             }
         }
         else if (params.configId === CONFIG_ID_MODEL) {
             await this.#applyModelChange(rec, value);
-            await patchSessionMeta(this.#acpRoot, params.sessionId, { model: value });
+            await patchSessionEntry(this.#acpRoot, params.sessionId, {
+                model: value,
+            });
+            // 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)
+            // 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)) {
+                await this.#sendUsageUpdate(this.#requireClient(), params.sessionId, rec, undefined);
+            }
         }
         else if (params.configId === CONFIG_ID_EFFORT) {
             const parsed = parseReasoningEffortArg(value);
@@ -388,7 +537,7 @@ export class HoomanAcpAgent {
             });
         }
         return {
-            configOptions: buildSessionConfigOptions(rec.config, resolveSessionMode(getModeState(rec.agent).mode)),
+            configOptions: buildSessionConfigOptions(rec.config, resolveSessionMode(getModeState(rec.agent).mode), isYoloEnabled(rec.agent)),
         };
     }
     /** Whether a prompt turn is currently streaming for this session. */
@@ -522,6 +671,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).catch(() => null);
         }
         catch (error) {
             if (previous) {
@@ -541,7 +691,7 @@ export class HoomanAcpAgent {
      * Apply settings changes deferred during a turn (mode tool-surface + model
      * rebuild). Runs at the turn boundary before the next turn may start.
      */
-    async #flushPendingSettings(rec) {
+    async #flushPendingSettings(rec, client, sessionId) {
         if (rec.pendingModeReapply) {
             rec.pendingModeReapply = false;
             applySessionMode(rec.agent);
@@ -560,6 +710,11 @@ export class HoomanAcpAgent {
                 if (persistEffort) {
                     this.#persistProviderEffort(rec, persistEffort.provider, persistEffort.effort);
                 }
+                // The rebuild re-resolved billing; 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.
+                await this.#sendUsageUpdate(client, sessionId, rec, undefined).catch(() => undefined);
             }
         }
     }
@@ -567,117 +722,14 @@ export class HoomanAcpAgent {
      * Execute an inline (non-model) slash command and return the text reply to
      * stream back as an `agent_message_chunk`. `/init` is handled by the caller.
      */
-    #runControlCommand(client, sessionId, rec, command) {
+    #runControlCommand(rec, command) {
         switch (command.name) {
-            case "mode":
-                return this.#commandSetMode(client, sessionId, rec, command.args);
-            case "model":
-                return this.#commandSetModel(client, sessionId, rec, command.args);
-            case "effort":
-                return this.#commandSetEffort(client, sessionId, rec, command.args);
-            case "yolo":
-                return this.#commandSetYolo(sessionId, rec, command.args);
             case "compact":
                 return this.#commandCompact(rec);
             default:
                 return Promise.resolve(`Unknown command "/${command.name}".`);
         }
     }
-    async #commandSetMode(client, sessionId, rec, args) {
-        const current = resolveSessionMode(getModeState(rec.agent).mode);
-        const arg = args.trim().toLowerCase();
-        if (!arg) {
-            return `Usage: /mode <${formatModeNames()}>. Current mode: "${current}".`;
-        }
-        if (!isKnownSessionMode(arg)) {
-            return `Unknown mode "${arg}". Use ${formatModeNames()}.`;
-        }
-        if (!this.#transitionMode(rec, arg)) {
-            return `Already in "${arg}" mode.`;
-        }
-        await this.#syncCurrentMode(client, sessionId, rec);
-        return `Switched session mode to "${arg}".`;
-    }
-    async #commandSetModel(client, sessionId, rec, args) {
-        const arg = args.trim();
-        if (!arg) {
-            return this.#listModelsText(rec);
-        }
-        if (!rec.config.llms.some((entry) => entry.name === arg)) {
-            return `Unknown model "${arg}".\n\n${this.#listModelsText(rec)}`;
-        }
-        if (arg === currentModelName(rec.config)) {
-            return `Already using model "${arg}".`;
-        }
-        try {
-            await this.#applyModelChange(rec, arg);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return `Could not switch to model "${arg}": ${message}`;
-        }
-        await patchSessionMeta(this.#acpRoot, sessionId, { model: arg });
-        await this.#sendUpdate(client, sessionId, {
-            sessionUpdate: "config_option_update",
-            configOptions: buildSessionConfigOptions(rec.config, resolveSessionMode(getModeState(rec.agent).mode)),
-        });
-        return `Switched model to "${arg}".`;
-    }
-    #listModelsText(rec) {
-        const current = currentModelName(rec.config);
-        const lines = rec.config.llms.map((entry) => {
-            const marker = entry.name === current ? "*" : "-";
-            return `${marker} ${entry.name} (${entry.provider}/${entry.options.model})`;
-        });
-        return [
-            `Current model: ${current ?? "(none)"}`,
-            "Available models:",
-            ...lines,
-            'Use "/model <name>" to switch.',
-        ].join("\n");
-    }
-    async #commandSetEffort(client, sessionId, rec, args) {
-        const current = currentReasoningEffort(rec.config);
-        const arg = args.trim();
-        if (!arg) {
-            return `Current reasoning effort: "${current ?? REASONING_EFFORT_OFF}". Use ${REASONING_EFFORT_LEVELS.join(", ")} or ${REASONING_EFFORT_OFF}.`;
-        }
-        const parsed = parseReasoningEffortArg(arg);
-        if (!parsed) {
-            return `Unknown effort "${arg}". Use ${REASONING_EFFORT_LEVELS.join(", ")} or ${REASONING_EFFORT_OFF}.`;
-        }
-        if (parsed.value === current) {
-            return `Reasoning effort is already "${current ?? REASONING_EFFORT_OFF}".`;
-        }
-        try {
-            await this.#applyEffortChange(rec, parsed.value);
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            return `Could not set reasoning effort: ${message}`;
-        }
-        await this.#sendUpdate(client, sessionId, {
-            sessionUpdate: "config_option_update",
-            configOptions: buildSessionConfigOptions(rec.config, resolveSessionMode(getModeState(rec.agent).mode)),
-        });
-        return `Set reasoning effort to "${parsed.value ?? REASONING_EFFORT_OFF}".`;
-    }
-    async #commandSetYolo(sessionId, rec, args) {
-        const arg = args.trim();
-        if (!arg) {
-            return `Usage: /yolo <on|off>. Auto-approve is currently ${isYoloEnabled(rec.agent) ? "on" : "off"}.`;
-        }
-        const enabled = parseYoloToggle(arg);
-        if (enabled === undefined) {
-            return `Unknown value "${arg}". Use on or off.`;
-        }
-        if (isYoloEnabled(rec.agent) === enabled) {
-            return `Auto-approve is already ${enabled ? "on" : "off"}.`;
-        }
-        setYoloEnabled(rec.agent, enabled);
-        await patchSessionMeta(this.#acpRoot, sessionId, { yolo: enabled });
-        return `Auto-approve tools ${enabled ? "enabled" : "disabled"}.`;
-    }
     async #commandCompact(rec) {
         const conversationManager = getAgentConversationManager(rec.agent);
         if (!conversationManager) {
@@ -717,6 +769,28 @@ export class HoomanAcpAgent {
             /* ignore */
         }
     }
+    /**
+     * Queue guidance for the currently active turn via {@link ChatTurnSteeringController}
+     * rather than starting a new turn. Echoes the steered text back to the
+     * client tagged with `_meta["hoomanjs/steered"]` so it can be shown inline
+     * in the transcript. Errors (no active turn) surface as a normal RPC error.
+     */
+    async #steerActiveTurn(client, rec, params) {
+        if (!this.#isTurnActive(rec)) {
+            throw RequestError.invalidParams({
+                message: "No active turn to steer.",
+            });
+        }
+        const text = acpPromptEchoText(params.prompt);
+        rec.steering.queue([{ text, attachments: [] }]);
+        await this.#sendUpdate(client, params.sessionId, {
+            sessionUpdate: "user_message_chunk",
+            content: { type: "text", text },
+            messageId: crypto.randomUUID(),
+            _meta: { "hoomanjs/steered": true },
+        });
+        return { stopReason: "end_turn" };
+    }
     /** Run one prompt turn: stream model output, tool calls, and a stop reason. */
     async prompt(params) {
         const rec = this.#sessions.get(params.sessionId);
@@ -724,6 +798,12 @@ export class HoomanAcpAgent {
             throw RequestError.invalidParams({ sessionId: params.sessionId });
         }
         const client = this.#requireClient();
+        // A client-side "steer" request injects guidance into the *currently
+        // running* turn (via the steering intervention) instead of queuing a
+        // brand new one. See `_meta["hoomanjs/steer"]` extensibility contract.
+        if (params._meta?.["hoomanjs/steer"] === true) {
+            return this.#steerActiveTurn(client, rec, params);
+        }
         // Serialize concurrent prompt turns for the same session.
         const prevExclusive = rec.promptExclusive;
         let releaseExclusive;
@@ -737,6 +817,7 @@ export class HoomanAcpAgent {
         rec.streamedToolCallIds.clear();
         rec.streamingToolInputJson.clear();
         rec.lastStreamToolUseId = null;
+        rec.currentAssistantMessageId = null;
         let stopReason = "end_turn";
         try {
             const echo = acpPromptEchoText(params.prompt);
@@ -744,6 +825,7 @@ export class HoomanAcpAgent {
                 await this.#sendUpdate(client, params.sessionId, {
                     sessionUpdate: "user_message_chunk",
                     content: { type: "text", text: echo },
+                    messageId: crypto.randomUUID(),
                 });
                 await this.#maybeDeriveTitle(client, params.sessionId, echo);
             }
@@ -751,11 +833,12 @@ export class HoomanAcpAgent {
             // (no model turn); `/init` rewrites the prompt and runs normally.
             const command = parseAcpSlashCommand(echo);
             if (command && command.name !== "init") {
-                const reply = await this.#runControlCommand(client, params.sessionId, rec, command);
+                const reply = await this.#runControlCommand(rec, command);
                 if (reply) {
                     await this.#sendUpdate(client, params.sessionId, {
                         sessionUpdate: "agent_message_chunk",
                         content: { type: "text", text: reply },
+                        messageId: crypto.randomUUID(),
                     });
                 }
                 return { stopReason: "end_turn" };
@@ -826,6 +909,7 @@ export class HoomanAcpAgent {
                             }
                             else if (ev.type === "agentResultEvent") {
                                 stopReason = toAcpStopReason(ev.result.stopReason);
+                                await this.#sendUsageUpdate(client, params.sessionId, rec, ev.result.contextSize);
                             }
                             iter = await stream.next();
                         }
@@ -842,6 +926,7 @@ export class HoomanAcpAgent {
                     await this.#sendUpdate(client, params.sessionId, {
                         sessionUpdate: "agent_message_chunk",
                         content: { type: "text", text: `\n[error] ${message}\n` },
+                        messageId: this.#assistantMessageId(rec),
                     });
                     stopReason = "refusal";
                 }
@@ -857,10 +942,13 @@ export class HoomanAcpAgent {
             rec.turnAbort = null;
             // Apply mode/model changes requested mid-turn before releasing the gate
             // so the next turn sees the settled state.
-            await this.#flushPendingSettings(rec);
+            await this.#flushPendingSettings(rec, client, params.sessionId);
             releaseExclusive();
+            // Conversation history is persisted by the Strands session manager
+            // (snapshot save on AfterInvocation, which fires even on error/cancel);
+            // only the index's `updatedAt` needs bumping for `session/list` order.
             try {
-                await saveSessionMessages(this.#acpRoot, params.sessionId, serializeAgentMessages(rec.agent));
+                await touchSessionEntry(this.#acpRoot, params.sessionId);
             }
             catch {
                 /* ignore */
@@ -868,6 +956,46 @@ export class HoomanAcpAgent {
         }
         return { stopReason };
     }
+    /**
+     * 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 /
+     *   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
+     *   resolved rates — otherwise omitted rather than reporting a lowball.
+     * - `_meta["hoomanjs/tokens"]`: cumulative token totals for the session
+     *   (mirroring the CLI TUI's `in`/`cin`/`out` billing meter).
+     */
+    #sendUsageUpdate(client, sessionId, rec, used) {
+        const contextUsed = rec.lastContextTokens ?? used;
+        if (contextUsed === undefined) {
+            return Promise.resolve();
+        }
+        const tokens = rec.cumulativeUsage;
+        const includeCost = rec.billing?.costs !== undefined && !rec.costUnpriced;
+        return this.#sendUpdate(client, sessionId, {
+            sessionUpdate: "usage_update",
+            used: contextUsed,
+            size: rec.billing?.context ?? 0,
+            ...(includeCost && {
+                cost: { amount: rec.cumulativeCostUsd, currency: "USD" },
+            }),
+            _meta: {
+                "hoomanjs/tokens": {
+                    input: tokens.inputTokens,
+                    output: tokens.outputTokens,
+                    ...(tokens.cacheReadInputTokens !== undefined && {
+                        cacheRead: tokens.cacheReadInputTokens,
+                    }),
+                    ...(tokens.cacheWriteInputTokens !== undefined && {
+                        cacheWrite: tokens.cacheWriteInputTokens,
+                    }),
+                },
+            },
+        });
+    }
     /**
      * Surface the agent's todo list as an ACP `plan` update. Sends the complete
      * list, as the client replaces the plan wholesale on each update. The
@@ -892,7 +1020,7 @@ export class HoomanAcpAgent {
      */
     async #syncCurrentMode(client, sessionId, rec) {
         const modeId = resolveSessionMode(getModeState(rec.agent).mode);
-        await patchSessionMeta(this.#acpRoot, sessionId, { sessionMode: modeId });
+        await patchSessionEntry(this.#acpRoot, sessionId, { sessionMode: modeId });
         await this.#sendUpdate(client, sessionId, {
             sessionUpdate: "current_mode_update",
             currentModeId: modeId,
@@ -900,16 +1028,20 @@ export class HoomanAcpAgent {
         // Config Options supersede modes; mirror the change for config-aware clients.
         await this.#sendUpdate(client, sessionId, {
             sessionUpdate: "config_option_update",
-            configOptions: buildSessionConfigOptions(rec.config, modeId),
+            configOptions: buildSessionConfigOptions(rec.config, modeId, isYoloEnabled(rec.agent)),
         });
     }
-    /** Derive + persist a title from the first meaningful prompt echo. */
+    /**
+     * Derive + persist an instant placeholder title from the first meaningful
+     * prompt echo. The session-title plugin upgrades it with an AI-generated
+     * summary once the turn runs (see `onSessionTitle` in the bootstrap meta).
+     */
     async #maybeDeriveTitle(client, sessionId, echo) {
-        const meta = await readSessionMeta(this.#acpRoot, sessionId);
-        const needsTitle = meta &&
-            (meta.title === undefined ||
-                meta.title === null ||
-                String(meta.title).trim() === "");
+        const entry = await readSessionEntry(this.#acpRoot, sessionId);
+        const needsTitle = entry &&
+            (entry.title === undefined ||
+                entry.title === null ||
+                String(entry.title).trim() === "");
         if (!needsTitle) {
             return;
         }
@@ -917,7 +1049,7 @@ export class HoomanAcpAgent {
         if (!title) {
             return;
         }
-        await patchSessionMeta(this.#acpRoot, sessionId, { title });
+        await patchSessionEntry(this.#acpRoot, sessionId, { title });
         await this.#sendUpdate(client, sessionId, {
             sessionUpdate: "session_info_update",
             title,
@@ -931,6 +1063,12 @@ export class HoomanAcpAgent {
             return;
         }
         switch (inner.type) {
+            case "modelMessageStartEvent": {
+                // A new assistant message starts a fresh `messageId` shared by all of
+                // its `agent_message_chunk`/`agent_thought_chunk` updates.
+                rec.currentAssistantMessageId = crypto.randomUUID();
+                return;
+            }
             case "modelContentBlockStartEvent": {
                 const start = inner.start;
                 if (start?.type === "toolUseStart") {
@@ -954,6 +1092,7 @@ export class HoomanAcpAgent {
                     await this.#sendUpdate(client, sessionId, {
                         sessionUpdate: "agent_message_chunk",
                         content: { type: "text", text: delta.text },
+                        messageId: this.#assistantMessageId(rec),
                     });
                     return;
                 }
@@ -962,6 +1101,7 @@ export class HoomanAcpAgent {
                         await this.#sendUpdate(client, sessionId, {
                             sessionUpdate: "agent_thought_chunk",
                             content: { type: "text", text: delta.text },
+                            messageId: this.#assistantMessageId(rec),
                         });
                     }
                     return;
@@ -990,11 +1130,34 @@ export class HoomanAcpAgent {
                                 type: "text",
                                 text: `[citations: ${n} reference(s)]\n`,
                             },
+                            messageId: this.#assistantMessageId(rec),
                         });
                     }
                 }
                 return;
             }
+            case "modelMetadataEvent": {
+                if (inner.usage) {
+                    // Providers like OpenAI/Moonshot report input inclusive of cache
+                    // reads; normalize to the additive shape so `in`/`cin` don't
+                    // double-count in the client's meter.
+                    const additive = toAdditiveUsage(inner.usage, rec.agent.model);
+                    accumulateUsage(rec.cumulativeUsage, additive);
+                    rec.lastContextTokens = contextTokensFromUsage(additive);
+                    // Session cost accrues per request at the rates of the model that
+                    // 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);
+                        }
+                        else {
+                            rec.costUnpriced = true;
+                        }
+                    }
+                }
+                return;
+            }
             case "modelRedactionEvent": {
                 const replace = inner.outputRedaction?.replaceContent ??
                     inner.inputRedaction?.replaceContent;
@@ -1002,6 +1165,7 @@ export class HoomanAcpAgent {
                     await this.#sendUpdate(client, sessionId, {
                         sessionUpdate: "agent_message_chunk",
                         content: { type: "text", text: replace },
+                        messageId: this.#assistantMessageId(rec),
                     });
                 }
                 return;
@@ -1010,6 +1174,13 @@ export class HoomanAcpAgent {
                 return;
         }
     }
+    /** Lazily assign a `messageId` for the in-flight assistant message. */
+    #assistantMessageId(rec) {
+        if (!rec.currentAssistantMessageId) {
+            rec.currentAssistantMessageId = crypto.randomUUID();
+        }
+        return rec.currentAssistantMessageId;
+    }
     #streamToolUseIdForInputDelta(rec) {
         if (rec.lastStreamToolUseId &&
             rec.streamedToolCallIds.has(rec.lastStreamToolUseId)) {
@@ -1029,7 +1200,7 @@ export class HoomanAcpAgent {
         }
         return this.#client;
     }
-    async #bootstrapSession(sessionId, cwd, userId, mcpServers, mode, preferredModel) {
+    async #bootstrapSession(sessionId, cwd, userId, mcpServers, mode, preferredModel, vscode = false) {
         const client = this.#requireClient();
         const sessionConfig = createSessionConfig();
         if (preferredModel &&
@@ -1042,18 +1213,37 @@ export class HoomanAcpAgent {
                 })),
             });
         }
+        const steering = new ChatTurnSteeringController();
         const { config, agent, mcp: { manager }, } = await bootstrap("acp", {
             userId,
             sessionId,
             mode,
+            interventions: [createChatTurnSteeringIntervention(steering)],
             createInterventions: () => [
                 createAcpToolApprovalIntervention(client, sessionId, () => this.#sessions.get(sessionId)?.streamedToolCallIds ??
                     EMPTY_STREAMED_TOOL_CALL_IDS),
             ],
-            acp: { mcpServers: mcpServers ?? [] },
+            // The session-title plugin generated an AI title (upgrading the
+            // echo-derived placeholder): persist it and notify the client.
+            onSessionTitle: async (title) => {
+                await patchSessionEntry(this.#acpRoot, sessionId, { title });
+                await this.#sendUpdate(client, sessionId, {
+                    sessionUpdate: "session_info_update",
+                    title,
+                    updatedAt: new Date().toISOString(),
+                });
+            },
+            acp: {
+                mcpServers: mcpServers ?? [],
+                vscode,
+                cwd,
+            },
         }, false, sessionConfig);
         this.#registerTextFsBackend(agent, client, sessionId);
         this.#registerTerminalBackend(agent, client, sessionId);
+        setAskUserBackend(agent, createAcpAskUserBackend(client, sessionId));
+        const activeLlm = config.llm;
+        const billing = await resolveLlmBilling(activeLlm.billing, activeLlm.llmOptions.model).catch(() => null);
         return {
             cwd,
             agent,
@@ -1061,14 +1251,21 @@ export class HoomanAcpAgent {
             mcpDisconnect: () => manager.disconnect().catch(() => undefined),
             turnAbort: null,
             promptExclusive: Promise.resolve(),
+            steering,
             streamedToolCallIds: new Set(),
             streamingToolInputJson: new Map(),
             lastStreamToolUseId: null,
             terminalByToolCall: new Map(),
+            currentAssistantMessageId: null,
             pendingModeReapply: false,
             pendingModelRebuild: false,
             pendingPersistModel: null,
             pendingPersistEffort: null,
+            cumulativeUsage: createEmptyUsage(),
+            billing,
+            cumulativeCostUsd: 0,
+            costUnpriced: false,
+            lastContextTokens: undefined,
         };
     }
     /**
@@ -1224,10 +1421,12 @@ export function createAcpApp(agent) {
         .onRequest(methods.agent.initialize, (ctx) => agent.initialize(ctx.params))
         .onRequest(methods.agent.session.new, (ctx) => agent.newSession(ctx.params))
         .onRequest(methods.agent.session.load, (ctx) => agent.loadSession(ctx.params, ctx.client))
+        .onRequest(methods.agent.session.resume, (ctx) => agent.resumeSession(ctx.params, ctx.client))
+        .onRequest(methods.agent.session.close, (ctx) => agent.closeSession(ctx.params))
         .onRequest(methods.agent.session.list, (ctx) => agent.listSessions(ctx.params))
         .onRequest(methods.agent.session.delete, (ctx) => agent.deleteSession(ctx.params))
-        .onRequest(methods.agent.session.setMode, (ctx) => agent.setSessionMode(ctx.params))
-        .onRequest(methods.agent.session.setConfigOption, (ctx) => agent.setSessionConfigOption(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))
         .onNotification(methods.agent.session.cancel, (ctx) => agent.cancel(ctx.params));
 }