@cjhyy/code-shell-core 0.8.6 → 0.8.8

package/dist/panel-apps/manifest.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 export declare const PANEL_APP_MANIFEST_FILE = ".codeshell-panel/panel.json";
-export declare const PANEL_APP_PERMISSIONS: readonly ["context.session", "context.workspace", "storage", "external.open", "agent.submitPrompt", "workspace.info", "workspace.read", "workspace.write", "notifications.send"];
+export declare const PANEL_APP_PERMISSIONS: readonly ["context.session", "context.workspace", "storage", "external.open", "agent.submitPrompt", "workspace.info", "workspace.read", "workspace.write", "notifications.send", "audio.transcribe", "credentials.cookies", "automations.manage"];
 export declare const PANEL_APP_ICONS: readonly ["panel", "activity", "bar-chart-3", "chart", "file-text", "globe", "image", "layout-dashboard", "line-chart", "palette", "pie-chart", "table", "terminal"];
 export declare const PanelAppAgentTool: z.ZodEffects<z.ZodObject<{
     name: z.ZodString;
@@ -116,12 +116,12 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
     icon: z.ZodDefault<z.ZodEnum<["panel", "activity", "bar-chart-3", "chart", "file-text", "globe", "image", "layout-dashboard", "line-chart", "palette", "pie-chart", "table", "terminal"]>>;
     placement: z.ZodDefault<z.ZodLiteral<"right-dock">>;
     singleton: z.ZodDefault<z.ZodBoolean>;
-    permissions: z.ZodDefault<z.ZodArray<z.ZodEnum<["context.session", "context.workspace", "storage", "external.open", "agent.submitPrompt", "workspace.info", "workspace.read", "workspace.write", "notifications.send"]>, "many">>;
+    permissions: z.ZodDefault<z.ZodArray<z.ZodEnum<["context.session", "context.workspace", "storage", "external.open", "agent.submitPrompt", "workspace.info", "workspace.read", "workspace.write", "notifications.send", "audio.transcribe", "credentials.cookies", "automations.manage"]>, "many">>;
     schemaVersion: z.ZodLiteral<1>;
 }, "strict", z.ZodTypeAny, {
     id: string;
     version: string;
-    permissions: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send")[];
+    permissions: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage")[];
     entry: string;
     title: {
         default: string;
@@ -144,7 +144,7 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
     };
     schemaVersion: 1;
     description?: string | undefined;
-    permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send")[] | undefined;
+    permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage")[] | undefined;
     icon?: "terminal" | "image" | "panel" | "activity" | "bar-chart-3" | "chart" | "file-text" | "globe" | "layout-dashboard" | "line-chart" | "palette" | "pie-chart" | "table" | undefined;
     placement?: "right-dock" | undefined;
     singleton?: boolean | undefined;
@@ -230,12 +230,12 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
     icon: z.ZodDefault<z.ZodEnum<["panel", "activity", "bar-chart-3", "chart", "file-text", "globe", "image", "layout-dashboard", "line-chart", "palette", "pie-chart", "table", "terminal"]>>;
     placement: z.ZodDefault<z.ZodLiteral<"right-dock">>;
     singleton: z.ZodDefault<z.ZodBoolean>;
-    permissions: z.ZodDefault<z.ZodArray<z.ZodEnum<["context.session", "context.workspace", "storage", "external.open", "agent.submitPrompt", "workspace.info", "workspace.read", "workspace.write", "notifications.send"]>, "many">>;
+    permissions: z.ZodDefault<z.ZodArray<z.ZodEnum<["context.session", "context.workspace", "storage", "external.open", "agent.submitPrompt", "workspace.info", "workspace.read", "workspace.write", "notifications.send", "audio.transcribe", "credentials.cookies", "automations.manage"]>, "many">>;
     schemaVersion: z.ZodLiteral<2>;
 }, "strict", z.ZodTypeAny, {
     id: string;
     version: string;
-    permissions: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send")[];
+    permissions: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage")[];
     entry: string;
     title: {
         default: string;
@@ -276,14 +276,14 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
         }[] | undefined;
     } | undefined;
     description?: string | undefined;
