@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/tool-system/builtin/background-jobs.js

@@ -20,7 +20,9 @@
  * loops run in the main engine process, so start/finish and the engine's wait
  * loop observe the same instance.
  */
-import { normalizeCwdPath } from "../../cc-orchestrator/cwd-normalize.js";
+import { normalizeCwdPath } from "../../utils/cwd-normalize.js";
+import { execFileSync } from "node:child_process";
+import { resolveGit } from "../../utils/exec.js";
 function isValidSessionId(sid) {
     return typeof sid === "string" && sid.length > 0;
 }
@@ -28,22 +30,50 @@ function isValidSessionId(sid) {
  *  UX limit; a human never spawns this many background jobs in one session. */
 const MAX_TERMINAL_JOBS_PER_SESSION = 50;
 const CANCEL_WAIT_TIMEOUT_MS = 5_000;
+/** Resolve once at registration/query time. Git failures and non-git paths
+ *  intentionally collapse to the legacy normalized-cwd identity. */
+function resolveEffectiveWorkspaceIdentity(cwd) {
+    const normalizedCwd = normalizeCwdPath(cwd);
+    try {
+        const output = execFileSync(resolveGit(), ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"], {
+            cwd: normalizedCwd,
+            encoding: "utf-8",
+            timeout: 5_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const [rawRoot, rawCommonDir] = output.split(/\r?\n/);
+        if (rawRoot && rawCommonDir) {
+            return {
+                root: normalizeCwdPath(rawRoot),
+                kind: "git-worktree",
+                gitCommonDir: normalizeCwdPath(rawCommonDir),
+            };
+        }
+    }
+    catch {
+        // Non-git, missing git, deleted cwd, and timeouts all retain legacy cwd
+        // comparison semantics. Conflict detection must never break job launch.
+    }
+    return { root: normalizedCwd, kind: "cwd" };
+}
 function isActiveStatus(status) {
     return status === "running" || status === "cancelling";
 }
 async function waitForAbort(abort) {
     let timer;
     try {
-        await Promise.race([
+        const result = await Promise.race([
             Promise.resolve().then(abort),
             new Promise((resolve) => {
-                timer = setTimeout(resolve, CANCEL_WAIT_TIMEOUT_MS);
+                timer = setTimeout(() => resolve(undefined), CANCEL_WAIT_TIMEOUT_MS);
             }),
         ]);
+        return result && typeof result === "object" ? result : undefined;
     }
     catch {
         // Cancellation is best-effort; the terminal state still closes after the
         // abort hook settles or the hard deadline expires.
+        return undefined;
     }
     finally {
         if (timer)
@@ -57,6 +87,14 @@ class BackgroundJobRegistry {
     start(jobId, sessionId, description = "", options) {
         if (!isValidSessionId(sessionId))
             return;
+        const rawLaunchCwd = options?.launchCwd ?? options?.cwd;
+        const launchCwd = rawLaunchCwd ? normalizeCwdPath(rawLaunchCwd) : undefined;
+        const effectiveWorkspaceCwd = options?.effectiveWorkspaceCwd
+            ? normalizeCwdPath(options.effectiveWorkspaceCwd)
+            : launchCwd;
+        const workspaceIdentity = effectiveWorkspaceCwd
+            ? resolveEffectiveWorkspaceIdentity(effectiveWorkspaceCwd)
+            : undefined;
         this.jobs.set(jobId, {
             jobId,
             sessionId,
@@ -64,9 +102,29 @@ class BackgroundJobRegistry {
             description,
             status: "running",
             startedAt: Date.now(),
-            ...(options?.cwd ? { cwd: normalizeCwdPath(options.cwd) } : {}),
+            ...(launchCwd ? { launchCwd, cwd: launchCwd } : {}),
+            ...(effectiveWorkspaceCwd ? { effectiveWorkspaceCwd } : {}),
+            ...(options?.workspaceRoot ? { workspaceRoot: normalizeCwdPath(options.workspaceRoot) } : {}),
+            ...(workspaceIdentity
+                ? {
+                    effectiveWorkspaceRoot: workspaceIdentity.root,
+                    effectiveWorkspaceKind: workspaceIdentity.kind,
+                    ...(workspaceIdentity.gitCommonDir
+                        ? { gitCommonDir: workspaceIdentity.gitCommonDir }
+                        : {}),
+                }
+                : {}),
             ...(options?.promptSummary ? { promptSummary: options.promptSummary } : {}),
             ...(options?.cli ? { cli: options.cli } : {}),
+            ...(options?.isolation ? { isolation: options.isolation } : {}),
+            ...(options?.worktreePath ? { worktreePath: normalizeCwdPath(options.worktreePath) } : {}),
+            ...(options?.worktreeBranch ? { worktreeBranch: options.worktreeBranch } : {}),
+            ...(options?.worktreeBaseRef ? { worktreeBaseRef: options.worktreeBaseRef } : {}),
+            ...(options?.worktreeCleanup ? { worktreeCleanup: options.worktreeCleanup } : {}),
+            ...(options?.worktreeBranchPrefix
+                ? { worktreeBranchPrefix: options.worktreeBranchPrefix }
+                : {}),
+            ...(options?.worktreePath ? { worktreeLifecycle: "running" } : {}),
             ...(options?.originClientMessageId
                 ? { originClientMessageId: options.originClientMessageId }
                 : {}),
@@ -90,6 +148,9 @@ class BackgroundJobRegistry {
             entry.ccSessionId = outcome.ccSessionId;
         if (outcome?.changedFiles !== undefined)
             entry.changedFiles = outcome.changedFiles;
+        if (outcome?.worktreeLifecycle !== undefined) {
+            entry.worktreeLifecycle = outcome.worktreeLifecycle;
+        }
         this.evictTerminalOverCap(entry.sessionId);
         this.notify();
     }
@@ -106,6 +167,17 @@ class BackgroundJobRegistry {
         if (artifacts.changedFiles !== undefined)
             entry.changedFiles = artifacts.changedFiles;
     }
+    /** Update retained DriveAgent lifecycle state after an explicit cleanup. */
+    recordWorktreeLifecycle(jobId, lifecycle, note) {
+        const entry = this.jobs.get(jobId);
+        if (!entry || !entry.worktreePath)
+            return false;
+        entry.worktreeLifecycle = lifecycle;
+        if (note)
+            entry.finalText = `${entry.finalText ? `${entry.finalText}\n\n` : ""}[worktree lifecycle] ${note}`;
+        this.notify();
+        return true;
+    }
     async cancel(jobId, outcome) {
         const entry = this.jobs.get(jobId);
         if (!entry)
@@ -118,20 +190,22 @@ class BackgroundJobRegistry {
         // process as active until the abort hook confirms exit.
         entry.status = "cancelling";
         this.notify();
-        if (entry.abort)
-            await waitForAbort(entry.abort);
+        const abortOutcome = entry.abort ? await waitForAbort(entry.abort) : undefined;
         // Session teardown/reset may have removed the entry while termination was
         // in flight. Do not resurrect or notify for a closed session.
         if (this.jobs.get(jobId) !== entry || entry.status !== "cancelling")
             return false;
-        entry.status = "cancelled";
+        entry.status = abortOutcome?.status ?? "cancelled";
         entry.finishedAt = Date.now();
-        if (outcome?.finalText !== undefined)
-            entry.finalText = outcome.finalText;
-        if (outcome?.ccSessionId !== undefined)
-            entry.ccSessionId = outcome.ccSessionId;
-        if (outcome?.changedFiles !== undefined)
-            entry.changedFiles = outcome.changedFiles;
+        const finalText = abortOutcome?.finalText ?? outcome?.finalText;
+        const ccSessionId = abortOutcome?.ccSessionId ?? outcome?.ccSessionId;
+        const changedFiles = abortOutcome?.changedFiles ?? outcome?.changedFiles;
+        if (finalText !== undefined)
+            entry.finalText = finalText;
+        if (ccSessionId !== undefined)
+            entry.ccSessionId = ccSessionId;
+        if (changedFiles !== undefined)
+            entry.changedFiles = changedFiles;
         this.evictTerminalOverCap(entry.sessionId);
         this.notify();
         return true;
@@ -148,10 +222,32 @@ class BackgroundJobRegistry {
     listRunningForSession(sessionId) {
         return [...this.jobs.values()].filter((e) => e.sessionId === sessionId && isActiveStatus(e.status));
     }
-    /** Running jobs, across all sessions, that are operating in the same cwd. */
+    /** Running jobs, across all sessions, in the same effective workspace.
+     *
+     * Git paths compare by canonical worktree root, so sibling launch directories
+     * collide while distinct linked worktrees do not. A declared
+     * effectiveWorkspaceCwd takes precedence over launchCwd. If either side could
+     * not be resolved through git, exact launch-cwd matching remains the
+     * conservative back-compatible fallback. */
     listRunningByCwd(cwd) {
+        return this.listByWorkspaceCwd(cwd).filter((e) => isActiveStatus(e.status));
+    }
+    /** Running and retained terminal jobs in the effective workspace containing
+     *  cwd. Used by DriveAgentJobs' cross-session cwd filter. */
+    listByWorkspaceCwd(cwd) {
         const normalized = normalizeCwdPath(cwd);
-        return [...this.jobs.values()].filter((e) => isActiveStatus(e.status) && e.cwd === normalized);
+        const queryIdentity = resolveEffectiveWorkspaceIdentity(normalized);
+        return [...this.jobs.values()].filter((e) => {
+            if (e.effectiveWorkspaceRoot === queryIdentity.root)
+                return true;
+            if (e.effectiveWorkspaceKind === "git-worktree" && queryIdentity.kind === "git-worktree") {
+                return false;
+            }
+            // Mixed git-resolution states compare the declared effective cwd
+            // snapshot. Only entries created before that field existed fall back to
+            // the legacy launch cwd alias.
+            return (e.effectiveWorkspaceCwd ?? e.launchCwd ?? e.cwd) === normalized;
+        });
     }
     /** All jobs (running + retained terminal) for `sessionId`. Feeds the panel. */
     listForSession(sessionId) {

package/dist/tool-system/builtin/background-work.d.ts

@@ -1,5 +1,5 @@
 import { type AsyncAgentStatus } from "./agent-registry.js";
-import { type BackgroundJobStatus } from "./background-jobs.js";
+import { type BackgroundJobKind, type BackgroundJobStatus, type ExternalCliKind } from "./background-jobs.js";
 import { type BgShell } from "../../runtime/background-shell.js";
 export type BackgroundWorkKind = "subagent" | "job" | "shell";
 export interface BackgroundWorkItem {
@@ -51,6 +51,17 @@ export type BackgroundWorkEntry = WithSource<{
     finalText?: string;
     /** Files an external agent (DriveAgent) changed, parsed from its transcript. */
     changedFiles?: string[];
+    /** Machine-readable job kind and external-session linkage for DriveAgent. */
+    jobKind?: BackgroundJobKind;
+    externalSessionId?: string;
+    cli?: ExternalCliKind;
+    cwd?: string;
+    isolation?: "current" | "worktree" | "none";
+    worktreePath?: string;
+    worktreeBranch?: string;
+    worktreeBaseRef?: string;
+    worktreeCleanup?: "auto" | "keep" | "detach" | "discard";
+    worktreeLifecycle?: "running" | "kept" | "detached" | "discarded" | "cleanup-failed";
 }>;
 /**
  * Every background-work item spawned by `sessionId`, with per-kind detail, for

package/dist/tool-system/builtin/background-work.js

@@ -14,7 +14,7 @@
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { asyncAgentRegistry } from "./agent-registry.js";
-import { backgroundJobRegistry } from "./background-jobs.js";
+import { backgroundJobRegistry, } from "./background-jobs.js";
 import { backgroundShellManager } from "../../runtime/background-shell.js";
 import { codeShellHome } from "../../session/session-manager.js";
 /** List every still-running background work item spawned by `sessionId`. */
@@ -116,6 +116,7 @@ export function listBackgroundWorkForUI(sessionId, opts = {}) {
         ? backgroundJobRegistry.list()
         : backgroundJobRegistry.listForSession(sessionId);
     for (const j of jobs) {
+        const launchCwd = j.launchCwd ?? j.cwd;
         entries.push({
             kind: "job",
             jobId: j.jobId,
@@ -125,6 +126,16 @@ export function listBackgroundWorkForUI(sessionId, opts = {}) {
             ...(j.finishedAt != null ? { finishedAt: j.finishedAt } : {}),
             ...(j.finalText != null ? { finalText: j.finalText } : {}),
             ...(j.changedFiles && j.changedFiles.length ? { changedFiles: j.changedFiles } : {}),
+            ...(j.kind ? { jobKind: j.kind } : {}),
+            ...(j.ccSessionId ? { externalSessionId: j.ccSessionId } : {}),
+            ...(j.cli === "claude" || j.cli === "codex" ? { cli: j.cli } : {}),
+            ...(launchCwd ? { cwd: launchCwd } : {}),
+            ...(j.isolation ? { isolation: j.isolation } : {}),
+            ...(j.worktreePath ? { worktreePath: j.worktreePath } : {}),
+            ...(j.worktreeBranch ? { worktreeBranch: j.worktreeBranch } : {}),
+            ...(j.worktreeBaseRef ? { worktreeBaseRef: j.worktreeBaseRef } : {}),
+            ...(j.worktreeCleanup ? { worktreeCleanup: j.worktreeCleanup } : {}),
+            ...(j.worktreeLifecycle ? { worktreeLifecycle: j.worktreeLifecycle } : {}),
             sourceSession: sourceSession(sessionId, j.sessionId),
         });
     }

package/dist/tool-system/builtin/bash.d.ts

@@ -16,9 +16,7 @@
  *     Killed by signal, the truncation message, sandbox denial hints).
  */
 import type { ToolContext } from "../context.js";
-import type { ToolDefinition, ToolResult } from "../../types.js";
+import type { ToolDefinition } from "../../types.js";
+import type { ToolExecutionResult } from "./index.js";
 export declare const bashToolDef: ToolDefinition;
-export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | {
-    result: string;
-    sandbox: ToolResult["sandbox"];
-}>;
+export declare function bashTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | ToolExecutionResult>;

package/dist/tool-system/builtin/bash.js

@@ -29,7 +29,7 @@ function sandboxMark(backend) {
 export const bashToolDef = {
     name: "Bash",
     description: "Execute a shell command and return its output. " +
-        "Use for ordinary shell commands, system operations, git commands, " +
+        "Use for ordinary shell commands, system operations, version-control commands, " +
         "package-manager commands, running tests, installing packages, etc. Prefer Bash " +
         "over PowerShell unless the task needs PowerShell-specific syntax or APIs.",
     inputSchema: {
@@ -82,7 +82,8 @@ export async function bashTool(args, ctx) {
     const sandbox = sandboxMark(backend);
     // Tag every textual return below with the sandbox mark so the UI badge
     // shows up whether the command succeeded, failed, timed out, or aborted.
-    const mark = (result) => ({ result, sandbox });
+    const mark = (result) => ({ ok: true, result, sandbox });
+    const fail = (error, details = {}) => ({ ok: false, error, sandbox, ...details });
     // Project localEnvironment.env (ctx.shellEnv) layers on top of either the
     // full passthrough (off) or the hardened allowlist (sandboxed) — see
     // mergeShellEnv. Background mode merges the same way inside the manager.
@@ -93,7 +94,11 @@ export async function bashTool(args, ctx) {
     // blocked, and Engine.run's wait-for-background loop never waits on it
     // (§难点5: that loop only looks at asyncAgentRegistry).
     if (args.run_in_background === true) {
-        return mark(runInBackground(command, ctx));
+        const backgroundResult = runInBackground(command, ctx);
+        if (backgroundResult.startsWith("Error:"))
+            return fail(backgroundResult);
+        ctx?.runYield?.request("background_notification");
+        return mark(backgroundResult);
     }
     // A6: lifecycle (spawn, kill cascade, IO drain, byte cap, abort/timeout)
     // is centralized in safeSpawnShell. We still handle Bash's user-facing
@@ -112,13 +117,13 @@ export async function bashTool(args, ctx) {
         signal: ctx?.signal,
     });
     if (result.aborted) {
-        return mark(wasAbortedBeforeStart ? "Bash aborted before starting." : "Bash aborted by signal.");
+        return fail(wasAbortedBeforeStart ? "Bash aborted before starting." : "Bash aborted by signal.");
     }
     if (result.timedOut) {
-        return mark(`Command timed out after ${timeout}ms`);
+        return fail(`Command timed out after ${timeout}ms`);
     }
     if (result.spawnFailed) {
-        return mark(`Failed to spawn command: ${result.error ?? "unknown error"}`);
+        return fail(`Failed to spawn command: ${result.error ?? "unknown error"}`);
     }
     let body = "";
     if (result.stdout)
@@ -150,6 +155,9 @@ export async function bashTool(args, ctx) {
     const hint = backend.hintForBlockedOutput?.(result.stderr);
     if (hint)
         output += hint;
+    if ((code !== 0 && code !== null) || (code === null && sig)) {
+        return fail(output, { exitCode: code, signal: sig, stderr: result.stderr });
+    }
     return mark(output);
 }
 /**

package/dist/tool-system/builtin/browser-tools.d.ts

@@ -1,6 +1,9 @@
 /**
- * Browser automation tools — drive the in-app webview via the BrowserBridge
- * (CDP under the hood). Collapsed into THREE semantic tools (was 9 flat tools)
+ * Browser automation tools — drive a host-owned Browser Runtime through the
+ * BrowserBridge compatibility port. The default runtime owns a background tab
+ * in the in-app profile; user-opened tabs require an explicit claim. Collapsed
+ * into THREE semantic tools
+ * (was 9 flat tools)
  * to keep the LLM's tool list lean:
  *
  *   browser_observe  — observe the page: snapshot (a11y elements) / read (text) /
@@ -14,7 +17,7 @@
  * snapshot returns interactive elements as a compact ref-tagged list (a11y tree,
  * token-economical, no screenshots); act references elements by the ref the
  * latest snapshot assigned. All tools degrade with a clear error when no browser
- * is wired. isConcurrencySafe:false — a single webview is driven serially.
+ * runtime is wired. isConcurrencySafe:false — one runtime tab is driven serially.
  *
  * Permission: browser_act is permissionDefault "allow"; the sensitive actions
  * (click/type/select) are escalated to "ask" by a preset PermissionRule keyed on
@@ -22,9 +25,9 @@
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
-import type { BuiltinToolResult } from "./index.js";
+import type { BuiltinToolReturn } from "./index.js";
 export declare const browserObserveToolDef: ToolDefinition;
-export declare function browserObserveTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<BuiltinToolResult>;
+export declare function browserObserveTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<BuiltinToolReturn>;
 export declare const browserActToolDef: ToolDefinition;
 export declare function browserActTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const browserNavigateToolDef: ToolDefinition;

package/dist/tool-system/builtin/browser-tools.js

@@ -1,6 +1,9 @@
 /**
- * Browser automation tools — drive the in-app webview via the BrowserBridge
- * (CDP under the hood). Collapsed into THREE semantic tools (was 9 flat tools)
+ * Browser automation tools — drive a host-owned Browser Runtime through the
+ * BrowserBridge compatibility port. The default runtime owns a background tab
+ * in the in-app profile; user-opened tabs require an explicit claim. Collapsed
+ * into THREE semantic tools
+ * (was 9 flat tools)
  * to keep the LLM's tool list lean:
  *
  *   browser_observe  — observe the page: snapshot (a11y elements) / read (text) /
@@ -14,7 +17,7 @@
  * snapshot returns interactive elements as a compact ref-tagged list (a11y tree,
  * token-economical, no screenshots); act references elements by the ref the
  * latest snapshot assigned. All tools degrade with a clear error when no browser
- * is wired. isConcurrencySafe:false — a single webview is driven serially.
+ * runtime is wired. isConcurrencySafe:false — one runtime tab is driven serially.
  *
  * Permission: browser_act is permissionDefault "allow"; the sensitive actions
  * (click/type/select) are escalated to "ask" by a preset PermissionRule keyed on
@@ -22,8 +25,7 @@
  */
 import { renderElementList } from "../browser-bridge.js";
 import { capabilitiesFor } from "../../llm/capabilities/index.js";
-const NO_BROWSER = "Error: browser automation is not available (no browser panel in this session). " +
-    "It requires the desktop app with an open browser panel.";
+const NO_BROWSER = "Error: browser automation runtime is not available in this host session.";
 function bridge(ctx) {
     return ctx?.browser;
 }
@@ -33,13 +35,15 @@ const STALE = (ref) => `Error: ref ${ref} is no longer valid (page changed). Re-
 // ════════════════════════════════════════════════════════════════════════════
 export const browserObserveToolDef = {
     name: "browser_observe",
-    description: "Observe the current page in the browser panel. Modes:\n" +
+    description: "Observe the task-owned page in the CodeShell Browser Runtime. It shares the " +
+        "in-app browser profile but never controls a user-opened tab without an " +
+        "explicit claim. Modes:\n" +
         "- snapshot (default): URL/title + a compact list of interactive elements, each " +
         "tagged [ref=eN] for browser_act. ALWAYS snapshot before acting, and re-snapshot " +
         "after navigation/page changes (refs are only valid for the latest snapshot). " +
         "Passwords show as [sensitive] with no value.\n" +
-        "- read: the page's main readable text (for summarizing/scraping an article/post; " +
-        "long pages truncate — scroll + read again).\n" +
+        "- read: a cursor-paged chunk of the page's normalized readable text. Continue " +
+        "with the returned nextCursor until complete; scrolling is only for lazy/infinite loading.\n" +
         "- extract: the real URLs on the page (hyperlink hrefs, image srcs, video srcs) " +
         "that snapshot omits — each image/video is tagged [ref=imgN/vidN] for image mode.\n" +
         "- image: SEE the actual pixels of page images (refs from extract, e.g. img3) — for " +
@@ -60,7 +64,18 @@ export const browserObserveToolDef = {
                 items: { type: "string" },
                 description: "image mode: image refs (imgN/vidN from extract) to see, one or more",
             },
-            ref: { type: "string", description: "vision mode (optional): screenshot just this element's region" },
+            ref: {
+                type: "string",
+                description: "vision mode (optional): screenshot just this element's region",
+            },
+            cursor: {
+                type: "string",
+                description: "read mode: opaque nextCursor returned by the previous read chunk",
+            },
+            max_chars: {
+                type: "number",
+                description: "read mode: requested chunk size (clamped by the runtime)",
+            },
         },
     },
 };
@@ -86,17 +101,32 @@ export async function browserObserveTool(args, ctx) {
     switch (mode) {
         case "snapshot": {
             const snap = await b.snapshot();
+            if (snap.detail)
+                return `Error: ${snap.detail}`;
             const header = `URL: ${snap.url}${snap.title ? `\nTitle: ${snap.title}` : ""}`;
             const human = snap.needsHuman
-                ? `\n\n⚠ ${snap.needsHuman} — please complete it in the browser panel, then continue.`
+                ? `\n\n⚠ ${snap.needsHuman} — please complete it in the browser window, then continue.`
                 : "";
             return `${header}\n\n${renderElementList(snap.elements)}${human}`;
         }
         case "read": {
-            const c = await b.readContent();
+            const c = await b.readContent({
+                cursor: typeof args.cursor === "string" ? args.cursor : undefined,
+                maxChars: typeof args.max_chars === "number" ? args.max_chars : undefined,
+            });
             if (!c.ok)
                 return `Error: ${c.detail ?? "could not read page content"}`;
-            const head = `URL: ${c.url}${c.title ? `\nTitle: ${c.title}` : ""}${c.truncated ? "\n(content truncated)" : ""}`;
+            const progress = c.done
+                ? "\nRead: complete"
+                : c.nextCursor
+                    ? `\nRead: more available\nnextCursor: ${c.nextCursor}`
+                    : c.truncated
+                        ? "\nRead: truncated"
+                        : "";
+            const scroll = c.scroll
+                ? `\nScroll: ${Math.round(c.scroll.y)}/${Math.round(c.scroll.maxY)}${c.scroll.atEnd ? " (end)" : ""}`
+                : "";
+            const head = `URL: ${c.url}${c.title ? `\nTitle: ${c.title}` : ""}${progress}${scroll}`;
             return `${head}\n\n${c.text || "(no readable text)"}`;
         }
         case "extract": {
@@ -109,7 +139,9 @@ export async function browserObserveTool(args, ctx) {
                 : "Links: (none)";
             const images = r.images.length > 0
                 ? "Images (use the ref with browser_observe(image) to SEE one):\n" +
-                    r.images.map((im) => `- [${im.ref ?? "?"}] ${im.alt ? `${im.alt} → ` : ""}${im.url}`).join("\n")
+                    r.images
+                        .map((im) => `- [${im.ref ?? "?"}] ${im.alt ? `${im.alt} → ` : ""}${im.url}`)
+                        .join("\n")
                 : "Images: (none)";
             const videos = r.videos && r.videos.length > 0
                 ? "Videos:\n" + r.videos.map((v) => `- ${v.url}`).join("\n")
@@ -139,7 +171,10 @@ export async function browserObserveTool(args, ctx) {
             }
             if (blocks.length === 0)
                 return `Error: no images loaded — ${notes.join("; ")}`;
-            return { contentBlocks: blocks, result: `[loaded ${blocks.length} image(s): ${notes.join("; ")}]` };
+            return {
+                contentBlocks: blocks,
+                result: `[loaded ${blocks.length} image(s): ${notes.join("; ")}]`,
+            };
         }
         case "vision": {
             if (!modelSupportsVision(ctx)) {
@@ -161,7 +196,9 @@ export async function browserObserveTool(args, ctx) {
 // ════════════════════════════════════════════════════════════════════════════
 export const browserActToolDef = {
     name: "browser_act",
-    description: "Act on the page in the browser panel. Use refs (eN) from the latest " +
+    description: "Act on the task-owned tab in the CodeShell Browser Runtime. By default it " +
+        "shares the in-app browser profile but never controls a user-opened tab " +
+        "without an explicit claim. Use refs (eN) from the latest " +
         "browser_observe(snapshot). Actions:\n" +
         "- click {ref}: click an element.\n" +
         "- type {ref, text}: type text into an input (focuses first).\n" +
@@ -181,7 +218,17 @@ export const browserActToolDef = {
         properties: {
             action: {
                 type: "string",
-                enum: ["click", "type", "select", "press_key", "hover", "scroll", "wait", "list_tabs", "switch_tab"],
+                enum: [
+                    "click",
+                    "type",
+                    "select",
+                    "press_key",
+                    "hover",
+                    "scroll",
+                    "wait",
+                    "list_tabs",
+                    "switch_tab",
+                ],
                 description: "The interaction to perform",
             },
             ref: { type: "string", description: "Element ref (eN) — click/type/select/hover/press_key" },
@@ -191,7 +238,10 @@ export const browserActToolDef = {
             direction: { type: "string", enum: ["up", "down"], description: "Scroll direction — scroll" },
             amount: { type: "number", description: "Pixels to scroll (default one viewport) — scroll" },
             timeout_ms: { type: "number", description: "Max wait in ms (default 10000) — wait" },
-            tabId: { type: "string", description: "Target tab — required for switch_tab; optional on others (switches first)" },
+            tabId: {
+                type: "string",
+                description: "Target tab — required for switch_tab; optional on others (switches first)",
+            },
         },
         required: ["action"],
     },
@@ -215,13 +265,17 @@ export async function browserActTool(args, ctx) {
             if (tabs.length === 0)
                 return "(no open browser tabs)";
             return ("Open tabs:\n" +
-                tabs.map((t) => `- [${t.tabId}]${t.active ? " (active)" : ""} ${t.title || "(untitled)"} — ${t.url || "(blank)"}`).join("\n"));
+                tabs
+                    .map((t) => `- [${t.tabId}]${t.active ? " (active)" : ""} ${t.title || "(untitled)"} — ${t.url || "(blank)"}`)
+                    .join("\n"));
         }
         case "switch_tab": {
             if (!tabId)
                 return "Error: tabId is required for switch_tab (see list_tabs)";
             const r = await b.switchTab(tabId);
-            return r.ok ? `Switched to tab ${tabId} — re-observe to see it` : `Error: ${r.detail ?? "switch failed"}`;
+            return r.ok
+                ? `Switched to tab ${tabId} — re-observe to see it`
+                : `Error: ${r.detail ?? "switch failed"}`;
         }
         case "click": {
             if (!ref)
@@ -273,11 +327,20 @@ export async function browserActTool(args, ctx) {
             if (dir !== "up" && dir !== "down")
                 return "Error: direction must be 'up' or 'down'";
             const r = await b.scroll(dir, args.amount);
-            return r.ok ? `Scrolled ${dir}` : `Error: ${r.detail ?? "scroll failed"}`;
+            if (!r.ok) {
+                const code = r.code ? ` [${r.code}]` : "";
+                return `Error${code}: ${r.detail ?? "scroll failed"}`;
+            }
+            const state = r.scroll
+                ? ` — position ${Math.round(r.scroll.y)}/${Math.round(r.scroll.maxY)}${r.scroll.atEnd ? " (end)" : ""}`
+                : "";
+            return `Scrolled ${dir}${state}`;
         }
         case "wait": {
             const r = await b.waitForLoad(args.timeout_ms);
-            return r.ok ? `Page ready${r.detail ? ` (${r.detail})` : ""}` : `Error: ${r.detail ?? "wait failed"}`;
+            return r.ok
+                ? `Page ready${r.detail ? ` (${r.detail})` : ""}`
+                : `Error: ${r.detail ?? "wait failed"}`;
         }
         default:
             return `Error: unknown action "${action}"`;
@@ -288,8 +351,11 @@ export async function browserActTool(args, ctx) {
 // ════════════════════════════════════════════════════════════════════════════
 export const browserNavigateToolDef = {
     name: "browser_navigate",
-    description: "Navigate the browser panel to a URL (opens the panel automatically if none " +
-        "is open). Then call browser_act(wait) + browser_observe to see the page.",
+    description: "Navigate the CodeShell browser runtime to a URL. It does not control the " +
+        "user-facing built-in browser unless the user explicitly grants a future handoff. " +
+        "Navigation stays in the background; the runtime's own window appears only when login or a " +
+        "high-consequence action needs human control. Then call browser_act(wait) + " +
+        "browser_observe to inspect the page.",
     inputSchema: {
         type: "object",
         properties: { url: { type: "string", description: "Absolute URL to open" } },

package/dist/tool-system/builtin/edit-model-catalog.d.ts

@@ -1,3 +1,9 @@
 import type { ToolDefinition } from "../../types.js";
+/** Notifies process hosts after the user catalog has been persisted. Desktop
+ * uses this to refresh mounted settings/connection views without waiting for
+ * a parent turn_complete event (which may be absent for child/yielded runs). */
+type ModelCatalogChangedSink = () => void;
+export declare function setModelCatalogChangedSink(sink: ModelCatalogChangedSink | null): void;
 export declare const editModelCatalogToolDef: ToolDefinition;
 export declare function editModelCatalogTool(args: Record<string, unknown>): Promise<string>;
+export {};