@cjhyy/code-shell-core 0.9.6 → 0.9.7

package/dist/session/transcript.js

@@ -4,6 +4,7 @@
  */
 import { appendFileSync, chmodSync, closeSync, existsSync, fchmodSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
+import { createHash } from "node:crypto";
 import { nanoid } from "nanoid";
 import { logger } from "../logging/logger.js";
 const DEFAULT_CONTEXT_TAIL_SCAN_BYTES = 32 * 1024 * 1024;
@@ -33,6 +34,131 @@ function appendTranscriptLine(filePath, data) {
 const defaultTranscriptWriter = (filePath, data) => {
     appendTranscriptLine(filePath, data);
 };
+function checkpointHash(snapshot) {
+    return createHash("sha256").update(JSON.stringify(snapshot)).digest("hex");
+}
+/** Complete, ordered provider pairs are required before a checkpoint can commit. */
+export function hasCompleteContextToolPairs(messages) {
+    const pending = new Set();
+    const used = new Set();
+    for (const message of messages) {
+        if (pending.size > 0 &&
+            (message.role !== "user" ||
+                !Array.isArray(message.content) ||
+                message.content.length === 0 ||
+                message.content.some((block) => block.type !== "tool_result")))
+            return false;
+        if (!Array.isArray(message.content))
+            continue;
+        for (const block of message.content) {
+            if (block.type === "tool_use") {
+                if (message.role !== "assistant" || !block.id || used.has(block.id))
+                    return false;
+                used.add(block.id);
+                pending.add(block.id);
+            }
+            else if (block.type === "tool_result") {
+                if (message.role !== "user" || !block.tool_use_id || !pending.delete(block.tool_use_id)) {
+                    return false;
+                }
+            }
+        }
+    }
+    return pending.size === 0;
+}
+function readCheckpoint(event, precedingEvents) {
+    if (event.type !== "context_checkpoint")
+        return undefined;
+    const data = event.data;
+    if (!data ||
+        typeof data !== "object" ||
+        data.version !== 1 ||
+        typeof data.noteId !== "string" ||
+        typeof data.coveredThroughEventId !== "string" ||
+        !Array.isArray(data.messages) ||
+        data.messages.length === 0 ||
+        !Array.isArray(data.clientMessageIds))
+        return undefined;
+    const noteIndex = precedingEvents.findIndex((candidate) => candidate.id === data.noteId);
+    const cursorIndex = precedingEvents.findIndex((candidate) => candidate.id === data.coveredThroughEventId);
+    const note = precedingEvents[noteIndex];
+    if (cursorIndex < 0 ||
+        noteIndex <= cursorIndex ||
+        note?.type !== "context_note" ||
+        !note.data ||
+        typeof note.data.text !== "string" ||
+        note.data.text.trim().length === 0 ||
+        note.data.coveredThroughEventId !== data.coveredThroughEventId)
+        return undefined;
+    for (const value of data.messages) {
+        if (!value || typeof value !== "object")
+            return undefined;
+        const message = value;
+        if (!["user", "assistant", "system", "tool"].includes(message.role))
+            return undefined;
+        if (!validCheckpointContent(message.content))
+            return undefined;
+    }
+    const seen = new Set();
+    for (const pair of data.clientMessageIds) {
+        if (!Array.isArray(pair) ||
+            pair.length !== 2 ||
+            typeof pair[0] !== "string" ||
+            seen.has(pair[0]) ||
+            !Number.isSafeInteger(pair[1]) ||
+            pair[1] < 0 ||
+            pair[1] >= data.messages.length)
+            return undefined;
+        seen.add(pair[0]);
+    }
+    const snapshot = {
+        version: 1,
+        noteId: data.noteId,
+        coveredThroughEventId: data.coveredThroughEventId,
+        messages: data.messages,
+        clientMessageIds: data.clientMessageIds,
+    };
+    if (data.checksum !== checkpointHash(snapshot) ||
+        !hasCompleteContextToolPairs(snapshot.messages)) {
+        return undefined;
+    }
+    return snapshot;
+}
+function validCheckpointContent(content, depth = 0) {
+    if (typeof content === "string")
+        return true;
+    if (!Array.isArray(content) || depth > 8)
+        return false;
+    return content.every((value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return false;
+        const block = value;
+        switch (block.type) {
+            case "text":
+            case "reasoning":
+                return ((block.text === undefined || typeof block.text === "string") &&
+                    (block.reasoningContent === undefined || typeof block.reasoningContent === "string"));
+            case "image":
+                return (block.source?.type === "base64" &&
+                    typeof block.source.media_type === "string" &&
+                    typeof block.source.data === "string");
+            case "tool_use":
+                return (depth === 0 &&
+                    typeof block.id === "string" &&
+                    (block.name === undefined || typeof block.name === "string") &&
+                    (block.input === undefined ||
+                        (block.input !== null &&
+                            typeof block.input === "object" &&
+                            !Array.isArray(block.input))));
+            case "tool_result":
+                return (depth === 0 &&
+                    typeof block.tool_use_id === "string" &&
+                    (block.content === undefined || validCheckpointContent(block.content, depth + 1)));
+            default:
+                return false;
+        }
+    });
+}
 const CONTEXT_EVENT_TYPES = new Set([
     "message",
     "tool_use",
@@ -47,6 +173,18 @@ function isSyntheticInterruptedToolResult(event) {
         event.data.toolName === "unknown" &&
         event.data.error === INTERRUPTED_TOOL_RESULT_ERROR);
 }
+function toolResultContentBlock(event) {
+    const { toolCallId, result, error, contentBlocks } = event.data;
+    return {
+        type: "tool_result",
+        tool_use_id: toolCallId,
+        content: error
+            ? `Error: ${error}`
+            : Array.isArray(contentBlocks) && contentBlocks.length > 0
+                ? structuredClone(contentBlocks)
+                : (result ?? "(no output)"),
+    };
+}
 /**
  * Choose at most one result for every declared tool call. A real late result
  * wins over the legacy synthetic "interrupted" placeholder that an older
@@ -120,6 +258,40 @@ export class Transcript {
         transcript.loadEvents(events);
         return transcript;
     }
+    /** Preserve checkpoint provenance when a fork assigns fresh event ids. */
+    static remapContextForkReferences(sourceEvents, copiedEvents) {
+        if (!sourceEvents.some((event) => event.type === "context_note"))
+            return;
+        const eventIds = new Map(sourceEvents.map((event, index) => [event.id, copiedEvents[index].id]));
+        for (const [index, source] of sourceEvents.entries()) {
+            const copied = copiedEvents[index];
+            // An inherited note can cite old event ids. Resolve those aliases only
+            // against the copied prefix, never by reaching into the parent session.
+            copied.data.contextHistorySourceIds = [
+                ...(Array.isArray(source.data.contextHistorySourceIds)
+                    ? source.data.contextHistorySourceIds.filter((id) => typeof id === "string")
+                    : []),
+                source.id,
+            ];
+            if (source.type === "context_note") {
+                const cursor = source.data.coveredThroughEventId;
+                if (typeof cursor === "string" && eventIds.has(cursor)) {
+                    copied.data.coveredThroughEventId = eventIds.get(cursor);
+                }
+            }
+            if (source.type !== "context_checkpoint")
+                continue;
+            const snapshot = readCheckpoint(source, sourceEvents.slice(0, index));
+            if (!snapshot)
+                continue; // Never turn a corrupt source checkpoint into a valid one.
+            const noteId = eventIds.get(snapshot.noteId);
+            const coveredThroughEventId = eventIds.get(snapshot.coveredThroughEventId);
+            if (!noteId || !coveredThroughEventId)
+                continue;
+            const remapped = { ...snapshot, noteId, coveredThroughEventId };
+            Object.assign(copied.data, remapped, { checksum: checkpointHash(remapped) });
+        }
+    }
     isPersistent() {
         return this.persistent;
     }
@@ -135,6 +307,41 @@ export class Transcript {
         this.flush(event);
         return event;
     }
+    /** Failed note/checkpoint writes must never change the active replay. */
+    appendContextNote(text, coveredThroughEventId) {
+        return this.appendDurableContextEvent("context_note", { text, coveredThroughEventId });
+    }
+    appendContextCheckpoint(snapshot) {
+        const frozen = structuredClone(snapshot);
+        const data = { ...frozen, checksum: checkpointHash(frozen) };
+        const candidate = {
+            id: "validation",
+            type: "context_checkpoint",
+            timestamp: Date.now(),
+            turnNumber: this.currentTurn,
+            data,
+        };
+        if (!readCheckpoint(candidate, this.events))
+            return undefined;
+        return this.appendDurableContextEvent("context_checkpoint", data);
+    }
+    appendDurableContextEvent(type, data) {
+        // A missing earlier event makes a durable cursor unreliable, even when
+        // this particular append would succeed.
+        if (this.dirty)
+            return undefined;
+        const event = {
+            id: nanoid(12),
+            type,
+            timestamp: Date.now(),
+            turnNumber: this.currentTurn,
+            data,
+        };
+        if (!this.flush(event))
+            return undefined;
+        this.events.push(event);
+        return event;
+    }
     /**
      * Append a chat message to the transcript.
      *
@@ -288,10 +495,11 @@ export class Transcript {
      *   payloads, and transport metadata must not leak into them.
      */
     toMessagesWithIndex() {
+        const events = this.contextReplayEvents();
         const messages = [];
         const liveIndexByClientMessageId = new Map();
-        const selectedToolResults = preferredToolResults(this.events);
-        const hasRangeArchive = this.events.some((e) => e.type === "range_archive");
+        const selectedToolResults = preferredToolResults(events);
+        const hasRangeArchive = events.some((e) => e.type === "range_archive");
         const spansByFromId = new Map();
         let openingSpan;
         if (hasRangeArchive) {
@@ -302,7 +510,7 @@ export class Transcript {
             // while scanning forward, so it would never close — silently swallowing
             // the rest of the conversation. Fail open instead: ignore the marker.
             const firstIndexByClientId = new Map();
-            for (const [index, event] of this.events.entries()) {
+            for (const [index, event] of events.entries()) {
                 if (event.type === "message" && typeof event.data.clientMessageId === "string") {
                     if (!firstIndexByClientId.has(event.data.clientMessageId)) {
                         firstIndexByClientId.set(event.data.clientMessageId, index);
@@ -310,7 +518,7 @@ export class Transcript {
                 }
             }
             const presentClientIds = new Set(firstIndexByClientId.keys());
-            for (const event of this.events) {
+            for (const event of events) {
                 if (event.type !== "range_archive")
                     continue;
                 const { summary, toClientMessageId, fromClientMessageId } = event.data;
@@ -351,7 +559,7 @@ export class Transcript {
         // preferred) real result landed outside it — would be an orphaned block
         // that breaks provider validation; skip it instead of emitting it.
         const emittedToolUseIds = new Set();
-        for (const event of this.events) {
+        for (const event of events) {
             // Span bookkeeping runs on message events only: exit before entry so
             // adjacent spans (A.to === B.from) hand over on the boundary message.
             if (event.type === "message") {
@@ -387,7 +595,9 @@ export class Transcript {
                             }
                         }
                     }
-                    messages.push({ role: role, content });
+                    // Tool results can be merged into this array below. Never mutate
+                    // the source event (or a checkpoint) during a read-only replay.
+                    messages.push({ role: role, content: structuredClone(content) });
                     break;
                 }
                 case "tool_use": {
@@ -402,18 +612,9 @@ export class Transcript {
                         !emittedToolUseIds.has(eventToolCallId)) {
                         break;
                     }
-                    const { toolCallId, result, error, contentBlocks } = event.data;
                     // Find if there's already a user message with tool_results to append to
                     const lastMsg = messages[messages.length - 1];
-                    const block = {
-                        type: "tool_result",
-                        tool_use_id: toolCallId,
-                        content: error
-                            ? `Error: ${error}`
-                            : Array.isArray(contentBlocks) && contentBlocks.length > 0
-                                ? contentBlocks
-                                : (result ?? "(no output)"),
-                    };
+                    const block = toolResultContentBlock(event);
                     if (lastMsg?.role === "user" && Array.isArray(lastMsg.content)) {
                         lastMsg.content.push(block);
                     }
@@ -449,6 +650,55 @@ export class Transcript {
         }
         return { messages, liveIndexByClientMessageId };
     }
+    contextReplayEvents() {
+        for (let index = this.events.length - 1; index >= 0; index -= 1) {
+            const event = this.events[index];
+            if (event.type !== "context_checkpoint")
+                continue;
+            const snapshot = readCheckpoint(event, this.events.slice(0, index));
+            if (!snapshot)
+                continue; // Corrupt or truncated checkpoints fail open.
+            const clientIdByIndex = new Map(snapshot.clientMessageIds.map(([id, i]) => [i, id]));
+            const snapshotEvents = snapshot.messages.map((message, messageIndex) => ({
+                id: `${event.id}:${messageIndex}`,
+                type: "message",
+                timestamp: event.timestamp,
+                turnNumber: event.turnNumber,
+                data: {
+                    role: message.role,
+                    content: structuredClone(message.content),
+                    ...(clientIdByIndex.has(messageIndex)
+                        ? { clientMessageId: clientIdByIndex.get(messageIndex) }
+                        : {}),
+                },
+            }));
+            const tail = this.events.slice(index + 1);
+            const lateResults = preferredToolResults([...snapshotEvents, ...tail]);
+            const completedIds = new Set();
+            for (const snapshotEvent of snapshotEvents) {
+                const content = snapshotEvent.data.content;
+                if (!Array.isArray(content))
+                    continue;
+                snapshotEvent.data.content = content.map((block) => {
+                    if (block.type !== "tool_result" || !block.tool_use_id)
+                        return block;
+                    completedIds.add(block.tool_use_id);
+                    const late = lateResults.get(block.tool_use_id);
+                    // Reconcile late duplicates in the original result position, so a
+                    // result cannot become orphaned or split an unrelated later batch.
+                    return late && !isSyntheticInterruptedToolResult(late)
+                        ? toolResultContentBlock(late)
+                        : block;
+                });
+            }
+            return [
+                ...snapshotEvents,
+                ...tail.filter((candidate) => candidate.type !== "tool_result" ||
+                    !completedIds.has(candidate.data.toolCallId)),
+            ];
+        }
+        return this.events;
+    }
     getEvents(type) {
         if (!type)
             return [...this.events];
@@ -727,6 +977,11 @@ export class Transcript {
                 return Transcript.loadFromFile(filePath);
             }
         }
+        // Checkpoint validity references its note and covered cursor. A bounded
+        // range-archive tail may omit either, so use the full loader here.
+        if (events.some((event) => event.type === "context_checkpoint")) {
+            return Transcript.loadFromFile(filePath);
+        }
         let markerIndex = -1;
         let toClientMessageId;
         for (const [index, event] of events.entries()) {

package/dist/settings/schema.d.ts

@@ -405,6 +405,7 @@ export declare const SettingsSchema: z.ZodObject<{
         defaultMode?: "default" | "auto" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "plan" | undefined;
     }>>;
     context: z.ZodDefault<z.ZodObject<{
+        strategy: z.ZodOptional<z.ZodEnum<["summary", "notes"]>>;
         maxTokens: z.ZodDefault<z.ZodNumber>;
         compactAtRatio: z.ZodDefault<z.ZodNumber>;
         summarizeAtRatio: z.ZodDefault<z.ZodNumber>;
@@ -414,8 +415,10 @@ export declare const SettingsSchema: z.ZodObject<{
         compactAtRatio: number;
         summarizeAtRatio: number;
         microcompactFloorRatio: number;
+        strategy?: "summary" | "notes" | undefined;
     }, {
         maxTokens?: number | undefined;
+        strategy?: "summary" | "notes" | undefined;
         compactAtRatio?: number | undefined;
         summarizeAtRatio?: number | undefined;
         microcompactFloorRatio?: number | undefined;
@@ -1429,6 +1432,7 @@ export declare const SettingsSchema: z.ZodObject<{
         defaultMode?: "default" | "auto" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "plan" | undefined;
     }>>;
     context: z.ZodDefault<z.ZodObject<{
+        strategy: z.ZodOptional<z.ZodEnum<["summary", "notes"]>>;
         maxTokens: z.ZodDefault<z.ZodNumber>;
         compactAtRatio: z.ZodDefault<z.ZodNumber>;
         summarizeAtRatio: z.ZodDefault<z.ZodNumber>;
@@ -1438,8 +1442,10 @@ export declare const SettingsSchema: z.ZodObject<{
         compactAtRatio: number;
         summarizeAtRatio: number;
         microcompactFloorRatio: number;
+        strategy?: "summary" | "notes" | undefined;
     }, {
         maxTokens?: number | undefined;
+        strategy?: "summary" | "notes" | undefined;
         compactAtRatio?: number | undefined;
         summarizeAtRatio?: number | undefined;
         microcompactFloorRatio?: number | undefined;
@@ -2453,6 +2459,7 @@ export declare const SettingsSchema: z.ZodObject<{
         defaultMode?: "default" | "auto" | "acceptEdits" | "dontAsk" | "bypassPermissions" | "plan" | undefined;
     }>>;
     context: z.ZodDefault<z.ZodObject<{
+        strategy: z.ZodOptional<z.ZodEnum<["summary", "notes"]>>;
         maxTokens: z.ZodDefault<z.ZodNumber>;
         compactAtRatio: z.ZodDefault<z.ZodNumber>;
         summarizeAtRatio: z.ZodDefault<z.ZodNumber>;
@@ -2462,8 +2469,10 @@ export declare const SettingsSchema: z.ZodObject<{
         compactAtRatio: number;
         summarizeAtRatio: number;
         microcompactFloorRatio: number;
+        strategy?: "summary" | "notes" | undefined;
     }, {
         maxTokens?: number | undefined;
+        strategy?: "summary" | "notes" | undefined;
         compactAtRatio?: number | undefined;
         summarizeAtRatio?: number | undefined;
         microcompactFloorRatio?: number | undefined;

package/dist/settings/schema.js

@@ -257,6 +257,10 @@ export const SettingsSchema = z
         .default({}),
     context: z
         .object({
+        strategy: z
+            .enum(["summary", "notes"])
+            .optional()
+            .describe("上下文策略：notes 使用接续笔记和历史检索；summary 使用现有摘要压缩。未设置时跟随行为配置。"),
         maxTokens: z.number().default(200_000),
         // 压缩阈值（占上下文窗口的比例）。窗口越大可调越高：1M 窗口的模型
         // 把 compactAtRatio 调到 0.95 能少浪费几十万 token。三档须满足

package/dist/themes/paths.js

@@ -9,8 +9,27 @@ export class ThemeReviewChangedError extends ThemeInstallError {
         super("theme content changed since preview");
     }
 }
+/**
+ * Where installed themes live.
+ *
+ * This used to resolve HOME on its own, so a test that reached it without
+ * CODE_SHELL_HOME wrote into the developer's real theme registry — eight
+ * "concurrent-N" fixture packs showed up in a real settings picker on
+ * 2026-09-06. The sessions-root guard did not cover it because this was a
+ * second, independent home resolution.
+ *
+ * Fails closed under a test runner instead. `bun test` sets NODE_ENV=test
+ * itself, so no test has to opt in, and a real host run is untouched.
+ */
 function userHome() {
-    return process.env.CODE_SHELL_HOME ?? process.env.HOME ?? homedir();
+    const explicit = process.env.CODE_SHELL_HOME;
+    if (explicit)
+        return explicit;
+    if (process.env.NODE_ENV === "test" || process.env.BUN_TEST === "1") {
+        throw new ThemeInstallError("Refusing to use the real ~/.code-shell/themes from a test. Set CODE_SHELL_HOME " +
+            "to a temp dir (packages/core/test-setup.ts does this via the bunfig preload).");
+    }
+    return process.env.HOME ?? homedir();
 }
 /** A theme id must be a single safe path segment matching the manifest pattern. */
 export function assertSafeThemeName(id) {

package/dist/tool-system/browser-bridge.d.ts

@@ -57,7 +57,7 @@ export interface BrowserSnapshot {
     /** Which login identity this page is being viewed as (§8.3). */
     identity?: BrowserIdentity;
 }
-export type BrowserResultCode = "OK" | "STALE_SNAPSHOT" | "STALE_CURSOR" | "NO_PROGRESS" | "NAVIGATION" | "BLOCKED" | "NEEDS_HUMAN" | "FAILED";
+export type BrowserResultCode = "OK" | "STALE_SNAPSHOT" | "STALE_CURSOR" | "TARGET_CLOSED" | "NO_PROGRESS" | "NAVIGATION" | "BLOCKED" | "NEEDS_HUMAN" | "FAILED";
 export interface BrowserScrollState {
     x: number;
     y: number;
@@ -210,6 +210,8 @@ export interface BrowserBridge {
 }
 /** One open browser tab, as the agent sees it. */
 export interface BrowserTab {
+    /** Closed task-owned targets can be listed with a URL for explicit recovery. */
+    status?: "open" | "closed";
     /** Stable id (the desktop webContents id, as a string). */
     tabId: string;
     url: string;

package/dist/tool-system/browser-discovery.d.ts

@@ -0,0 +1,6 @@
+import type { RegisteredTool } from "../types.js";
+export declare function isBuiltinBrowserTool(tool: Pick<RegisteredTool, "name" | "source">): boolean;
+/** Prefer the native path for generic browser discovery, without redirecting
+ * exact selections, named providers, or DevTools-specific requests. Only the
+ * run's already-authorized tools are scored by the caller. */
+export declare function browserDiscoveryScore(tool: RegisteredTool, query: string): number;

package/dist/tool-system/browser-discovery.js

@@ -0,0 +1,17 @@
+const BROWSER_TOOLS = ["browser_navigate", "browser_observe", "browser_act"];
+export function isBuiltinBrowserTool(tool) {
+    return tool.source === "builtin" && BROWSER_TOOLS.some((name) => name === tool.name);
+}
+/** Prefer the native path for generic browser discovery, without redirecting
+ * exact selections, named providers, or DevTools-specific requests. Only the
+ * run's already-authorized tools are scored by the caller. */
+export function browserDiscoveryScore(tool, query) {
+    if (!isBuiltinBrowserTool(tool))
+        return 0;
+    if (!/\b(browser|browse|webpage)\b|浏览器|网页/i.test(query))
+        return 0;
+    if (/\b(mcp|chrome|chromium|playwright|selenium|firefox|edge|devtools|network|console|performance|trace)\b|网络请求|控制台|性能/i.test(query)) {
+        return 0;
+    }
+    return 40 - BROWSER_TOOLS.findIndex((name) => name === tool.name);
+}

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

@@ -222,7 +222,7 @@ export const browserActToolDef = {
         "- select {ref, value}: choose an option in a NATIVE <select> (value = option " +
         "value or visible text). Custom dropdowns: click to expand, then click the option.\n" +
         "- press_key {key, ref?}: press a key/combo (Enter, Tab, Escape, ArrowDown, " +
-        "Control+a). Focuses ref first if given.\n" +
+        "ControlOrMeta+a; resolves to Command on macOS, Control elsewhere). Focuses ref first if given.\n" +
         "- hover {ref}: hover to reveal menus/tooltips.\n" +
         "- scroll {direction: up|down, amount?}: scroll the page, then re-observe.\n" +
         "- wait {timeout_ms?}: wait for the page to finish loading before observing.\n" +
@@ -255,7 +255,10 @@ export const browserActToolDef = {
             ref: { type: "string", description: "Element ref (eN) — click/type/select/hover/press_key" },
             text: { type: "string", description: "Text to type — type" },
             value: { type: "string", description: "Option value or visible text — select" },
-            key: { type: "string", description: "Key name or combo (Enter/Tab/Control+a) — press_key" },
+            key: {
+                type: "string",
+                description: "Key or combo (Enter/Tab/ControlOrMeta+a). ControlOrMeta uses the browser host's platform; literal Control and Meta stay distinct — press_key",
+            },
             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" },
@@ -294,9 +297,9 @@ export async function browserActTool(args, ctx) {
             const tabs = await b.listTabs();
             if (tabs.length === 0)
                 return "(no open browser tabs)";
-            return ("Open tabs:\n" +
+            return ("Browser tabs:\n" +
                 tabs
-                    .map((t) => `- [${t.tabId}]${t.active ? " (active)" : ""} ${t.title || "(untitled)"} — ${t.url || "(blank)"}`)
+                    .map((t) => `- [${t.tabId}]${t.status === "closed" ? " (closed — navigate to reopen; old refs expired)" : t.active ? " (active)" : ""} ${t.title || "(untitled)"} — ${t.url || "(blank)"}`)
                     .join("\n"));
         }
         case "switch_tab": {
@@ -381,10 +384,11 @@ export async function browserActTool(args, ctx) {
 // ════════════════════════════════════════════════════════════════════════════
 export const browserNavigateToolDef = {
     name: "browser_navigate",
-    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) + " +
+    description: "Open a URL in a task-owned tab of CodeShell's built-in browser. Default for web page " +
+        "tasks unless the user specifies another browser or a required capability is unavailable. " +
+        "Shares the in-app browser profile; existing user-opened tabs require an explicit grant. " +
+        "Starts in the background; browser_act(request_takeover) reveals this same tab when the user " +
+        "wants to see it or needs to sign in. Then call browser_act(wait) + " +
         "browser_observe to inspect the page.",
     inputSchema: {
         type: "object",

package/dist/tool-system/builtin/context-notes.d.ts

@@ -0,0 +1,12 @@
+/** Session working memory tools. The owning loop applies rollover after the tool batch. */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const SAVE_CONTEXT_NOTE_TOOL_NAME = "SaveContextNote";
+export declare const NEW_CONTEXT_TOOL_NAME = "NewContext";
+export declare const SEARCH_HISTORY_TOOL_NAME = "SearchHistory";
+export declare const saveContextNoteToolDef: ToolDefinition;
+export declare const newContextToolDef: ToolDefinition;
+export declare const searchHistoryToolDef: ToolDefinition;
+export declare function saveContextNoteTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function newContextTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function searchHistoryTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;