-    permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send")[] | undefined;
+    permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage")[] | undefined;
     icon?: "terminal" | "image" | "panel" | "activity" | "bar-chart-3" | "chart" | "file-text" | "globe" | "layout-dashboard" | "line-chart" | "palette" | "pie-chart" | "table" | undefined;
     placement?: "right-dock" | undefined;
     singleton?: boolean | undefined;
 }>]>, {
     id: string;
     version: string;
-    permissions: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send")[];
+    permissions: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage")[];
     entry: string;
     title: {
         default: string;
@@ -298,7 +298,7 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
 } | {
     id: string;
     version: string;
-    permissions: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send")[];
+    permissions: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage")[];
     entry: string;
     title: {
         default: string;
@@ -330,7 +330,7 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
     };
     schemaVersion: 1;
     description?: string | undefined;
-    permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send")[] | undefined;
+    permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage")[] | undefined;
     icon?: "terminal" | "image" | "panel" | "activity" | "bar-chart-3" | "chart" | "file-text" | "globe" | "layout-dashboard" | "line-chart" | "palette" | "pie-chart" | "table" | undefined;
     placement?: "right-dock" | undefined;
     singleton?: boolean | undefined;
@@ -354,7 +354,7 @@ export declare const PanelAppManifest: z.ZodEffects<z.ZodDiscriminatedUnion<"sch
         }[] | undefined;
     } | undefined;
     description?: string | undefined;
-    permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send")[] | undefined;
+    permissions?: ("context.session" | "context.workspace" | "storage" | "external.open" | "agent.submitPrompt" | "workspace.info" | "workspace.read" | "workspace.write" | "notifications.send" | "audio.transcribe" | "credentials.cookies" | "automations.manage")[] | undefined;
     icon?: "terminal" | "image" | "panel" | "activity" | "bar-chart-3" | "chart" | "file-text" | "globe" | "layout-dashboard" | "line-chart" | "palette" | "pie-chart" | "table" | undefined;
     placement?: "right-dock" | undefined;
     singleton?: boolean | undefined;

package/dist/panel-apps/manifest.js

@@ -11,6 +11,9 @@ export const PANEL_APP_PERMISSIONS = [
     "workspace.read",
     "workspace.write",
     "notifications.send",
+    "audio.transcribe",
+    "credentials.cookies",
+    "automations.manage",
 ];
 export const PANEL_APP_ICONS = [
     "panel",
@@ -136,7 +139,7 @@ const PanelAppManifestFields = {
     icon: z.enum(PANEL_APP_ICONS).default("panel"),
     placement: z.literal("right-dock").default("right-dock"),
     singleton: z.boolean().default(true),
-    permissions: z.array(z.enum(PANEL_APP_PERMISSIONS)).max(8).default([]),
+    permissions: z.array(z.enum(PANEL_APP_PERMISSIONS)).max(12).default([]),
 };
 /**
  * Schema v2 keeps one installable Panel App identity while allowing it to
@@ -178,12 +181,22 @@ export const PanelAppManifest = z
         });
     }
     if ((value.permissions.includes("workspace.read") ||
-        value.permissions.includes("workspace.write")) &&
+        value.permissions.includes("workspace.write") ||
+        value.permissions.includes("audio.transcribe")) &&
         !value.permissions.includes("context.workspace")) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["permissions"],
-            message: "workspace.read and workspace.write require context.workspace",
+            message: "workspace.read, workspace.write, and audio.transcribe require context.workspace",
+        });
+    }
+    if (value.permissions.includes("automations.manage") &&
+        (!value.permissions.includes("context.session") ||
+            !value.permissions.includes("context.workspace"))) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["permissions"],
+            message: "automations.manage requires context.session and context.workspace",
         });
     }
 });

package/dist/prompt/composer.d.ts

@@ -89,6 +89,13 @@ export interface ComposerOptions {
      * Undefined/0 → inject all.
      */
     memoriesMaxAgeDays?: number;
+    /**
+     * When true (set from the active behavior profile, e.g. the Pet manager),
+     * the injected memory index keeps only memories relevant to this cwd —
+     * global-layer project/dream records tied to other projects are dropped.
+     * See MemoryManager.buildInjectionIndex(currentProjectOnly).
+     */
+    memoryCurrentProjectOnly?: boolean;
 }
 export declare class PromptComposer {
     private readonly options;

package/dist/prompt/composer.js

@@ -102,18 +102,24 @@ export class PromptComposer {
         });
         const skillsListing = buildSkillListing(skills);
         const declaredSkillGap = this.buildDeclaredSkillGap(skills);
