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

package/dist/prompt/composer.d.ts

@@ -16,6 +16,10 @@ export interface ComposerOptions {
     preset?: AgentPreset;
     customSystemPrompt?: string;
     appendSystemPrompt?: string;
+    /** User's preferred response language (free text), injected as a stable system section. */
+    responseLanguage?: string;
+    /** How to address the user / short profile (free text). */
+    userProfile?: string;
     /**
      * Skill names (full names including any "<plugin>:" prefix) the user
      * has disabled in settings. Filtered out of the LLM's skills listing
@@ -29,6 +33,20 @@ export interface ComposerOptions {
      * `${pluginName}:` is filtered. See scanSkills(opts.disabledPlugins).
      */
     disabledPlugins?: string[];
+    /**
+     * Sub-agent skill allowlist (hard isolation). When set, only these skills
+     * appear in the LLM's skills listing — applied on top of the disabled
+     * lists. Undefined → the full (non-disabled) pool. Mirrors
+     * scanSkills(opts.skillAllowlist) so the prompt matches the Skill tool's
+     * dispatch gate.
+     */
+    skillAllowlist?: string[];
+    /**
+     * settings.memories.maxAge (days). When > 0, memories whose file mtime is
+     * older than this are dropped from the injected memory context (TODO 8.1).
+     * Undefined/0 → inject all.
+     */
+    memoriesMaxAgeDays?: number;
 }
 export declare class PromptComposer {
     private readonly options;
@@ -48,6 +66,19 @@ export declare class PromptComposer {
      * Only injects git status if the resolved preset opts in.
      */
     buildSystemContext(): Promise<string>;
+    /**
+     * 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.
+     */
+    buildDynamicContextMessage(): Promise<Message | null>;
     invalidateCache(sectionName?: string): void;
     private getSections;
     private getInstructions;

package/dist/prompt/composer.js

@@ -31,15 +31,21 @@ 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;
-        const currentDate = `Today's date is ${new Date().toISOString().split("T")[0]}.`;
+        // Local date, not UTC — toISOString() is UTC and would show the wrong
+        // "today" for users whose timezone has crossed midnight (review-2026-05-30).
+        const now = new Date();
+        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 };
     }
@@ -83,6 +89,38 @@ 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 parts = [skillsListing, gitStatus, memoryContext].filter(Boolean);
+        if (parts.length === 0)
+            return null;
+        return {
+            role: "user",
+            content: `<system-reminder>\n${parts.join("\n\n")}\n</system-reminder>`,
+        };
+    }
     invalidateCache(sectionName) {
         this.sectionCache.invalidate(sectionName);
         if (!sectionName) {
@@ -111,36 +149,45 @@ export class PromptComposer {
                 compute: () => this.options.customSystemPrompt,
             });
         }
-        // Tool definitions
+        // Tool listing — name + one-line description only. The full JSON schema
+        // is NOT repeated here: the provider clients already send it in the
+        // native `tools` field (Anthropic tools / OpenAI functions), so dumping
+        // `Parameters: {...}` into the system prompt sent every tool's schema
+        // twice — a large, per-request token cost for no added model signal.
         if (tools.length > 0) {
             sections.push({
                 name: "tool_definitions",
                 compute: () => {
-                    const toolLines = tools.map((t) => `### ${t.name}\n${t.description}\n` +
-                        `Parameters: ${JSON.stringify(t.inputSchema, null, 2)}`);
+                    const toolLines = tools.map((t) => `### ${t.name}\n${t.description}`);
                     return `# Available Tools\n\n${toolLines.join("\n\n")}`;
                 },
             });
         }
-        // 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);
             },
         });
+        // 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({
@@ -148,6 +195,23 @@ export class PromptComposer {
                 compute: () => this.options.appendSystemPrompt,
             });
         }
