wtagent 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -1,21 +1,21 @@
 # WTAgent
 
-Turn ChatGPT Web into a local CLI agent.
+Turn GPT Web into a local CLI agent.
 
-把 ChatGPT 网页版变成一个本地 CLI Agent。
+把 GPT 网页聊天变成一个本地 CLI Agent。
 
 [中文](#中文) · [English](#english)
 
 ## 中文
 
-WTAgent 使用你自己的 ChatGPT Pro 网页会话，提供类似 Codex 的本地 CLI Agent 体验。
+WTAgent 把 GPT 网页聊天连接到本地工具，提供类似 Codex 的 CLI Agent 体验。当前首个适配器支持 ChatGPT Web。
 
-ChatGPT Web 负责思考，WTAgent 在本机：
+网页 GPT 负责思考，WTAgent 在本机：
 
 - 读取和修改本地文件
 - 调用本地 Shell，运行构建、测试和开发服务
 
-不需要 OpenAI API Key。WTAgent 使用独立的 Chrome Profile 保存 ChatGPT 登录状态。
+不需要 OpenAI API Key，也不要求 ChatGPT Pro。WTAgent 使用独立的 Chrome Profile 保存你的网页登录状态，并使用该账号在网页上实际可用的模型和额度；如果账号拥有 Pro，它会成为额外优势。
 
 ### 快速开始
 
@@ -40,18 +40,20 @@ wtagent "检查这个项目并修复测试"
 wtagent -C ./my-project "创建一个网站"
 ```
 
-之后直接在终端中继续对话。WTAgent 会把任务交给 ChatGPT Web，并在本地执行文件和 Shell 操作。
+之后直接在终端中继续对话。WTAgent 会把任务交给 GPT Web，并在本地执行文件和 Shell 操作。使用 `↑` / `↓` 浏览本次 CLI 会话的历史输入。
+
+按 `Ctrl+C` 或 `Ctrl+D` 可退出并关闭专用 Chrome。若上一次异常退出留下了 Chrome，WTAgent 会在验证其 CDP 身份后复用并接管它。
 
 ## English
 
-WTAgent turns your own ChatGPT Pro web session into a Codex-like local CLI agent.
+WTAgent connects GPT Web chat to local tools, providing a Codex-like CLI agent experience. The first adapter currently supports ChatGPT Web.
 
-ChatGPT Web handles reasoning. WTAgent runs locally to:
+GPT Web handles reasoning. WTAgent runs locally to:
 
 - Read and edit local files
 - Run shell commands, builds, tests, and development servers
 
-No OpenAI API key is required. WTAgent stores the ChatGPT session in a dedicated Chrome profile.
+No OpenAI API key or ChatGPT Pro subscription is required. WTAgent stores your web login in a dedicated Chrome profile and uses the models and quota actually available to that account. Pro is an optional bonus when the account has it.
 
 ### Quick start
 
@@ -76,7 +78,9 @@ wtagent "inspect this project and fix the tests"
 wtagent -C ./my-project "build a website"
 ```
 
-Continue chatting in the terminal. WTAgent sends tasks to ChatGPT Web and executes file and shell operations locally.
+Continue chatting in the terminal. WTAgent sends tasks to GPT Web and executes file and shell operations locally. Use `↑` / `↓` to browse input history from the current CLI session.
+
+Press `Ctrl+C` or `Ctrl+D` to exit and close the dedicated Chrome. If an abnormal exit leaves Chrome running, WTAgent verifies and adopts that CDP instance on the next start.
 
 ## License
 

package/docs/technical-design.md

@@ -1,4 +1,4 @@
-# WTAgent：ChatGPT Web 本地工具 Agent 技术方案
+# WTAgent：GPT Web 本地工具 Agent 技术方案
 
 ## 1. 结论
 
@@ -6,7 +6,7 @@
 
 - 用户在终端中选择项目目录并输入开发任务。
 - CLI 启动一个独立、可见、持久化 Profile 的 Chrome。
-- 用户首次在该 Chrome 中手动登录自己的 ChatGPT Pro。
+- 用户首次在该 Chrome 中手动登录自己的 ChatGPT Web 账号；Pro 不是前提，只是账号可用时的额外模型与额度。
 - ChatGPT Web 只负责推理；本地 Runtime 负责工具、权限、状态和恢复。
 - 双方通过普通聊天文本中的自定义 XML 交换工具调用和结果。
 - Runtime 循环执行“网页回复 → 解析工具 → 本地执行 → 回填结果”，直到任务完成。
@@ -593,7 +593,7 @@ sessions/<session-id>/
   tool-output.jsonl
 ```
 
-`session.json` 保存项目根目录、ChatGPT 会话 URL、当前 run phase、最近 turn、等待回填的工具结果和副作用恢复日志。它没有不可继续的 `completed task` 状态；`done=true` 只结束当前 run，Session 回到 `idle`。
+`session.json` 保存项目根目录、ChatGPT 会话 URL、最近确认的 assistant message ID、最近确认的实际模式、当前 run phase、最近 turn、等待回填的工具结果和副作用恢复日志。它没有不可继续的 `completed task` 状态；`done=true` 只结束当前 run，Session 回到 `idle`。
 
 `rollout-*.jsonl` 从创建时起直接使用 **Codex rollout 风格**：首行 `session_meta`，后续每行 `{timestamp, type: "response_item", payload}`，payload 采用 OpenAI Responses 形状（`message` / `function_call` / `function_call_output`）。
 
@@ -626,8 +626,11 @@ sessionId + assistantMessageIdentity + normalizedToolCall
 
 ### 9.3 浏览器恢复
 
-- Chrome 仍在：重新连接 Page 并校验会话 URL。
+- Chrome 仍在：根据专用 Profile、PID、CDP 端口和健康检查验证身份，复用浏览器并创建新的 Page。
 - Chrome 崩溃：用相同 Profile 重启并打开会话 URL。
+- 同一 CLI 进程中的 follow-up 保持在当前会话 Page，不重复导航；跨进程恢复需要等待本地记录的最近 assistant message ID 出现在 DOM 后才能发送。
+- 每次发送记录已有消息 ID 和新 user turn，只接受位于该 user turn 之后的新 assistant turn；无法建立可靠消息身份时超时并保存诊断，禁止退化为基于数量或文本变化猜测。
+- 同一 Profile 同时只允许一个 WTAgent CLI Session；启动和接管过程使用 Profile 级互斥锁。
 - 登录失效或出现验证：进入 `AUTH_REQUIRED`/`PAUSED`，让用户接管。
 - 会话页面丢失：从本地记录打开原会话；无法恢复时创建新的本地 Session 和新的网页对话，不向旧 rollout 继续追加。
 
@@ -639,6 +642,8 @@ sessionId + assistantMessageIdentity + normalizedToolCall
 2. 当前可用工具及参数 Schema。
 3. 用户任务、项目根目录语义和执行边界。
 
+同一网页会话中的普通 follow-up 只发送新的用户输入，并在末尾追加短 `<system_reminder>`；不得重复发送完整 `<agent_protocol>`、工具目录或初始任务。只有没有新用户输入的中断恢复流程可以发送完整 resume scaffold。
+
 关键规则：
 
 - 一轮最多一个工具调用。
@@ -686,8 +691,8 @@ Session 界面展示：
 
 用户可随时：
 
-- `Ctrl+C` 第一次请求安全暂停；
-- 再次 `Ctrl+C` 强制终止当前 run；
+- `Ctrl+C` 或 `Ctrl+D` 退出 CLI，并关闭专用 Chrome；
+- 若关闭未完成，保留经过验证的 CDP 状态，下一次启动复用后再次执行关闭；
 - 输入补充指令；
 - 打开浏览器人工接管；
 - 恢复自动化。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtagent",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "Turn your own web AI session into a local tool-using agent.",
   "repository": {
     "type": "git",

package/src/browser/cdp-browser.js

@@ -2,6 +2,16 @@ import net from "node:net";
 import { spawn } from "node:child_process";
 import { chromium } from "playwright-core";
 import { killProcessTree } from "../tools/process-utils.js";
+import {
+  acquireCdpProfileLock,
+  discoverReusableCdpState,
+  fetchCdpVersion,
+  processMatchesCdpState,
+  reapStaleProfileChrome,
+  removeCdpState,
+  saveCdpState,
+  waitForProcessExit,
+} from "./cdp-state.js";
 
 async function reservePort() {
   return await new Promise((resolve, reject) => {
@@ -22,6 +32,47 @@ async function reservePort() {
   });
 }
 
+async function settleWithin(promise, timeoutMs) {
+  let timer;
+  try {
+    await Promise.race([
+      Promise.resolve(promise).catch(() => null),
+      new Promise((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Races a promise against a timeout. On timeout the returned promise rejects
+// with a TIMEOUT-tagged error. Used to bound connectOverCDP + the first CDP
+// round-trip: a Chrome whose profile is locked by a stale instance answers the
+// WS handshake but never finishes protocol init, so an unbounded connect hangs
+// for the full Playwright default (30s) before failing.
+class CdpTimeoutError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CdpTimeoutError";
+    this.code = "CDP_CONNECT_TIMEOUT";
+  }
+}
+
+async function withTimeout(promise, timeoutMs, message) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new CdpTimeoutError(message)), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function waitForCdp({
   endpoint,
   child,
@@ -42,7 +93,7 @@ async function waitForCdp({
       if (response.ok) {
         const version = await response.json();
         if (version.webSocketDebuggerUrl) {
-          return;
+          return version;
         }
       }
     } catch (error) {
@@ -57,21 +108,6 @@ async function waitForCdp({
   );
 }
 
-async function waitForExit(child, timeoutMs) {
-  if (child.exitCode != null || child.signalCode != null) {
-    return true;
-  }
-
-  return await new Promise((resolve) => {
-    const timer = setTimeout(() => resolve(false), timeoutMs);
-    timer.unref?.();
-    child.once("close", () => {
-      clearTimeout(timer);
-      resolve(true);
-    });
-  });
-}
-
 // Sets the OS window state (e.g. "minimized" / "normal") of the window hosting
 // `page` via the CDP Browser domain. On macOS the Chromium launch flags for
 // minimizing (--start-minimized) and off-screen positioning are ignored or
@@ -101,41 +137,140 @@ export async function launchAndConnectCdpChrome({
   profileDir,
   url = "about:blank",
   minimized = false,
-}) {
-  const port = await reservePort();
-  const endpoint = `http://127.0.0.1:${port}`;
-  const child = spawn(
-    executablePath,
-    [
-      `--remote-debugging-port=${port}`,
-      "--remote-debugging-address=127.0.0.1",
-      `--user-data-dir=${profileDir}`,
-      "--profile-directory=Default",
-      "--no-first-run",
-      "--no-default-browser-check",
-      url,
-    ],
-    {
-      detached: process.platform !== "win32",
-      stdio: "ignore",
-      windowsHide: false,
-    },
-  );
+}, {
+  acquireProfileLock = acquireCdpProfileLock,
+  connectOverCDP = (endpoint) => chromium.connectOverCDP(endpoint),
+  discoverReusable = discoverReusableCdpState,
+  fetchVersion = fetchCdpVersion,
+  killTree = killProcessTree,
+  matchesState = processMatchesCdpState,
+  reapStale = reapStaleProfileChrome,
+  removeState = removeCdpState,
+  reserveCdpPort = reservePort,
+  saveState = saveCdpState,
+  spawnChrome = spawn,
+  waitForExit = waitForProcessExit,
+  waitForReady = waitForCdp,
+  connectTimeoutMs = 20_000,
+} = {}) {
+  const releaseProfileLock = await acquireProfileLock(profileDir);
+  let child = null;
+  let state = null;
+  let browser = null;
+  let closePromise = null;
+  let reused = false;
 
-  await new Promise((resolve, reject) => {
-    child.once("spawn", resolve);
-    child.once("error", reject);
-  });
+  async function findReusable() {
+    return await discoverReusable(profileDir, { fetchVersion });
+  }
 
   try {
-    await waitForCdp({ endpoint, child });
-    const browser = await chromium.connectOverCDP(endpoint);
-    const context = browser.contexts()[0];
+    state = await findReusable();
+    if (state) {
+      reused = true;
+    } else {
+      await removeState(profileDir);
+      // A prior instance may have died leaving renderer children (and Chrome's
+      // SingletonLock) still holding this profile. Reap those stale holders
+      // before launching, or the new Chrome hangs during profile init and
+      // connectOverCDP times out.
+      await reapStale(profileDir, { fetchVersion, killTree }).catch(() => null);
+      const port = await reserveCdpPort();
+      const endpoint = `http://127.0.0.1:${port}`;
+      child = spawnChrome(
+        executablePath,
+        [
+          `--remote-debugging-port=${port}`,
+          "--remote-debugging-address=127.0.0.1",
+          `--user-data-dir=${profileDir}`,
+          "--profile-directory=Default",
+          "--no-first-run",
+          "--no-default-browser-check",
+          url,
+        ],
+        {
+          detached: process.platform !== "win32",
+          stdio: "ignore",
+          windowsHide: false,
+        },
+      );
+
+      await new Promise((resolve, reject) => {
+        child.once("spawn", resolve);
+        child.once("error", reject);
+      });
+
+      try {
+        const version = await waitForReady({ endpoint, child });
+        state = await saveState(profileDir, {
+          pid: child.pid,
+          port,
+          endpoint,
+          profileDir,
+          browser: version.Browser ?? null,
+          webSocketDebuggerUrl: version.webSocketDebuggerUrl,
+        });
+      } catch (error) {
+        // Chrome may forward the URL to an existing process using the same
+        // profile and then exit successfully. Re-scan after that handoff and
+        // adopt the verified live CDP instance instead of reporting a false
+        // launch failure.
+        if (child.exitCode === 0 && child.signalCode == null) {
+          state = await findReusable();
+          if (state) {
+            reused = true;
+          }
+        }
+        if (!state) {
+          throw error;
+        }
+      }
+    }
+
+    // Bound the connect + first CDP round-trip. If Chrome's profile is held by
+    // a stale instance, the WS connects but protocol init never completes;
+    // without this guard Playwright hangs ~30s and leaves a dirty CDP state.
+    let context;
+    try {
+      browser = await withTimeout(
+        connectOverCDP(state.endpoint),
+        connectTimeoutMs,
+        `Timed out connecting to Chrome CDP at ${state.endpoint} after ${connectTimeoutMs}ms.`,
+      );
+      // contexts() forces a real protocol round-trip, so it hangs too when the
+      // browser main thread is stuck — keep it inside the timeout budget.
+      const contexts = await withTimeout(
+        Promise.resolve().then(() => browser.contexts()),
+        connectTimeoutMs,
+        `Timed out reading Chrome browser context at ${state.endpoint}.`,
+      );
+      context = contexts[0];
+    } catch (error) {
+      if (error instanceof CdpTimeoutError) {
+        // The verified-but-unusable instance we launched is a dead end. Kill it
+        // (only if we own it) and drop its CDP state so the next run starts
+        // clean instead of trying to reuse a hung endpoint.
+        await browser?.close().catch(() => null);
+        if (!reused && child?.pid) {
+          await killTree(child.pid).catch(() => null);
+        }
+        await removeState(profileDir, state).catch(() => null);
+        throw new Error(
+          `${error.message} The Chrome profile may be held by another instance. `
+          + "Close other windows using this profile, or run `wtagent logout` to reset it, then retry.",
+        );
+      }
+      throw error;
+    }
     if (!context) {
       throw new Error("Chrome CDP connection did not expose a browser context.");
     }
 
-    const page = context.pages()[0] ?? await context.newPage();
+    // A reused browser may still contain the previous conversation. Keep it
+    // intact and create a fresh target for this CLI session.
+    const page = reused
+      ? await context.newPage()
+      : context.pages()[0] ?? await context.newPage();
     if (minimized) {
       await setWindowState(context, page, "minimized");
     }
@@ -144,27 +279,75 @@ export async function launchAndConnectCdpChrome({
       browser,
       context,
       child,
-      endpoint,
+      endpoint: state.endpoint,
+      page,
+      pid: state.pid,
+      reused,
       // Minimize / restore the visible window on demand. The runtime restores
       // the window when it needs the user (manual login, CAPTCHA) and
       // re-minimizes afterward. Uses the live current page each time so it
       // targets the window the user is actually looking at.
       async minimize() {
-        return await setWindowState(context, context.pages()[0] ?? page, "minimized");
+        return await setWindowState(context, page, "minimized");
       },
       async restore() {
-        return await setWindowState(context, context.pages()[0] ?? page, "normal");
+        return await setWindowState(context, page, "normal");
       },
       async close() {
-        await browser.close().catch(() => null);
-        if (!await waitForExit(child, 2_000)) {
-          await killProcessTree(child.pid);
-          await waitForExit(child, 2_000);
+        if (closePromise) {
+          return await closePromise;
         }
+        closePromise = (async () => {
+          let exited = false;
+          try {
+            // browser.close() on a connectOverCDP browser only disconnects the
+            // Playwright transport. Browser.close asks Chrome itself to exit.
+            const session = await browser.newBrowserCDPSession()
+              .catch(() => null);
+            if (session) {
+              await settleWithin(session.send("Browser.close"), 1_500);
+              await settleWithin(session.detach(), 500);
+            }
+            exited = await waitForExit(state.pid, 3_000);
+            await settleWithin(browser.close(), 1_500);
+
+            if (!exited) {
+              const childStillOwnsPid = child?.pid === state.pid
+                && child.exitCode == null
+                && child.signalCode == null;
+              const safeToKill = childStillOwnsPid
+                || await matchesState(state);
+              if (safeToKill) {
+                await killTree(state.pid);
+                exited = await waitForExit(state.pid, 3_000);
+              }
+            }
+
+            if (exited) {
+              await removeState(profileDir, state);
+              return;
+            }
+            throw new Error(
+              `Chrome pid=${state.pid} did not exit; its verified CDP state `
+              + "was kept so the next WTAgent run can reuse it.",
+            );
+          } finally {
+            await releaseProfileLock();
+          }
+        })();
+        return await closePromise;
       },
     };
   } catch (error) {
-    await killProcessTree(child.pid);
+    await browser?.close().catch(() => null);
+    if (
+      child
+      && child.exitCode == null
+      && child.signalCode == null
+    ) {
+      await killTree(child.pid);
+    }
+    await releaseProfileLock();
     throw error;
   }
 }