feat: auto-close adapter windows, add OPENCLI_WINDOW_FOCUSED, document config (#915)

* feat: auto-close adapter windows, add OPENCLI_WINDOW_FOCUSED, document config

1. Adapter commands now close the automation window immediately after
   completion instead of waiting for the 30s idle timeout.

2. OPENCLI_WINDOW_FOCUSED=1 opens automation windows in the foreground
   (useful for debugging). Default remains background.

3. Add Configuration section to README (EN/ZH) and opencli-usage skill
   listing all stable user-facing environment variables.

* Fix OPENCLI_WINDOW_FOCUSED to be per-request, not frozen at daemon startup

Move env var read from daemon (startup-time constant) to CLI side
(sendCommandRaw), so it works correctly with the persistent daemon model.
Each request now reads the env var fresh and includes windowFocused in
the command payload.

Author: jackwener

README.md

@@ -141,6 +141,20 @@ OpenCLI is not only for websites. It can also:
 
 > **Important**: Browser-backed commands reuse your Chrome/Chromium login session. If you get empty data or permission-like failures, first confirm the site is already open and authenticated in Chrome/Chromium.
 
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCLI_DAEMON_PORT` | `19825` | HTTP port for the daemon-extension bridge |
+| `OPENCLI_WINDOW_FOCUSED` | `false` | Set to `1` to open automation windows in the foreground (useful for debugging) |
+| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `30` | Seconds to wait for browser connection |
+| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | Seconds to wait for a single browser command |
+| `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | `120` | Seconds to wait for explore/record operations |
+| `OPENCLI_CDP_ENDPOINT` | — | Chrome DevTools Protocol endpoint for remote browser or Electron apps |
+| `OPENCLI_CDP_TARGET` | — | Filter CDP targets by URL substring (e.g. `detail.1688.com`) |
+| `OPENCLI_VERBOSE` | `false` | Enable verbose logging (`-v` flag also works) |
+| `OPENCLI_DIAGNOSTIC` | `false` | Set to `1` to capture structured diagnostic context on failures |
+
 ## Update
 
 ```bash

README.zh-CN.md

@@ -129,6 +129,20 @@ OpenCLI 不只是网站 CLI，还可以：
 
 > **重要**：浏览器型命令直接复用你的 Chrome/Chromium 登录态。如果拿到空数据或出现权限类失败，先确认目标站点已经在浏览器里打开并完成登录。
 
+## 配置
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `OPENCLI_DAEMON_PORT` | `19825` | daemon-extension 通信端口 |
+| `OPENCLI_WINDOW_FOCUSED` | `false` | 设为 `1` 时 automation 窗口在前台打开（适合调试） |
+| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `30` | 浏览器连接超时（秒） |
+| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | 单个浏览器命令超时（秒） |
+| `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | `120` | explore/record 操作超时（秒） |
+| `OPENCLI_CDP_ENDPOINT` | — | Chrome DevTools Protocol 端点，用于远程浏览器或 Electron 应用 |
+| `OPENCLI_CDP_TARGET` | — | 按 URL 子串过滤 CDP target（如 `detail.1688.com`） |
+| `OPENCLI_VERBOSE` | `false` | 启用详细日志（`-v` 也可以） |
+| `OPENCLI_DIAGNOSTIC` | `false` | 设为 `1` 时在失败时输出结构化诊断上下文 |
+
 ## 更新
 
 ```bash

extension/src/background.ts

@@ -124,6 +124,7 @@ type AutomationSession = {
 
 const automationSessions = new Map<string, AutomationSession>();
 const WINDOW_IDLE_TIMEOUT = 30000; // 30s — quick cleanup after command finishes
+let windowFocused = false; // set per-command from daemon's OPENCLI_WINDOW_FOCUSED
 
 function getWorkspaceKey(workspace?: string): string {
   return workspace?.trim() || 'default';
@@ -176,7 +177,7 @@ async function getAutomationWindow(workspace: string, initialUrl?: string): Prom
   // state value for windows.create(). The window defaults to 'normal' state anyway.
   const win = await chrome.windows.create({
     url: startUrl,
-    focused: false,
+    focused: windowFocused,
     width: 1280,
     height: 900,
     type: 'normal',
@@ -272,6 +273,7 @@ chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
 
 async function handleCommand(cmd: Command): Promise<Result> {
   const workspace = getWorkspaceKey(cmd.workspace);
+  windowFocused = cmd.windowFocused === true;
   // Reset idle timer on every command (window stays alive while active)
   resetWindowIdleTimer(workspace);
   try {

extension/src/protocol.ts

@@ -63,6 +63,8 @@ export interface Command {
   cdpMethod?: string;
   /** CDP method params for 'cdp' action */
   cdpParams?: Record<string, unknown>;
+  /** When true, automation windows are created in the foreground (focused) */
+  windowFocused?: boolean;
 }
 
 export interface Result {

skills/opencli-usage/SKILL.md

@@ -182,6 +182,20 @@ opencli record <url>            # Record API calls manually
 
 All commands support: `--format` / `-f` with `table` `json` `yaml` `md` `csv`
 
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCLI_DAEMON_PORT` | `19825` | Daemon-extension bridge port |
+| `OPENCLI_WINDOW_FOCUSED` | `false` | `1` = open automation windows in foreground |
+| `OPENCLI_BROWSER_CONNECT_TIMEOUT` | `30` | Browser connection timeout (seconds) |
+| `OPENCLI_BROWSER_COMMAND_TIMEOUT` | `60` | Single command timeout (seconds) |
+| `OPENCLI_BROWSER_EXPLORE_TIMEOUT` | `120` | Explore/record timeout (seconds) |
+| `OPENCLI_CDP_ENDPOINT` | — | CDP endpoint for remote browser / Electron apps |
+| `OPENCLI_CDP_TARGET` | — | Filter CDP targets by URL substring |
+| `OPENCLI_VERBOSE` | `false` | Verbose logging (`-v` flag also works) |
+| `OPENCLI_DIAGNOSTIC` | `false` | `1` = structured diagnostic on failures |
+
 ## Self-Repair
 
 If a command fails due to a site change (selector, API, or response schema), **automatically fix the adapter and retry** instead of reporting failure. Re-run the command with `OPENCLI_DIAGNOSTIC=1` to get structured diagnostic context, then fix the adapter file at `RepairContext.adapter.sourcePath` and retry. Max 3 repair rounds. See the `opencli-autofix` skill for the full workflow.

src/browser/daemon-client.ts

@@ -48,6 +48,8 @@ export interface DaemonCommand {
   pattern?: string;
   cdpMethod?: string;
   cdpParams?: Record<string, unknown>;
+  /** When true, automation windows are created in the foreground */
+  windowFocused?: boolean;
 }
 
 export interface DaemonResult {
@@ -137,7 +139,9 @@ async function sendCommandRaw(
 
   for (let attempt = 1; attempt <= maxRetries; attempt++) {
     const id = generateId();
-    const command: DaemonCommand = { id, action, ...params };
+    const wf = process.env.OPENCLI_WINDOW_FOCUSED;
+    const windowFocused = (wf === '1' || wf === 'true') ? true : undefined;
+    const command: DaemonCommand = { id, action, ...params, ...(windowFocused && { windowFocused }) };
     try {
       const res = await requestDaemon('/command', {
         method: 'POST',

src/execution.ts

@@ -193,10 +193,14 @@ export async function executeCommand(
           }
         }
         try {
-          return await runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+          const result = await runWithTimeout(runCommand(cmd, page, kwargs, debug), {
             timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
             label: fullName(cmd),
           });
+          // Adapter commands are one-shot — close the automation window immediately
+          // instead of waiting for the 30s idle timeout.
+          await page.closeWindow?.().catch(() => {});
+          return result;
         } catch (err) {
           // Collect diagnostic while page is still alive (before browserSession closes it).
           if (isDiagnosticEnabled()) {