-        const capabilityContext = await this.buildSystemContext();
+        // Capability and sources context are independent I/O — resolve them
+        // concurrently instead of serially.
+        const [capabilityContext, sourcesContext] = await Promise.all([
+            this.buildSystemContext(),
+            (async () => {
+                try {
+                    return (await this.options.sourcesContextProvider?.()) ?? "";
+                }
+                catch {
+                    // Optional metadata context must not make a turn fail.
+                    return "";
+                }
+            })(),
+        ]);
         // 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();
-        let sourcesContext = "";
-        try {
-            sourcesContext = (await this.options.sourcesContextProvider?.()) ?? "";
-        }
-        catch {
-            // Optional metadata context must not make a turn fail.
-        }
         const goalToolContext = this.buildGoalToolContext();
         const parts = [
             skillsListing,
@@ -268,6 +274,7 @@ export class PromptComposer {
                 projectDir: this.options.cwd,
                 profileDir: this.options.profileMemoryDir,
                 maxAgeDays: this.options.memoriesMaxAgeDays,
+                currentProjectOnly: this.options.memoryCurrentProjectOnly,
             });
         }
         catch {

package/dist/prompt/sections/browser.md

@@ -1,11 +1,11 @@
 ## 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 — use the three browser tools. They drive a task-owned background tab in CodeShell's in-app browser profile. The tab can share that profile's login state, but it never controls a user-opened tab unless the user explicitly grants that exact tab. The user's regular Chrome profile is available only through an explicit Chrome extension grant.
-- The Browser Runtime starts lazily in the background. Call `browser_navigate{url}`, then `browser_act{action:"wait"}` and `browser_observe`. If login, 2FA, or a high-consequence action needs the user, CodeShell reveals the exact same runtime-owned in-app target for takeover. Scheduled and explicitly isolated work may use a separate Dedicated Playwright profile instead.
+- The Browser Runtime starts lazily in the background. Call `browser_navigate{url}`, then `browser_act{action:"wait"}` and `browser_observe`. If login, 2FA, CAPTCHA, or a high-consequence action needs the user—or the user explicitly asks to see the page—call `browser_act{action:"request_takeover"}`. CodeShell reveals the exact same runtime-owned in-app target; do not send a second link and claim it is the page you operated. Scheduled and explicitly isolated work may use a separate Dedicated Playwright profile instead.
 - 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"}`. If it returns `nextCursor`, continue with `browser_observe{mode:"read",cursor:"..."}` until `Read: complete`. Do NOT scroll merely to obtain the next text chunk. Use scroll only to load lazy/infinite content; stop when it reports `NO_PROGRESS` or `(end)`. For real link/image/video URLs, use `browser_observe{mode:"extract"}` (media is 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 revealed Browser Runtime window, then continue — do not attempt to enter credentials yourself. Sensitive actions (payment, delete, entering card/password values) require user approval.
+- If `browser_observe` reports a sign-in is required (or you hit a login wall / 2FA / CAPTCHA), call `browser_act{action:"request_takeover"}`, STOP, and ask the user to act in the revealed Browser Runtime window. Continue only after the user finishes; do not attempt to enter credentials yourself. Sensitive actions (payment, delete, entering card/password values) require user approval.
 - If the tools report that no Browser Runtime is available, the current host does not provide browser automation — say so rather than retrying.

package/dist/protocol/server.js

@@ -2240,7 +2240,17 @@ export class AgentServer {
                 if (!archiveEngine)
                     return;
                 try {
-                    const result = await archiveEngine.archiveTurnRange(archiveSessionId, { start, end });
+                    const toClientMessageId = typeof params.toClientMessageId === "string" ? params.toClientMessageId : undefined;
+                    const anchors = toClientMessageId
+                        ? {
+                            toClientMessageId,
+                            ...(typeof params.fromClientMessageId === "string"
+                                ? { fromClientMessageId: params.fromClientMessageId }
+                                : {}),
+                            ...(typeof params.segmentId === "string" ? { segmentId: params.segmentId } : {}),
+                        }
+                        : undefined;
+                    const result = await archiveEngine.archiveTurnRange(archiveSessionId, { start, end }, anchors);
                     if (result.before > result.after) {
                         const event = {
                             type: "context_compact",
@@ -2265,6 +2275,35 @@ export class AgentServer {
                 }
                 break;
             }
+            case "archive_marker": {
+                const markerSessionId = typeof params.sessionId === "string" && params.sessionId.length > 0
+                    ? params.sessionId
+                    : undefined;
+                const summary = typeof params.summary === "string" ? params.summary : undefined;
+                const toClientMessageId = typeof params.toClientMessageId === "string" ? params.toClientMessageId : undefined;
+                if (!markerSessionId || !summary || !toClientMessageId) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, "archive_marker requires sessionId, summary and toClientMessageId"));
+                    return;
+                }
+                const markerEngine = await this.resolveEngineForSessionQuery(req, markerSessionId, engine, "archive_marker");
+                if (!markerEngine)
+                    return;
+                try {
+                    const appended = await markerEngine.appendArchiveMarker(markerSessionId, {
+                        summary,
+                        toClientMessageId,
+                        ...(typeof params.fromClientMessageId === "string"
+                            ? { fromClientMessageId: params.fromClientMessageId }
+                            : {}),
+                        ...(typeof params.segmentId === "string" ? { segmentId: params.segmentId } : {}),
+                    });
+                    this.transport.send(createResponse(req.id, { type: "archive_marker", data: { appended } }));
+                }
+                catch (err) {
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
+                }
+                break;
+            }
             case "models": {
                 if (!engine) {
                     this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, "No engine available for models query"));
@@ -2790,6 +2829,7 @@ export class AgentServer {
     makeBrowserBridge(session, sessionId) {
         const call = (action, payload) => this.requestBrowserActionForSession(session, sessionId, action, payload);
         return {
+            requestHumanTakeover: () => call("requestTakeover", {}),
             snapshot: () => call("snapshot", {}),
             click: (ref) => call("click", { ref }),
             type: (ref, text) => call("type", { ref, text }),

package/dist/protocol/types.d.ts

@@ -342,6 +342,20 @@ export interface QueryParams {
     start?: unknown;
     /** Used by archive_range: half-open message-index window end (exclusive). */
     end?: unknown;
+    /**
+     * Used by archive_range (optional) and archive_marker (required): the
+     * clientMessageId the archived/marked span ends at. archive_range only
+     * persists a boundary when this anchor is supplied and resolves to a live
+     * message; without it, archive_range behaves exactly as before (in-memory
+     * compaction only, no persisted range_archive event).
+     */
+    toClientMessageId?: string;
+    /** Used by archive_range / archive_marker: optional start-of-span anchor. */
+    fromClientMessageId?: string;
+    /** Used by archive_range / archive_marker: optional idempotency key. */
+    segmentId?: string;
+    /** Used by archive_marker: the summary text to persist without a model call. */
+    summary?: string;
 }
 export interface QueryResult {
     type: string;

package/dist/session/memory.d.ts

@@ -233,6 +233,16 @@ export declare class MemoryManager {
         baseDir?: string;
         maxAgeDays?: number;
         now?: number;
+        /**
+         * Trim the global layer to what is relevant to this run's project:
+         * project-type and dream-scope records are per-project experience, so
+         * they are kept only when their origin metadata ties them to
+         * `projectDir`. General knowledge (user/feedback/reference in user
+         * scope) always stays; the project layer is untouched because it is
+         * already this project's own store. Set by behavior profiles whose runs
+         * never work inside other repos (e.g. a manager/dispatcher session).
+         */
+        currentProjectOnly?: boolean;
     }): string;
     /**
      * Load every entry belonging to the given scope, without changing the

package/dist/session/memory.js

@@ -651,7 +651,13 @@ export class MemoryManager {
         const profile = opts.profileDir ? new MemoryManager({ baseDir: opts.profileDir }) : null;
         const pinnedFirst = (a, b) => Number(b.pinned ?? false) - Number(a.pinned ?? false);
         const collect = (mm) => filterByAge([...mm.loadScope("user"), ...mm.loadScope("dream")], opts.maxAgeDays, opts.now).sort(pinnedFirst);
-        const globalEntries = collect(global);
+        let globalEntries = collect(global);
+        if (opts.currentProjectOnly) {
+            const tiedToProject = (e) => opts.projectDir !== undefined &&
+                (e.originProject === opts.projectDir ||
+                    (e.originProjects?.includes(opts.projectDir) ?? false));
+            globalEntries = globalEntries.filter((e) => (e.type !== "project" && e.scope !== "dream") || tiedToProject(e));
+        }
         const profileEntries = profile ? collect(profile) : [];
         const projectEntries = project ? collect(project) : [];
         if (globalEntries.length === 0 && profileEntries.length === 0 && projectEntries.length === 0) {

package/dist/session/session-manager.js

@@ -154,6 +154,7 @@ const FORK_COPY_EVENT_TYPES = new Set([
     "tool_result",
     "summary",
     "context_transfer",
+    "range_archive",
     "content_replace",
     "subagent",
     "external_file_changes",

package/dist/session/transcript.d.ts

@@ -106,12 +106,48 @@ export declare class Transcript {
      */
     appendTurnStopped(): TranscriptEvent | undefined;
     appendSummary(summary: string, metadata: SummaryAppendMetadata): TranscriptEvent;
+    /**
+     * Persist a range-archival boundary. Span is [fromClientMessageId,
+     * toClientMessageId) over message events; an absent from means "from the
+     * beginning". Idempotent on segmentId so a crash-replayed closure cannot
+     * double-archive.
+     */
+    appendRangeArchive(data: {
+        summary: string;
+        toClientMessageId: string;
+        fromClientMessageId?: string;
+        segmentId?: string;
+    }): TranscriptEvent | undefined;
     appendError(error: string, details?: Record<string, unknown>): TranscriptEvent;
     /**
      * Derive Message[] from transcript events for sending to the LLM.
      * This is the critical boundary: the LLM never sees the event log directly.
      */
     toMessages(): Message[];
+    /**
+     * Marker-aware replay that ALSO reports, for every emitted message event
+     * carrying a clientMessageId, the LIVE index (its position in the returned
+     * messages array) of its FIRST emission. This is how the engine resolves an
+     * anchored archival window: raw transcript indices grow forever and go stale
+     * the moment a range_archive marker trims the replay, so any caller-held
+     * index range is meaningless — only client-message-id anchors resolved over
+     * THIS replay identify the right span.
+     *
+     * Contract details:
+     * - Messages dropped inside an archived span get NO index entry — they are
+     *   not in the live list, so a window anchored on them cannot be built
+     *   (the engine fails open in that case).
+     * - Only the FIRST emission of a duplicated clientMessageId is recorded
+     *   (duplicates replay as plain messages per the one-shot span rule; the
+     *   first index is the meaningful one).
+     * - The clientMessageId is deliberately NOT attached to the Message objects
+     *   themselves: Message[] is exactly what gets serialized into LLM request
+     *   payloads, and transport metadata must not leak into them.
+     */
+    toMessagesWithIndex(): {
+        messages: Message[];
+        liveIndexByClientMessageId: Map<string, number>;
+    };
     getEvents(type?: TranscriptEventType): TranscriptEvent[];
     get turnNumber(): number;
     get eventCount(): number;

package/dist/session/transcript.js

@@ -12,6 +12,7 @@ const CONTEXT_EVENT_TYPES = new Set([
     "tool_result",
     "summary",
     "context_transfer",
+    "range_archive",
 ]);
 const INTERRUPTED_TOOL_RESULT_ERROR = "[Tool result missing due to interrupted session]";
 function isSyntheticInterruptedToolResult(event) {
@@ -212,6 +213,19 @@ export class Transcript {
             },
         });
     }
+    /**
+     * Persist a range-archival boundary. Span is [fromClientMessageId,
+     * toClientMessageId) over message events; an absent from means "from the
+     * beginning". Idempotent on segmentId so a crash-replayed closure cannot
+     * double-archive.
+     */
+    appendRangeArchive(data) {
+        if (data.segmentId &&
+            this.events.some((e) => e.type === "range_archive" && e.data.segmentId === data.segmentId)) {
+            return undefined;
+        }
+        return this.append("range_archive", { ...data });
+    }
     appendError(error, details) {
         return this.append("error", { error, ...details });
     }
@@ -220,12 +234,128 @@ export class Transcript {
      * This is the critical boundary: the LLM never sees the event log directly.
      */
     toMessages() {
+        return this.toMessagesWithIndex().messages;
+    }
+    /**
+     * Marker-aware replay that ALSO reports, for every emitted message event
+     * carrying a clientMessageId, the LIVE index (its position in the returned
+     * messages array) of its FIRST emission. This is how the engine resolves an
+     * anchored archival window: raw transcript indices grow forever and go stale
+     * the moment a range_archive marker trims the replay, so any caller-held
+     * index range is meaningless — only client-message-id anchors resolved over
+     * THIS replay identify the right span.
+     *
+     * Contract details:
+     * - Messages dropped inside an archived span get NO index entry — they are
+     *   not in the live list, so a window anchored on them cannot be built
+     *   (the engine fails open in that case).
+     * - Only the FIRST emission of a duplicated clientMessageId is recorded
+     *   (duplicates replay as plain messages per the one-shot span rule; the
+     *   first index is the meaningful one).
+     * - The clientMessageId is deliberately NOT attached to the Message objects
+     *   themselves: Message[] is exactly what gets serialized into LLM request
+     *   payloads, and transport metadata must not leak into them.
+     */
+    toMessagesWithIndex() {
         const messages = [];
+        const liveIndexByClientMessageId = new Map();
         const selectedToolResults = preferredToolResults(this.events);
+        const hasRangeArchive = this.events.some((e) => e.type === "range_archive");
+        const spansByFromId = new Map();
+        let openingSpan;
+        if (hasRangeArchive) {
+            // First-occurrence event index per client message id, so a marker whose
+            // `to` does not come strictly after its `from` (out of order, or a
+            // degenerate from === to) can be rejected. Without this check the span
+            // opens at `from` but its close condition (`to`) was already passed
+            // 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()) {
+                if (event.type === "message" && typeof event.data.clientMessageId === "string") {
+                    if (!firstIndexByClientId.has(event.data.clientMessageId)) {
+                        firstIndexByClientId.set(event.data.clientMessageId, index);
+                    }
+                }
+            }
+            const presentClientIds = new Set(firstIndexByClientId.keys());
+            for (const event of this.events) {
+                if (event.type !== "range_archive")
+                    continue;
+                const { summary, toClientMessageId, fromClientMessageId } = event.data;
+                if (typeof summary !== "string" || !presentClientIds.has(toClientMessageId))
+                    continue;
+                if (fromClientMessageId === undefined) {
+                    // Multiple from-less markers compete for this single opening-span
+                    // slot; the LAST one wins (matching spansByFromId's Map.set
+                    // semantics below). Last-wins is CORRECT by construction, not
+                    // merely a tiebreak: the engine resolves a from-less archival
+                    // window as [0, to) over the LIVE replay, so the window that
+                    // produced a LATER from-less marker began with the EARLIER
+                    // marker's replayed summary message, and summarizeRange merge-fed
+                    // that prior summary (extractAnchoredSummary) into the new one.
+                    // The later summary therefore already contains the earlier one's
+                    // content — dropping the earlier marker here loses nothing. (And
+                    // in production from-less windows only advance: each new marker
+                    // ends at a later boundary, so the surviving span is the widest.)
+                    openingSpan = { summary, toClientMessageId };
+                }
+                else if (presentClientIds.has(fromClientMessageId)) {
+                    const fromIndex = firstIndexByClientId.get(fromClientMessageId);
+                    const toIndex = firstIndexByClientId.get(toClientMessageId);
+                    if (toIndex <= fromIndex)
+                        continue; // out of order or degenerate: fail open
+                    spansByFromId.set(fromClientMessageId, { summary, toClientMessageId });
+                }
+            }
+        }
+        let activeSpan = null;
+        if (openingSpan) {
+            activeSpan = openingSpan;
+            messages.push({ role: "user", content: openingSpan.summary });
+        }
+        // tool_use ids actually emitted into assistant message content blocks so
+        // far. A tool_result whose tool_use_id isn't in this set — e.g. because
+        // its opening tool_use fell inside an archived span while the (later,
+        // 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) {
+            // 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") {
+                const clientMessageId = typeof event.data.clientMessageId === "string" ? event.data.clientMessageId : undefined;
+                if (activeSpan && clientMessageId === activeSpan.toClientMessageId) {
+                    activeSpan = null;
+                }
+                if (!activeSpan && clientMessageId && spansByFromId.has(clientMessageId)) {
+                    activeSpan = spansByFromId.get(clientMessageId);
+                    // One-shot: a duplicate `from` message (e.g. from a torn JSONL
+                    // reload) must not reopen this span a second time — it would have
+                    // no more `to` ahead of it and swallow the rest of the transcript.
+                    spansByFromId.delete(clientMessageId);
+                    messages.push({ role: "user", content: activeSpan.summary });
+                }
+            }
+            if (activeSpan)
+                continue; // archived span: drop every context event inside
             switch (event.type) {
                 case "message": {
-                    const { role, content } = event.data;
+                    const { role, content, clientMessageId } = event.data;
+                    // Record the live index of this message's FIRST emission before
+                    // pushing it (the index it is about to occupy). Dropped-in-span
+                    // messages never reach this point, so they get no entry.
+                    if (typeof clientMessageId === "string" &&
+                        !liveIndexByClientMessageId.has(clientMessageId)) {
+                        liveIndexByClientMessageId.set(clientMessageId, messages.length);
+                    }
+                    if (role === "assistant" && Array.isArray(content)) {
+                        for (const block of content) {
+                            if (block.type === "tool_use" && typeof block.id === "string") {
+                                emittedToolUseIds.add(block.id);
+                            }
+                        }
+                    }
                     messages.push({ role: role, content });
                     break;
                 }
@@ -237,7 +367,8 @@ export class Transcript {
                 case "tool_result": {
                     const eventToolCallId = event.data.toolCallId;
                     if (typeof eventToolCallId !== "string" ||
-                        selectedToolResults.get(eventToolCallId) !== event) {
+                        selectedToolResults.get(eventToolCallId) !== event ||
+                        !emittedToolUseIds.has(eventToolCallId)) {
                         break;
                     }
                     const { toolCallId, result, error, contentBlocks } = event.data;
@@ -280,10 +411,12 @@ export class Transcript {
                     break;
                 }
                 // turn_boundary, run_result, session_meta, file_history, plan_operation, error
-                // are not included in LLM messages
+                // are not included in LLM messages. range_archive is handled entirely
+                // by the pre-pass above (it emits the summary at span entry and drops
+                // events inside the span); it never falls through to this switch.
             }
         }
-        return messages;
+        return { messages, liveIndexByClientMessageId };
     }
     getEvents(type) {
         if (!type)
@@ -448,6 +581,18 @@ export class Transcript {
                     });
                     break;
                 }
+                case "range_archive": {
+                    // A hand-picked context range is an explicit user selection: inject
+                    // the archive summary as context but do NOT replace/drop the
+                    // messages inside its span the way toMessages() does — the caller
+                    // asked for exactly this range and expects to see it in full.
+                    const { summary } = event.data;
+                    messages.push({
+                        role: "user",
+                        content: `<system-reminder>Archived summary for part of this range:\n${summary}</system-reminder>`,
+                    });
+                    break;
+                }
             }
         }
         return messages;

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