+        // Personalization — stable user preferences (language + how to address
+        // the user). Placed in the cacheable system prefix because it doesn't
+        // change per-turn. Only emitted when at least one field is set.
+        const { responseLanguage, userProfile } = this.options;
+        if (responseLanguage || userProfile) {
+            sections.push({
+                name: "personalization",
+                compute: () => {
+                    const lines = ["# User & Response Preferences"];
+                    if (userProfile)
+                        lines.push(`- About the user: ${userProfile}`);
+                    if (responseLanguage)
+                        lines.push(`- Response language: ${responseLanguage}`);
+                    return lines.join("\n");
+                },
+            });
+        }
         return sections;
     }
     getInstructions() {
@@ -159,8 +223,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,6 @@ 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.
+ - 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/prompt/sections/orchestration.md

@@ -6,6 +6,14 @@
  - Avoid creating files unless they are genuinely needed. Prefer editing existing files to creating new ones.
  - Avoid giving time estimates or predictions for how long tasks will take.
 
+# Delegating to sub-agents (Agent)
+ - A sub-agent runs in its own **clean, isolated context** and returns only its final report. It is stateless — you cannot send follow-up messages, so its prompt must be a complete, self-contained task description.
+ - **The primary reason to delegate is context hygiene, not speed.** When a task needs to read many files or run a long exploration but you only need the *conclusion*, hand it to a sub-agent: it does the noisy work in its own context and you keep the answer, not the file dumps. This is the default move for any sweep that would otherwise flood your own context with intermediate output.
+ - **Parallel fan-out is the exception, not the default.** Only launch several sub-agents at once when the work genuinely splits into independent pieces with no shared state or ordering. Don't open multiple agents just because a task *could* be subdivided — one well-scoped delegation usually beats a swarm.
+ - **Delegate the dirty work, keep the thinking.** Push file-reading, searching, and broad investigation into sub-agents; do the synthesis, decisions, and edits yourself in the main thread.
+ - **Don't delegate trivial lookups.** If you know the file/symbol/value and expect a few matches, use Read/Grep/Glob directly — spinning up an agent for that wastes a turn and tokens.
+ - If you delegate a chunk of work, add a TodoWrite item for it so the user sees it without reading the sub-agent's transcript.
+
 # Task tracking (TodoWrite)
  - When the user's request decomposes into 3+ discrete steps, call **TodoWrite** with the complete list up front. The user has a pinned task panel and relies on it to see what's queued, in progress, and done.
  - **TodoWrite takes the complete list each time** — there is no per-item update. To change a status, call TodoWrite again with the whole list, only that item's `status` changed. Your previous TodoWrite input IS the source of truth — re-read it before rewriting.

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" | "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
@@ -24,8 +24,21 @@ export declare class ChatSessionManager {
     constructor(opts: ChatSessionManagerOptions);
     getOrCreate(sessionId: string, slice: EngineConfigSlice): ChatSession;
     get(sessionId: string): ChatSession | undefined;
+    /**
+     * Iterate every live session once. Public iterator so callers (e.g. the
+     * protocol server's config hot-reload / sessions query) don't reach into
+     * the private `sessions` map with an `as any` cast. Iterates a snapshot of
+     * the values so a callback that closes a session can't perturb the walk.
+     */
+    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,4 +1,6 @@
 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();
     factory;
@@ -14,6 +16,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) {
@@ -29,6 +42,16 @@ export class ChatSessionManager {
     get(sessionId) {
         return this.sessions.get(sessionId);
     }
+    /**
+     * Iterate every live session once. Public iterator so callers (e.g. the
+     * protocol server's config hot-reload / sessions query) don't reach into
+     * the private `sessions` map with an `as any` cast. Iterates a snapshot of
+     * the values so a callback that closes a session can't perturb the walk.
+     */
+    forEachSession(fn) {
+        for (const s of [...this.sessions.values()])
+            fn(s);
+    }
     close(sessionId) {
         const s = this.sessions.get(sessionId);
         if (!s)
@@ -37,8 +60,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

@@ -10,6 +10,13 @@ export interface TurnOpts {
      *  configured cwd. */
     cwd?: string;
     onStream?: (event: StreamEvent) => void;
+    /** 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;
 }
 /**
  * One ChatSession per UI chat tab. Owns a single Engine, an AbortController
@@ -32,8 +39,39 @@ export declare class ChatSession {
     private active;
     private controller;
     private readonly defaultOnStream?;
+    /**
+     * Model-pool key requested via requestModelSwitch while a turn was in
+     * flight. Applied at the next run boundary (before the next turn starts) so
+     * we never swap the model out from under a running LLM client — the bug the
+     * 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.
      *
@@ -44,6 +82,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;
+    /**
+     * 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;
 }