@agentrhq/webcmd 0.2.5 → 0.3.1

package/clis/twitter/article.js

@@ -1,8 +1,13 @@
 import { AuthRequiredError, CommandExecutionError } from '@agentrhq/webcmd/errors';
 import { cli, Strategy } from '@agentrhq/webcmd/registry';
-import { resolveTwitterQueryId, describeTwitterApiError } from './shared.js';
+import { resolveTwitterQueryId, describeTwitterApiError, unwrapBrowserResult } from './shared.js';
 import { TWITTER_BEARER_TOKEN } from './utils.js';
 const TWEET_RESULT_BY_REST_ID_QUERY_ID = '7xflPyRiUxGVbJd4uWmbfg';
+
+function isPlainObject(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
 cli({
     site: 'twitter',
     name: 'article',
@@ -43,10 +48,11 @@ cli({
           return null;
         })()
       `);
-            if (!resolvedId || typeof resolvedId !== 'string') {
+            const resolvedTweetId = unwrapBrowserResult(resolvedId);
+            if (!resolvedTweetId || typeof resolvedTweetId !== 'string') {
                 throw new CommandExecutionError(`Could not resolve article ${tweetId} to a tweet ID. The article page may not contain a linked tweet.`);
             }
-            tweetId = resolvedId;
+            tweetId = resolvedTweetId;
         }
         // Navigate to the tweet page for cookie context
         await page.goto(`https://x.com/i/status/${tweetId}`);
@@ -57,9 +63,9 @@ cli({
         if (!ct0)
             throw new AuthRequiredError('x.com', 'Not logged into x.com (no ct0 cookie)');
         const queryId = await resolveTwitterQueryId(page, 'TweetResultByRestId', TWEET_RESULT_BY_REST_ID_QUERY_ID);
-        const result = await page.evaluate(`
+        const rawResult = unwrapBrowserResult(await page.evaluate(`
       async () => {
-        const tweetId = "${tweetId}";
+        const tweetId = ${JSON.stringify(tweetId)};
         const ct0 = ${JSON.stringify(ct0)};
 
         const bearer = ${JSON.stringify(TWITTER_BEARER_TOKEN)};
@@ -95,18 +101,49 @@ cli({
           + '&features=' + encodeURIComponent(features)
           + '&fieldToggles=' + encodeURIComponent(fieldToggles);
 
-        const resp = await fetch(url, {headers, credentials: 'include'});
+        let resp;
+        try {
+          resp = await fetch(url, {headers, credentials: 'include'});
+        } catch (error) {
+          return {error: 'Twitter article request failed: ' + String(error && error.message || error)};
+        }
         if (!resp.ok) return {httpStatus: resp.status};
-        const d = await resp.json();
+        let d;
+        try {
+          d = await resp.json();
+        } catch {
+          return {error: 'Twitter API response was not valid JSON', hint: 'You may be logged out or the request was blocked'};
+        }
+        if (!d || typeof d !== 'object' || Array.isArray(d)) {
+          return {error: 'Twitter API response payload was malformed'};
+        }
 
-        const result = d.data?.tweetResult?.result;
-        if (!result) return {error: 'Article not found'};
+        const result = d?.data?.tweetResult?.result;
+        if (!result) {
+          if (Array.isArray(d.errors) && d.errors.length > 0) {
+            return {error: 'Twitter TweetResultByRestId returned GraphQL errors: ' + JSON.stringify(d.errors).slice(0, 200)};
+          }
+          return {error: 'Article not found'};
+        }
 
         // Unwrap TweetWithVisibilityResults
+        if (!result || typeof result !== 'object' || Array.isArray(result)) {
+          return {error: 'Twitter API response tweet result was malformed'};
+        }
         const tw = result.tweet || result;
+        if (!tw || typeof tw !== 'object' || Array.isArray(tw)) {
+          return {error: 'Twitter API response tweet result was malformed'};
+        }
         const legacy = tw.legacy || {};
         const user = tw.core?.user_results?.result;
-        const screenName = user?.legacy?.screen_name || user?.core?.screen_name || 'unknown';
+        const returnedTweetId = tw.rest_id || legacy.id_str;
+        if (typeof returnedTweetId !== 'string' || returnedTweetId !== tweetId) {
+          return {error: 'Twitter API response did not match requested tweet ' + tweetId};
+        }
+        const screenName = user?.legacy?.screen_name || user?.core?.screen_name || '';
+        if (typeof screenName !== 'string' || !/^[A-Za-z0-9_]{1,15}$/.test(screenName)) {
+          return {error: 'Twitter API response did not include a valid author screen name for tweet ' + tweetId};
+        }
 
         // Extract article content
         const articleResults = tw.article?.article_results?.result;
@@ -123,15 +160,25 @@ cli({
           }
           return {error: 'Tweet ' + tweetId + ' has no article content'};
         }
+        if (!articleResults || typeof articleResults !== 'object' || Array.isArray(articleResults)) {
+          return {error: 'Twitter API response article result was malformed'};
+        }
 
         const title = articleResults.title || '(Untitled)';
         const contentState = articleResults.content_state || {};
+        if (!contentState || typeof contentState !== 'object' || Array.isArray(contentState)) {
+          return {error: 'Twitter API response article content was malformed'};
+        }
         const blocks = contentState.blocks || [];
+        if (!Array.isArray(blocks)) {
+          return {error: 'Twitter API response article blocks were malformed'};
+        }
 
         // Convert draft.js blocks to Markdown
         const parts = [];
         let orderedCounter = 0;
         for (const block of blocks) {
+          if (!block || typeof block !== 'object' || Array.isArray(block)) continue;
           const blockType = block.type || 'unstyled';
           if (blockType === 'atomic') continue;
           const text = block.text || '';
@@ -158,13 +205,23 @@ cli({
           url: 'https://x.com/' + screenName + '/status/' + tweetId,
         }];
       }
-    `);
-        if (result?.httpStatus) {
-            throw new CommandExecutionError(describeTwitterApiError('TweetResultByRestId', result.httpStatus));
+    `));
+        if (!Array.isArray(rawResult) && !isPlainObject(rawResult)) {
+            throw new CommandExecutionError('Twitter article response payload is malformed');
+        }
+        if (rawResult?.httpStatus) {
+            const message = describeTwitterApiError('TweetResultByRestId', rawResult.httpStatus);
+            if (rawResult.httpStatus === 401 || rawResult.httpStatus === 403) {
+                throw new AuthRequiredError('x.com', message);
+            }
+            throw new CommandExecutionError(message);
+        }
+        if (rawResult?.error) {
+            throw new CommandExecutionError(rawResult.error + (rawResult.hint ? ` (${rawResult.hint})` : ''));
         }
-        if (result?.error) {
-            throw new CommandExecutionError(result.error + (result.hint ? ` (${result.hint})` : ''));
+        if (!Array.isArray(rawResult)) {
+            throw new CommandExecutionError('Twitter article response payload is malformed');
         }
-        return result || [];
+        return rawResult;
     }
 });

package/clis/twitter/article.test.js

@@ -0,0 +1,209 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@agentrhq/webcmd/registry';
+import { AuthRequiredError, CommandExecutionError } from '@agentrhq/webcmd/errors';
+import './article.js';
+
+const TWEET_ID = '1234567890';
+
+function createPage(articleResult) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    getCookies: vi.fn().mockResolvedValue([{ name: 'ct0', value: 'csrf-token' }]),
+    evaluate: vi.fn()
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce(articleResult),
+  };
+}
+
+function createPageWithEvaluateResults(evaluateResults) {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    wait: vi.fn().mockResolvedValue(undefined),
+    getCookies: vi.fn().mockResolvedValue([{ name: 'ct0', value: 'csrf-token' }]),
+    evaluate: vi.fn().mockImplementation(() => Promise.resolve(evaluateResults.shift())),
+  };
+}
+
+function validArticlePayload(tweetOverrides = {}) {
+  return {
+    data: {
+      tweetResult: {
+        result: {
+          tweet: {
+            rest_id: TWEET_ID,
+            legacy: { full_text: 'fallback text' },
+            core: {
+              user_results: {
+                result: { legacy: { screen_name: 'alice' } },
+              },
+            },
+            article: {
+              article_results: {
+                result: {
+                  title: 'Long article',
+                  content_state: {
+                    blocks: [{ type: 'unstyled', text: 'body' }],
+                  },
+                },
+              },
+            },
+            ...tweetOverrides,
+          },
+        },
+      },
+    },
+  };
+}
+
+async function evaluateArticleFetchScript(script, fetchImplementation) {
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = vi.fn(fetchImplementation);
+  try {
+    return await eval(`(${script})`)();
+  } finally {
+    globalThis.fetch = previousFetch;
+  }
+}
+
+function createFetchPage(fetchImplementation) {
+  const page = createPageWithEvaluateResults([]);
+  page.evaluate
+    .mockImplementationOnce(() => Promise.resolve(null))
+    .mockImplementationOnce((script) => evaluateArticleFetchScript(script, fetchImplementation));
+  return page;
+}
+
+function jsonResponse(payload, overrides = {}) {
+  return {
+    ok: true,
+    status: 200,
+    json: vi.fn().mockResolvedValue(payload),
+    ...overrides,
+  };
+}
+
+describe('twitter article command', () => {
+  const command = getRegistry().get('twitter/article');
+  const rows = [{
+    title: 'Long article',
+    author: 'alice',
+    content: 'body',
+    url: `https://x.com/alice/status/${TWEET_ID}`,
+  }];
+
+  it('accepts raw Cloak rows and legacy Browser Bridge envelopes', async () => {
+    await expect(command.func(createPage(rows), { 'tweet-id': TWEET_ID })).resolves.toEqual(rows);
+    await expect(command.func(createPage({ session: 'browser:default', data: rows }), { 'tweet-id': TWEET_ID }))
+      .resolves.toEqual(rows);
+  });
+
+  it('unwraps legacy envelopes while resolving article URLs', async () => {
+    const page = createPageWithEvaluateResults([
+      { session: 'browser:default', data: TWEET_ID },
+      null,
+      rows,
+    ]);
+
+    await expect(command.func(page, { 'tweet-id': 'https://x.com/i/article/987654321' }))
+      .resolves.toEqual(rows);
+    expect(page.goto).toHaveBeenNthCalledWith(1, 'https://x.com/i/article/987654321');
+    expect(page.goto).toHaveBeenNthCalledWith(2, `https://x.com/i/status/${TWEET_ID}`);
+  });
+
+  it('maps 401 and 403 API responses to AuthRequiredError', async () => {
+    for (const httpStatus of [401, 403]) {
+      await expect(command.func(createPage({ httpStatus }), { 'tweet-id': TWEET_ID }))
+        .rejects.toBeInstanceOf(AuthRequiredError);
+    }
+  });
+
+  it('fails closed for malformed evaluated response payloads', async () => {
+    for (const value of [null, 42, {}, { session: 'browser:default', data: {} }]) {
+      await expect(command.func(createPage(value), { 'tweet-id': TWEET_ID }))
+        .rejects.toBeInstanceOf(CommandExecutionError);
+    }
+  });
+
+  it('reports invalid JSON and network failures as typed command errors', async () => {
+    const invalidJsonPage = createFetchPage(async () => ({
+      ok: true,
+      status: 200,
+      json: vi.fn().mockRejectedValue(new SyntaxError('invalid JSON')),
+    }));
+    await expect(command.func(invalidJsonPage, { 'tweet-id': TWEET_ID }))
+      .rejects.toBeInstanceOf(CommandExecutionError);
+
+    const networkPage = createFetchPage(async () => {
+      throw new Error('socket closed');
+    });
+    await expect(command.func(networkPage, { 'tweet-id': TWEET_ID }))
+      .rejects.toBeInstanceOf(CommandExecutionError);
+  });
+
+  it('rejects null and array GraphQL roots', async () => {
+    for (const payload of [null, []]) {
+      const page = createFetchPage(async () => jsonResponse(payload));
+      await expect(command.func(page, { 'tweet-id': TWEET_ID }))
+        .rejects.toBeInstanceOf(CommandExecutionError);
+    }
+  });
+
+  it('surfaces GraphQL errors instead of returning a generic not-found error', async () => {
+    const page = createFetchPage(async () => jsonResponse({
+      errors: [{ message: 'rate limited' }],
+    }));
+
+    await expect(command.func(page, { 'tweet-id': TWEET_ID }))
+      .rejects.toThrow(/GraphQL errors/);
+  });
+
+  it('requires the returned tweet identity to match the request', async () => {
+    const page = createFetchPage(async () => jsonResponse(validArticlePayload({ rest_id: '999' })));
+
+    await expect(command.func(page, { 'tweet-id': TWEET_ID }))
+      .rejects.toThrow(/did not match requested tweet/);
+  });
+
+  it('requires a valid author screen name', async () => {
+    for (const screenName of ['', 'bad/name']) {
+      const payload = validArticlePayload({
+        core: { user_results: { result: { legacy: { screen_name: screenName } } } },
+      });
+      const page = createFetchPage(async () => jsonResponse(payload));
+      await expect(command.func(page, { 'tweet-id': TWEET_ID }))
+        .rejects.toThrow(/valid author screen name/);
+    }
+  });
+
+  it('fails closed for malformed tweet, article, content, and block shapes', async () => {
+    const payloads = [
+      { data: { tweetResult: { result: 'not-an-object' } } },
+      { data: { tweetResult: { result: { tweet: 'not-an-object' } } } },
+      validArticlePayload({ article: { article_results: { result: 'not-an-object' } } }),
+      validArticlePayload({ article: { article_results: { result: { content_state: [] } } } }),
+      validArticlePayload({ article: { article_results: { result: { content_state: { blocks: {} } } } } }),
+    ];
+
+    for (const payload of payloads) {
+      const page = createFetchPage(async () => jsonResponse(payload));
+      await expect(command.func(page, { 'tweet-id': TWEET_ID }))
+        .rejects.toBeInstanceOf(CommandExecutionError);
+    }
+  });
+
+  it('keeps the valid note-tweet fallback', async () => {
+    const payload = validArticlePayload({
+      article: undefined,
+      note_tweet: { note_tweet_results: { result: { text: 'A long note' } } },
+    });
+    const page = createFetchPage(async () => jsonResponse(payload));
+
+    await expect(command.func(page, { 'tweet-id': TWEET_ID })).resolves.toEqual([{
+      title: '(Note Tweet)',
+      author: 'alice',
+      content: 'A long note',
+      url: `https://x.com/alice/status/${TWEET_ID}`,
+    }]);
+  });
+});

package/clis/twitter/download.js

@@ -311,7 +311,12 @@ cli({
         { name: 'username', positional: true, help: 'Twitter username (with or without @) to scan their profile media. Either <username> or --tweet-url is required.' },
         { name: 'tweet-url', help: 'Single tweet URL to download. Use this OR <username>, not both required at once.' },
         { name: 'limit', type: 'int', default: 10, help: 'Maximum number of media items to download when scanning a profile (default 10). Ignored when --tweet-url is used.' },
-        { name: 'output', default: './twitter-downloads', help: 'Output directory (default ./twitter-downloads). A per-source subdir is created inside.' },
+        {
+            name: 'output',
+            default: './twitter-downloads',
+            help: 'Output directory (default ./twitter-downloads). A per-source subdir is created inside.',
+            file: { direction: 'output', pathKind: 'directory', multiple: false },
+        },
     ],
     columns: ['index', 'tweet_id', 'url', 'type', 'status', 'size'],
     func: async (page, kwargs) => {

package/clis/twitter/post.js

@@ -258,7 +258,20 @@ cli({
     browser: true,
     args: [
         { name: 'text', type: 'string', required: true, positional: true, help: 'The text content of the tweet' },
-        { name: 'images', type: 'string', required: false, help: 'Image paths, comma-separated, max 4 (jpg/png/gif/webp)' },
+        {
+            name: 'images',
+            type: 'string',
+            required: false,
+            help: 'Image paths, comma-separated, max 4 (jpg/png/gif/webp)',
+            file: {
+                direction: 'input',
+                pathKind: 'file',
+                multiple: true,
+                separator: ',',
+                contentTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+                maxBytes: 26_214_400,
+            },
+        },
     ],
     columns: ['status', 'message', 'text', 'id', 'url'],
     func: async (page, kwargs) => {

package/clis/twitter/profile.js

@@ -88,7 +88,7 @@ cli({
         const queryId = await resolveTwitterQueryId(page, 'UserByScreenName', USER_BY_SCREEN_NAME_QUERY_ID);
         const rawResult = unwrapBrowserResult(await page.evaluate(`
       async () => {
-        const screenName = "${username}";
+        const screenName = ${JSON.stringify(username)};
         const ct0 = ${JSON.stringify(ct0)};
 
         const bearer = ${JSON.stringify(TWITTER_BEARER_TOKEN)};

package/clis/twitter/profile.test.js

@@ -4,6 +4,14 @@ import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultErr
 import { __test__ } from './profile.js';
 
 describe('twitter profile command', () => {
+    it('serializes the validated screen name before embedding it in page.evaluate', () => {
+        const command = getRegistry().get('twitter/profile');
+        const source = command.func.toString();
+
+        expect(source).toContain('const screenName = ${JSON.stringify(username)};');
+        expect(source).not.toContain('const screenName = "${username}";');
+    });
+
     it('maps current result.core profile fields while preserving legacy fallback fields', () => {
         const rows = __test__.mapTwitterProfileResult({
             core: {

package/clis/twitter/quote.js

@@ -112,7 +112,17 @@ cli({
     args: [
         { name: 'url', type: 'string', required: true, positional: true, help: 'The URL of the tweet to quote' },
         { name: 'text', type: 'string', required: true, positional: true, help: 'The text content of your quote' },
-        { name: 'image', help: 'Optional local image path to attach to the quote tweet' },
+        {
+            name: 'image',
+            help: 'Optional local image path to attach to the quote tweet',
+            file: {
+                direction: 'input',
+                pathKind: 'file',
+                multiple: false,
+                contentTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+                maxBytes: 26_214_400,
+            },
+        },
         { name: 'image-url', help: 'Optional remote image URL to download and attach to the quote tweet' },
     ],
     columns: ['status', 'message', 'text'],

package/clis/twitter/reply.js

@@ -194,7 +194,17 @@ cli({
     args: [
         { name: 'url', type: 'string', required: true, positional: true, help: 'The URL of the tweet to reply to' },
         { name: 'text', type: 'string', required: true, positional: true, help: 'The text content of your reply' },
-        { name: 'image', help: 'Optional local image path to attach to the reply' },
+        {
+            name: 'image',
+            help: 'Optional local image path to attach to the reply',
+            file: {
+                direction: 'input',
+                pathKind: 'file',
+                multiple: false,
+                contentTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+                maxBytes: 26_214_400,
+            },
+        },
         { name: 'image-url', help: 'Optional remote image URL to download and attach to the reply' },
     ],
     columns: ['status', 'message', 'text', 'url'],

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

@@ -18,6 +18,25 @@ export interface ResolveSuccess {
      * clean `exact` match — the page changed, the action still succeeded.
      */
     match_level: TargetMatchLevel;
+    /**
+     * Which physical click path executed: `cdp` (trusted Input.dispatchMouseEvent),
+     * `js` (el.click() fallback), or `ax` (accessibility-node click). Surfaced so
+     * agents can tell a trusted synthetic click from the untrusted JS fallback.
+     */
+    click_method?: 'cdp' | 'js' | 'ax';
+    /**
+     * Result of hit-testing the click point against the resolved element:
+     * `target` (the point lands on the element or a descendant — trustworthy),
+     * `other` (an overlay/sibling covers it — the CDP click would miss), or
+     * `none` (nothing at the point). Only set on click().
+     */
+    hit?: 'target' | 'ancestor' | 'other' | 'none';
+    /**
+     * True when the click was retargeted from the resolved element to a nearby
+     * clickable ancestor (e.g. an <svg> icon whose click handler lives on the
+     * wrapping <div>), so the handler actually fires. See issue #2071.
+     */
+    retargeted?: boolean;
 }
 export interface FillTextResult extends ResolveSuccess {
     filled: boolean;
@@ -139,6 +158,13 @@ export declare abstract class BasePage implements IPage {
     }): Promise<void>;
     networkRequests(includeStatic?: boolean): Promise<unknown[]>;
     consoleMessages(_level?: string): Promise<unknown[]>;
+    /**
+     * Pure client-side sleep with no page evaluation.
+     *
+     * Poll loops that already re-check state should use this instead of
+     * `wait(number)`, whose DOM-stability probe observes the whole document.
+     */
+    sleep(seconds: number): Promise<void>;
     wait(options: number | WaitOptions): Promise<void>;
     snapshot(opts?: SnapshotOptions): Promise<unknown>;
     private collectAxSnapshotTrees;

package/dist/src/browser/base-page.js

@@ -182,23 +182,29 @@ export class BasePage {
         // Phase 2: measure first so native click can run before DOM el.click().
         // Custom dropdowns often listen to pointer/mouse down/up; DOM el.click()
         // only fires click and can silently report success without opening/selecting.
-        const rect = await this.evaluate(boundingRectResolvedJs({ skipScroll: nativeScrolled }));
-        if (rect?.visible === true) {
+        const rect = await this.evaluate(boundingRectResolvedJs({ skipScroll: nativeScrolled, forClick: true }));
+        const meta = { hit: rect?.hit, retargeted: rect?.retargeted };
+        // Trust a CDP click when the point hit-tests onto the target, a descendant,
+        // or an ancestor (open shadow-DOM host / own wrapper — CDP still reaches the
+        // target there). Only an unrelated overlay ('other') forces the el.click()
+        // fallback, which dispatches straight on the node. See issues #2076/#2071.
+        if (rect?.visible === true && (rect.hit === 'target' || rect.hit === 'ancestor')) {
             const success = await this.tryNativeClick(rect.x, rect.y);
             if (success)
-                return resolved;
+                return { ...resolved, click_method: 'cdp', ...meta };
         }
-        // JS fallback for older backends or zero-rect targets.
+        // JS fallback: el.click() dispatches straight on __resolved, bypassing the
+        // occluding overlay (also covers older backends / zero-rect targets).
         const result = await this.evaluate(clickResolvedJs({ skipScroll: nativeScrolled }));
         if (typeof result === 'string' || result == null)
-            return resolved;
+            return { ...resolved, click_method: 'js', ...meta };
         if (result.status === 'clicked')
-            return resolved;
+            return { ...resolved, click_method: 'js', ...meta };
         // JS click failed — try CDP native click if coordinates available
         if (result.x != null && result.y != null) {
             const success = await this.tryNativeClick(result.x, result.y);
             if (success)
-                return resolved;
+                return { ...resolved, click_method: 'cdp', ...meta };
         }
         throw new Error(`Click failed: ${result.error ?? 'JS click and CDP fallback both failed'}`);
     }
@@ -275,7 +281,7 @@ export class BasePage {
             return null;
         try {
             await nativeClick.call(this, resolved.x, resolved.y);
-            return { matches_n: 1, match_level: resolved.matchLevel };
+            return { matches_n: 1, match_level: resolved.matchLevel, click_method: 'ax' };
         }
         catch {
             return null;
@@ -851,6 +857,15 @@ export class BasePage {
     async consoleMessages(_level = 'info') {
         return [];
     }
+    /**
+     * Pure client-side sleep with no page evaluation.
+     *
+     * Poll loops that already re-check state should use this instead of
+     * `wait(number)`, whose DOM-stability probe observes the whole document.
+     */
+    async sleep(seconds) {
+        await new Promise(resolve => setTimeout(resolve, seconds * 1000));
+    }
     async wait(options) {
         if (typeof options === 'number') {
             if (options >= 1) {