dsh-browser-playwright-codex 0.5.4 → 0.6.0

package/lib/session.d.ts

@@ -7,6 +7,7 @@ import type { BrowserContext, CDPSession, Locator, Page, Request } from 'playwri
 import type { PlaywrightProvider } from './provider.ts';
 import type { BrowserNode, BrowserSnapshot, DiagnosticsEntry, LoadState } from './types.ts';
 import type { RefSignature } from './page-snapshot.ts';
+import { type CookieRow } from './login-sites.ts';
 import type { ActionResult, PendingDialogRecord } from './provider.ts';
 /** Live session over one browser context owned by one caller. */
 export declare class PlaywrightSession {
@@ -50,6 +51,23 @@ export declare class PlaywrightSession {
     /** Nonce of the baseline ref space; a change means navigation reset. */
     lastRefNonce: string | undefined;
     constructor(provider: PlaywrightProvider, owner: string, context: BrowserContext);
+    /**
+     * The session's cookies, reduced to what the login inference needs. `value` is dropped here,
+     * at the only place cookies enter the summary path, so nothing downstream can leak it.
+     */
+    cookieJar(): Promise<readonly CookieRow[]>;
+    /**
+     * Registrable domains of the pages this browser currently has open — the "first-party" set the
+     * login inference attributes cookies to. Taken from the live pages rather than the browser's
+     * history database: the plugin only claims what it can see, and never reads a new data source.
+     */
+    /**
+     * Page titles by registrable domain for the pages currently open — the site's own name for
+     * itself, which is what browsers and password managers show instead of a bare hostname. Titles
+     * are display-only and trimmed; a domain with no open page simply has no title.
+     */
+    siteTitles(): Promise<Map<string, string>>;
+    visitedHosts(): string[];
     /** Run one operation under busy tracking: idle disposal defers until it settles. */
     run<T>(operation: () => Promise<T>): Promise<T>;
     /** Fast actionability pre-check (visible/enabled/editable) before an action. */
@@ -87,7 +105,7 @@ export declare class PlaywrightSession {
      * Answer the pending native dialog and let the action blocked behind it
      * finish. This is the only place a dialog is ever accepted or dismissed.
      */
-    resolveDialog(accept: boolean, promptText: string | undefined, signal: AbortSignal | undefined): Promise<BrowserSnapshot>;
+    resolveDialog(accept: boolean, promptText: string | undefined, signal?: AbortSignal): Promise<BrowserSnapshot>;
     /** Read the snapshot tree from one page (must run inside a run()). */
     capture(page: Page, opts: {
         interactiveOnly?: boolean;
@@ -135,7 +153,7 @@ export declare class PlaywrightSession {
     buildRefSignatures(nodes: readonly BrowserNode[]): Map<string, RefSignature>;
     /** The document nonce shared by this snapshot's refs, or undefined. */
     refNonce(nodes: readonly BrowserNode[]): string | undefined;
-    navigate(url: string, waitUntil: LoadState, signal: AbortSignal | undefined): Promise<BrowserSnapshot | {
+    navigate(url: string, waitUntil: LoadState, signal?: AbortSignal): Promise<BrowserSnapshot | {
         url: string;
         title: string;
         nodes: never[];
@@ -162,13 +180,13 @@ export declare class PlaywrightSession {
      * an overlaying element can never swallow the click silently. Returns the
      * first unobstructed {x, y}, or throws describing what intercepted it.
      */
-    resolveClickPoint(locator: Locator, signal: AbortSignal | undefined): Promise<{
+    resolveClickPoint(locator: Locator, signal?: AbortSignal): Promise<{
         x: number;
         y: number;
         hitDesc: string;
         hitSelf: boolean;
     }>;
-    click(ref: string, signal: AbortSignal | undefined): Promise<BrowserSnapshot | {
+    click(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot | {
         url: string;
         title: string;
         nodes: never[];
@@ -178,12 +196,12 @@ export declare class PlaywrightSession {
     }>;
     /**
      * Click an element the snapshot gave no ref, addressed by its visible label
-     * (e.g. a menu item revealed by browser_hover that is plain text). The
+     * (e.g. a menu item revealed by browser_click with mode "hover" that is plain text). The
      * label must equal an element's own direct text; the deepest match wins,
      * and the landing note names what was actually clicked plus how many
      * elements shared the label.
      */
-    clickText(text: string, signal: AbortSignal | undefined): Promise<BrowserSnapshot | {
+    clickText(text: string, signal?: AbortSignal): Promise<BrowserSnapshot | {
         url: string;
         title: string;
         nodes: never[];
@@ -230,7 +248,7 @@ export declare class PlaywrightSession {
         truncated: boolean;
         dialogNote: string;
     }>;
-    clickAt(x: number, y: number, signal: AbortSignal | undefined): Promise<BrowserSnapshot | {
+    clickAt(x: number, y: number, signal?: AbortSignal): Promise<BrowserSnapshot | {
         url: string;
         title: string;
         nodes: never[];
@@ -238,7 +256,7 @@ export declare class PlaywrightSession {
         truncated: boolean;
         dialogNote: string;
     }>;
-    clickAtRef(ref: string, signal: AbortSignal | undefined): Promise<BrowserSnapshot | {
+    clickAtRef(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot | {
         url: string;
         title: string;
         nodes: never[];
@@ -246,10 +264,10 @@ export declare class PlaywrightSession {
         truncated: boolean;
         dialogNote: string;
     }>;
-    fill(ref: string, text: string, signal: AbortSignal | undefined): Promise<BrowserSnapshot>;
+    fill(ref: string, text: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
     /** Read the field back and decide whether the fill landed. */
     verifyFill(locator: Locator, tag: string, text: string): Promise<boolean>;
-    press(ref: string, key: string, signal: AbortSignal | undefined): Promise<BrowserSnapshot | {
+    press(ref: string, key: string, signal?: AbortSignal): Promise<BrowserSnapshot | {
         url: string;
         title: string;
         nodes: never[];
@@ -265,14 +283,14 @@ export declare class PlaywrightSession {
      * moves is the only cheap proof that something appeared, so the returned
      * snapshot carries a note comparing them.
      */
-    hover(ref: string, signal: AbortSignal | undefined): Promise<BrowserSnapshot>;
+    hover(ref: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
     /**
      * Hover a trigger the snapshot gave no ref, addressed by its visible label
      * (e.g. a plain span that reveals a menu on mouseenter). The label must
      * equal an element's own direct text; the deepest match wins, and the
      * landing note names what was hovered plus how many elements shared it.
      */
-    hoverText(text: string, signal: AbortSignal | undefined): Promise<BrowserSnapshot>;
+    hoverText(text: string, signal?: AbortSignal): Promise<BrowserSnapshot>;
     /**
      * Shared hover core: rest the pointer on a resolved locator, then report
      * what the actionable ref count did. The label names the target in the
@@ -280,17 +298,17 @@ export declare class PlaywrightSession {
      * target came from a ref).
      */
     hoverLocator(locator: Locator, signal: AbortSignal | undefined, label: string, shared: number): Promise<BrowserSnapshot>;
-    scroll(direction: 'up' | 'down', amount: number, ref: string, signal: AbortSignal | undefined): Promise<BrowserSnapshot>;
-    back(signal: AbortSignal | undefined): Promise<BrowserSnapshot>;
-    forward(signal: AbortSignal | undefined): Promise<BrowserSnapshot>;
-    wait(ms: number, signal: AbortSignal | undefined): Promise<void>;
+    scroll(direction: 'up' | 'down', amount: number, ref: string | undefined, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    back(signal?: AbortSignal): Promise<BrowserSnapshot>;
+    forward(signal?: AbortSignal): Promise<BrowserSnapshot>;
+    wait(ms: number, signal?: AbortSignal): Promise<void>;
     tabs(): Promise<{
         index: number;
         url: string;
         title: string;
         active: boolean;
     }[]>;
-    switchTab(index: number, signal: AbortSignal | undefined): Promise<BrowserSnapshot | {
+    switchTab(index: number, signal?: AbortSignal): Promise<BrowserSnapshot | {
         url: string;
         title: string;
         nodes: never[];
@@ -298,8 +316,8 @@ export declare class PlaywrightSession {
         truncated: boolean;
         dialogNote: string;
     }>;
-    openTab(url: string, waitUntil: LoadState, signal: AbortSignal | undefined): Promise<BrowserSnapshot>;
-    closeTab(index: number, signal: AbortSignal | undefined): Promise<void>;
+    openTab(url: string, waitUntil: LoadState, signal?: AbortSignal): Promise<BrowserSnapshot>;
+    closeTab(index: number, signal?: AbortSignal): Promise<void>;
     /**
      * Screenshots get their own floor instead of reusing the navigation budget: a
      * full-page capture is sized by the page and encoded by the CPU, so a loaded machine
@@ -311,12 +329,12 @@ export declare class PlaywrightSession {
     screenshot(opts: {
         fullPage?: boolean;
         ref?: string;
-    } | undefined, signal: AbortSignal | undefined): Promise<{
+    } | undefined, signal?: AbortSignal): Promise<{
         mime: "image/png";
         bytes: Buffer<ArrayBufferLike>;
     }>;
     pageData(): Promise<unknown>;
-    evaluate(expression: string, signal: AbortSignal | undefined): Promise<unknown>;
+    evaluate(expression: string, signal?: AbortSignal): Promise<unknown>;
     /**
      * Send one raw CDP command on the current page's session and return its
      * result. This is the "direct protocol" escape hatch behind every other
@@ -325,7 +343,7 @@ export declare class PlaywrightSession {
      * are allowed) lives in the tool layer via lib/cdp-policy.js; this method
      * itself performs no filtering so internal callers keep full control.
      */
-    cdp(method: string, params: Record<string, unknown>, signal: AbortSignal | undefined): Promise<unknown>;
+    cdp(method: string, params: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
     close(): Promise<void>;
     timeoutMs(): number;
     ensurePage(): Promise<Page>;

package/lib/session.js

@@ -1,3 +1,4 @@
+import { looksLikeToken, registrableDomain } from "./login-sites.js";
 import { BrowserError } from "./errors.js";
 import { asTimeoutError, isAbortError, isContextDestroyed, isCrashError } from "./page-diagnostics.js";
 import { consoleMessages, networkRequests, pageData, trackPage } from "./page-diagnostics.js";
@@ -45,6 +46,69 @@ export class PlaywrightSession {
         this.owner = owner;
         this.context = context;
     }
+    /**
+     * The session's cookies, reduced to what the login inference needs. `value` is dropped here,
+     * at the only place cookies enter the summary path, so nothing downstream can leak it.
+     */
+    async cookieJar() {
+        const raw = await this.context.cookies();
+        return raw.map((cookie) => ({
+            name: cookie.name,
+            domain: cookie.domain,
+            ...(typeof cookie.expires === 'number' ? { expires: cookie.expires } : {}),
+            ...(cookie.httpOnly === true ? { httpOnly: true } : {}),
+            ...(cookie.secure === true ? { secure: true } : {}),
+            // The value is inspected here and reduced to one boolean; it never leaves this function.
+            ...(looksLikeToken(cookie.value) ? { tokenLike: true } : {}),
+        }));
+    }
+    /**
+     * Registrable domains of the pages this browser currently has open — the "first-party" set the
+     * login inference attributes cookies to. Taken from the live pages rather than the browser's
+     * history database: the plugin only claims what it can see, and never reads a new data source.
+     */
+    /**
+     * Page titles by registrable domain for the pages currently open — the site's own name for
+     * itself, which is what browsers and password managers show instead of a bare hostname. Titles
+     * are display-only and trimmed; a domain with no open page simply has no title.
+     */
+    async siteTitles() {
+        const titles = new Map();
+        for (const page of this.context.pages()) {
+            try {
+                const url = page.url();
+                if (!url.startsWith('http://') && !url.startsWith('https://'))
+                    continue;
+                const domain = registrableDomain(new URL(url).host);
+                if (domain === '' || titles.has(domain))
+                    continue;
+                const title = (await page.title()).replace(/\s+/g, ' ').trim();
+                if (title !== '')
+                    titles.set(domain, title.slice(0, 80));
+            }
+            catch {
+                /* a page can be mid-navigation or already closed */
+            }
+        }
+        return titles;
+    }
+    visitedHosts() {
+        const hosts = new Set();
+        for (const page of this.context.pages()) {
+            try {
+                const url = page.url();
+                if (!url.startsWith('http://') && !url.startsWith('https://'))
+                    continue;
+                const domain = registrableDomain(new URL(url).host);
+                if (domain !== '')
+                    hosts.add(domain);
+            }
+            catch {
+                /* a page can be mid-navigation or already closed */
+            }
+        }
+        return [...hosts];
+    }
     /** Run one operation under busy tracking: idle disposal defers until it settles. */
     run(operation) {
         this.provider.beginOp(this.owner);
@@ -223,7 +287,7 @@ export class PlaywrightSession {
     }
     /**
      * Click an element the snapshot gave no ref, addressed by its visible label
-     * (e.g. a menu item revealed by browser_hover that is plain text). The
+     * (e.g. a menu item revealed by browser_click with mode "hover" that is plain text). The
      * label must equal an element's own direct text; the deepest match wins,
      * and the landing note names what was actually clicked plus how many
      * elements shared the label.

package/lib/site-aliases.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 域名对照表（升级版）：每个域名一条「说明 + 归属公司」，卡片按公司折叠成一行。
+ *
+ * 用户的原话："这种一个类型的肯定要放一起啊" —— 京东系二十来个域各自占一行，小半屏都是它，
+ * 既看不出重点、也找不到别的站。所以这份表不只回答"这是什么"，还回答"它属于谁"。
+ *
+ * 两条来源，按可靠性排序：
+ *   1. **网页自己的标题**（浏览器/密码管理器的做法）：网站自己报的名字，不出网、不会过期；
+ *      由 provider 提供，只在那个域当前开着页面时才有。
+ *   2. **这份表**：离线、可测、覆盖常见的国内服务与大厂；**会被时代淘汰**，所以只在标题缺失时兜底，
+ *      而且**宁可留空也不瞎猜**（认不出的就显示域名本身，也没有归属）。
+ *
+ * 附带的好处：广告/统计类域名在表里被标出来，而且**整族归到"广告/统计平台"一组** —— 它们成片出现在
+ * "像登录态"里，本身就是判据被数据相似性骗了的信号。
+ * @module dsh-browser-playwright-codex/site-aliases
+ */
+/**
+ * A short Chinese explanation of what a domain is, or undefined when we do not know.
+ * @param domain - registrable domain, e.g. `jinritemai.com`.
+ * @returns the explanation, or undefined (never a guess).
+ */
+export declare function siteAlias(domain: string): string | undefined;
+/**
+ * Which company a domain belongs to, for collapsing sibling domains into one row.
+ * @param domain - registrable domain.
+ * @returns the group key and its 中文 label, or undefined when the domain is not part of a group.
+ */
+export declare function siteGroup(domain: string): {
+    key: string;
+    label: string;
+} | undefined;
+/** How many domains this table explains — tests and docs use it to stay honest about coverage. */
+export declare const ALIAS_COUNT: number;

package/lib/site-aliases.js

@@ -0,0 +1,132 @@
+/**
+ * 域名对照表（升级版）：每个域名一条「说明 + 归属公司」，卡片按公司折叠成一行。
+ *
+ * 用户的原话："这种一个类型的肯定要放一起啊" —— 京东系二十来个域各自占一行，小半屏都是它，
+ * 既看不出重点、也找不到别的站。所以这份表不只回答"这是什么"，还回答"它属于谁"。
+ *
+ * 两条来源，按可靠性排序：
+ *   1. **网页自己的标题**（浏览器/密码管理器的做法）：网站自己报的名字，不出网、不会过期；
+ *      由 provider 提供，只在那个域当前开着页面时才有。
+ *   2. **这份表**：离线、可测、覆盖常见的国内服务与大厂；**会被时代淘汰**，所以只在标题缺失时兜底，
+ *      而且**宁可留空也不瞎猜**（认不出的就显示域名本身，也没有归属）。
+ *
+ * 附带的好处：广告/统计类域名在表里被标出来，而且**整族归到"广告/统计平台"一组** —— 它们成片出现在
+ * "像登录态"里，本身就是判据被数据相似性骗了的信号。
+ * @module dsh-browser-playwright-codex/site-aliases
+ */
+/** Group key → 折叠行显示的中文名. */
+const GROUP_LABELS = {
+    jd: '京东系',
+    alibaba: '阿里系',
+    bytedance: '字节系',
+    microsoft: '微软系',
+    meta: 'Meta 系',
+    google: 'Google 系',
+    ads: '广告 / 统计平台',
+    tencent: '腾讯系',
+    netease: '网易系',
+};
+/** Domain → what it is and who owns it. Keys are registrable domains. */
+const SITES = {
+    // ── 京东系（真实名单里占了二十来个域，所以单独成组）──────────────────────────
+    'jd.com': { name: '京东', group: 'jd' },
+    'jingdong.com': { name: '京东（旧域名）', group: 'jd' },
+    'jd.hk': { name: '京东香港', group: 'jd' },
+    'jddj.com': { name: '京东到家', group: 'jd' },
+    'jdpay.com': { name: '京东支付', group: 'jd' },
+    'jcloud.com': { name: '京东云', group: 'jd' },
+    'jdcloud.com': { name: '京东云', group: 'jd' },
+    'jdbusiness.com': { name: '京东企业购', group: 'jd' },
+    'jdindustry.com': { name: '京东工业', group: 'jd' },
+    'jdl.cn': { name: '京东物流', group: 'jd' },
+    'jdl.com': { name: '京东物流', group: 'jd' },
+    'jdwl.com': { name: '京东物流', group: 'jd' },
+    'healthjd.com': { name: '京东健康', group: 'jd' },
+    'jingdonghealth.cn': { name: '京东健康', group: 'jd' },
+    '7fresh.com': { name: '七鲜（京东生鲜超市）', group: 'jd' },
+    'baitiao.com': { name: '京东白条', group: 'jd' },
+    'jingxi.com': { name: '京喜', group: 'jd' },
+    'five-star.cn': { name: '京东五星电器', group: 'jd' },
+    // ── 阿里系 ──────────────────────────────────────────────────────────────────
+    'taobao.com': { name: '淘宝', group: 'alibaba' },
+    'tmall.com': { name: '天猫', group: 'alibaba' },
+    'goofish.com': { name: '闲鱼（二手交易）', group: 'alibaba' },
+    'qianwen.com': { name: '通义千问（阿里的 AI 助手）', group: 'alibaba' },
+    'qianwenai.com': { name: '通义千问（阿里的 AI 助手）', group: 'alibaba' },
+    'a-mo.net': { name: '阿里妈妈（广告投放域名）', group: 'alibaba' },
+    'a-mx.com': { name: '阿里妈妈（广告投放域名）', group: 'alibaba' },
+    'yangkeduo.com': { name: '拼多多', group: 'alibaba' },
+    // ── 字节系 ──────────────────────────────────────────────────────────────────
+    'douyin.com': { name: '抖音', group: 'bytedance' },
+    'doubao.com': { name: '豆包（字节的 AI 助手）', group: 'bytedance' },
+    'toutiao.com': { name: '今日头条', group: 'bytedance' },
+    'volcengine.com': { name: '火山引擎（字节云服务）', group: 'bytedance' },
+    'jinritemai.com': { name: '巨量千川（抖音电商广告后台）', group: 'bytedance' },
+    'feishu.cn': { name: '飞书', group: 'bytedance' },
+    'larksuite.com': { name: '飞书（国际版）', group: 'bytedance' },
+    // ── 其他国内 ────────────────────────────────────────────────────────────────
+    'chaoxing.com': { name: '超星学习通（网课平台）' },
+    'juejin.cn': { name: '掘金（开发者社区）' },
+    'baidu.com': { name: '百度' },
+    'kuaishou.com': { name: '快手' },
+    'deepseek.com': { name: 'DeepSeek（深度求索）' },
+    // ── 微软系 ──────────────────────────────────────────────────────────────────
+    'live.com': { name: '微软账号（Outlook 等）', group: 'microsoft' },
+    'microsoftonline.com': { name: '微软企业账号登录', group: 'microsoft' },
+    'bing.com': { name: '必应（微软搜索）', group: 'microsoft' },
+    'clarity.ms': { name: 'Microsoft Clarity（行为统计）', group: 'microsoft' },
+    // ── Meta 系 ─────────────────────────────────────────────────────────────────
+    'meta.com': { name: 'Meta（Facebook 母公司）', group: 'meta' },
+    'facebook.com': { name: 'Facebook', group: 'meta' },
+    // ── Google 系 ───────────────────────────────────────────────────────────────
+    'doubleclick.net': { name: 'Google 广告', group: 'google' },
+    'google-analytics.com': { name: 'Google Analytics（统计）', group: 'google' },
+    'googletagmanager.com': { name: 'Google Tag Manager（统计）', group: 'google' },
+    // ── 其他国外服务 ────────────────────────────────────────────────────────────
+    'github.com': { name: 'GitHub（代码托管）' },
+    'openrouter.ai': { name: 'OpenRouter（AI 模型聚合服务）' },
+    'fearlessrevolution.com': { name: 'FearlessRevolution（游戏修改器社区）' },
+    // ── 广告 / 统计平台（成片出现时就是"判据被骗了"的信号）────────────────────────
+    'adroll.com': { name: 'AdRoll（广告再营销）', group: 'ads' },
+    'pubmatic.com': { name: 'PubMatic（广告交易平台）', group: 'ads' },
+    'criteo.com': { name: 'Criteo（广告再营销）', group: 'ads' },
+    'adnxs.com': { name: 'Xandr/AppNexus（广告交易平台）', group: 'ads' },
+    'rubiconproject.com': { name: 'Magnite（广告交易平台）', group: 'ads' },
+    'casalemedia.com': { name: 'Index Exchange（广告交易平台）', group: 'ads' },
+    'scorecardresearch.com': { name: 'Comscore（受众统计）', group: 'ads' },
+    'adsrvr.org': { name: 'The Trade Desk（广告投放）', group: 'ads' },
+    'taboola.com': { name: 'Taboola（内容推荐广告）', group: 'ads' },
+    'outbrain.com': { name: 'Outbrain（内容推荐广告）', group: 'ads' },
+    'mmstat.com': { name: '阿里统计', group: 'ads' },
+    'umeng.com': { name: '友盟（移动统计）', group: 'ads' },
+    'umengcloud.com': { name: '友盟（移动统计）', group: 'ads' },
+    'cnzz.com': { name: 'CNZZ 站长统计', group: 'ads' },
+    'hotjar.com': { name: 'Hotjar（行为统计）', group: 'ads' },
+    'sentry.io': { name: 'Sentry（错误监控）', group: 'ads' },
+    sajssdk: { name: '神策数据（统计）', group: 'ads' },
+    sensorsdata: { name: '神策数据（统计）', group: 'ads' },
+};
+/**
+ * A short Chinese explanation of what a domain is, or undefined when we do not know.
+ * @param domain - registrable domain, e.g. `jinritemai.com`.
+ * @returns the explanation, or undefined (never a guess).
+ */
+export function siteAlias(domain) {
+    return SITES[normalize(domain)]?.name;
+}
+/**
+ * Which company a domain belongs to, for collapsing sibling domains into one row.
+ * @param domain - registrable domain.
+ * @returns the group key and its 中文 label, or undefined when the domain is not part of a group.
+ */
+export function siteGroup(domain) {
+    const key = SITES[normalize(domain)]?.group;
+    if (key === undefined)
+        return undefined;
+    return { key, label: GROUP_LABELS[key] ?? key };
+}
+/** How many domains this table explains — tests and docs use it to stay honest about coverage. */
+export const ALIAS_COUNT = Object.keys(SITES).length;
+function normalize(domain) {
+    return domain.trim().replace(/^\./, '').toLowerCase();
+}