feat(grok): add browser chat baseline commands (read/history/detail/new/send/status) (#1392)

Phase 3 — Grok adapter baseline (LLM browser-chat command family, parallel to ChatGPT/Qwen/Yuanbao).

## Surface
6 commands: `status` / `history` / `read` / `detail` / `new` / `send`. Site-local `clis/grok/utils.js` justified by 6 commands sharing helpers, not over-abstraction.

## 4-head review iteration

1. **`b4e81bad`** — initial baseline (12 Grok/shared files)
2. **`0a8112fc`** — mechanical rebase (CHANGELOG conflict only, all 12 Grok files preserved business-equivalent through rebase)
3. **`481e87e2`** — security fix: `parseGrokSessionId()` SSRF-shape vulnerability close — switched from regex string match to `new URL()` parser with branch separation:
   - Bare UUID mode: only exact UUID shape (no URL/query suffix accepted)
   - URL mode: requires `https` scheme + exact `grok.com` or subdomain host + exact `/c/<uuid>` path
4. **`a082023c`** — test-only hardening: 2 additional negative anchors covering existing implementation rejections (bare UUID `?next=abc` query tail / `grok.com.evil.com` host-suffix trick)

## Negative anchor coverage (8 cases)
http / off-domain / fakegrok / host-suffix subdomain / embedded URL / path suffix / UUID-tail / bare query tail

## Better-solution evidence form
LLM browser-chat family pattern (matching ChatGPT/Qwen/Yuanbao baseline) + 5 live probes — not first-site hostile scrape. TipTap editor API send seam (`editor.commands.focus/clearContent/insertContent`) is correct boundary because Grok ignores DOM input events; isolated in `sendMessage()`. Lack of full TipTap mock = residual risk, not blocker.

## Invariants locked
- `parseGrokSessionId()` URL parser branch separation (bare UUID exact / URL exact path)
- `history --limit` rejects invalid/out-of-range
- `status` uses `null` for unknowns (no fabrication)
- Bubble extraction preserves image-only assistant turns (no silent HTML-only drop)
- Auth/empty semantics aligned with LLM browser-chat baseline family

## Verification
Local: Grok adapter tests `28/28`, typecheck, build/manifest, docs:build, typed-error-lint `189/189`, silent-column-drop `103/103`, doc coverage `140/140`, listing-id advisory `13` unchanged, diff-check clean.
GitHub: build ubuntu/macos/windows × unit-test 1/2 + 2/2, bun-test, adapter-test, audit, doc-coverage, docs-build all SUCCESS. PR CLEAN/MERGEABLE.

Lead: codex-mini1. Aux: First-principles-1. Coordination: pr-monitor.

Author: jackwener

CHANGELOG.md

@@ -14,6 +14,7 @@
 * **browser lifecycle** — owned browser workspaces now lease tabs inside a shared dedicated automation container instead of owning one Chrome window per workspace; lease state is persisted for MV3 service-worker reconciliation and idle cleanup is backed by alarms.
 * **browser session** — adapter commands can opt into site-level tab reuse with `browserSession.reuse = 'site'`; Grok and other browser-backed LLM adapters now keep a shared site tab by default, and users can override with `--reuse <none|site>`.
 * **chatgpt** — add browser-web baseline commands: `ask`, `send`, `read`, `history`, `detail`, `new`, and `status`.
+* **grok** — add browser-web baseline commands: `read`, `history`, `detail`, `new`, `send`, and `status` (existing `ask` and `image` unchanged).
 * **yuanbao** — add browser-web baseline commands: `send`, `status`, `read`, `history`, and `detail` (joining the existing `ask` and `new`).
 * **web read** — make page extraction render-aware: same-origin iframe content is merged into the Markdown source, `--wait-for` can wait inside main/iframe documents, `--wait-until networkidle` waits for captured requests to settle, and `--diagnose` reports frames, empty containers, and API-like XHRs for shell/AJAX pages.
 

cli-manifest.json

@@ -10281,6 +10281,181 @@
       "reuse": "site"
     }
   },