@@ -145,6 +145,9 @@ export interface BrowserImageData {
     detail?: string;
 }
 export interface BrowserBridge {
+    /** Reveal the exact task-owned browser target so the user can complete a
+     * login, 2FA, CAPTCHA, or another interaction that requires human control. */
+    requestHumanTakeover?(): Promise<BrowserResult>;
     snapshot(): Promise<BrowserSnapshot>;
     click(ref: string): Promise<BrowserResult>;
     type(ref: string, text: string): Promise<BrowserResult>;

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

@@ -209,6 +209,9 @@ export const browserActToolDef = {
         "- 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" +
+        "- request_takeover: reveal the exact task-owned Browser Runtime page so the " +
+        "user can see it and complete login, 2FA, CAPTCHA, or another required manual step. " +
+        "Use only when the user asks to see the page or human interaction is required.\n" +
         "- list_tabs: list open browser tabs (tabId, url, title, which is active).\n" +
         "- switch_tab {tabId}: make another tab the active one that actions drive.\n" +
         "Pass tabId on any action to target a specific tab (switches to it first). " +
@@ -226,6 +229,7 @@ export const browserActToolDef = {
                     "hover",
                     "scroll",
                     "wait",
+                    "request_takeover",
                     "list_tabs",
                     "switch_tab",
                 ],
@@ -260,6 +264,15 @@ export async function browserActTool(args, ctx) {
             return `Error: could not switch to tab ${tabId} — ${sw.detail ?? "not found"}`;
     }
     switch (action) {
+        case "request_takeover": {
+            if (!b.requestHumanTakeover) {
+                return "Error: this Browser Runtime cannot reveal its page for user takeover";
+            }
+            const r = await b.requestHumanTakeover();
+            return r.ok
+                ? `Browser Runtime is visible for user takeover${r.detail ? ` — ${r.detail}` : ""}`
+                : `Error: ${r.detail ?? "could not reveal Browser Runtime"}`;
+        }
         case "list_tabs": {
             const tabs = await b.listTabs();
             if (tabs.length === 0)