@cjhyy/code-shell-core 0.5.0-rc.2 → 0.6.0-rc.10

package/dist/prompt/composer.js

@@ -31,8 +31,13 @@ export class PromptComposer {
      */
     buildUserContextMessage() {
         const instructions = this.getInstructions();
-        const memoryContext = this.getMemoryContext();
-        if (!instructions && !memoryContext)
+        // NOTE: memory is intentionally NOT here. It used to be, but memory mutates
+        // constantly (extraction, recall usage++/lastUsed, approve/demote), and this
+        // message sits in the cacheable system prefix — so every memory change
+        // invalidated the whole prefix and re-billed it. Memory now rides
+        // buildDynamicContextMessage (tail, past the cache breakpoint), same as the
+        // skills listing and git status which had the identical problem.
+        if (!instructions)
             return null;
         // Local date, not UTC — toISOString() is UTC and would show the wrong
         // "today" for users whose timezone has crossed midnight (review-2026-05-30).
@@ -40,10 +45,7 @@ export class PromptComposer {
         const ymd = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, "0")}-${String(now.getDate()).padStart(2, "0")}`;
         const currentDate = `Today's date is ${ymd}.`;
         let content = `<system-reminder>\n${currentDate}\n\n`;
-        if (instructions)
-            content += `${instructions}\n\n`;
-        if (memoryContext)
-            content += `${memoryContext}\n`;
+        content += `${instructions}\n`;
         content += `</system-reminder>`;
         return { role: "user", content };
     }
@@ -87,6 +89,46 @@ export class PromptComposer {
         }
         return gitStatus;
     }
+    /**
+     * Per-turn dynamic context, delivered as a trailing <system-reminder> user
+     * message rather than baked into the system prefix.
+     *
+     * Holds the two things that change *within* a session — the skills listing
+     * (changes when a skill is installed/disabled) and the git-status snapshot
+     * (changes whenever the working tree changes). Keeping them out of the
+     * system prompt means installing a skill or editing a file no longer
+     * invalidates the cached system prefix. Placed at the END of the messages
+     * array (after the user task) so it sits past the conversation's cache
+     * breakpoint — a change here never re-bills the history prefix.
+     */
+    async buildDynamicContextMessage() {
+        const skills = scanSkills(this.options.cwd, {
+            disabledSkills: this.options.disabledSkills,
+            disabledPlugins: this.options.disabledPlugins,
+            skillAllowlist: this.options.skillAllowlist,
+        });
+        const skillsListing = buildSkillListing(skills);
+        const gitStatus = await this.buildSystemContext();
+        // Memory rides here (tail, past the cache breakpoint) — not the system
+        // prefix — so a memory change (extraction / recall usage++ / approve) never
+        // re-bills the cached prefix. See buildUserContextMessage for the rationale.
+        const memoryContext = this.getMemoryContext();
+        const goalToolContext = this.buildGoalToolContext();
+        const parts = [skillsListing, gitStatus, memoryContext, goalToolContext].filter(Boolean);
+        if (parts.length === 0)
+            return null;
+        return {
+            role: "user",
+            content: `<system-reminder>\n${parts.join("\n\n")}\n</system-reminder>`,
+        };
+    }
+    buildGoalToolContext() {
+        if (!this.options.goalToolState)
+            return "";
+        return this.options.goalToolState.hasGoal
+            ? "当前存在 active goal。只有在目标完全完成时才可调用 complete_goal；只有用户明确要求取消/停止/放弃该目标时才可调用 cancel_goal。"
+            : "当前没有 active goal。不要调用 complete_goal/cancel_goal；如果误调用，系统会拒绝。";
+    }
     invalidateCache(sectionName) {
         this.sectionCache.invalidate(sectionName);
         if (!sectionName) {
@@ -129,25 +171,31 @@ export class PromptComposer {
                 },
             });
         }
