@cjhyy/code-shell-core 0.8.5 → 0.8.7

package/dist/automation/scheduler.d.ts

@@ -62,11 +62,15 @@ export interface CronJob {
  * job_error carries the message `fire()` would otherwise swallow.
  */
 export interface CronJobLifecycleEvent {
-    type: "job_start" | "job_end" | "job_stopped" | "job_cancelled" | "job_error";
+    type: "job_start" | "job_end" | "job_stopped" | "job_cancelled" | "job_error" | "job_missed";
     job: CronJob;
     durationMs?: number;
     reason?: string;
     error?: string;
+    /** Planned wall-clock instant that was skipped after the host woke too late. */
+    scheduledFor?: number;
+    /** Time the scheduler observed the skipped occurrence. */
+    observedAt?: number;
 }
 /** Optional semantic outcome returned by an executor after a non-throwing run. */
 export interface CronExecutionOutcome {
@@ -128,10 +132,10 @@ export declare class CronScheduler {
     setStore(store: CronStore): void;
     setExecutor(fn: (job: CronJob, signal: AbortSignal) => Promise<void | CronExecutionOutcome>): void;
     /**
-     * Observe job execution lifecycle
-     * (job_start → job_end | job_stopped | job_cancelled | job_error). Hosts
-     * wire this to their notification surface so scheduled runs — especially
-     * failures, which `fire()` otherwise swallows — are no longer silent.
+     * Observe job execution lifecycle. A real execution emits job_start followed
+     * by one terminal event; a sleep/wake skip emits job_missed without pretending
+     * the job started. Hosts wire this to their notification surface so failures
+     * and intentionally skipped occurrences are no longer silent.
      * Listener errors are swallowed; observation never affects scheduling.
      */
     setJobEventListener(listener: ((event: CronJobLifecycleEvent) => void) | undefined): void;

package/dist/automation/scheduler.js

@@ -88,10 +88,10 @@ export class CronScheduler {
         this.onExecute = fn;
     }
     /**
-     * Observe job execution lifecycle
-     * (job_start → job_end | job_stopped | job_cancelled | job_error). Hosts
-     * wire this to their notification surface so scheduled runs — especially
-     * failures, which `fire()` otherwise swallows — are no longer silent.
+     * Observe job execution lifecycle. A real execution emits job_start followed
+     * by one terminal event; a sleep/wake skip emits job_missed without pretending
+     * the job started. Hosts wire this to their notification surface so failures
+     * and intentionally skipped occurrences are no longer silent.
      * Listener errors are swallowed; observation never affects scheduling.
      */
     setJobEventListener(listener) {
@@ -167,6 +167,14 @@ export class CronScheduler {
             if (Number.isFinite(n) && n > maxId)
                 maxId = n;
             if (!prev) {
+                const observedAt = Date.now();
+                const missedWhileStopped = arm &&
+                    this.executionEnabled &&
+                    job.enabled &&
+                    typeof job.nextRun === "number" &&
+                    isCronMisfire(job.nextRun, observedAt)
+                    ? job.nextRun
+                    : undefined;
                 this.jobs.set(job.id, job);
                 if (arm && job.enabled) {
                     this.arm(job);
@@ -174,6 +182,15 @@ export class CronScheduler {
                 else {
                     this.refreshNextRunForDisplay(job);
                 }
+                if (missedWhileStopped !== undefined) {
+                    this.persistRunStats(job);
+                    this.emitJobEvent({
+                        type: "job_missed",
+                        job,
+                        scheduledFor: missedWhileStopped,
+                        observedAt,
+                    });
+                }
                 continue;
             }
             const definitionChanged = this.jobDefinitionChanged(prev, job);
@@ -600,8 +617,11 @@ export class CronScheduler {
             // Interval jobs get the same misfire semantics cron already had: if we
             // wake far PAST the target (host slept through it), skip this occurrence
             // and re-arm on the next absolute slot instead of firing late.
-            if (isCronMisfire(scheduledFor, Date.now())) {
+            const observedAt = Date.now();
+            if (isCronMisfire(scheduledFor, observedAt)) {
                 rearm();
+                this.persistRunStats(job);
+                this.emitJobEvent({ type: "job_missed", job, scheduledFor, observedAt });
                 return;
             }
             void this.fire(job, rearm).then((ran) => {
@@ -636,9 +656,12 @@ export class CronScheduler {
             // resume). If we wake too far PAST the scheduled instant, this is a
             // misfire: skip running and re-arm to the next correct occurrence rather
             // than running at the wrong time.
-            if (isCronMisfire(scheduledFor, Date.now())) {
+            const observedAt = Date.now();
+            if (isCronMisfire(scheduledFor, observedAt)) {
                 if (job.enabled)
                     this.armCron(job);
+                this.persistRunStats(job);
+                this.emitJobEvent({ type: "job_missed", job, scheduledFor, observedAt });
                 return;
             }
             const rearm = () => {

package/dist/engine/engine.js

@@ -1956,7 +1956,11 @@ export class Engine {
             disabledPlugins,
             skillAllowlist: this.config.skillAllowlist,
             memoriesMaxAgeDays: this.readMemoriesConfig()?.maxAge,
-            goalToolState: { hasGoal: hasRunnableGoal },
+            goalToolState: !profile?.allowedToolNames ||
+                profile.allowedToolNames.has("complete_goal") ||
+                profile.allowedToolNames.has("cancel_goal")
+                ? { hasGoal: hasRunnableGoal }
+                : undefined,
             capabilityPromptSections: this.capabilityPromptSections,
             dynamicContextProviders: this.capabilityDynamicContextProviders,
             getSettingsManager: () => this.getSettingsManager(),

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export declare const VERSION = "0.8.5";
+export declare const VERSION = "0.8.7";
 export type { Message, ContentBlock, ToolDefinition, ToolCall, ToolResult, RegisteredTool, TranscriptEvent, TranscriptEventType, SessionState, SessionKind, SessionWorkspace, SessionForkLineage, ContextUsageAnchor, SessionStatus, TokenUsage, CompiledInput, PermissionDecision, PermissionMode, PermissionRule, TurnPhase, TurnResult, TerminalReason, TurnCompletionKind, StreamEvent, StreamCallback, LLMConfig, ClientDefaults, LLMResponse, Settings, MCPServerConfig, } from "./types.js";
 export type { GoalConfig, GoalLifecycleConfig, GoalLifecyclePhase, GoalLifecycleTerminalReason, GoalLifecycleV1, } from "./goal/lifecycle.js";
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * Public API exports.
  */
-export const VERSION = "0.8.5";
+export const VERSION = "0.8.7";
 // ─── Exceptions ──────────────────────────────────────────────────
 export { FrameworkError, LLMError, LLMRateLimitError, ContextLimitError, ToolError, ToolNotFoundError, ToolExecutionError, ToolTimeoutError, PermissionDeniedError, SessionError, TranscriptError, ConfigError, SandboxUnavailableError, } from "./exceptions.js";
 // ─── Engine (primary API) ────────────────────────────────────────

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", "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", "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" | "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" | "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", "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" | "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" | "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" | "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" | "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" | "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" | "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,8 @@ export const PANEL_APP_PERMISSIONS = [
     "workspace.read",
     "workspace.write",
     "notifications.send",
+    "credentials.cookies",
+    "automations.manage",
 ];
 export const PANEL_APP_ICONS = [
     "panel",
@@ -136,7 +138,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
@@ -186,4 +188,13 @@ export const PanelAppManifest = z
             message: "workspace.read and workspace.write 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.js

@@ -134,8 +134,8 @@ export class PromptComposer {
         if (!this.options.goalToolState)
             return "";
         return this.options.goalToolState.hasGoal
-            ? "当前存在 active goal。只有在目标完全完成时才可调用 complete_goal；只有用户明确要求取消/停止/放弃该目标时才可调用 cancel_goal。"
-            : "当前没有 active goal。不要调用 complete_goal/cancel_goal；如果误调用，系统会拒绝。";
+            ? "Goal 工具状态：本会话存在一个持久 Goal。只有在该 Goal 完全完成时才可调用 complete_goal；只有用户明确要求取消/停止/放弃该 Goal 时才可调用 cancel_goal。此状态不代表后台任务或其他 Session 的运行状态，不要把它改写成系统是否空闲。"
+            : "Goal 工具状态：本会话没有持久 Goal，因此不要调用 complete_goal/cancel_goal；如果误调用，系统会拒绝。这只描述 Goal 工具的可用状态，不代表没有后台任务、没有运行中的 Session 或系统正在待命，也不要向用户复述为任务状态。";
     }
     invalidateCache(sectionName) {
         this.sectionCache.invalidate(sectionName);

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

@@ -2790,6 +2790,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/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)

package/dist/tool-system/path-policy.js

@@ -432,9 +432,10 @@ function isSkillTreeResource(resolved, skillsRoot) {
  *
  * Keep the exception narrow:
  *   - read-only (the caller checks the operation);
- *   - user Skills, or an installed plugin recorded in the V2 registry;
+ *   - user Skills, an installed plugin recorded in the V2 registry, or a
+ *     declared Skill in the installed Panel App registry;
  *   - plugin installs must realpath beneath the managed plugin cache;
- *   - the target must remain inside a directory containing a real SKILL.md.
+ *   - the target must remain inside the registered Skill directory.
  */
 function isRegisteredSkillResourceRead(resolved) {
     let codeShellRoot;
@@ -448,6 +449,8 @@ function isRegisteredSkillResourceRead(resolved) {
         return false;
     if (isSkillTreeResource(resolved, join(codeShellRoot, "skills")))
         return true;
+    if (isInstalledPanelAppSkillResourceRead(resolved, codeShellRoot))
+        return true;
     let cacheRoot;
     try {
         cacheRoot = realpathSync(join(codeShellRoot, "plugins", "cache"));
@@ -475,6 +478,84 @@ function isRegisteredSkillResourceRead(resolved) {
     }
     return false;
 }
+/**
+ * Panel App Skills live under the otherwise-sensitive
+ * `~/.code-shell/panel-apps` tree. Installation already reviews and copies the
+ * package, and the Skill scanner exposes only entries declared by the app
+ * manifest. Mirror that exact boundary here so reading a Skill reference does
+ * not trigger a second approval prompt.
+ *
+ * Registry, app root, manifest, declared SKILL.md and target are all
+ * realpathed and containment-checked. This deliberately does not trust an
+ * undeclared Skill directory or a symlink escaping the installed app.
+ */
+function isInstalledPanelAppSkillResourceRead(resolved, codeShellRoot) {
+    let appsRoot;
+    let registryPath;
+    try {
+        appsRoot = realpathSync(join(codeShellRoot, "panel-apps"));
+        if (!isInsideDir(appsRoot, codeShellRoot))
+            return false;
+        registryPath = realpathSync(join(appsRoot, "installed.json"));
+        if (!isInsideDir(registryPath, appsRoot))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    let registry;
+    try {
+        registry = JSON.parse(readFileSync(registryPath, "utf-8"));
+    }
+    catch {
+        return false;
+    }
+    if (registry.version !== 1 || !Array.isArray(registry.apps))
+        return false;
+    for (const rawEntry of registry.apps) {
+        if (!rawEntry || typeof rawEntry !== "object")
+            continue;
+        const id = rawEntry.id;
+        if (typeof id !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(id))
+            continue;
+        try {
+            const appRoot = realpathSync(join(appsRoot, id));
+            if (appRoot === appsRoot || !isInsideDir(appRoot, appsRoot))
+                continue;
+            const manifestPath = realpathSync(join(appRoot, ".codeshell-panel", "panel.json"));
+            if (!isInsideDir(manifestPath, appRoot) || !statSync(manifestPath).isFile())
+                continue;
+            const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+            if (manifest.schemaVersion !== 2 ||
+                manifest.id !== id ||
+                !Array.isArray(manifest.agent?.skills)) {
+                continue;
+            }
+            for (const skillEntry of manifest.agent.skills) {
+                if (typeof skillEntry !== "string")
+                    continue;
+                const segments = skillEntry.split("/");
+                if (segments.length !== 4 ||
+                    segments[0] !== "agent" ||
+                    segments[1] !== "skills" ||
+                    !/^[a-z][a-z0-9-]{0,63}$/.test(segments[2] ?? "") ||
+                    segments[3] !== "SKILL.md") {
+                    continue;
+                }
+                const skillManifest = realpathSync(join(appRoot, ...segments));
+                if (!isInsideDir(skillManifest, appRoot) || !statSync(skillManifest).isFile())
+                    continue;
+                const skillRoot = dirname(skillManifest);
+                if (isInsideDir(resolved, skillRoot))
+                    return true;
+            }
+        }
+        catch {
+            // A stale, malformed, or tampered Panel App entry grants no read access.
+        }
+    }
+    return false;
+}
 /**
  * Returns the matching sensitive-dir entry (with the user's home prefix) if
  * `resolved` lives underneath any sensitive directory, else undefined.
@@ -564,9 +645,7 @@ export function classifyPath(rawPath, opts) {
     // files through the ordinary Read tool as well. A credential-shaped basename
     // (.env, token.txt, key files, ...) deliberately keeps the sensitive-file
     // gate even inside a Skill tree.
-    if (opts.operation === "read" &&
-        !sensitiveFile &&
-        isRegisteredSkillResourceRead(resolved)) {
+    if (opts.operation === "read" && !sensitiveFile && isRegisteredSkillResourceRead(resolved)) {
         return {
             decision: "allow",
             reason: "registered Skill resource read",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",