+  {
+    "site": "grok",
+    "name": "detail",
+    "description": "Open a Grok conversation by ID and read its messages",
+    "access": "read",
+    "domain": "grok.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "id",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Session ID (UUID) or full https://grok.com/c/<id> URL"
+      },
+      {
+        "name": "markdown",
+        "type": "boolean",
+        "default": false,
+        "required": false,
+        "help": "Emit assistant replies as markdown"
+      }
+    ],
+    "columns": [
+      "Role",
+      "Text"
+    ],
+    "type": "js",
+    "modulePath": "grok/detail.js",
+    "sourceFile": "grok/detail.js",
+    "navigateBefore": false,
+    "browserSession": {
+      "reuse": "site"
+    }
+  },
+  {
+    "site": "grok",
+    "name": "history",
+    "description": "List recent Grok conversations from the sidebar (requires login)",
+    "access": "read",
+    "domain": "grok.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "limit",
+        "type": "int",
+        "default": 20,
+        "required": false,
+        "help": "Max conversations to show (default 20, max 100)"
+      }
+    ],
+    "columns": [
+      "Index",
+      "Title",
+      "Url"
+    ],
+    "type": "js",
+    "modulePath": "grok/history.js",
+    "sourceFile": "grok/history.js",
+    "navigateBefore": false,
+    "browserSession": {
+      "reuse": "site"
+    }
+  },
+  {
+    "site": "grok",
+    "name": "new",
+    "description": "Start a new conversation in Grok",
+    "access": "write",
+    "domain": "grok.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [],
+    "columns": [
+      "Status"
+    ],
+    "type": "js",
+    "modulePath": "grok/new.js",
+    "sourceFile": "grok/new.js",
+    "navigateBefore": false,
+    "browserSession": {
+      "reuse": "site"
+    }
+  },
+  {
+    "site": "grok",
+    "name": "read",
+    "description": "Read messages in the current Grok conversation",
+    "access": "read",
+    "domain": "grok.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "markdown",
+        "type": "boolean",
+        "default": false,
+        "required": false,
+        "help": "Emit assistant replies as markdown"
+      }
+    ],
+    "columns": [
+      "Role",
+      "Text"
+    ],
+    "type": "js",
+    "modulePath": "grok/read.js",
+    "sourceFile": "grok/read.js",
+    "navigateBefore": false,
+    "browserSession": {
+      "reuse": "site"
+    }
+  },
+  {
+    "site": "grok",
+    "name": "send",
+    "description": "Fire-and-forget: send a prompt to Grok without waiting for the reply",
+    "access": "write",
+    "domain": "grok.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [
+      {
+        "name": "prompt",
+        "type": "str",
+        "required": true,
+        "positional": true,
+        "help": "Prompt to send to Grok"
+      },
+      {
+        "name": "new",
+        "type": "boolean",
+        "default": false,
+        "required": false,
+        "help": "Start a new chat before sending"
+      }
+    ],
+    "columns": [
+      "Status",
+      "Prompt"
+    ],
+    "type": "js",
+    "modulePath": "grok/send.js",
+    "sourceFile": "grok/send.js",
+    "navigateBefore": false,
+    "browserSession": {
+      "reuse": "site"
+    }
+  },
+  {
+    "site": "grok",
+    "name": "status",
+    "description": "Check Grok page availability, login state, current session and model",
+    "access": "read",
+    "domain": "grok.com",
+    "strategy": "cookie",
+    "browser": true,
+    "args": [],
+    "columns": [
+      "Status",
+      "Login",
+      "Model",
+      "SessionId",
+      "Url"
+    ],
+    "type": "js",
+    "modulePath": "grok/status.js",
+    "sourceFile": "grok/status.js",
+    "navigateBefore": false,
+    "browserSession": {
+      "reuse": "site"
+    }
+  },
   {
     "site": "hackernews",
     "name": "ask",

clis/grok/detail.js

@@ -0,0 +1,60 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    GROK_DOMAIN,
+    bubbleHtmlToMarkdown,
+    getMessageBubbles,
+    normalizeBooleanFlag,
+    parseGrokSessionId,
+} from './utils.js';
+
+cli({
+    site: 'grok',
+    name: 'detail',
+    access: 'read',
+    description: 'Open a Grok conversation by ID and read its messages',
+    domain: GROK_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    navigateBefore: false,
+    browserSession: { reuse: 'site' },
+    args: [
+        { name: 'id', positional: true, required: true, help: 'Session ID (UUID) or full https://grok.com/c/<id> URL' },
+        { name: 'markdown', type: 'boolean', default: false, help: 'Emit assistant replies as markdown' },
+    ],
+    columns: ['Role', 'Text'],
+    func: async (page, kwargs) => {
+        const sessionId = parseGrokSessionId(kwargs.id);
+        const wantMarkdown = normalizeBooleanFlag(kwargs.markdown, false);
+
+        await page.goto(`https://grok.com/c/${sessionId}`);
+        await page.wait(2);
+
+        // Poll for the conversation transcript to load. Grok renders the chat
+        // page shell before fetching message history, so a fixed wait can race
+        // the initial empty render. Cap at ~20s so genuinely missing IDs surface
+        // an EmptyResultError rather than hanging.
+        let bubbles = [];
+        const POLL_DEADLINE_MS = 20_000;
+        const POLL_INTERVAL_S = 1;
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < POLL_DEADLINE_MS) {
+            bubbles = await getMessageBubbles(page);
+            if (bubbles.length > 0) break;
+            await page.wait(POLL_INTERVAL_S);
+        }
+
+        if (!bubbles.length) {
+            throw new EmptyResultError(
+                'grok detail',
+                `No visible messages found for conversation ${sessionId}. Verify the ID is correct and that the conversation belongs to the signed-in account.`,
+            );
+        }
+        return bubbles.map((b) => ({
+            Role: b.role,
+            Text: wantMarkdown && b.role === 'Assistant' && b.html
+                ? (bubbleHtmlToMarkdown(b.html) || b.text)
+                : b.text,
+        }));
+    },
+});