-        // Behavioral instructions — loaded from preset's section files
+        // Behavioral instructions — loaded from preset's section files. Pass the
+        // turn's effective tool names so tool-gated sections (e.g. "browser") drop
+        // when their tools are disabled: browser capability = tools + instructions
+        // as one on/off unit.
+        const activeToolNames = tools.map((t) => t.name);
         sections.push({
             name: "behavior",
+            // cacheBreak: this section's content varies by activeToolNames (tool-gated
+            // sections like "browser" drop when their tools are off). The cache is
+            // keyed by section NAME only, so without cacheBreak a reused composer could
+            // serve a stale behavior block across an on/off change. Recompute always —
+            // it's a cheap string join, and it makes the browser on/off unit correct
+            // regardless of composer lifetime.
+            cacheBreak: true,
             compute: () => {
                 const preset = this.options.preset ?? resolveAgentPreset();
-                return buildPresetSystemPrompt(preset);
-            },
-        });
-        // Skills listing
-        sections.push({
-            name: "skills",
-            compute: () => {
-                const skills = scanSkills(this.options.cwd, {
-                    disabledSkills: this.options.disabledSkills,
-                    disabledPlugins: this.options.disabledPlugins,
-                });
-                return buildSkillListing(skills);
+                return buildPresetSystemPrompt(preset, { activeToolNames, platform: process.platform });
             },
         });
