@jackwener/opencli 1.7.4 → 1.7.6

package/dist/src/browser/network-key.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Stable keys for network capture entries.
+ *
+ * Agents reference entries by key (e.g. `UserTweets`, `GET api.x.com/1.1/home`)
+ * instead of array index, so the mapping survives new captures.
+ *
+ * Rules:
+ *   GraphQL (URL contains `/graphql/`): key = operationName derived from URL path
+ *                                       (the segment after a 22-char query id, or the last segment)
+ *   Everything else: key = `METHOD host+pathname`
+ *
+ * On collision assignKeys suffixes duplicates as `base#2`, `base#3`, ... —
+ * the first occurrence stays bare (there is no `#1`).
+ */
+export interface KeyableRequest {
+    url: string;
+    method: string;
+}
+export declare function deriveKey(req: KeyableRequest): string;
+export declare function assignKeys<T extends KeyableRequest>(requests: T[]): Array<T & {
+    key: string;
+}>;

package/dist/src/browser/network-key.js

@@ -0,0 +1,66 @@
+/**
+ * Stable keys for network capture entries.
+ *
+ * Agents reference entries by key (e.g. `UserTweets`, `GET api.x.com/1.1/home`)
+ * instead of array index, so the mapping survives new captures.
+ *
+ * Rules:
+ *   GraphQL (URL contains `/graphql/`): key = operationName derived from URL path
+ *                                       (the segment after a 22-char query id, or the last segment)
+ *   Everything else: key = `METHOD host+pathname`
+ *
+ * On collision assignKeys suffixes duplicates as `base#2`, `base#3`, ... —
+ * the first occurrence stays bare (there is no `#1`).
+ */
+export function deriveKey(req) {
+    const parsed = safeParseUrl(req.url);
+    if (!parsed)
+        return `${req.method.toUpperCase()} ${truncate(req.url, 120)}`;
+    const path = parsed.pathname;
+    if (path.includes('/graphql/')) {
+        const op = graphqlOperationName(path);
+        if (op)
+            return op;
+    }
+    return `${req.method.toUpperCase()} ${parsed.host}${path}`;
+}
+export function assignKeys(requests) {
+    const counts = new Map();
+    const out = [];
+    for (const req of requests) {
+        const base = deriveKey(req);
+        const n = counts.get(base) ?? 0;
+        counts.set(base, n + 1);
+        const key = n === 0 ? base : `${base}#${n + 1}`;
+        out.push({ ...req, key });
+    }
+    return out;
+}
+function graphqlOperationName(pathname) {
+    // Patterns we've seen in the wild:
+    //   /i/api/graphql/<queryId>/UserTweets
+    //   /graphql/<queryId>/SomeOp
+    //   /graphql/SomeOp                       (rare, no id)
+    const segments = pathname.split('/').filter(Boolean);
+    const idx = segments.indexOf('graphql');
+    if (idx < 0)
+        return null;
+    const tail = segments.slice(idx + 1);
+    if (tail.length === 0)
+        return null;
+    if (tail.length === 1)
+        return tail[0];
+    // tail[0] is usually a query id; the operation name is the next segment.
+    return tail[1] || tail[0];
+}
+function safeParseUrl(url) {
+    try {
+        return new URL(url);
+    }
+    catch {
+        return null;
+    }
+}
+function truncate(s, max) {
+    return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}