clis/grok/history.js

@@ -0,0 +1,48 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, EmptyResultError } from '@jackwener/opencli/errors';
+import {
+    GROK_DOMAIN,
+    authRequired,
+    ensureOnGrok,
+    getHistoryFromSidebar,
+    isLoggedIn,
+} from './utils.js';
+
+cli({
+    site: 'grok',
+    name: 'history',
+    access: 'read',
+    description: 'List recent Grok conversations from the sidebar (requires login)',
+    domain: GROK_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    browserSession: { reuse: 'site' },
+    navigateBefore: false,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Max conversations to show (default 20, max 100)' },
+    ],
+    columns: ['Index', 'Title', 'Url'],
+    func: async (page, kwargs) => {
+        const limit = Number(kwargs.limit ?? 20);
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new ArgumentError('limit', 'must be a positive integer');
+        }
+        if (limit > 100) {
+            throw new ArgumentError('limit', 'must be <= 100');
+        }
+        await ensureOnGrok(page);
+        await page.wait(2);
+        if (!(await isLoggedIn(page))) {
+            throw authRequired();
+        }
+        const sessions = await getHistoryFromSidebar(page, limit);
+        if (!sessions.length) {
+            throw new EmptyResultError('grok history', 'No Grok conversations found in the sidebar for the signed-in account.');
+        }
+        return sessions.slice(0, limit).map((s, i) => ({
+            Index: i + 1,
+            Title: s.title || '(untitled)',
+            Url: `https://grok.com/c/${s.id}`,
+        }));
+    },
+});

clis/grok/new.js

@@ -0,0 +1,20 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { GROK_DOMAIN, startNewChat } from './utils.js';
+
+cli({
+    site: 'grok',
+    name: 'new',
+    access: 'write',
+    description: 'Start a new conversation in Grok',
+    domain: GROK_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    browserSession: { reuse: 'site' },
+    navigateBefore: false,
+    args: [],
+    columns: ['Status'],
+    func: async (page) => {
+        await startNewChat(page);
+        return [{ Status: 'New chat started' }];
+    },
+});

clis/grok/read.js

@@ -0,0 +1,39 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import {
+    GROK_DOMAIN,
+    bubbleHtmlToMarkdown,
+    ensureOnGrok,
+    getMessageBubbles,
+    normalizeBooleanFlag,
+} from './utils.js';
+
+cli({
+    site: 'grok',
+    name: 'read',
+    access: 'read',
+    description: 'Read messages in the current Grok conversation',
+    domain: GROK_DOMAIN,
+    strategy: Strategy.COOKIE,
+    browser: true,
+    browserSession: { reuse: 'site' },
+    navigateBefore: false,
+    args: [
+        { name: 'markdown', type: 'boolean', default: false, help: 'Emit assistant replies as markdown' },
+    ],
+    columns: ['Role', 'Text'],
+    func: async (page, kwargs) => {
+        const wantMarkdown = normalizeBooleanFlag(kwargs.markdown, false);
+        await ensureOnGrok(page);
+        await page.wait(2);
+        const bubbles = await getMessageBubbles(page);
+        if (!bubbles.length) {
+            return [{ Role: 'system', Text: 'No visible messages in the current conversation.' }];
+        }
+        return bubbles.map((b) => ({
+            Role: b.role,
+            Text: wantMarkdown && b.role === 'Assistant' && b.html
+                ? (bubbleHtmlToMarkdown(b.html) || b.text)
+                : b.text,
+        }));
+    },
+});