chatccc 0.2.187 → 0.2.188

package/src/__tests__/orchestrator.test.ts

@@ -77,10 +77,11 @@ import {
   _setAdapterForToolForTest,
   _setSessionRegistryFileForTest,
   _setSessionToolsFileForTest,
-  loadSessionRegistryForBinding,
-  recordSessionRegistry,
-  resetState,
-} from "../session.ts";
+  loadSessionRegistryForBinding,
+  recordSessionRegistry,
+  resetState,
+  sessionInfoMap,
+} from "../session.ts";
 import { activePrompts, resetBindingState } from "../session-chat-binding.ts";
 import { ABD_APPEND_PROMPT } from "../shared-prefix.ts";
 
@@ -362,11 +363,11 @@ describe("handleCommand WeChat processing ack", () => {
     expect(userText).not.toContain("/abd");
   });
 
-  it("cleans stale Feishu p2p binding but keeps valid commands from auto-creating a group", async () => {
-    const platform = mockPlatform("feishu");
-    await recordSessionRegistry({
-      chatId: "feishu-p2p",
-      sessionId: "stale-sid",
+  it("cleans stale Feishu p2p binding but keeps valid commands from auto-creating a group", async () => {
+    const platform = mockPlatform("feishu");
+    await recordSessionRegistry({
+      chatId: "feishu-p2p",
+      sessionId: "stale-sid",
       tool: "claude",
       chatName: "旧私聊绑定",
       running: false,
@@ -376,13 +377,109 @@ describe("handleCommand WeChat processing ack", () => {
 
     expect(platform.createGroup).not.toHaveBeenCalled();
     expect(platform.sendRawCard).toHaveBeenCalled();
-    const registry = await loadSessionRegistryForBinding();
-    expect(registry["feishu-p2p"]).toBeUndefined();
-  });
-
-  it("handles /usage without creating a new Feishu group", async () => {
-    const platform = mockPlatform("feishu");
-    mockGetCodexUsageSummary.mockResolvedValue({
+    const registry = await loadSessionRegistryForBinding();
+    expect(registry["feishu-p2p"]).toBeUndefined();
+  });
+
+  it("shows Claude effort switch card in an active Feishu session", async () => {
+    const platform = mockPlatform("feishu");
+    vi.mocked(platform.getChatInfo).mockResolvedValue({ name: "claude-session", description: "Claude Session: sid-claude-effort" });
+    vi.mocked(platform.extractSessionInfo).mockReturnValue({ sessionId: "sid-claude-effort", tool: "claude" });
+    await recordSessionRegistry({
+      chatId: "feishu-chat",
+      sessionId: "sid-claude-effort",
+      tool: "claude",
+      chatName: "claude-session",
+      running: false,
+    });
+    sessionInfoMap.set("feishu-chat", {
+      sessionId: "sid-claude-effort",
+      tool: "claude",
+      turnCount: 0,
+      lastContextTokens: 0,
+      startTime: Date.now(),
+    });
+
+    await handleCommand(platform, "/effort", "feishu-chat", "ou-user", Date.now(), "group");
+
+    expect(platform.sendRawCard).toHaveBeenCalled();
+    const card = JSON.parse(vi.mocked(platform.sendRawCard).mock.calls[0][1]);
+    const raw = JSON.stringify(card);
+    expect(raw).toContain("/effort low");
+    expect(raw).toContain("/effort xhigh");
+    expect(raw).toContain("/effort max");
+  });
+
+  it("switches Codex effort for the current session and reflects it in /state", async () => {
+    const platform = mockPlatform("feishu");
+    vi.mocked(platform.getChatInfo).mockResolvedValue({ name: "codex-session", description: "Codex Session: sid-codex-effort" });
+    vi.mocked(platform.extractSessionInfo).mockReturnValue({ sessionId: "sid-codex-effort", tool: "codex" });
+    _setAdapterForToolForTest("codex", mockAdapter("sid-codex-effort"));
+    await recordSessionRegistry({
+      chatId: "codex-chat",
+      sessionId: "sid-codex-effort",
+      tool: "codex",
+      chatName: "codex-session",
+      running: false,
+    });
+    sessionInfoMap.set("codex-chat", {
+      sessionId: "sid-codex-effort",
+      tool: "codex",
+      turnCount: 0,
+      lastContextTokens: 0,
+      startTime: Date.now(),
+    });
+
+    await handleCommand(platform, "/effort xhigh", "codex-chat", "ou-user", Date.now(), "group");
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "codex-chat",
+      "Effort 切换",
+      expect.stringContaining("xhigh"),
+      "green",
+    );
+
+    vi.mocked(platform.sendCard).mockClear();
+    vi.mocked(platform.sendRawCard).mockClear();
+    await handleCommand(platform, "/state", "codex-chat", "ou-user", Date.now() + 1, "group");
+
+    expect(platform.sendRawCard).toHaveBeenCalled();
+    const card = JSON.parse(vi.mocked(platform.sendRawCard).mock.calls[0][1]);
+    expect(JSON.stringify(card)).toContain("xhigh");
+  });
+
+  it("rejects /effort in Cursor sessions", async () => {
+    const platform = mockPlatform("feishu");
+    vi.mocked(platform.getChatInfo).mockResolvedValue({ name: "cursor-session", description: "Cursor Session: sid-cursor-effort" });
+    vi.mocked(platform.extractSessionInfo).mockReturnValue({ sessionId: "sid-cursor-effort", tool: "cursor" });
+    _setAdapterForToolForTest("cursor", mockAdapter("sid-cursor-effort"));
+    await recordSessionRegistry({
+      chatId: "cursor-chat",
+      sessionId: "sid-cursor-effort",
+      tool: "cursor",
+      chatName: "cursor-session",
+      running: false,
+    });
+    sessionInfoMap.set("cursor-chat", {
+      sessionId: "sid-cursor-effort",
+      tool: "cursor",
+      turnCount: 0,
+      lastContextTokens: 0,
+      startTime: Date.now(),
+    });
+
+    await handleCommand(platform, "/effort high", "cursor-chat", "ou-user", Date.now(), "group");
+
+    expect(platform.sendCard).toHaveBeenCalledWith(
+      "cursor-chat",
+      "Effort 切换",
+      expect.stringContaining("不支持 effort"),
+      "red",
+    );
+  });
+
+  it("handles /usage without creating a new Feishu group", async () => {
+    const platform = mockPlatform("feishu");
+    const usage = {
       fiveHour: { usedPercent: 37, remainingPercent: 63, resetAtEpochSeconds: 1781528212, resetAfterSeconds: 10349 },
       weekly: { usedPercent: 12, remainingPercent: 88, resetAtEpochSeconds: 1781842926, resetAfterSeconds: 325063 },
       rateLimitResetCreditsAvailable: 2,
@@ -390,7 +487,8 @@ describe("handleCommand WeChat processing ack", () => {
         { grantedAt: "2026-06-12T04:01:47.770016Z", expiresAt: "2026-07-12T04:01:47.770016Z" },
         { grantedAt: "2026-06-18T00:44:23.904386Z", expiresAt: "2026-07-18T00:44:23.904386Z" },
       ],
-    });
+    };
+    mockGetCodexUsageSummary.mockResolvedValue(usage);
 
     await handleCommand(platform, "/usage", "feishu-p2p", "ou-user", Date.now(), "p2p");
 
@@ -411,6 +509,7 @@ describe("handleCommand WeChat processing ack", () => {
     expect(card.elements[0].text.content).toContain("[██░░░░░░░░░░░░░░░░░░]");
     expect(card.elements[2].actions[0].text.content).toBe("发起重置");
     expect(card.elements[2].actions[0].value).toEqual({ action: "codex_reset_request", availableCount: 2 });
+    expect(platform.setChatAvatar).toHaveBeenCalledWith("feishu-p2p", "codex", "idle", { codexUsage: usage });
   });
 
   it("adds ChatGPT subscription expiry to Codex /usage when CDP lookup succeeds", async () => {
@@ -445,6 +544,24 @@ describe("handleCommand WeChat processing ack", () => {
     expect(card.elements[0].text.content).toContain("- 自动续费: 否");
   });
 
+  it("shows an actionable ChatGPT subscription failure reason when Chrome CDP is enabled", async () => {
+    const platform = mockPlatform("feishu");
+    mockGetChatGptSubscriptionStatus.mockResolvedValue({
+      ok: false,
+      code: "chatgpt_session_missing",
+      reason: "ChatGPT browser session has no access token.",
+      chromeCdp: { enabled: true, port: 15166, status: "healthy" },
+      chatgpt: { sessionOk: true },
+    });
+
+    await handleCommand(platform, "/usage", "feishu-p2p", "ou-user", Date.now(), "p2p");
+
+    const card = JSON.parse(vi.mocked(platform.sendRawCard).mock.calls[0][1]);
+    expect(card.elements[0].text.content).toContain("**ChatGPT 订阅查询失败:**");
+    expect(card.elements[0].text.content).toContain("请在 15166 端口对应的 Chrome 浏览器中登录 ChatGPT");
+    expect(card.elements[0].text.content).toContain("ChatGPT browser session has no access token.");
+  });
+
   it("handles /usage as Cursor usage in Cursor chats", async () => {
     const platform = mockPlatform("feishu");
     await recordSessionRegistry({
@@ -472,6 +589,37 @@ describe("handleCommand WeChat processing ack", () => {
       expect.stringContaining("Pool remaining: $171417.76"),
       "blue",
     );
+    expect(platform.setChatAvatar).toHaveBeenCalledWith(
+      "cursor-chat",
+      "cursor",
+      "idle",
+      { cursorUsage: expect.objectContaining({ displayMessage: "You've hit your usage limit" }) },
+    );
+  });
+
+  it("keeps the busy avatar status when /usage runs for an active Cursor session", async () => {
+    const platform = mockPlatform("feishu");
+    await recordSessionRegistry({
+      chatId: "cursor-chat",
+      sessionId: "sid-cursor",
+      tool: "cursor",
+      chatName: "cursor-session",
+      running: true,
+    });
+    activePrompts.set("sid-cursor", {
+      controller: new AbortController(),
+      stopped: false,
+      startTime: Date.now(),
+    });
+
+    await handleCommand(platform, "/usage", "cursor-chat", "ou-user", Date.now(), "group");
+
+    expect(platform.setChatAvatar).toHaveBeenCalledWith(
+      "cursor-chat",
+      "cursor",
+      "busy",
+      { cursorUsage: expect.objectContaining({ displayMessage: "You've hit your usage limit" }) },
+    );
   });
 
   it("advertises /usage in new Codex and Cursor session ready messages", async () => {

package/src/__tests__/session.test.ts

@@ -91,11 +91,12 @@ import {
   stopSession,
   startUnifiedDisplayLoop,
   stopUnifiedDisplayLoop,
-  _setProcessAliveForTest,
-  _resetProcessAliveForTest,
-  _setProcessMonitorIntervalForTest,
-  _resetProcessMonitorIntervalForTest,
-} from "../session.ts";
+  _setProcessAliveForTest,
+  _resetProcessAliveForTest,
+  _setProcessMonitorIntervalForTest,
+  _resetProcessMonitorIntervalForTest,
+  setSessionEffortOverride,
+} from "../session.ts";
 import {
   activePrompts,
   bindChatToSession,
@@ -895,8 +896,17 @@ describe("getSessionStatus", () => {
     expect(status!.effort).not.toBeNull();
     // model 必为字符串（留空时显示 '(留空)'，否则为环境变量值）；不应是占位符
     expect(typeof status!.model).toBe("string");
-    expect(status!.model.length).toBeGreaterThan(0);
-  });
+    expect(status!.model.length).toBeGreaterThan(0);
+  });
+
+  it("Codex session status uses the per-session effort override", async () => {
+    mockSessionInfo("chat-codex", { sessionId: "sid-codex-effort", tool: "codex" });
+    setSessionEffortOverride("sid-codex-effort", "xhigh");
+
+    const status = await getSessionStatus("chat-codex");
+
+    expect(status!.effort).toBe("xhigh");
+  });
 
   it("Cursor 会话：effort 恒为 null（卡片渲染时隐藏该行，避免显示无意义的 effort）", async () => {
     mockSessionInfo("chat-cursor", { sessionId: "sid-cur", tool: "cursor" });

package/src/adapters/codex-adapter.ts

@@ -184,12 +184,13 @@ export function normalizeCodexMessage(
 // 子进程辅助函数
 // ---------------------------------------------------------------------------
 
-function spawnCodex(
-  args: string[],
-  cwd?: string,
-  stdinText?: string,
-  modelOverride?: string,
-): ChildProcess {
+function spawnCodex(
+  args: string[],
+  cwd?: string,
+  stdinText?: string,
+  modelOverride?: string,
+  effortOverride?: string,
+): ChildProcess {
   const allArgs = [...args];
   const model = modelOverride ?? resolveCodexModel();
   if (model) {
@@ -197,7 +198,7 @@ function spawnCodex(
     const execIdx = allArgs.indexOf("exec");
     allArgs.splice(execIdx + 1, 0, "-m", model);
   }
-  const effort = resolveCodexEffort();
+  const effort = effortOverride ?? resolveCodexEffort();
   if (effort) {
     allArgs.push("-c", `model_reasoning_effort="${effort}"`);
   }
@@ -258,15 +259,17 @@ async function* readJsonLines(
 // ---------------------------------------------------------------------------
 
 class CodexAdapter implements ToolAdapter {
-  readonly displayName = "Codex";
-  readonly sessionDescPrefix = "Codex Session:";
-  private metaStore: CodexSessionMetaStore;
-  private modelOverride: string | undefined;
-
-  constructor(metaStore: CodexSessionMetaStore, modelOverride?: string) {
-    this.metaStore = metaStore;
-    this.modelOverride = modelOverride;
-  }
+  readonly displayName = "Codex";
+  readonly sessionDescPrefix = "Codex Session:";
+  private metaStore: CodexSessionMetaStore;
+  private modelOverride: string | undefined;
+  private effortOverride: string | undefined;
+
+  constructor(metaStore: CodexSessionMetaStore, modelOverride?: string, effortOverride?: string) {
+    this.metaStore = metaStore;
+    this.modelOverride = modelOverride;
+    this.effortOverride = effortOverride;
+  }
 
   // createSession: 生成 sessionId，记录 cwd，不创建 Codex 线程（延迟到首次 prompt）
   async createSession(cwd: string): Promise<CreateSessionResult> {
@@ -296,7 +299,7 @@ class CodexAdapter implements ToolAdapter {
       ? [...baseArgs, "-C", cwd, "-"]
       : [...baseArgs, "resume", threadId, "-"];
 
-    const proc = spawnCodex(args, cwd, buildCodexPromptText(userText), this.modelOverride);
+    const proc = spawnCodex(args, cwd, buildCodexPromptText(userText), this.modelOverride, this.effortOverride);
     if (proc.pid !== undefined) options?.onProcessStart?.({ pid: proc.pid });
 
     // 关键：spawn 用了 shell:true，proc.pid 指向的是壳进程（cmd.exe / sh）。
@@ -350,7 +353,8 @@ class CodexAdapter implements ToolAdapter {
 export interface CreateCodexAdapterOptions {
   metaStore?: CodexSessionMetaStore;
   /** per-session 模型覆盖（/model 命令）；传了就用，不传走全局 codex.model */
-  model?: string;
+  model?: string;
+  effort?: string;
 }
 
 export function createCodexAdapter(
@@ -358,6 +362,7 @@ export function createCodexAdapter(
 ): ToolAdapter {
   return new CodexAdapter(
     options.metaStore ?? defaultCodexSessionMetaStore,
-    options.model,
-  );
-}
+    options.model,
+    options.effort,
+  );
+}

package/src/builtin/cli.ts

@@ -5,14 +5,11 @@
  *   npx tsx src/builtin/cli.ts
  *   npx tsx src/builtin/cli.ts --model deepseek-chat
  *   npx tsx src/builtin/cli.ts --cwd /path/to/project
- *
- * 环境变量:
- *   DEEPSEEK_API_KEY — DeepSeek API Key（必需）
- *   DEEPSEEK_BASE_URL — API 地址（可选，默认 https://api.deepseek.com/v1）
  */
 
 import * as readline from "node:readline";
 import * as process from "node:process";
+import { config as appConfig } from "../config.ts";
 import { ChatSession, type ChatSessionConfig, type ChatSessionOptions } from "./index.js";
 
 // ---------------------------------------------------------------------------
@@ -55,15 +52,14 @@ function printHelp(): void {
     "用法: npx tsx src/builtin/cli.ts [选项]",
     "",
     "选项:",
-    "  --model <name>   模型名称（默认 deepseek-chat）",
-    "  --base-url <url> API 地址（默认 https://api.deepseek.com/v1）",
-    "  --api-key <key>  API Key（默认读 DEEPSEEK_API_KEY 环境变量）",
+    `  --model <name>   模型名称（覆盖 config.ccc.model，当前默认 ${appConfig.ccc.model}）`,
+    `  --base-url <url> API 地址（覆盖 config.ccc.DEEPSEEK_BASE_URL，当前默认 ${appConfig.ccc.DEEPSEEK_BASE_URL}）`,
+    "  --api-key <key>  API Key（覆盖 config.ccc.DEEPSEEK_API_KEY）",
     "  --cwd <path>     工作目录",
     "  --help, -h       显示帮助",
     "",
-    "环境变量:",
-    "  DEEPSEEK_API_KEY   DeepSeek API Key",
-    "  DEEPSEEK_BASE_URL  API 地址",
+    "默认配置来源:",
+    "  ~/.chatccc/config.json 的 ccc.DEEPSEEK_API_KEY / ccc.DEEPSEEK_BASE_URL / ccc.model",
     "",
   ].join("\n"));
 }
@@ -87,12 +83,8 @@ const C = {
 async function main(): Promise<void> {
   const { config, options } = parseArgs();
 
-  // 环境变量回退
-  if (!config.baseURL) config.baseURL = process.env.DEEPSEEK_BASE_URL;
-  if (!config.apiKey) config.apiKey = process.env.DEEPSEEK_API_KEY;
-
   console.log(`${C.dim}ChatCCC 内置 Agent 原型${C.reset}`);
-  console.log(`${C.dim}模型: ${config.model ?? "deepseek-chat"}${C.reset}`);
+  console.log(`${C.dim}模型: ${config.model ?? appConfig.ccc.model}${C.reset}`);
   if (options.cwd) {
     console.log(`${C.dim}目录: ${options.cwd}${C.reset}`);
   }
@@ -194,4 +186,4 @@ async function main(): Promise<void> {
 main().catch((err) => {
   console.error(`${C.yellow}启动失败: ${(err as Error).message}${C.reset}`);
   process.exit(1);
-});
+});

package/src/builtin/index.ts

@@ -4,8 +4,11 @@
  * ChatSession 是程序化入口，既可以被 CLI 调用，也可以被其他模块（如 ToolAdapter）调用。
  */
 
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { streamText } from "ai";
 
+import { config as appConfig } from "../config.ts";
+
 // ---------------------------------------------------------------------------
 // 系统提示词 — 编译期冻结常量
 // ---------------------------------------------------------------------------
@@ -25,11 +28,11 @@ const SYSTEM_PROMPT = [
 // ---------------------------------------------------------------------------
 
 export interface ChatSessionConfig {
-  /** DeepSeek API 兼容的服务地址，默认 https://api.deepseek.com/v1 */
+  /** DeepSeek API 兼容的服务地址；传入时覆盖 config.ccc.DEEPSEEK_BASE_URL */
   baseURL?: string;
-  /** API Key（优先用 DEEPSEEK_API_KEY 环境变量） */
+  /** API Key；传入时覆盖 config.ccc.DEEPSEEK_API_KEY */
   apiKey?: string;
-  /** 模型名称，默认 deepseek-chat */
+  /** 模型名称；传入时覆盖 config.ccc.model */
   model?: string;
 }
 
@@ -66,21 +69,19 @@ export class ChatSession {
   private messages: ChatMessage[];
 
   constructor(
-    config: ChatSessionConfig = {},
+    overrides: ChatSessionConfig = {},
     options: ChatSessionOptions = {},
   ) {
-    const apiKey = config.apiKey ?? process.env.DEEPSEEK_API_KEY;
+    const apiKey = overrides.apiKey ?? appConfig.ccc.DEEPSEEK_API_KEY;
     if (!apiKey) {
       throw new Error(
-        "DEEPSEEK_API_KEY 未设置。请设置环境变量 DEEPSEEK_API_KEY 或传入 apiKey",
+        "ccc.DEEPSEEK_API_KEY 未设置。请在 config.json 中配置，或通过 --api-key 临时传入",
       );
     }
 
-    const baseURL = config.baseURL ?? "https://api.deepseek.com/v1";
-    const modelId = config.model ?? "deepseek-chat";
+    const baseURL = overrides.baseURL ?? appConfig.ccc.DEEPSEEK_BASE_URL;
+    const modelId = overrides.model ?? appConfig.ccc.model;
 
-    // 动态 import 以支持 ESM 包在 CJS 环境下的加载（tsx 处理）
-    const { createOpenAICompatible } = require("@ai-sdk/openai-compatible");
     const provider = createOpenAICompatible({
       name: "deepseek",
       baseURL,
@@ -164,4 +165,4 @@ export class ChatSession {
     const system = this.messages[0];
     this.messages = [system];
   }
-}
+}

package/src/cards.ts

@@ -498,10 +498,10 @@ export function buildCodexResetConfirmCard(params: {
 
 /** 模型切换卡片（/model 命令，飞书专用，含切换按钮） */
 export function buildModelCard(
-  currentModel: string,
-  models: string[],
-  tool?: string,
-): string {
+  currentModel: string,
+  models: string[],
+  tool?: string,
+): string {
   const toolLabel = tool ? ` (${tool})` : "";
   const currentLine = currentModel
     ? `**当前模型:** \`${currentModel}\``
@@ -535,7 +535,48 @@ export function buildModelCard(
       { tag: "div", text: { tag: "lark_md", content: lines.join("\n") } },
       { tag: "hr" },
       buildButtons(buttons),
-    ],
-  });
-}
+    ],
+  });
+}
+
+export function buildEffortCard(
+  currentEffort: string,
+  efforts: string[],
+  tool?: string,
+): string {
+  const toolLabel = tool ? ` (${tool})` : "";
+  const currentLine = currentEffort
+    ? `**当前 effort:** \`${currentEffort}\``
+    : "**当前 effort:** 未指定";
+
+  const lines: string[] = [currentLine];
+  if (efforts.length > 0) {
+    lines.push("", "**可切换 effort**");
+    for (const effort of efforts) {
+      lines.push(`- \`${effort}\``);
+    }
+    lines.push("", "点击按钮切换 effort，或输入 `/effort clear` 恢复默认");
+  } else {
+    lines.push("", "当前 agent 不支持 effort 切换。");
+  }
+
+  const buttons: ButtonDef[] = [];
+  for (const effort of efforts.slice(0, 20)) {
+    buttons.push({
+      text: `/effort ${effort}`,
+      value: JSON.stringify({ cmd: `/effort ${effort}` }),
+      type: "primary",
+    });
+  }
+
+  return JSON.stringify({
+    config: { wide_screen_mode: true },
+    header: { template: "blue", title: { content: `Effort 切换${toolLabel}`, tag: "plain_text" } },
+    elements: [
+      { tag: "div", text: { tag: "lark_md", content: lines.join("\n") } },
+      { tag: "hr" },
+      buildButtons(buttons),
+    ],
+  });
+}
 

package/src/chrome-devtools-guard.ts

@@ -33,6 +33,18 @@ export interface ChromeCdpEnsureResult {
 
 export type ChromeCdpProbeStatus = "healthy" | "occupied" | "unreachable";
 
+interface ChromeCdpPage {
+  id?: string;
+  type?: string;
+  url?: string;
+}
+
+export interface EnsureChatcccPageResult {
+  ok: boolean;
+  opened: boolean;
+  error?: string;
+}
+
 let guardTimer: ReturnType<typeof setInterval> | null = null;
 let ensureInFlight: Promise<ChromeCdpEnsureResult> | null = null;
 
@@ -81,11 +93,11 @@ export function resolveChromeUserDataDir(port: number, env: NodeJS.ProcessEnv =
   return join(root, `chrome-cdp-${port}`);
 }
 
-async function fetchWithTimeout(url: string, fetchImpl: FetchLike, timeoutMs: number): Promise<Response> {
+async function fetchWithTimeout(url: string, fetchImpl: FetchLike, timeoutMs: number, init: RequestInit = {}): Promise<Response> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
-    return await fetchImpl(url, { signal: controller.signal });
+    return await fetchImpl(url, { ...init, signal: controller.signal });
   } finally {
     clearTimeout(timer);
   }
@@ -163,6 +175,61 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function cdpBaseUrl(port: number): string {
+  return `http://${CDP_HOST}:${port}`;
+}
+
+function isChatcccPageUrl(value: string | undefined, chatcccPort: number): boolean {
+  if (!value) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" &&
+      (url.hostname === "localhost" || url.hostname === CDP_HOST) &&
+      url.port === String(chatcccPort);
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureChatcccPageOpen(
+  cdpPort: number,
+  chatcccPort: number,
+  deps: Pick<ChromeDevtoolsGuardDeps, "fetchImpl"> = {},
+): Promise<EnsureChatcccPageResult> {
+  const normalizedCdpPort = normalizePort(cdpPort);
+  const normalizedChatcccPort = normalizePort(chatcccPort);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+
+  try {
+    const listResponse = await fetchWithTimeout(
+      `${cdpBaseUrl(normalizedCdpPort)}/json/list`,
+      fetchImpl,
+      HEALTH_TIMEOUT_MS,
+    );
+    if (!listResponse.ok) {
+      return { ok: false, opened: false, error: `Cannot list Chrome CDP pages: HTTP ${listResponse.status}` };
+    }
+    const pages = await listResponse.json() as unknown;
+    if (Array.isArray(pages) && pages.some((page: ChromeCdpPage) => isChatcccPageUrl(page?.url, normalizedChatcccPort))) {
+      return { ok: true, opened: false };
+    }
+
+    const targetUrl = `http://localhost:${normalizedChatcccPort}/`;
+    const openResponse = await fetchWithTimeout(
+      `${cdpBaseUrl(normalizedCdpPort)}/json/new?${encodeURIComponent(targetUrl)}`,
+      fetchImpl,
+      HEALTH_TIMEOUT_MS,
+      { method: "PUT" },
+    );
+    if (!openResponse.ok) {
+      return { ok: false, opened: false, error: `Cannot open ${targetUrl}: HTTP ${openResponse.status}` };
+    }
+    return { ok: true, opened: true };
+  } catch (err) {
+    return { ok: false, opened: false, error: (err as Error).message };
+  }
+}
+
 export async function ensureChromeCdpRunning(
   cfg: ChromeDevtoolsConfig = config.chromeDevtools,
   deps: ChromeDevtoolsGuardDeps = {},
@@ -202,6 +269,9 @@ async function runGuardOnce(reason: string, deps: ChromeDevtoolsGuardDeps = {}):
   ensureInFlight = ensureChromeCdpRunning(config.chromeDevtools, deps);
   try {
     const result = await ensureInFlight;
+    const chatcccPage = config.chromeDevtools.enabled && result.ok
+      ? await ensureChatcccPageOpen(result.port, config.port, deps)
+      : null;
     appendStartupTrace("chrome-devtools-guard: ensure result", {
       reason,
       enabled: config.chromeDevtools.enabled,
@@ -209,6 +279,7 @@ async function runGuardOnce(reason: string, deps: ChromeDevtoolsGuardDeps = {}):
       ok: result.ok,
       started: result.started,
       error: result.error,
+      chatcccPage,
     });
     if (!config.chromeDevtools.enabled) return;
     if (result.ok && result.started) {
@@ -216,6 +287,11 @@ async function runGuardOnce(reason: string, deps: ChromeDevtoolsGuardDeps = {}):
     } else if (!result.ok) {
       log(`[${ts()}] [Chrome CDP] Guard failed: ${result.error}`);
     }
+    if (chatcccPage?.opened) {
+      log(`[${ts()}] [Chrome CDP] Opened ChatCCC page http://localhost:${config.port}/`);
+    } else if (chatcccPage && !chatcccPage.ok) {
+      log(`[${ts()}] [Chrome CDP] Failed to ensure ChatCCC page: ${chatcccPage.error}`);
+    }
   } finally {
     ensureInFlight = null;
   }