+        // Skills listing is intentionally NOT a system section: it changes when a
+        // skill is installed/disabled, which would invalidate the whole cached
+        // system prefix on every change. It rides in the per-turn dynamic-context
+        // message instead (buildDynamicContextMessage). Same reasoning keeps the
+        // git-status snapshot out of the system prefix — see buildSystemContext's
+        // callers.
         // Append system prompt
         if (this.options.appendSystemPrompt) {
             sections.push({
@@ -183,8 +231,14 @@ export class PromptComposer {
     }
     getMemoryContext() {
         try {
-            const mm = new MemoryManager(this.options.cwd);
-            return mm.buildMemoryContext();
+            // Two-layer injection (用户拍板): a compact index merging GLOBAL +
+            // PROJECT memories. Global memories are now surfaced every session
+            // regardless of cwd (the fix for "global memory never shows up"); the
+            // model reads full bodies on demand via MemoryRead.
+            return MemoryManager.buildInjectionIndex({
+                projectDir: this.options.cwd,
+                maxAgeDays: this.options.memoriesMaxAgeDays,
+            });
         }
         catch {
             return "";

package/dist/prompt/instruction-scanner.js

@@ -17,7 +17,7 @@
 import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, dirname, resolve } from "node:path";
 import { execSync } from "node:child_process";
-import { homedir } from "node:os";
+import { userHome } from "../settings/manager.js";
 // ─── Public API ─────────────────────────────────────────────────────
 /**
  * Scan for instruction files from cwd up to the project root,
@@ -32,8 +32,10 @@ export function scanInstructions(cwd, options = {}) {
     const configDirs = [".codeshell", ...(options.scanDirs ?? []), ".claude"];
     const entries = [];
     // 1. User-level instructions
-    const homeConfigDir = join(homedir(), ".code-shell");
-    const homeCompatDir = join(homedir(), ".claude");
+    // userHome() (not raw homedir(), bun-cached) so a test/host HOME override
+    // scans the intended user-level dirs, not the developer's real ~/.code-shell.
+    const homeConfigDir = join(userHome(), ".code-shell");
+    const homeCompatDir = join(userHome(), ".claude");
     for (const name of allNames) {
         tryAddFile(join(homeConfigDir, name), "user", -1, entries);
     }

package/dist/prompt/section-loader.js

@@ -13,6 +13,7 @@ const BUILTIN_SECTIONS = {
     base: readSectionFile("base"),
     orchestration: readSectionFile("orchestration"),
     coding: readSectionFile("coding"),
+    browser: readSectionFile("browser"),
     tone: readSectionFile("tone"),
 };
 /** Registry for custom sections added at runtime. */

package/dist/prompt/sections/base.md

@@ -31,5 +31,7 @@ When you encounter an obstacle, do not use destructive actions as a shortcut to
   - To search for files use Glob instead of find or ls
   - To search the content of files, use Grep instead of grep or rg
   - Reserve using the Bash exclusively for system commands and terminal operations that require shell execution.
+ - Shell choice: use Bash for ordinary shell commands, git operations, package-manager commands, test/build scripts, and POSIX-style command lines. Use PowerShell only when the user explicitly asks for it or the task requires PowerShell-specific cmdlets, Windows APIs, registry access, or `.ps1` behavior.
+ - For long-lived processes that don't exit on their own — a dev server (`npm run dev`, `vite`), a watcher, a tunnel — call Bash with `run_in_background: true`. It returns a `shell_id` immediately instead of blocking until a timeout. Then use `BashOutput(shell_id)` to read its logs (e.g. to confirm it started or to see an error), `ListShells()` to see what's running, and `KillShell(shell_id)` to stop it. Never run such a command in the foreground — it will just block until it's killed. Plain one-shot commands (build, test, git) stay foreground.
  - Break down and manage multi-step work with the TodoWrite tool. Pass the complete todo list each call; rewrite it as items move pending → in_progress → completed.
  - You can call multiple tools in a single response. If you intend to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel.

package/dist/prompt/sections/browser.md

@@ -0,0 +1,10 @@
+## Browser automation (browser_observe / browser_act / browser_navigate)
+ - When a task needs you to operate a real web page — search a site, open a result, read/extract an article, fill a form — drive the built-in browser panel with the three browser tools. They run on the panel's logged-in session, so the user's existing logins are reused.
+ - You do NOT need the user to open the panel first: if none is open, just call `browser_navigate{url}` and the panel opens automatically. After navigating, `browser_act{action:"wait"}` then `browser_observe`.
+ - The loop is observe → act → re-observe: ALWAYS `browser_observe` first (default mode `snapshot`) to see the page's interactive elements (each tagged `[ref=eN]`), then `browser_act` on elements BY THAT ref: `{action:"click",ref}`, `{action:"type",ref,text}`, `{action:"select",ref,value}` (native `<select>`), `{action:"hover",ref}`. Refs are only valid for the most recent snapshot — after any navigation, content-loading click, or `{action:"scroll"}`, run `{action:"wait"}` then `browser_observe` again. If an action says a ref is stale, re-observe.
+ - To submit a search: `browser_act{action:"type",ref,text}` into the search box, then `browser_act{action:"press_key",key:"Enter"}`, then `{action:"wait"}` + `browser_observe`. `press_key` also does Tab / Escape / arrows / combos like `Control+a`.
+ - To extract/summarize page content, navigate/click to it, `browser_act{action:"wait"}`, then `browser_observe{mode:"read"}` — cleaned readable text to summarize (long pages truncate; `{action:"scroll"}` + read again). For the real link/image/video URLs the snapshot omits, use `browser_observe{mode:"extract"}` (each image/video tagged [ref=imgN/vidN]).
+ - To SEE an actual image's content (e.g. a 小红书 笔记配图 or product photo), `browser_observe{mode:"extract"}` to get image refs, then `browser_observe{mode:"image", refs:["img3"]}` — it loads the real pixels (works behind hotlink protection). A vidN ref grabs the video's current frame. To see the rendered layout/canvas/chart, `browser_observe{mode:"vision"}` (optionally `ref` for one region). Use images sparingly — they cost tokens; prefer snapshot/read. (Both need a vision-capable model; on a non-vision model they're skipped.) Do NOT repeat `vision` on the same page hoping for a clearer view — one screenshot is all you get. If snapshot/screenshot don't reveal what you need (infinite-scroll/canvas feeds), scroll + re-observe or extract the URLs and act on them — don't loop screenshots.
+ - Multiple tabs: `browser_act{action:"list_tabs"}` shows open tabs (tabId/url/title/active); `browser_act{action:"switch_tab", tabId}` makes another the active one (then re-observe). Any action also accepts `tabId` to target a specific tab (it switches first). Refs are per-tab — re-observe after switching.
+ - If `browser_observe` reports a sign-in is required (or you hit a login wall / 2FA), STOP and ask the user to log in manually in the browser panel, then continue — do not attempt to enter credentials yourself. Sensitive actions (payment, delete, entering card/password values) require user approval.
+ - These tools need the desktop app's browser panel; if they report unavailable, the environment has no panel (headless) — say so rather than retrying.

package/dist/prompt/sections/coding.md

@@ -26,6 +26,10 @@ The default job in this preset is software engineering in the current working di
  - When referencing specific functions or pieces of code include the pattern file_path:line_number to allow the user to easily navigate to the source code location.
  - When referencing GitHub issues or pull requests, use the owner/repo#123 format so they render as clickable links.
 
+## Opening URLs and local previews
+ - To show the user a web page or a local dev-server preview, print the address in your reply as a bare URL or a markdown link (e.g. `http://localhost:5173` or [预览](http://localhost:5173)) — do NOT wrap it in backticks. The desktop app turns a link in your answer into a clickable link that opens inside its built-in browser panel; backtick-wrapped URLs render as plain code and are not clickable.
+ - Do NOT run shell commands to open a URL (`open <url>` on macOS, `xdg-open` on Linux, `start <url>` on Windows). Those launch the user's external system browser and bypass the in-app browser panel. Start the dev server, then just tell the user the address as a link.
+
 ## Coding tools
  - Use git/worktree/LSP/notebook tools when they help, but treat them as optional helpers rather than core assumptions.
  - If the user asks for help or feedback, point them to /help and the project repository.

package/dist/protocol/chat-session-manager.d.ts

@@ -1,8 +1,8 @@
 import { ChatSession } from "./chat-session.js";
 import type { Engine } from "../engine/engine.js";
 import type { EngineRuntime } from "../engine/runtime.js";
-import type { EngineConfig } from "../engine/engine.js";
-export type EngineConfigSlice = Pick<EngineConfig, "permissionMode" | "preset" | "customSystemPrompt" | "appendSystemPrompt" | "goal" | "maxTurns" | "maxContextTokens" | "cwd">;
+import type { EngineConfig } from "../engine/types.js";
+export type EngineConfigSlice = Pick<EngineConfig, "permissionMode" | "preset" | "customSystemPrompt" | "appendSystemPrompt" | "goal" | "maxTurns" | "maxContextTokens" | "cwd" | "projectTrusted">;
 export interface ChatSessionManagerOptions {
     /**
      * Shared runtime, supplied here so callers and engineFactory closures
@@ -17,6 +17,7 @@ export interface ChatSessionManagerOptions {
 }
 export declare class ChatSessionManager {
     private readonly sessions;
+    readonly runtime: EngineRuntime;
     private readonly factory;
     private readonly maxSessions;
     private readonly idleTtlMs;
@@ -33,6 +34,12 @@ export declare class ChatSessionManager {
     forEachSession(fn: (s: ChatSession) => void): void;
     close(sessionId: string): void;
     closeAll(): void;
+    /**
+     * Await-able shutdown. Cancels every session and reaps every background
+     * shell, *waiting* for the kill grace so a caller that exits the process
+     * immediately afterward (the TUI REPL) doesn't orphan detached dev servers.
+     */
+    closeAllAsync(): Promise<void>;
     sessionCount(): number;
     sweepIdle(): void;
     startIdleSweeper(intervalMs?: number): void;

package/dist/protocol/chat-session-manager.js

@@ -1,11 +1,15 @@
 import { ChatSession } from "./chat-session.js";
+import { backgroundShellManager } from "../runtime/background-shell.js";
+import { clearAgentOutputFiles } from "../tool-system/builtin/agent-output-file.js";
 export class ChatSessionManager {
     sessions = new Map();
+    runtime;
     factory;
     maxSessions;
     idleTtlMs;
     sweeper = null;
     constructor(opts) {
+        this.runtime = opts.runtime;
         this.factory = opts.engineFactory;
         this.maxSessions = opts.maxSessions ?? 16;
         this.idleTtlMs = opts.idleTtlMs ?? 30 * 60 * 1000;
@@ -14,6 +18,17 @@ export class ChatSessionManager {
         const existing = this.sessions.get(sessionId);
         if (existing) {
             existing.lastActivityAt = Date.now();
+            // Re-apply the per-send permission mode so a pill change on an
+            // already-running session takes effect on the NEXT turn. Without this the
+            // engine kept whatever mode it was first created with — changing the pill
+            // on a resumed session was silently ignored at enforcement time (#11
+            // secondary: "档位 doesn't take effect after first send"). setPermissionMode
+            // reconfigures the live permission backend, so it's safe between turns.
+            if (slice.permissionMode &&
+                typeof existing.engine.getPermissionMode === "function" &&
+                existing.engine.getPermissionMode() !== slice.permissionMode) {
+                existing.engine.setPermissionMode(slice.permissionMode);
+            }
             return existing;
         }
         if (this.sessions.size >= this.maxSessions) {
@@ -47,8 +62,31 @@ export class ChatSessionManager {
         this.sessions.delete(sessionId);
     }
     closeAll() {
+        // Fire-and-forget variant for callers that can't await (e.g. AgentServer
+        // teardown inside a sync stop path). The TUI exit path uses closeAllAsync()
+        // below so the SIGTERM→SIGKILL grace actually completes before the process
+        // exits — otherwise startInkRepl's process.exit(0) races the kill and the
+        // detached shells leak as orphans.
+        void this.closeAllAsync();
+    }
+    /**
+     * Await-able shutdown. Cancels every session and reaps every background
+     * shell, *waiting* for the kill grace so a caller that exits the process
+     * immediately afterward (the TUI REPL) doesn't orphan detached dev servers.
+     */
+    async closeAllAsync() {
         for (const id of [...this.sessions.keys()])
             this.close(id);
+        // App/worker shutdown — reap every background shell so a detached
+        // `npm run dev` doesn't outlive the process as an orphan holding a port
+        // (design §6 / §难点1). NOTE: deliberately NOT in close()/sweepIdle() —
+        // an idle chat tab must keep its dev server alive (§6 "切走再回来 server 还在").
+        await backgroundShellManager.killAll();
+        // Background-agent output files are a debugging convenience, not durable
+        // state — wipe them on shutdown so ~/.code-shell/agents doesn't grow
+        // unbounded across runs. (notificationQueue, the real result path, is
+        // in-memory and already gone.)
+        await clearAgentOutputFiles();
     }
     sessionCount() {
         return this.sessions.size;

package/dist/protocol/chat-session.d.ts

@@ -1,4 +1,5 @@
 import type { Engine, EngineResult } from "../engine/engine.js";
+import type { ModelEntry } from "../llm/model-pool.js";
 import type { StreamEvent } from "../types.js";
 export interface ChatSessionOptions {
     id: string;
@@ -13,6 +14,12 @@ export interface TurnOpts {
     /** Goal mode for this turn — forwarded to engine.run (loop-until-done).
      *  String objective or full GoalConfig (objective + optional budgets). */
     goal?: string | import("../engine/goal.js").GoalConfig;
+    /** Marks this turn as a synthetic system-reminder injection (background-job
+     *  completion notification) rather than the user's own input — persisted so
+     *  the disk reader skips it as a user bubble on replay. See Engine.run. */
+    injected?: boolean;
+    /** Stable id for this user-intent; forwarded to Engine.run for idempotency. */
+    clientMessageId?: string;
 }
 /**
  * One ChatSession per UI chat tab. Owns a single Engine, an AbortController
@@ -42,8 +49,32 @@ export declare class ChatSession {
      * session-isolation research flagged. null = nothing pending.
      */
     private pendingModel;
+    /**
+     * Set by cancel() so the in-flight turn's abort error resolves as a clean
+     * "cancelled" result instead of rejecting (which the RPC layer would surface
+     * as a scary red Error in the UI for what was a user-initiated Stop). The
+     * onboarding flow cancels + immediately re-runs the same task; without this
+     * the cancelled first run popped "Error: Request cancelled".
+     */
+    private cancelledActive;
+    /**
+     * Sticky flag: the user cancelled (Stop) and has not started a new turn
+     * since. cancel() leaves the session idle (active=null), so isBusy() can't
+     * distinguish "naturally idle" from "user just stopped me". A background-job
+     * completion that lands in this window must NOT auto-resume the session —
+     * that would defeat the Stop. Cleared the moment a real turn is enqueued
+     * (the user is engaging again) so normal wakeups resume working afterward.
+     */
+    private cancelledSinceLastTurn;
     constructor(opts: ChatSessionOptions);
     enqueueTurn(task: string, opts: TurnOpts): Promise<EngineResult>;
+    /**
+     * True when the user hit Stop and hasn't started a new turn since. The server
+     * consults this before auto-waking an idle session on a background-job
+     * completion, so a download finishing right after Stop doesn't restart the
+     * agent the user just halted.
+     */
+    wasCancelledSinceLastTurn(): boolean;
     /**
      * Abort the in-flight turn and drain queued turns.
      *
@@ -54,13 +85,50 @@ export declare class ChatSession {
      */
     cancel(): void;
     isBusy(): boolean;
+    /**
+     * Extend the in-flight goal run's turn/budget ceilings (TODO 3.1). Delegates
+     * to the engine, which forwards to the active TurnLoop. Returns null when no
+     * run is active (or the run has no extendable loop). Mirrors the cancel()
+     * mid-run control path.
+     */
+    extendGoalRun(opts: {
+        addTurns?: number;
+        addTokenBudget?: number;
+        addTimeBudgetMs?: number;
+        addStopBlocks?: number;
+    }): {
+        maxTurns: number;
+        tokenBudget?: number;
+        timeBudgetMs?: number;
+        maxStopBlocks: number;
+    } | null;
+    /**
+     * Read this session's persisted active goal (state.activeGoal), or undefined
+     * when none. Cheap — reads only state.json. The host calls this on session
+     * load to re-surface the goal block + Cancel button after a reload.
+     */
+    getGoal(): import("../engine/goal.js").GoalConfig | undefined;
+    /**
+     * Clear this session's persisted active goal (CC /goal clear). Works idle or
+     * mid-run. Returns true if a goal was actually cleared.
+     */
+    clearGoal(): boolean;
     /**
      * Switch this session's active model (per-session, not worker-global).
      * Applies immediately when idle; defers to the next run boundary when a
      * turn is in flight so a hot switch never mutates the model under a
      * running LLM client.
      */
-    requestModelSwitch(key: string): void;
+    requestModelSwitch(key: string): ModelEntry;
+    /**
+     * Perform the actual model switch for this session: rotate the engine's model
+     * and reset the session's cumulative usage on disk — a different model has a
+     * different prompt cache, so the old cache-hit stats no longer apply. The
+     * renderer zeroes its own cumulative display when it issues the switch (it's
+     * renderer-initiated), so no stream event is needed here. Shared by the idle
+     * path and the deferred run-boundary path.
+     */
+    private applyModelSwitch;
     queueDepth(): number;
     private pump;
 }

package/dist/protocol/chat-session.js

@@ -1,3 +1,4 @@
+import { isAbortError } from "../llm/client-base.js";
 /**
  * One ChatSession per UI chat tab. Owns a single Engine, an AbortController
  * for the active turn, and a FIFO queue so a fast second send waits for the
@@ -26,6 +27,23 @@ export class ChatSession {
      * session-isolation research flagged. null = nothing pending.
      */
     pendingModel = null;
+    /**
+     * Set by cancel() so the in-flight turn's abort error resolves as a clean
+     * "cancelled" result instead of rejecting (which the RPC layer would surface
+     * as a scary red Error in the UI for what was a user-initiated Stop). The
+     * onboarding flow cancels + immediately re-runs the same task; without this
+     * the cancelled first run popped "Error: Request cancelled".
+     */
+    cancelledActive = false;
+    /**
+     * Sticky flag: the user cancelled (Stop) and has not started a new turn
+     * since. cancel() leaves the session idle (active=null), so isBusy() can't
+     * distinguish "naturally idle" from "user just stopped me". A background-job
+     * completion that lands in this window must NOT auto-resume the session —
+     * that would defeat the Stop. Cleared the moment a real turn is enqueued
+     * (the user is engaging again) so normal wakeups resume working afterward.
+     */
+    cancelledSinceLastTurn = false;
     constructor(opts) {
         this.id = opts.id;
         this.engine = opts.engine;
@@ -33,11 +51,24 @@ export class ChatSession {
     }
     enqueueTurn(task, opts) {
         this.lastActivityAt = Date.now();
+        // The user (or a wakeup the guard already let through) is starting a turn —
+        // clear the post-Stop suppression so future background-job completions
+        // wake the session again.
+        this.cancelledSinceLastTurn = false;
         return new Promise((resolve, reject) => {
             this.queue.push({ task, opts, resolve, reject });
             this.pump();
         });
     }
+    /**
+     * True when the user hit Stop and hasn't started a new turn since. The server
+     * consults this before auto-waking an idle session on a background-job
+     * completion, so a download finishing right after Stop doesn't restart the
+     * agent the user just halted.
+     */
+    wasCancelledSinceLastTurn() {
+        return this.cancelledSinceLastTurn;
+    }
     /**
      * Abort the in-flight turn and drain queued turns.
      *
@@ -47,6 +78,12 @@ export class ChatSession {
      * are always rejected regardless.
      */
     cancel() {
+        // Mark the in-flight turn as user-cancelled so pump()'s catch resolves it
+        // as a clean aborted result rather than rejecting (→ UI Error).
+        if (this.active)
+            this.cancelledActive = true;
+        // Suppress auto-wakeup until the user engages again (see the field doc).
+        this.cancelledSinceLastTurn = true;
         this.controller?.abort();
         // Drain queued turns as cancelled
         const drained = this.queue.splice(0);
@@ -57,6 +94,30 @@ export class ChatSession {
     isBusy() {
         return this.active !== null;
     }
+    /**
+     * Extend the in-flight goal run's turn/budget ceilings (TODO 3.1). Delegates
+     * to the engine, which forwards to the active TurnLoop. Returns null when no
+     * run is active (or the run has no extendable loop). Mirrors the cancel()
+     * mid-run control path.
+     */
+    extendGoalRun(opts) {
+        return this.engine.extendGoalRun(opts);
+    }
+    /**
+     * Read this session's persisted active goal (state.activeGoal), or undefined
+     * when none. Cheap — reads only state.json. The host calls this on session
+     * load to re-surface the goal block + Cancel button after a reload.
+     */
+    getGoal() {
+        return this.engine.getGoal(this.id);
+    }
+    /**
+     * Clear this session's persisted active goal (CC /goal clear). Works idle or
+     * mid-run. Returns true if a goal was actually cleared.
+     */
+    clearGoal() {
+        return this.engine.clearGoal(this.id);
+    }
     /**
      * Switch this session's active model (per-session, not worker-global).
      * Applies immediately when idle; defers to the next run boundary when a
@@ -65,10 +126,27 @@ export class ChatSession {
      */
     requestModelSwitch(key) {
         if (this.isBusy()) {
+            const pool = this.engine.getModelPool();
+            const entry = pool.get(key);
+            if (!entry)
+                throw new Error(`Model not found: ${key}`);
             this.pendingModel = key;
-            return;
+            return entry;
         }
-        this.engine.switchModel(key);
+        return this.applyModelSwitch(key);
+    }
+    /**
+     * Perform the actual model switch for this session: rotate the engine's model
+     * and reset the session's cumulative usage on disk — a different model has a
+     * different prompt cache, so the old cache-hit stats no longer apply. The
+     * renderer zeroes its own cumulative display when it issues the switch (it's
+     * renderer-initiated), so no stream event is needed here. Shared by the idle
+     * path and the deferred run-boundary path.
+     */
+    applyModelSwitch(key) {
+        const entry = this.engine.switchModel(key);
+        this.engine.resetSessionUsage(this.id);
+        return entry;
     }
     queueDepth() {
         return this.queue.length;
@@ -80,6 +158,7 @@ export class ChatSession {
         if (!next)
             return;
         this.active = next;
+        this.cancelledActive = false;
         this.controller = new AbortController();
         try {
             const onStream = next.opts.onStream ?? this.defaultOnStream;
@@ -89,21 +168,40 @@ export class ChatSession {
                 signal: this.controller.signal,
                 onStream,
                 goal: next.opts.goal,
+                injected: next.opts.injected,
+                clientMessageId: next.opts.clientMessageId,
             });
             this.lastActivityAt = Date.now();
             next.resolve(result);
         }
         catch (err) {
-            next.reject(err);
+            // A user-initiated cancel (Stop, or the onboarding cancel+rerun flow)
+            // aborts the in-flight run. That's not a failure — resolve it as a clean
+            // aborted result so the RPC layer doesn't surface "Error: Request
+            // cancelled" in the UI. Only abort errors on a cancelled turn are
+            // swallowed this way; a genuine error still rejects.
+            if (this.cancelledActive && (isAbortError(err) || this.controller?.signal.aborted)) {
+                next.resolve({
+                    text: "",
+                    reason: "aborted_streaming",
+                    sessionId: this.id,
+                    turnCount: 0,
+                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                });
+            }
+            else {
+                next.reject(err);
+            }
         }
         finally {
             this.active = null;
             this.controller = null;
+            this.cancelledActive = false;
             // Run boundary: apply any model switch that was deferred because it was
             // requested mid-run. Done here (not in pump) so it still applies when
             // no further turn is queued.
             if (this.pendingModel !== null) {
-                this.engine.switchModel(this.pendingModel);
+                this.applyModelSwitch(this.pendingModel);
                 this.pendingModel = null;
             }
             // Drain the next turn if one is waiting.

package/dist/protocol/client.d.ts

@@ -23,6 +23,7 @@ export interface AgentRunOptions {
     cwd?: string;
     sessionId?: string;
     permissionMode?: PermissionMode;
+    model?: string;
     planMode?: boolean;
 }
 export type BackgroundAgentCompletedHandler = (sessionId: string, event: BackgroundAgentCompletedEvent) => void;
@@ -64,6 +65,36 @@ export declare class AgentClient {
      * Legacy form:        cancel(reason?)
      */
     cancel(sessionId?: string, reason?: string): Promise<void>;
+    /**
+     * Clear a session's persisted active goal (CC `/goal clear`). Returns whether
+     * a goal was actually cleared (false = there was none).
+     */
+    goalClear(sessionId?: string): Promise<boolean>;
+    /**
+     * Read a session's persisted active goal objective, or null when there's
+     * none. The host calls this on session load to re-surface the goal block +
+     * Cancel button after a reload (a persistent goal isn't replayed from the
+     * transcript, so the live stream never re-announces it).
+     */
+    goalGet(sessionId: string): Promise<string | null>;
+    /**
+     * Steer an in-flight run: queue a user message spliced in at the next
+     * turn-loop step (不打断 — does not abort the current step). `id` is a stable
+     * host-side handle that rides through to the steer_injected event and lets
+     * unsteer() revoke a still-pending entry. Mirrors the server's handleSteer +
+     * the desktop preload's steer(); without it the SDK can't reach the method
+     * (request() is private) — the protocol was asymmetric after the steer merge.
+     */
+    steer(sessionId: string, text: string, id?: string, clientMessageId?: string): Promise<{
+        accepted: boolean;
+        id?: string;
+    }>;
+    /**
+     * Revoke a still-pending steer entry by id (before the loop consumes it).
+     * Returns false when the loop already consumed it (not an error — it will
+     * arrive as a normal user bubble).
+     */
+    unsteer(sessionId: string, id: string): Promise<boolean>;
     /**
      * Update runtime configuration on the server.
      */