cli: add --await and --tab flags to bbx eval

packages/agent-client/src/cli.js

@@ -665,18 +665,27 @@ async function main() {
     }
 
     if (command === 'eval') {
-      let expression = rest.join(' ');
+      const { tabId, rest: evalArgs } = extractTabFlag(rest);
+      // --await: wait for the result if the expression returns a Promise
+      const awaitIndex = evalArgs.indexOf('--await');
+      const awaitPromise = awaitIndex !== -1;
+      if (awaitIndex !== -1) evalArgs.splice(awaitIndex, 1);
+
+      let expression = evalArgs.join(' ');
       if (!expression || expression === '-') expression = await readStdin();
       if (!expression)
-        throw new Error('Usage: eval <expression>  (or pipe via stdin: echo "expr" | bbx eval -)');
+        throw new Error(
+          'Usage: eval [--tab <id>] [--await] <expression>  (or pipe via stdin: echo "expr" | bbx eval -)'
+        );
       const response = await requestBridge(
         client,
         'page.evaluate',
         {
           expression,
           returnByValue: true,
+          ...(awaitPromise ? { awaitPromise: true } : {}),
         },
-        { source: REQUEST_SOURCE }
+        { source: REQUEST_SOURCE, tabId }
       );
       await printSummary(response);
       return;

packages/agent-client/src/command-registry.js

@@ -294,7 +294,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
   {
     title: 'Page',
     lines: [
-      'bbx eval <expression>                                              Evaluate JS in page context (use - for stdin)',
+      'bbx eval [--await] <expression>                                     Evaluate JS in page context (--await for async, - for stdin)',
       ...[
         'console',
         'network',

packages/agent-client/test/cli-commands.test.ts

@@ -1166,6 +1166,6 @@ test('bbx eval with empty stdin reports the usage error', async () => {
   assert.equal(payload.evidence, null);
   assert.equal(
     payload.summary,
-    'ERROR: Usage: eval <expression>  (or pipe via stdin: echo "expr" | bbx eval -)'
+    'ERROR: Usage: eval [--tab <id>] [--await] <expression>  (or pipe via stdin: echo "expr" | bbx eval -)'
   );
 });