package/dist/src/browser/network-key.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/network-key.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { assignKeys, deriveKey } from './network-key.js';
+describe('deriveKey', () => {
+    it('extracts operationName from Twitter-style graphql URLs', () => {
+        expect(deriveKey({
+            method: 'GET',
+            url: 'https://x.com/i/api/graphql/6fWQaBPK51aGyC_VC7t9GQ/UserTweets?variables=...',
+        })).toBe('UserTweets');
+    });
+    it('handles graphql URLs without a query id', () => {
+        expect(deriveKey({
+            method: 'POST',
+            url: 'https://example.com/graphql/MyOp?vars=1',
+        })).toBe('MyOp');
+    });
+    it('uses METHOD host+pathname for REST calls', () => {
+        expect(deriveKey({
+            method: 'get',
+            url: 'https://api.example.com/v1/users?page=1',
+        })).toBe('GET api.example.com/v1/users');
+    });
+    it('falls back to truncated raw url when URL parsing fails', () => {
+        const key = deriveKey({ method: 'GET', url: 'not-a-valid-url' });
+        expect(key.startsWith('GET ')).toBe(true);
+        expect(key).toContain('not-a-valid-url');
+    });
+});
+describe('assignKeys', () => {
+    it('disambiguates collisions with #N suffixes', () => {
+        const out = assignKeys([
+            { url: 'https://x.com/i/api/graphql/a/UserTweets', method: 'GET' },
+            { url: 'https://x.com/i/api/graphql/b/UserTweets', method: 'GET' },
+            { url: 'https://api.example.com/v1/u', method: 'GET' },
+            { url: 'https://api.example.com/v1/u', method: 'GET' },
+            { url: 'https://api.example.com/v1/u', method: 'GET' },
+        ]);
+        expect(out.map(o => o.key)).toEqual([
+            'UserTweets',
+            'UserTweets#2',
+            'GET api.example.com/v1/u',
+            'GET api.example.com/v1/u#2',
+            'GET api.example.com/v1/u#3',
+        ]);
+    });
+    it('preserves extra fields on each request', () => {
+        const out = assignKeys([{ url: 'https://a.com/x', method: 'GET', status: 200 }]);
+        expect(out[0]).toMatchObject({ status: 200, key: 'GET a.com/x' });
+    });
+});

package/dist/src/browser/page.d.ts

@@ -15,7 +15,8 @@ import { BasePage } from './base-page.js';
  */
 export declare class Page extends BasePage {
     private readonly workspace;
-    constructor(workspace?: string);
+    private readonly _idleTimeout;
+    constructor(workspace?: string, idleTimeout?: number);
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     private _page;
     private _networkCaptureUnsupported;
@@ -30,8 +31,8 @@ export declare class Page extends BasePage {
     }): Promise<void>;
     /** Get the active page identity (targetId) */
     getActivePage(): string | undefined;
-    /** @deprecated Use getActivePage() instead */
-    getActiveTabId(): number | undefined;
+    /** Bind this Page instance to a specific page identity (targetId). */
+    setActivePage(page?: string): void;
     private _markUnsupportedNetworkCapture;
     evaluate(js: string): Promise<unknown>;
     getCookies(opts?: {
@@ -41,7 +42,9 @@ export declare class Page extends BasePage {
     /** Close the automation window in the extension */
     closeWindow(): Promise<void>;
     tabs(): Promise<unknown[]>;
-    selectTab(index: number): Promise<void>;
+    newTab(url?: string): Promise<string | undefined>;
+    closeTab(target?: number | string): Promise<void>;
+    selectTab(target: number | string): Promise<void>;
     /**
      * Capture a screenshot via CDP Page.captureScreenshot.
      */
@@ -55,6 +58,13 @@ export declare class Page extends BasePage {
      */
     setFileInput(files: string[], selector?: string): Promise<void>;
     insertText(text: string): Promise<void>;
+    frames(): Promise<Array<{
+        index: number;
+        frameId: string;
+        url: string;
+        name: string;
+    }>>;
+    evaluateInFrame(js: string, frameIndex: number): Promise<unknown>;
     cdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
     /** CDP native click fallback — called when JS el.click() fails */
     protected tryNativeClick(x: number, y: number): Promise<boolean>;

package/dist/src/browser/page.js

@@ -27,9 +27,11 @@ function isUnsupportedNetworkCaptureError(err) {
  */
 export class Page extends BasePage {
     workspace;
-    constructor(workspace = 'default') {
+    _idleTimeout;
+    constructor(workspace = 'default', idleTimeout) {
         super();
         this.workspace = workspace;
+        this._idleTimeout = idleTimeout;
     }
     /** Active page identity (targetId), set after navigate and used in all subsequent commands */
     _page;
@@ -37,13 +39,14 @@ export class Page extends BasePage {
     _networkCaptureWarned = false;
     /** Helper: spread workspace into command params */
     _wsOpt() {
-        return { workspace: this.workspace };
+        return { workspace: this.workspace, ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }) };
     }
     /** Helper: spread workspace + page identity into command params */
     _cmdOpts() {
         return {
             workspace: this.workspace,
             ...(this._page !== undefined && { page: this._page }),
+            ...(this._idleTimeout != null && { idleTimeout: this._idleTimeout }),
         };
     }
     async goto(url, options) {
@@ -102,9 +105,10 @@ export class Page extends BasePage {
     getActivePage() {
         return this._page;
     }
-    /** @deprecated Use getActivePage() instead */
-    getActiveTabId() {
-        return undefined;
+    /** Bind this Page instance to a specific page identity (targetId). */
+    setActivePage(page) {
+        this._page = page;
+        this._lastUrl = null;
     }
     _markUnsupportedNetworkCapture() {
         this._networkCaptureUnsupported = true;
@@ -150,10 +154,39 @@ export class Page extends BasePage {
         const result = await sendCommand('tabs', { op: 'list', ...this._wsOpt() });
         return Array.isArray(result) ? result : [];
     }
-    async selectTab(index) {
-        const result = await sendCommandFull('tabs', { op: 'select', index, ...this._wsOpt() });
+    async newTab(url) {
+        const result = await sendCommandFull('tabs', {
+            op: 'new',
+            ...(url !== undefined && { url }),
+            ...this._wsOpt(),
+        });
+        this._lastUrl = null;
+        return result.page;
+    }
+    async closeTab(target) {
+        const params = { op: 'close', ...this._wsOpt() };
+        if (typeof target === 'number')
+            params.index = target;
+        else if (typeof target === 'string')
+            params.page = target;
+        else if (this._page !== undefined)
+            params.page = this._page;
+        const result = await sendCommand('tabs', params);
+        const closedPage = typeof result?.closed === 'string' ? result.closed : undefined;
+        if ((closedPage && closedPage === this._page) || (!closedPage && (target === undefined || target === this._page))) {
+            this._page = undefined;
+            this._lastUrl = null;
+        }
+    }
+    async selectTab(target) {
+        const result = await sendCommandFull('tabs', {
+            op: 'select',
+            ...(typeof target === 'number' ? { index: target } : { page: target }),
+            ...this._wsOpt(),
+        });
         if (result.page)
             this._page = result.page;
+        this._lastUrl = null;
     }
     /**
      * Capture a screenshot via CDP Page.captureScreenshot.
@@ -227,6 +260,14 @@ export class Page extends BasePage {
             throw new Error('insertText returned no inserted flag — command may not be supported by the extension');
         }
     }
+    async frames() {
+        const result = await sendCommand('frames', { ...this._cmdOpts() });
+        return Array.isArray(result) ? result : [];
+    }
+    async evaluateInFrame(js, frameIndex) {
+        const code = wrapForEval(js);
+        return sendCommand('exec', { code, frameIndex, ...this._cmdOpts() });
+    }
     async cdp(method, params = {}) {
         return sendCommand('cdp', {
             cdpMethod: method,

package/dist/src/browser/page.test.js

@@ -102,3 +102,100 @@ describe('Page network capture compatibility', () => {
         expect(warnMock).toHaveBeenCalledTimes(1);
     });
 });
+describe('Page active target tracking', () => {
+    beforeEach(() => {
+        sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
+    });
+    it('tracks only one active page identity at a time', async () => {
+        sendCommandFullMock
+            .mockResolvedValueOnce({ data: { url: 'https://first.example' }, page: 'page-1' })
+            .mockResolvedValueOnce({ data: { selected: true }, page: 'page-2' });
+        sendCommandMock.mockResolvedValue('ok');
+        const page = new Page('browser:default');
+        await page.goto('https://first.example', { waitUntil: 'none' });
+        expect(page.getActivePage()).toBe('page-1');
+        await page.selectTab(1);
+        expect(page.getActivePage()).toBe('page-2');
+        await page.evaluate('1 + 1');
+        expect(sendCommandMock).toHaveBeenLastCalledWith('exec', expect.objectContaining({
+            workspace: 'browser:default',
+            page: 'page-2',
+        }));
+    });
+    it('allows the caller to bind a specific active page identity explicitly', async () => {
+        sendCommandMock.mockResolvedValue('bound');
+        const page = new Page('browser:default');
+        page.setActivePage?.('page-explicit');
+        await page.evaluate('1 + 1');
+        expect(sendCommandMock).toHaveBeenCalledWith('exec', expect.objectContaining({
+            workspace: 'browser:default',
+            page: 'page-explicit',
+        }));
+    });
+    it('creates a new tab without changing the current active page binding', async () => {
+        sendCommandFullMock
+            .mockResolvedValueOnce({ data: { url: 'https://first.example' }, page: 'page-1' })
+            .mockResolvedValueOnce({
+            data: { url: 'https://second.example' },
+            page: 'page-2',
+        });
+        sendCommandMock.mockResolvedValue('ok');
+        const page = new Page('browser:default');
+        await page.goto('https://first.example', { waitUntil: 'none' });
+        const created = await page.newTab?.('https://second.example');
+        expect(created).toBe('page-2');
+        expect(page.getActivePage()).toBe('page-1');
+        await page.evaluate('1 + 1');
+        expect(sendCommandMock).toHaveBeenLastCalledWith('exec', expect.objectContaining({
+            workspace: 'browser:default',
+            page: 'page-1',
+        }));
+    });
+    it('allows the caller to adopt a new tab explicitly after creation', async () => {
+        sendCommandFullMock.mockResolvedValueOnce({
+            data: { url: 'https://second.example' },
+            page: 'page-2',
+        });
+        const page = new Page('browser:default');
+        const created = await page.newTab?.('https://second.example');
+        expect(created).toBe('page-2');
+        expect(page.getActivePage()).toBeUndefined();
+        page.setActivePage?.(created);
+        expect(page.getActivePage()).toBe('page-2');
+        expect(sendCommandFullMock).toHaveBeenCalledWith('tabs', expect.objectContaining({
+            op: 'new',
+            url: 'https://second.example',
+            workspace: 'browser:default',
+        }));
+    });
+    it('closes a tab by explicit page identity', async () => {
+        sendCommandMock.mockResolvedValueOnce({ closed: 'page-2' });
+        const page = new Page('browser:default');
+        await page.closeTab?.('page-2');
+        expect(sendCommandMock).toHaveBeenCalledWith('tabs', expect.objectContaining({
+            op: 'close',
+            workspace: 'browser:default',
+            page: 'page-2',
+        }));
+    });
+    it('clears the active page binding when closing the selected tab by numeric index', async () => {
+        sendCommandFullMock.mockResolvedValueOnce({ data: { selected: true }, page: 'page-2' });
+        sendCommandMock
+            .mockResolvedValueOnce({ closed: 'page-2' })
+            .mockResolvedValueOnce('ok');
+        const page = new Page('browser:default');
+        await page.selectTab(1);
+        expect(page.getActivePage()).toBe('page-2');
+        await page.closeTab?.(1);
+        expect(page.getActivePage()).toBeUndefined();
+        await page.evaluate('1 + 1');
+        const evalCall = sendCommandMock.mock.calls.at(-1);
+        expect(evalCall?.[0]).toBe('exec');
+        expect(evalCall?.[1]).toEqual(expect.objectContaining({
+            workspace: 'browser:default',
+        }));
+        expect(evalCall?.[1]).not.toHaveProperty('page');
+    });
+});

package/dist/src/browser/shape-filter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Shape-based field filter for `browser network --filter <fields>`.
+ *
+ * Agents know what fields a target request's body should contain
+ * (e.g. "author, text, likes") but not which of the captured requests
+ * carries that body. This module lets the network command filter
+ * entries down to those whose inferred shape exposes every requested
+ * field name as some path segment.
+ *
+ * Matching is "any-segment" (not last-segment-only): a field matches
+ * if it equals any segment name of any path in the shape map. This
+ * keeps nested-container fields (e.g. `legacy`, `author` used as an
+ * object key with further nesting) findable.
+ */
+import type { Shape } from './shape.js';
+export interface ParsedFilter {
+    /** Deduped, order-preserving, trimmed non-empty field names. */
+    fields: string[];
+}
+export interface FilterParseError {
+    /** `invalid_filter` structured error reason for agents. */
+    reason: string;
+}
+/**
+ * Parse `--filter` argument value. Splits on `,`, trims, drops empties,
+ * and dedupes (first-seen wins). Returns `FilterParseError` when the
+ * result is empty after cleaning — which means the caller passed only
+ * whitespace, commas, or an empty string.
+ */
+export declare function parseFilter(raw: string): ParsedFilter | FilterParseError;
+/**
+ * Extract named segments from a shape path. Drops the leading `$`,
+ * strips `[N]` array indices, and unwraps `["key"]` bracket-quoted
+ * keys back to their raw string.
+ *
+ * Examples:
+ *   `$`                              → []
+ *   `$.data.items[0].author`         → ['data','items','author']
+ *   `$.data.user["nick name"]`       → ['data','user','nick name']
+ *   `$.rows[0][1]`                   → ['rows']
+ */
+export declare function extractSegments(path: string): string[];
+/**
+ * Collect the set of segment names used anywhere in a shape map.
+ * The returned set is what we test field membership against.
+ */
+export declare function collectShapeSegments(shape: Shape): Set<string>;
+/**
+ * True iff every field in `fields` equals some segment name in `shape`.
+ * AND semantics: all fields must be present.
+ */
+export declare function shapeMatchesFilter(shape: Shape, fields: string[]): boolean;

package/dist/src/browser/shape-filter.js

@@ -0,0 +1,101 @@
+/**
+ * Parse `--filter` argument value. Splits on `,`, trims, drops empties,
+ * and dedupes (first-seen wins). Returns `FilterParseError` when the
+ * result is empty after cleaning — which means the caller passed only
+ * whitespace, commas, or an empty string.
+ */
+export function parseFilter(raw) {
+    if (typeof raw !== 'string') {
+        return { reason: `--filter value must be a non-empty comma-separated field list` };
+    }
+    const parts = raw.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
+    if (parts.length === 0) {
+        return { reason: `--filter value must be a non-empty comma-separated field list (got "${raw}")` };
+    }
+    const seen = new Set();
+    const fields = [];
+    for (const p of parts) {
+        if (!seen.has(p)) {
+            seen.add(p);
+            fields.push(p);
+        }
+    }
+    return { fields };
+}
+/**
+ * Extract named segments from a shape path. Drops the leading `$`,
+ * strips `[N]` array indices, and unwraps `["key"]` bracket-quoted
+ * keys back to their raw string.
+ *
+ * Examples:
+ *   `$`                              → []
+ *   `$.data.items[0].author`         → ['data','items','author']
+ *   `$.data.user["nick name"]`       → ['data','user','nick name']
+ *   `$.rows[0][1]`                   → ['rows']
+ */
+export function extractSegments(path) {
+    if (!path || path === '$')
+        return [];
+    const out = [];
+    // Start past the leading `$`; if path doesn't start with `$` treat
+    // it as a raw segment list (keeps us robust to unexpected input).
+    let i = path.startsWith('$') ? 1 : 0;
+    while (i < path.length) {
+        const c = path[i];
+        if (c === '.') {
+            i++;
+            continue;
+        }
+        if (c === '[') {
+            // Either `[N]` (numeric) or `["key"]` (quoted key). Handle both.
+            const end = path.indexOf(']', i);
+            if (end === -1)
+                break;
+            const inner = path.slice(i + 1, end);
+            i = end + 1;
+            if (inner.length >= 2 && inner.startsWith('"') && inner.endsWith('"')) {
+                try {
+                    out.push(JSON.parse(inner));
+                }
+                catch {
+                    out.push(inner.slice(1, -1));
+                }
+            }
+            // numeric index: drop
+            continue;
+        }
+        // Bare identifier: read up to next `.` or `[`
+        let j = i;
+        while (j < path.length && path[j] !== '.' && path[j] !== '[')
+            j++;
+        out.push(path.slice(i, j));
+        i = j;
+    }
+    return out;
+}
+/**
+ * Collect the set of segment names used anywhere in a shape map.
+ * The returned set is what we test field membership against.
+ */
+export function collectShapeSegments(shape) {
+    const acc = new Set();
+    for (const p of Object.keys(shape)) {
+        for (const seg of extractSegments(p))
+            acc.add(seg);
+    }
+    return acc;
+}
+/**
+ * True iff every field in `fields` equals some segment name in `shape`.
+ * AND semantics: all fields must be present.
+ */
+export function shapeMatchesFilter(shape, fields) {
+    if (fields.length === 0)
+        return true;
+    const segs = collectShapeSegments(shape);
+    for (const f of fields) {
+        if (!segs.has(f))
+            return false;
+    }
+    return true;
+}

package/dist/src/browser/shape-filter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/browser/shape-filter.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import { collectShapeSegments, extractSegments, parseFilter, shapeMatchesFilter, } from './shape-filter.js';
+describe('parseFilter', () => {
+    it('splits comma-separated fields, trims, and drops empty tokens', () => {
+        const r = parseFilter('author, text , likes');
+        expect(r).toEqual({ fields: ['author', 'text', 'likes'] });
+    });
+    it('dedupes while preserving first-seen order', () => {
+        const r = parseFilter('a,b,a,c,b');
+        expect(r).toEqual({ fields: ['a', 'b', 'c'] });
+    });
+    it('rejects empty string as invalid_filter', () => {
+        const r = parseFilter('');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+    it('rejects whitespace-only as invalid_filter', () => {
+        const r = parseFilter('   ');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+    it('rejects commas-only as invalid_filter', () => {
+        const r = parseFilter(',,,');
+        expect(r).toMatchObject({ reason: expect.stringContaining('non-empty') });
+    });
+    it('accepts a single field', () => {
+        expect(parseFilter('author')).toEqual({ fields: ['author'] });
+    });
+});
+describe('extractSegments', () => {
+    it('returns empty for root', () => {
+        expect(extractSegments('$')).toEqual([]);
+    });
+    it('splits dotted path and drops $', () => {
+        expect(extractSegments('$.data.user.name')).toEqual(['data', 'user', 'name']);
+    });
+    it('drops numeric array indices', () => {
+        expect(extractSegments('$.items[0].author')).toEqual(['items', 'author']);
+        expect(extractSegments('$.rows[0][12]')).toEqual(['rows']);
+    });
+    it('unwraps bracket-quoted keys', () => {
+        expect(extractSegments('$.data["weird key"]')).toEqual(['data', 'weird key']);
+    });
+    it('handles bracket-quoted keys at root', () => {
+        expect(extractSegments('$["123bad"]')).toEqual(['123bad']);
+    });
+    it('mixes bracket keys and dot segments', () => {
+        expect(extractSegments('$.data.user["nick name"].age'))
+            .toEqual(['data', 'user', 'nick name', 'age']);
+    });
+});
+describe('collectShapeSegments', () => {
+    it('collects every segment name from every path in a shape', () => {
+        const shape = {
+            '$': 'object',
+            '$.data': 'object',
+            '$.data.items': 'array(3)',
+            '$.data.items[0]': 'object',
+            '$.data.items[0].author': 'string',
+            '$.data.items[0].text': 'string',
+        };
+        const segs = collectShapeSegments(shape);
+        expect(segs.has('data')).toBe(true);
+        expect(segs.has('items')).toBe(true);
+        expect(segs.has('author')).toBe(true);
+        expect(segs.has('text')).toBe(true);
+        expect(segs.has('$')).toBe(false);
+        expect(segs.has('[0]')).toBe(false);
+    });
+    it('returns an empty set for an empty shape', () => {
+        expect(collectShapeSegments({}).size).toBe(0);
+    });
+});
+describe('shapeMatchesFilter', () => {
+    const shape = {
+        '$': 'object',
+        '$.data': 'object',
+        '$.data.items': 'array(1)',
+        '$.data.items[0].author': 'string',
+        '$.data.items[0].text': 'string',
+        '$.data.items[0].likes': 'number',
+    };
+    it('returns true when every field matches some path segment (AND)', () => {
+        expect(shapeMatchesFilter(shape, ['author', 'text', 'likes'])).toBe(true);
+    });
+    it('matches nested container names, not just leaves (any-segment rule)', () => {
+        // `data` and `items` are container segments, not leaves; still must match.
+        expect(shapeMatchesFilter(shape, ['data', 'items'])).toBe(true);
+    });
+    it('returns false when any field is missing', () => {
+        expect(shapeMatchesFilter(shape, ['author', 'missing'])).toBe(false);
+    });
+    it('is case-sensitive', () => {
+        expect(shapeMatchesFilter(shape, ['Author'])).toBe(false);
+        expect(shapeMatchesFilter(shape, ['author'])).toBe(true);
+    });
+    it('empty filter list vacuously matches', () => {
+        expect(shapeMatchesFilter(shape, [])).toBe(true);
+    });
+    it('rejects requests whose shape has no body (empty shape)', () => {
+        expect(shapeMatchesFilter({}, ['author'])).toBe(false);
+    });
+});

package/dist/src/browser/shape.d.ts

@@ -0,0 +1,23 @@
+/**
+ * JSON shape inference for browser network response previews.
+ *
+ * Produces a flat path → type descriptor map so agents can understand
+ * response structure without paying the token cost of the full body.
+ *
+ * Descriptors:
+ *   string | number | boolean | null              primitives
+ *   string(len=N)                                 strings longer than sampleStringLen
+ *   array(0) | array(N)                           array at depth cap or summarized
+ *   object | object(empty)                        objects at depth cap or summarized
+ *   (truncated)                                   output size budget exceeded
+ */
+export interface InferShapeOptions {
+    /** Max path depth to descend into (default 6) */
+    maxDepth?: number;
+    /** Byte budget for the serialized output; truncates when exceeded (default 2048) */
+    maxBytes?: number;
+    /** Strings longer than this get summarized as `string(len=N)` (default 80) */
+    sampleStringLen?: number;
+}
+export type Shape = Record<string, string>;
+export declare function inferShape(value: unknown, opts?: InferShapeOptions): Shape;