Pup - the AI's own browser - docs/contract/pup_describe.json

by adom
pup gives your AI a real browser on your desktop that it drives completely, in the background, signed in as you: windows that never jump in front of your work, one shared profile that learns your logins, and every window labeled on the taskbar with its AI thread's name.
Overview Files Skills Discover Packages Releases Dependencies Issues9 Breadcrumbs Pull Requests Activity
master
History Download
John Lauer docs/contract: golden fixtures recorded from the Node build 2.0.399 for the Rust port 71c0e87 1mo ago
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801
{
  "_hint": "This list — the bridge's verbs + schemas + hints, for AD's Verbs tab. Read it once to learn the surface.",
  "_next": [
    "pup_status"
  ],
  "_timeoutHint": "ab waits up to 60s for this verb before the request times out. If it's a long operation (cloud open / download / export), DON'T treat a timeout as failure — the work usually keeps running on the bridge. Poll `pup_readiness` until it reports done.",
  "bridge": "puppeteer",
  "durationMs": 58,
  "error": "",
  "output": "{\"_hint\":\"This list — the bridge's verbs + schemas + hints, for AD's Verbs tab. Read it once to learn the surface.\",\"_next\":[\"pup_status\"],\"_timeoutHint\":\"ab waits up to 60s for this verb before the request times out. If it's a long operation (cloud open / download / export), DON'T treat a timeout as failure — the work usually keeps running on the bridge. Poll `pup_readiness` until it reports done.\",\"bridge\":\"puppeteer\",\"progressContract\":{\"activeKey\":\"active\",\"blockedByPhases\":[\"consent\",\"dialog\"],\"blockedOnUser\":{\"errorCode\":\"blocked_on_user\",\"inVerbWaitSec\":45,\"promptLifetimeSec\":120,\"rule\":\"ab BRIDGE_SDK 2.1.30: a verb parked on a HUMAN never bare-timeouts; it answers this shape\",\"stillRunning\":\"true = the wait continues in the background: re-call the SAME verb with the SAME args to re-attach (no second prompt) or watch pup_readiness.active[]; false = the human must act first, then re-issue the verb\"},\"slowVerbs\":[\"pup_open_window\",\"pup_prewarm\",\"pup_use\"],\"statusVerb\":\"pup_readiness\",\"timings\":{\"open_window_warm\":{\"confidence\":\"measured\",\"estimatedSec\":11,\"samples\":20}}},\"related\":[\"pup_status\"],\"statusVerb\":\"pup_readiness\",\"success\":true,\"timeoutSeconds\":60,\"verbs\":[{\"example\":{},\"hint\":\"START HERE for window management: everything YOUR thread owns — windows, tabs, urls, titles, state — with ready-to-run next steps. Zero args. You NEVER need an hwnd, desktop_find_window, or desktop_screenshot_window for a pup window: pup keys every window to its owning --ai-thread name and resolves ids for you — omit sessionId in any pup verb to target your own window, or pass \\\"ai-thread\\\" to address a thread by name (the CLI's --ai-thread flag, same spelling). pup_screenshot {} screenshots it; pup_reload {} refreshes it.\",\"input\":{\"ai-thread\":\"optional str — inspect another thread's windows (read-only listing); default = the calling thread. The CLI flag's exact spelling; aiThread also accepted\"},\"longRunning\":false,\"name\":\"pup_my_windows\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"START HERE for window management: everything YOUR thread owns — windows, tabs, urls, titles, state — with ready-to-run next steps. Zero args. You NEVER need an hwnd, desktop_find_window, or desktop_screenshot_window for a pup window: pup keys every window to its owning --ai-thread name and resolves ids for you — omit sessionId in any pup verb to target your own window, or pass \\\"ai-thread\\\" to address a thread by name (the CLI's --ai-thread flag, same spelling). pup_screenshot {} screenshots it; pup_reload {} refreshes it.\",\"timeoutSeconds\":10},{\"example\":{\"height\":540,\"owner\":\"mytask\",\"sessionId\":\"mytask-web\",\"url\":\"https://example.com\",\"width\":960},\"hint\":\"Opens a generic, fully-controllable pup window (a fresh isolated Chrome/Edge process — never your real signed-in browser) that you then drive by sessionId. To drive the user's REAL Chrome/Edge, use the Adom browser extension's nbrowser_* verbs instead.\",\"input\":{\"appIconB64\":\"optional base64 PNG — override the app icon worn in the taskbar overlay. Usually UNNECESSARY: pup auto-fetches the page's own <link rel=\\\"icon\\\"> favicon (the adom-ui-design standard artifact every app must serve) and wears it automatically. An app-looking URL with NO favicon gets a reprimand hint.\",\"appName\":\"optional str — the APP this window is driving (e.g. \\\"shotlog\\\"); shown in the hover tooltip\",\"autoFlash\":\"optional bool (default true) — mutating verbs auto-flash this window's taskbar (debounced, never steals focus) so the user notices the agent touched it; pass false to make this window silent by default\",\"foreground\":\"optional bool — request showing the window on the user's screen. GATED (v1.8.70): requires foregroundReason too, else the open succeeds but stays BACKGROUND with foregroundDenied set. Only when the USER explicitly asked to watch.\",\"foregroundReason\":\"required WITH foreground:true — quote/paraphrase what the user said that justifies putting a window on their screen (min 10 chars; logged + recorded in lastAgentUpdate, auditable)\",\"height\":\"optional int px\",\"isolated\":\"optional bool — private throwaway profile: fresh-login tests, acting as a different user. REASON-GATED (v2.0.101): requires isolationReason or the open is refused — every window defaults to the shared adom-you profile\",\"isolationReason\":\"required WITH isolated:true — why this window must NOT ride the shared adom-you profile (min 10 chars; logged, auditable). webSecurity:false and wikiView:public carry their own built-in reason\",\"owner\":\"optional str — your thread/task label; lets pup protect this window from other threads\",\"profile\":\"optional str — a named durable jar; DEFAULT is the shared \\\"adom-you\\\" profile (signed-in state shared across windows). isolated:true overrides to a throwaway\",\"sessionId\":\"optional str — OMIT IT (recommended): your thread gets its OWN window keyed on your --ai-thread name; the first open creates it, later opens become TABS in it, and no other thread can touch it. Pass an explicit id only when you need a SEPARATE window (task-prefix it, e.g. \\\"mytask-web\\\")\",\"silent\":\"optional bool — suppress the auto-flash for just this call\",\"takeover\":\"optional bool — claim a window owned by another thread (only when the user explicitly asks)\",\"updateNote\":\"optional str — a short \\\"what I did\\\" note, surfaced back in list_tabs/list_windows as lastAgentUpdate so the user knows what changed\",\"url\":\"optional str\",\"webSecurity\":\"optional false — dev escape hatch for cross-origin eval; FORCES isolation so insecure flags never touch the credentialed profile\",\"width\":\"optional int px — sizes for screenshot framing, stays background\",\"wikiView\":\"optional \\\"authed\\\"|\\\"public\\\" — for wiki.adom.inc URLs. THREE distinct cases: (1) OMIT = the shared adom-you profile, LOGGED IN as the user if they have signed into the wiki (the usual case); this is NOT anonymous. (2) \\\"public\\\" = the SERVER renders the page exactly as a signed-out visitor sees it via the ?view=public param (adom/wiki#126: request user nulled, byte-identical to logged-out, private pages 404) — the window STAYS on the shared profile, session untouched, no isolated jar; use this to verify a publish did not leak private source. (3) \\\"authed\\\" = the explicit logged-in view (30-day SSO; first use may need a one-time login — response says wikiLoginNeeded). To compare \\\"what I see\\\" vs \\\"what the world sees\\\", open one \\\"authed\\\" (or omit) AND one \\\"public\\\" tab — do NOT rely on omit for the public view.\",\"x\":\"optional int px\",\"y\":\"optional int px\"},\"longRunning\":false,\"name\":\"pup_open_window\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"sessionId is OPTIONAL: omit it and your thread gets its OWN window (keyed on your --ai-thread name; later opens become tabs in it). Pass one only for a deliberate separate window — it is then your handle for every later call\",\"profile defaults to the durable shared 'adom-you' profile (logins/localStorage persist + are shared across all pup windows); isolated:true for a private throwaway — omit it for a plain \\\"open in pup\\\"\",\"sessionIds are SHARED across all AI threads on this desktop — a generic id (\\\"wiki\\\", \\\"test\\\") may collide with another thread's window and navigating it away steals their work. Use a task-prefixed sessionId + pass owner:\\\"<your-task>\\\" so pup can protect it\",\"reusing an existing sessionId with a new url NAVIGATES that window — check pup_status (shows owner per window) first if unsure\"],\"related\":[\"pup_navigate\",\"pup_list_windows\",\"pup_close_window\"],\"statusVerb\":null,\"summary\":\"Open a generic pup window — a fresh isolated Chrome/Edge process (never your real signed-in browser), fully drivable via CDP. ALWAYS opens in the BACKGROUND (does not steal focus; never disturbs the user's main work; still fully screenshottable/drivable) UNLESS you pass foreground:true — do that ONLY when the user explicitly wants to watch. Pass width+height (+ optional x,y, screen px) to place it at a specific size/position for screenshot framing — this NO LONGER foregrounds it (sizing stays in the background too; default unsized is maximized). profile defaults to the durable shared 'adom-you' profile (logins/localStorage persist + are shared across all pup windows); isolated:true for a private throwaway. OWNERSHIP: sessionIds are shared across ALL AI threads — use a task-prefixed sessionId + owner:\\\"<your-task>\\\" so pup can refuse other threads stealing your window (reusing an existing id with a new url navigates it away; declared cross-owner reuse errors with session_owned_by_another_thread unless takeover:true). (For the user's REAL Chrome/Edge, use the Adom extension's nbrowser_* verbs.)\",\"timeoutSeconds\":60},{\"example\":{\"sessionId\":\"work\",\"url\":\"https://example.com\"},\"hint\":\"Adds a tab to an existing session; returns the new tabId.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"silent\":\"optional bool — suppress the auto-flash for this call\",\"updateNote\":\"optional str — short \\\"what I did\\\" note surfaced in list_tabs as lastAgentUpdate\",\"url\":\"optional str\"},\"longRunning\":false,\"name\":\"pup_open_tab\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"the session must already exist (pup_open_window first)\"],\"related\":[\"pup_switch_tab\",\"pup_list_tabs\",\"pup_close_tab\"],\"statusVerb\":null,\"summary\":\"Open a new tab in an EXISTING session/window (returns {tabId, tabCount, activeTabId} — no need to diff list_tabs). This is the right verb for multi-URL work: ONE window with many tabs (one taskbar button), not many windows. The window stays in the background; the tab auto-flashes the taskbar (debounced) so the user notices. The USER can click the window's taskbar button at any time to view it — pup never pulls it back down.\",\"timeoutSeconds\":30},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"Closes one tab; the session stays open.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"tabId\":\"optional str (default active)\"},\"longRunning\":false,\"name\":\"pup_close_tab\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"omit tabId to close the active tab — closing the last tab may close the window\"],\"related\":[\"pup_close_window\",\"pup_list_tabs\"],\"statusVerb\":null,\"summary\":\"Close a tab.\",\"timeoutSeconds\":15},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"Closes the whole session and all its tabs. Destructive.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_close_window\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"this ends the session — its sessionId is no longer valid afterward\"],\"related\":[\"pup_list_windows\"],\"statusVerb\":null,\"summary\":\"Close a window/session (its tabs go too).\",\"timeoutSeconds\":20},{\"example\":{},\"hint\":\"Everything about ONE pup window as JSON — owner AI thread, container, profile, tabs, age, last agent action, and the window's hwnd (for desktop_screenshot_window when you need the browser chrome in frame). For an AI caller this is a PURE DATA query: nothing is drawn on the user's screen. Visual surfaces are user-initiated only — a jump-list click shows the native taskbar caption, a toolbar-popup click shows the in-page floaty card. showCaption:true opts an AI caller into the caption ONLY when the user asked to have the window identified on screen. Read-only, never owner-gated.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"showCaption\":\"optional bool — draw the ~12s taskbar caption too; ONLY when the user asked to see which window this is\"},\"longRunning\":false,\"name\":\"pup_window_info\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Everything about ONE pup window as JSON — owner AI thread, container, profile, tabs, age, last agent action, and the window's hwnd (for desktop_screenshot_window when you need the browser chrome in frame). For an AI caller this is a PURE DATA query: nothing is drawn on the user's screen. Visual surfaces are user-initiated only — a jump-list click shows the native taskbar caption, a toolbar-popup click shows the in-page floaty card. showCaption:true opts an AI caller into the caption ONLY when the user asked to have the window identified on screen. Read-only, never owner-gated.\",\"timeoutSeconds\":15},{\"example\":{\"sessionId\":\"wiki-bmv080\",\"view\":\"authed\"},\"hint\":\"Flip a WIKI pup window between the logged-in and public view IN PLACE: every wiki tab reloads with the server-side ?view=public param appended (public) or stripped (authed) — adom/wiki#126 renders the request exactly as a signed-out visitor while the session stays untouched, so there is no relaunch, no cookie wipe, no profile switch (the legacy jar relaunch survives only as a fallback for servers that ignore the param). This is the callback for the per-window taskbar jump-list task (WINDOWS ONLY) — a USER-initiated action. AI threads should NOT call this; pass wikiView:\\\"authed\\\"|\\\"public\\\" on pup_open_window instead.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"view\":\"required \\\"authed\\\"|\\\"public\\\"|\\\"toggle\\\" — toggle flips whatever the window currently shows (the Alt+Shift+V hotkey form)\"},\"longRunning\":false,\"name\":\"pup_wiki_set_view\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Flip a WIKI pup window between the logged-in and public view IN PLACE: every wiki tab reloads with the server-side ?view=public param appended (public) or stripped (authed) — adom/wiki#126 renders the request exactly as a signed-out visitor while the session stays untouched, so there is no relaunch, no cookie wipe, no profile switch (the legacy jar relaunch survives only as a fallback for servers that ignore the param). This is the callback for the per-window taskbar jump-list task (WINDOWS ONLY) — a USER-initiated action. AI threads should NOT call this; pass wikiView:\\\"authed\\\"|\\\"public\\\" on pup_open_window instead.\",\"timeoutSeconds\":45},{\"example\":{\"sessionId\":\"work\",\"url\":\"https://example.com\"},\"hint\":\"Drives the active tab to url and waits for load. Verify with a screenshot before asserting success.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"url\":\"required str\"},\"longRunning\":false,\"name\":\"pup_navigate\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"navigation can race SPA routing — confirm with pup_screenshot\",\"some sites need pup_wait for a selector after navigate\"],\"related\":[\"pup_screenshot\",\"pup_wait\",\"pup_reload\"],\"statusVerb\":null,\"summary\":\"Navigate the active tab to a URL.\",\"timeoutSeconds\":45},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"History back on the active tab.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_back\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[\"pup_forward\",\"pup_navigate\"],\"statusVerb\":null,\"summary\":\"History back.\",\"timeoutSeconds\":20},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"History forward on the active tab.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_forward\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[\"pup_back\",\"pup_navigate\"],\"statusVerb\":null,\"summary\":\"History forward.\",\"timeoutSeconds\":20},{\"example\":{},\"hint\":\"Paint the Windows taskbar PROGRESS BAR on your window during a LONG multi-stage task (crawling a site, login->search->download loops, batch harvesting datasheets/STEP files) so the user sees work happening at a glance. mode:\\\"indeterminate\\\" (pulsing) to start, mode:\\\"value\\\" with value:0-100 as stages complete, mode:\\\"off\\\" when done or aborted (always clear!). Optional note:\\\"12/40 datasheets\\\" shows on the button hover tooltip. YOUR judgment: a single quick page open does NOT warrant a progress bar. See the pup-progress skill.\",\"input\":{\"mode\":\"\\\"indeterminate\\\" | \\\"value\\\" | \\\"off\\\"\",\"note\":\"optional short stage label for the hover tooltip\",\"sessionId\":\"optional — defaults to your thread's own window\",\"value\":\"optional 0-100 (mode:\\\"value\\\")\"},\"longRunning\":false,\"name\":\"pup_progress\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Paint the Windows taskbar PROGRESS BAR on your window during a LONG multi-stage task (crawling a site, login->search->download loops, batch harvesting datasheets/STEP files) so the user sees work happening at a glance. mode:\\\"indeterminate\\\" (pulsing) to start, mode:\\\"value\\\" with value:0-100 as stages complete, mode:\\\"off\\\" when done or aborted (always clear!). Optional note:\\\"12/40 datasheets\\\" shows on the button hover tooltip. YOUR judgment: a single quick page open does NOT warrant a progress bar. See the pup-progress skill.\",\"timeoutSeconds\":8},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"Reloads the active tab.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_reload\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"A page with unsaved changes raises a native \\\"Reload site?\\\" dialog that BLOCKS the window: the reload appears to time out and so does everything else. Answer it with pup_dialog.\"],\"related\":[\"pup_navigate\",\"pup_wait\",\"pup_dialog\"],\"statusVerb\":null,\"summary\":\"Reload the active tab.\",\"timeoutSeconds\":30},{\"example\":{\"selector\":\"button#go\",\"sessionId\":\"work\"},\"hint\":\"Clicks by CSS selector (preferred) or by x,y coords. Selector is more robust across layouts.\",\"input\":{\"button\":\"optional \\\"left\\\"|\\\"right\\\"|\\\"middle\\\"\",\"clickCount\":\"optional int 1-3\",\"domClick\":\"optional bool — dispatch a synthetic element.click() instead of a trusted CDP click; for React controls that ignore trusted clicks\",\"selector\":\"optional str\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"x\":\"optional int\",\"y\":\"optional int\"},\"longRunning\":false,\"name\":\"pup_click\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"selector must match exactly one visible element — verify with pup_evaluate first\",\"coords are viewport-relative; a scrolled element may be off-screen\"],\"related\":[\"pup_type\",\"pup_input_dispatch\",\"pup_screenshot\"],\"statusVerb\":null,\"summary\":\"Click an element (by selector or coords). Selector clicks LOCATE the element once then click by its center coordinates (fast on huge/animated DOMs, where page.click used to hit the 15s wall). Response includes method. If a React toggle/like/heart does NOT change state after a normal click, that control ignores trusted clicks — retry with domClick:true to fire a synthetic element.click().\",\"timeoutSeconds\":20},{\"example\":{\"label\":\"your Google account\",\"reason\":\"clicking your Google account to finish signing into Autodesk\",\"sessionId\":\"adsk\",\"x\":900,\"y\":379},\"hint\":\"RESPECTFUL real-cursor click for a surface pup CDP cannot drive (a NATIVE OS dialog, or a cross-origin FedCM \\\"Sign in with Google\\\" account chooser that rejects every in-page click). Do NOT hand-roll raise+desktop_click for these — use THIS. It: captions the reason + toasts BEFORE touching the screen; foregrounds; then WAITS, detecting if the user alt-tabbed away and holding (captioning \\\"Adom is waiting — click back when ready\\\") until the user is actually on the window; then runs the TIGHT real-cursor hover->click that FedCM accepts (interleaving any screenshot/eval between raise and click makes the click silently no-op); captions each step. Times out as user_not_ready clicking NOTHING if they never return. First take a desktop_screenshot_window of the session to read the target's WINDOW-pixel x,y.\",\"input\":{\"label\":\"required str — WHAT you are clicking (e.g. \\\"your Google account\\\")\",\"maxWaitMs\":\"optional int — how long to wait for the user (default 120000)\",\"reason\":\"required str — WHY you must click (shown to the user as a caption)\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"x\":\"required int — WINDOW-image pixel of the target (from desktop_screenshot_window)\",\"y\":\"required int\"},\"longRunning\":false,\"name\":\"pup_assisted_click\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"RESPECTFUL real-cursor click for a surface pup CDP cannot drive (a NATIVE OS dialog, or a cross-origin FedCM \\\"Sign in with Google\\\" account chooser that rejects every in-page click). Do NOT hand-roll raise+desktop_click for these — use THIS. It: captions the reason + toasts BEFORE touching the screen; foregrounds; then WAITS, detecting if the user alt-tabbed away and holding (captioning \\\"Adom is waiting — click back when ready\\\") until the user is actually on the window; then runs the TIGHT real-cursor hover->click that FedCM accepts (interleaving any screenshot/eval between raise and click makes the click silently no-op); captions each step. Times out as user_not_ready clicking NOTHING if they never return. First take a desktop_screenshot_window of the session to read the target's WINDOW-pixel x,y.\",\"timeoutSeconds\":130},{\"example\":{\"clear\":true,\"selector\":\"#user\",\"sessionId\":\"work\",\"text\":\"adominc1\"},\"hint\":\"Types into the focused or selector-targeted field.\",\"input\":{\"clear\":\"optional bool — empty the field first (replace, not append)\",\"selector\":\"optional str\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"text\":\"required str\"},\"longRunning\":false,\"name\":\"pup_type\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"focus the field first (pup_click the input) or pass selector\",\"does not clear existing text — select-all + delete if you need a clean field\"],\"related\":[\"pup_click\",\"pup_press_key\"],\"statusVerb\":null,\"summary\":\"Type text into a field via real CDP keystrokes (isTrusted). Reads the value back and returns valueLanded — real keystrokes only register in a FOREGROUNDED window, so if valueLanded:false the field stayed empty (the silent no-op): use pup_fill (background-safe) for a non-React input, or pup_login {realKeystrokes:true} for a login form. Pass clear:true to REPLACE instead of appending.\",\"timeoutSeconds\":20},{\"example\":{\"selector\":\"#email\",\"sessionId\":\"work\",\"text\":\"[email protected]\"},\"hint\":\"Set a field's value in the BACKGROUND (no foreground, no keystrokes): writes .value via the native setter and fires input+change so React/Vue/Angular controlled inputs pick it up. The fix for pup_type's silent no-op on a backgrounded window. Reads the value back and returns valueLanded. For React-MASKED password fields that reject programmatic writes, use pup_login {realKeystrokes:true} instead.\",\"input\":{\"selector\":\"required str\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"text\":\"required str\"},\"longRunning\":false,\"name\":\"pup_fill\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Set a field's value in the BACKGROUND (no foreground, no keystrokes): writes .value via the native setter and fires input+change so React/Vue/Angular controlled inputs pick it up. The fix for pup_type's silent no-op on a backgrounded window. Reads the value back and returns valueLanded. For React-MASKED password fields that reject programmatic writes, use pup_login {realKeystrokes:true} instead.\",\"timeoutSeconds\":20},{\"example\":{\"key\":\"a\",\"modifiers\":[\"Control\"],\"sessionId\":\"work\"},\"hint\":\"Presses a key or chord (Enter, Ctrl+A, Tab).\",\"input\":{\"key\":\"required str\",\"modifiers\":\"optional array — any of [\\\"Control\\\",\\\"Shift\\\",\\\"Alt\\\",\\\"Meta\\\"] (aliases ctrl/cmd/command/option accepted); held down around the key press\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_press_key\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"chord syntax is \\\"Ctrl+A\\\" — verify the page has focus on the intended element\"],\"related\":[\"pup_type\",\"pup_input_dispatch\"],\"statusVerb\":null,\"summary\":\"Press a key, optionally with modifier chords held (Ctrl+A, Ctrl+V, Shift+Tab).\",\"timeoutSeconds\":15},{\"example\":{},\"hint\":\"⛔ READ BEFORE USING AD's desktop_click / desktop_type / desktop_press_key ON A PUP WINDOW. Native OS input does NOT target a window — it goes to WHATEVER WINDOW HAS OS FOCUS at that instant. This user runs many AI threads and alt-tabs away from a foregrounded window almost immediately. If you fire native input without warning them, your keystrokes land in THEIR document (this happened: a username was typed into the user's own window). REQUIRED: notify_user toast + desktop_caption FIRST, tell them explicitly \\\"don't type or click until I say done\\\", wait until the window is genuinely foreground, re-verify immediately before EACH event, and caption when done. pup_assisted_click already does all of this — use it. And ALWAYS prefer CDP input (pup_click/pup_type/pup_hover): it needs no foreground and disturbs nobody. A native verb returning ok:true means the event was dispatched to the OS, NOT that it reached your window.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_NATIVE_INPUT_WARNING\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"⛔ READ BEFORE USING AD's desktop_click / desktop_type / desktop_press_key ON A PUP WINDOW. Native OS input does NOT target a window — it goes to WHATEVER WINDOW HAS OS FOCUS at that instant. This user runs many AI threads and alt-tabs away from a foregrounded window almost immediately. If you fire native input without warning them, your keystrokes land in THEIR document (this happened: a username was typed into the user's own window). REQUIRED: notify_user toast + desktop_caption FIRST, tell them explicitly \\\"don't type or click until I say done\\\", wait until the window is genuinely foreground, re-verify immediately before EACH event, and caption when done. pup_assisted_click already does all of this — use it. And ALWAYS prefer CDP input (pup_click/pup_type/pup_hover): it needs no foreground and disturbs nobody. A native verb returning ok:true means the event was dispatched to the OS, NOT that it reached your window.\",\"timeoutSeconds\":0},{\"example\":{\"reset\":true,\"sessionId\":\"work\"},\"hint\":\"Pin the page viewport (CDP device-metrics) to an exact size for deterministic screenshots — OR clear that pin. ⚠ A pin PERSISTS: it survives navigation and hard reload, and while set the window stops tracking OS resizing (a human resizing it sees no reflow, which looks exactly like an app layout bug). ALWAYS clear it when done. Reported as emulatedViewport in pup_status / pup_list_windows.\",\"input\":{\"deviceScaleFactor\":\"optional number (default 1)\",\"height\":\"int — required unless reset\",\"reset\":\"optional bool — CLEAR the override and track the OS window again (width/height not needed)\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"width\":\"int — required unless reset\"},\"longRunning\":false,\"name\":\"pup_set_viewport\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Pin the page viewport (CDP device-metrics) to an exact size for deterministic screenshots — OR clear that pin. ⚠ A pin PERSISTS: it survives navigation and hard reload, and while set the window stops tracking OS resizing (a human resizing it sees no reflow, which looks exactly like an app layout bug). ALWAYS clear it when done. Reported as emulatedViewport in pup_status / pup_list_windows.\",\"timeoutSeconds\":15},{\"example\":{},\"hint\":\"Status/trigger for the toolbar extension, which AUTO-INSTALLS invisibly at every profile launch (transient pipe-launch + CDP Extensions.loadUnpacked; persists in the profile). Running profiles pick it up on their next launch; cold profiles install immediately.\",\"input\":{\"profile\":\"optional, default adom-you\"},\"longRunning\":false,\"name\":\"pup_install_toolbar\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Status/trigger for the toolbar extension, which AUTO-INSTALLS invisibly at every profile launch (transient pipe-launch + CDP Extensions.loadUnpacked; persists in the profile). Running profiles pick it up on their next launch; cold profiles install immediately.\",\"timeoutSeconds\":30},{\"example\":{},\"hint\":\"TEST SEAM: simulate a user click on the floaty pencil (fires the same host click handler a mouse does; the sweep then starts annotate within ~4s). Built for the recurring floaty ralph — assert the annotate overlay appears after calling this.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"tabId\":\"optional tab\"},\"longRunning\":false,\"name\":\"pup_floaty_click\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"TEST SEAM: simulate a user click on the floaty pencil (fires the same host click handler a mouse does; the sweep then starts annotate within ~4s). Built for the recurring floaty ralph — assert the annotate overlay appears after calling this.\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"Start the HUMAN annotation overlay on a window's active tab (pen/arrow/box/text toolbar injected in-page; also on every window's taskbar jump list as \\\"Annotate this page\\\"). Two capture modes the user can also flip in the toolbar: \\\"auto\\\" (default) captures the instant the mouse lifts — the one-red-circle case; \\\"multi\\\" accumulates shapes (color swatches: red/blue/yellow one click, more in a flyout) and captures ONCE on Done. Done captures a PNG AND leaves the drawing in the DOM, so the owning thread's next pup_screenshot shows exactly what the user marked — check session.lastAnnotation via pup_list_windows. action:\\\"cancel\\\" removes the overlay.\",\"input\":{\"action\":\"optional \\\"cancel\\\"\",\"mode\":\"optional \\\"auto\\\"|\\\"multi\\\"\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_annotate\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Start the HUMAN annotation overlay on a window's active tab (pen/arrow/box/text toolbar injected in-page; also on every window's taskbar jump list as \\\"Annotate this page\\\"). Two capture modes the user can also flip in the toolbar: \\\"auto\\\" (default) captures the instant the mouse lifts — the one-red-circle case; \\\"multi\\\" accumulates shapes (color swatches: red/blue/yellow one click, more in a flyout) and captures ONCE on Done. Done captures a PNG AND leaves the drawing in the DOM, so the owning thread's next pup_screenshot shows exactly what the user marked — check session.lastAnnotation via pup_list_windows. action:\\\"cancel\\\" removes the overlay.\",\"timeoutSeconds\":15},{\"example\":{},\"hint\":\"Open the LIVE pup management dashboard in its OWN window (its own profile, so its own taskbar icon). Shows every window pup is driving as taskbar button -> window(s) -> tabs with each tab favicon, owning AI thread, foreground/background + the reason given to foreground it, highFps lease, uptime, and WHY each overlay icon was chosen. Live over SSE. Reuses the one window on repeat calls; backgrounded by default like any pup window.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_dashboard\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Open the LIVE pup management dashboard in its OWN window (its own profile, so its own taskbar icon). Shows every window pup is driving as taskbar button -> window(s) -> tabs with each tab favicon, owning AI thread, foreground/background + the reason given to foreground it, highFps lease, uptime, and WHY each overlay icon was chosen. Live over SSE. Reuses the one window on repeat calls; backgrounded by default like any pup window.\",\"timeoutSeconds\":30},{\"example\":{},\"hint\":\"Report pup dependency health (wiki issue #15): depsPresent, selfInstalledThisBoot, lastError. Use this to answer \\\"is pup broken?\\\" without reading spawn logs.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_deps\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Report pup dependency health (wiki issue #15): depsPresent, selfInstalledThisBoot, lastError. Use this to answer \\\"is pup broken?\\\" without reading spawn logs.\",\"timeoutSeconds\":10},{\"example\":{\"selector\":\"#menu\",\"sessionId\":\"work\"},\"hint\":\"Move the pointer over a target WITHOUT clicking (reveals tooltips / hover menus). Glides the visible Adom cursor there too.\",\"input\":{\"intent\":\"optional str — narrated on the cursor label\",\"selector\":\"optional str\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"steps\":\"optional int (default 8)\",\"x\":\"optional int\",\"y\":\"optional int\"},\"longRunning\":false,\"name\":\"pup_hover\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Move the pointer over a target WITHOUT clicking (reveals tooltips / hover menus). Glides the visible Adom cursor there too.\",\"timeoutSeconds\":15},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"Maximize (or restore/fullscreen/minimize) a pup window via CDP — no AD desktop verb required. Does NOT foreground it.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"state\":\"optional \\\"maximized\\\"|\\\"normal\\\"|\\\"minimized\\\"|\\\"fullscreen\\\" (default maximized)\"},\"longRunning\":false,\"name\":\"pup_maximize\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Maximize (or restore/fullscreen/minimize) a pup window via CDP — no AD desktop verb required. Does NOT foreground it.\",\"timeoutSeconds\":15},{\"example\":{\"avatarB64\":\"<base64 png>\",\"name\":\"John Lauer\"},\"hint\":\"Set the Adom identity shown in the floating owner chip on every pup window (avatar + name). Chrome's own profile chip cannot take a custom local image (Google sign-in only), so the user's Adom avatar lives here instead. Pass a pre-circle-cropped PNG as base64. Applies to live windows immediately + persists.\",\"input\":{\"avatarB64\":\"optional str — base64 PNG (ideally ~48px, circle-cropped); the leading data: prefix is stripped if present\",\"clear\":\"optional bool — remove the stored avatar + name\",\"enabled\":\"optional bool — turn the whole owner chip on/off\",\"name\":\"optional str — display name shown in the chip tooltip\"},\"longRunning\":false,\"name\":\"pup_set_identity\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Set the Adom identity shown in the floating owner chip on every pup window (avatar + name). Chrome's own profile chip cannot take a custom local image (Google sign-in only), so the user's Adom avatar lives here instead. Pass a pre-circle-cropped PNG as base64. Applies to live windows immediately + persists.\",\"timeoutSeconds\":15},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"PNG of the page. Your primary way to SEE state — call it after navigate/click to confirm.\",\"input\":{\"fullPage\":\"optional bool\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_screenshot\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"default is the viewport; pass fullPage:true for the whole scroll height\"],\"related\":[\"pup_screenshot_full_res\",\"pup_navigate\"],\"statusVerb\":null,\"summary\":\"Screenshot the page (PNG; fullPage optional). NOTE: fullPage only covers DOCUMENT-level scroll — on SPAs that scroll inside a nested container it returns just the viewport + a nestedScroll hint; use pup_screenshot_element or pup_scroll for those.\",\"timeoutSeconds\":30},{\"example\":{\"selector\":\".download-card\",\"sessionId\":\"work\"},\"hint\":\"Screenshot ONE element, resolved by CSS selector OR visible text (pierces shadow DOM), scrolled into view first. The clean way to grab a single card/widget on a component-heavy page. Text matches the TIGHTEST text node — to capture the enclosing CARD, add closest (e.g. {text:\\\"Download…\\\", closest:\\\".download-card\\\"}); with closest, an ambiguous phrase still lands on the real widget (skips prose that has no such ancestor). Returns base64 + filePath like pup_screenshot.\",\"input\":{\"closest\":\"optional selector — climb to the nearest ancestor matching it (the card container)\",\"deep\":\"optional bool — pierce shadow DOM (default true)\",\"padding\":\"optional int px around the element\",\"selector\":\"CSS selector (or use text)\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"text\":\"visible text to match (or use selector)\"},\"longRunning\":false,\"name\":\"pup_screenshot_element\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Screenshot ONE element, resolved by CSS selector OR visible text (pierces shadow DOM), scrolled into view first. The clean way to grab a single card/widget on a component-heavy page. Text matches the TIGHTEST text node — to capture the enclosing CARD, add closest (e.g. {text:\\\"Download…\\\", closest:\\\".download-card\\\"}); with closest, an ambiguous phrase still lands on the real widget (skips prose that has no such ancestor). Returns base64 + filePath like pup_screenshot.\",\"timeoutSeconds\":30},{\"example\":{\"sessionId\":\"work\",\"toText\":\"Download\"},\"hint\":\"Scroll the ACTUAL scrolling element (nearest ancestor whose scrollHeight>clientHeight, NOT just window — window.scrollTo no-ops on nested-scroll SPAs). Scroll by delta {dy,dx} OR to an element {toSelector|toText} (pierces shadow DOM). Returns {scrollElement, scrollTop, scrollHeight, clientHeight} so you can confirm it landed.\",\"input\":{\"behavior\":\"optional auto|smooth\",\"block\":\"optional start|center|end (for scroll-to; default center)\",\"dx\":\"optional int px\",\"dy\":\"optional int px (down+/up-)\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"toSelector\":\"optional CSS selector to scroll to\",\"toText\":\"optional visible text to scroll to\"},\"longRunning\":false,\"name\":\"pup_scroll\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Scroll the ACTUAL scrolling element (nearest ancestor whose scrollHeight>clientHeight, NOT just window — window.scrollTo no-ops on nested-scroll SPAs). Scroll by delta {dy,dx} OR to an element {toSelector|toText} (pierces shadow DOM). Returns {scrollElement, scrollTop, scrollHeight, clientHeight} so you can confirm it landed.\",\"timeoutSeconds\":30},{\"example\":{\"height\":900,\"sessionId\":\"work\",\"width\":1280},\"hint\":\"Set the page viewport (CDP device-metrics) deterministically, independent of the OS window size — fixes a too-small innerWidth so fullPage/element shots render at a known width. width+height required.\",\"input\":{\"deviceScaleFactor\":\"optional number (default 1)\",\"height\":\"required int px\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"width\":\"required int px\"},\"longRunning\":false,\"name\":\"pup_set_viewport\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Set the page viewport (CDP device-metrics) deterministically, independent of the OS window size — fixes a too-small innerWidth so fullPage/element shots render at a known width. width+height required.\",\"timeoutSeconds\":15},{\"example\":{\"expression\":\"document.title\",\"sessionId\":\"work\"},\"hint\":\"Runs JS in the page and returns the result — use it to read DOM state or verify selectors before acting.\",\"input\":{\"expression\":\"required str — aliases accepted: expr, script, js, code\",\"frame\":\"optional str — run inside this iframe instead of the top document\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_evaluate\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"the expression must be serializable JSON in its return value\",\"runs in the page context, not Node\"],\"related\":[\"pup_click\",\"pup_fetch_url\"],\"statusVerb\":null,\"summary\":\"Evaluate JS in the page and return the result — THE verb for reading DOM state / asserting on a page (same handler as pup_eval). Add frame:\\\"<name|url-substring|index>\\\" to run inside an iframe.\",\"timeoutSeconds\":30},{\"example\":{\"sessionId\":\"work\",\"url\":\"https://api.example.com\"},\"hint\":\"Fetches a URL using the tab's live cookies/session — for authed APIs the bare CLI can't reach. Returns bodyBase64.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"url\":\"required str\"},\"longRunning\":false,\"name\":\"pup_fetch_url\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"for session-scoped URLs pass the tabId whose cookies you need\",\"returns base64 — decode it caller-side\"],\"related\":[\"pup_navigate\",\"pup_evaluate\"],\"statusVerb\":null,\"summary\":\"Fetch a URL's content via the browser (cookies/session intact).\",\"timeoutSeconds\":45},{\"example\":{\"selector\":\"button.download\",\"sessionId\":\"work\"},\"hint\":\"Download a file THROUGH THE BROWSER, exactly as the user clicking it would — real session, real cookies, real anti-bot cookies — and Chrome saves it to the Downloads folder. This is the right verb for vendor files (datasheets, KiCad/Altium libraries, STEP 3D models) that a server-side fetch/curl can never get past the site's bot wall. Pass selector to click the actual download button (authentic), or url to force-download via an in-page a[download]. Confirms completion via Chrome's download events and returns the ACTUAL saved path + byte count + file magic. For a gated file, log in on the window first (pup_login).\",\"input\":{\"saveAs\":\"optional str — filename override\",\"saveDir\":\"optional str — default the user's Downloads folder\",\"selector\":\"optional str — the real download control to click\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"url\":\"optional str — download this URL via an in-page a[download] click\"},\"longRunning\":false,\"name\":\"pup_download\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Download a file THROUGH THE BROWSER, exactly as the user clicking it would — real session, real cookies, real anti-bot cookies — and Chrome saves it to the Downloads folder. This is the right verb for vendor files (datasheets, KiCad/Altium libraries, STEP 3D models) that a server-side fetch/curl can never get past the site's bot wall. Pass selector to click the actual download button (authentic), or url to force-download via an in-page a[download]. Confirms completion via Chrome's download events and returns the ACTUAL saved path + byte count + file magic. For a gated file, log in on the window first (pup_login).\",\"timeoutSeconds\":100},{\"example\":{\"sessionId\":\"work\",\"type\":\"mousePressed\",\"x\":100,\"y\":200},\"hint\":\"Low-level CDP mouse/keyboard input at coords — beats some overlays/iframes that swallow synthetic clicks.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"type\":\"required str\",\"x\":\"optional int\",\"y\":\"optional int\"},\"longRunning\":false,\"name\":\"pup_input_dispatch\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"coords are viewport pixels\",\"last-resort when pup_click can't reach the element — still cannot pass Cloudflare interactive challenges\"],\"related\":[\"pup_click\",\"pup_press_key\"],\"statusVerb\":null,\"summary\":\"Low-level input (mouse/keyboard) at coords — beats some overlays.\",\"timeoutSeconds\":20},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"Starts video recording of the page for this session.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_record_start\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"one recording per session — stop the current one before starting another\"],\"related\":[\"pup_record_stop\",\"pup_record_status\"],\"statusVerb\":null,\"summary\":\"Start recording the page (video).\",\"timeoutSeconds\":20},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"Stops recording and returns the saved file path.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_record_stop\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"no-op if nothing is recording for this session\"],\"related\":[\"pup_record_start\",\"pup_record_list\"],\"statusVerb\":null,\"summary\":\"Stop recording; returns the saved file.\",\"timeoutSeconds\":30},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"Whether a recording is active for the session.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_record_status\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[\"pup_record_start\",\"pup_record_stop\"],\"statusVerb\":null,\"summary\":\"Recording status for a session.\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"Lists saved page recordings.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_record_list\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[\"pup_record_start\"],\"statusVerb\":null,\"summary\":\"List recordings.\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"Open pup's Chrome screen-share recorder HUD (WebM; consent = the visible HUD). Canonical name (pup-bridge#94).\",\"input\":{\"reason\":\"str (required)\"},\"longRunning\":false,\"name\":\"pup_recorder_open\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Open pup's Chrome screen-share recorder HUD (WebM; consent = the visible HUD). Canonical name (pup-bridge#94).\",\"timeoutSeconds\":20},{\"example\":{},\"hint\":\"Start a whole-screen recording through Chrome screen-share (WebM VP9, system audio + mic). Canonical name; for a background no-browser MP4 of one window use ab-core desktop_record_window_start.\",\"input\":{\"audio\":\"bool\",\"confirmDesktopNotTabRecording\":\"true\",\"fps\":\"int\",\"maxDurationMs\":\"int\",\"reason\":\"str (required)\"},\"longRunning\":false,\"name\":\"pup_screen_record_start\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Start a whole-screen recording through Chrome screen-share (WebM VP9, system audio + mic). Canonical name; for a background no-browser MP4 of one window use ab-core desktop_record_window_start.\",\"timeoutSeconds\":20},{\"example\":{},\"hint\":\"Stop the Chrome screen recording; returns the .webm path.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_screen_record_stop\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Stop the Chrome screen recording; returns the .webm path.\",\"timeoutSeconds\":30},{\"example\":{},\"hint\":\"Status of the Chrome screen recorder + any active clip.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_screen_record_status\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Status of the Chrome screen recorder + any active clip.\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"List completed Chrome screen recordings on disk.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_screen_record_list\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"List completed Chrome screen recordings on disk.\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"Close the Chrome screen-recorder HUD (auto-stops a clip).\",\"input\":{},\"longRunning\":false,\"name\":\"pup_recorder_close\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Close the Chrome screen-recorder HUD (auto-stops a clip).\",\"timeoutSeconds\":15},{\"example\":{},\"hint\":\"Opens the desktop screen-recorder UI window. OWNERSHIP: the desktop_ namespace is ab-core's; pup serves these on ab's behalf only until ab-core's native whole-desktop recorder lands (adom-bridge#143), then they leave pup. Tab recording (pup_record_*) is pup's own.\",\"input\":{},\"longRunning\":false,\"name\":\"desktop_recorder_open\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[\"desktop_record_start\",\"desktop_recorder_close\"],\"statusVerb\":null,\"summary\":\"ALIAS of pup_recorder_open (routes to ab-core once its native recorder lands, adom-bridge#143).\",\"timeoutSeconds\":20},{\"example\":{},\"hint\":\"Starts a full desktop screen recording (served by pup for ab-core until adom-bridge#143 lands; needs ffmpeg on the box for the duration header).\",\"input\":{\"outPath\":\"optional str\"},\"longRunning\":false,\"name\":\"desktop_record_start\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"only one desktop recording at a time\"],\"related\":[\"desktop_record_stop\",\"desktop_record_status\"],\"statusVerb\":null,\"summary\":\"ALIAS of pup_screen_record_start (routes to ab-core once its native recorder lands, adom-bridge#143).\",\"timeoutSeconds\":20},{\"example\":{},\"hint\":\"Stops the desktop recording and returns the file.\",\"input\":{},\"longRunning\":false,\"name\":\"desktop_record_stop\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[\"desktop_record_start\",\"desktop_record_list\"],\"statusVerb\":null,\"summary\":\"ALIAS of pup_screen_record_stop.\",\"timeoutSeconds\":30},{\"example\":{},\"hint\":\"Cold-start readiness probe: {ready, chromeForTestingInstalled, installing, installProgressPct}. On a fresh PC, poll this until ready:true before pup_open_window — the bridge auto-installs Chrome for Testing on its own.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_readiness\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"ready:false with installing:true just means Chrome for Testing is still downloading — wait + poll, do NOT treat it as an error\",\"installPhase:\\\"failed\\\" → surface lastError to the user (usually network/proxy blocking the download, or low disk)\"],\"related\":[\"pup_prewarm\",\"pup_open_window\"],\"statusVerb\":null,\"summary\":\"Readiness + which browser pup will drive (installed Chrome/Edge, or cached Chrome for Testing) + the full candidate list and current default. READ-ONLY; never downloads.\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"Installs Chrome for Testing (the browser pup drives) WITHOUT opening a window — the warm-before-first-use path. Returns fast; poll pup_readiness for completion.\",\"input\":{\"setDefault\":\"optional bool (default true) — pin CfT as the default\",\"wait\":\"optional bool — block until installed\"},\"longRunning\":false,\"name\":\"pup_prewarm\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[\"the ~150 MB download needs network access to storage.googleapis.com\",\"does not open a window — call pup_open_window once readiness reports ready:true\"],\"related\":[\"pup_readiness\",\"pup_open_window\"],\"statusVerb\":null,\"summary\":\"Install Chrome for Testing WITHOUT opening a window, and pin it as the default. Use when you specifically want CfT rather than the machine's installed Chrome/Edge.\",\"timeoutSeconds\":240},{\"example\":{},\"hint\":\"Pin (or clear) the browser pup drives by default: chrome | edge | cft | auto (or an explicit executablePath). \\\"cft\\\" fetches Chrome for Testing then pins it. With {browser:\\\"chrome\\\", install:true} it DOWNLOADS & INSTALLS real Google Chrome on an Edge-only box, then pins it — SILENT on a normal PC; on a locked-down box (VM/managed device) it needs a Windows approval, so the bridge pops a native \\\"click YES on the UAC\\\" notification and, if it expires, re-notifies with a one-tap \\\"Approve now\\\" (all autonomous — no AI turn). Poll pup_readiness.chromeStablePhase: installing → awaiting_uac → ready. Persists across restarts; launch still spawn-verifies + falls back.\",\"input\":{\"browser\":\"\\\"chrome\\\" | \\\"edge\\\" | \\\"cft\\\" | \\\"auto\\\"\",\"elevate\":\"optional \\\"auto\\\"(default)|true|false — auto: quiet install, prompt only if it needs admin; false: never prompt; true: go straight to the prompt\",\"executablePath\":\"optional — pin an exact browser binary\",\"install\":\"optional bool — with browser:\\\"chrome\\\", install real Chrome if missing\"},\"longRunning\":false,\"name\":\"pup_use\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Pin (or clear) the browser pup drives by default: chrome | edge | cft | auto (or an explicit executablePath). \\\"cft\\\" fetches Chrome for Testing then pins it. With {browser:\\\"chrome\\\", install:true} it DOWNLOADS & INSTALLS real Google Chrome on an Edge-only box, then pins it — SILENT on a normal PC; on a locked-down box (VM/managed device) it needs a Windows approval, so the bridge pops a native \\\"click YES on the UAC\\\" notification and, if it expires, re-notifies with a one-tap \\\"Approve now\\\" (all autonomous — no AI turn). Poll pup_readiness.chromeStablePhase: installing → awaiting_uac → ready. Persists across restarts; launch still spawn-verifies + falls back.\",\"timeoutSeconds\":240},{\"example\":{},\"hint\":\"Send a pup window to the BACKGROUND (behind the user's windows) without stealing focus — still fully drivable. The default for open; use this to re-hide a window you foregrounded.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_lower_os_window\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Send a pup window to the BACKGROUND (behind the user's windows) without stealing focus — still fully drivable. The default for open; use this to re-hide a window you foregrounded.\",\"timeoutSeconds\":15},{\"example\":{\"foregroundReason\":\"user said \\\"show me the wiki page\\\"\"},\"hint\":\"Bring a pup window to the FOREGROUND (user's screen). GATED (v1.8.70): REFUSED with foreground_reason_required unless you pass foregroundReason — a quote/paraphrase of what the user said that justifies it (min 10 chars; logged, recorded in lastAgentUpdate, auditable). Allowed ONLY when the user EXPLICITLY must SEE it (a demo, recording, \\\"show me\\\"). It STEALS focus — to just signal \\\"I updated this window\\\", use pup_alert_window (or the auto-flash), NOT raise. After the show-me: pup_lower_os_window to return it to the background. Alias: pup_focus_window. IMPORTANT: if you are foregrounding in order to CLICK a native dialog or a cross-origin FedCM/Google account chooser, do NOT raise-then-click yourself — use pup_assisted_click, which waits for the user to actually be on the window (alt-tab aware) and narrates via captions, so you never act while they are not ready.\",\"input\":{\"foregroundReason\":\"REQUIRED — why the user asked to see this window\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_raise_os_window\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Bring a pup window to the FOREGROUND (user's screen). GATED (v1.8.70): REFUSED with foreground_reason_required unless you pass foregroundReason — a quote/paraphrase of what the user said that justifies it (min 10 chars; logged, recorded in lastAgentUpdate, auditable). Allowed ONLY when the user EXPLICITLY must SEE it (a demo, recording, \\\"show me\\\"). It STEALS focus — to just signal \\\"I updated this window\\\", use pup_alert_window (or the auto-flash), NOT raise. After the show-me: pup_lower_os_window to return it to the background. Alias: pup_focus_window. IMPORTANT: if you are foregrounding in order to CLICK a native dialog or a cross-origin FedCM/Google account chooser, do NOT raise-then-click yourself — use pup_assisted_click, which waits for the user to actually be on the window (alt-tab aware) and narrates via captions, so you never act while they are not ready.\",\"timeoutSeconds\":15},{\"example\":{\"sessionId\":\"work\",\"submit\":true,\"submitReason\":\"confirmed the tab is on the real vendor domain I intended to sign into\"},\"hint\":\"Fill (and optionally submit) an HTML login form in the CURRENT tab, in the BACKGROUND — no Chrome autofill dropdown, no foregrounding, React/Vue-safe. Creds from the keychain vault (matched on the tab URL; captured automatically as you log in, or stored via credential_set / save:true) or passed explicitly. Passwords are NEVER echoed back. Vault-matched pages AUTO-FILL on load (_autoLogin on the response). SUBMIT IS REASON-GATED: submit:true requires submitReason AND makes you confirm the live domain (the refusal regurgitates the exact host so a lookalike/phishing site is caught before the secret is sent). pup_configure {autoLogin:\\\"off\\\"} disables auto-fill; {captureLogins:\\\"off\\\"} stops auto-capture.\",\"input\":{\"host\":\"optional str — override the vault host key when saving\",\"password\":\"optional str — with username, fills these instead of the vault\",\"realKeystrokes\":\"optional bool — type with REAL key events instead of a background .value-set. Needed for React-controlled MASKED fields (Gusto/Keycloak SSO) that ignore .value and would submit an empty password. It briefly FOREGROUNDS the window (real keystrokes only register on-screen). Use when a normal fill returned filledPassword:false / reactMaskedFieldSuspected, or when the login-recipe for the site says so.\",\"save\":\"optional bool — with explicit creds, store them (OS keychain) so next time is automatic\",\"sessionId\":\"optional str — omit to target the window your own thread owns\",\"submit\":\"optional bool — submit after filling; REQUIRES submitReason\",\"submitReason\":\"required WITH submit:true — why you are confident the CURRENT domain is the correct, intended site to send these credentials to (min 10 chars; the refusal shows you the live host to confirm; logged, auditable)\",\"username\":\"optional str\"},\"longRunning\":false,\"name\":\"pup_login\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Fill (and optionally submit) an HTML login form in the CURRENT tab, in the BACKGROUND — no Chrome autofill dropdown, no foregrounding, React/Vue-safe. Creds from the keychain vault (matched on the tab URL; captured automatically as you log in, or stored via credential_set / save:true) or passed explicitly. Passwords are NEVER echoed back. Vault-matched pages AUTO-FILL on load (_autoLogin on the response). SUBMIT IS REASON-GATED: submit:true requires submitReason AND makes you confirm the live domain (the refusal regurgitates the exact host so a lookalike/phishing site is caught before the secret is sent). pup_configure {autoLogin:\\\"off\\\"} disables auto-fill; {captureLogins:\\\"off\\\"} stops auto-capture.\",\"timeoutSeconds\":20},{\"example\":{},\"hint\":\"List saved logins (host + username only; passwords are in the OS keychain and NEVER returned). pup captures these automatically as you sign into sites and auto-fills them in the background on return visits.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_credentials\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"List saved logins (host + username only; passwords are in the OS keychain and NEVER returned). pup captures these automatically as you sign into sites and auto-fills them in the background on return visits.\",\"timeoutSeconds\":10},{\"example\":{\"host\":\"github.com\",\"reason\":\"signing into GitHub in my own browser to open a PR for the user\"},\"hint\":\"Reveal ONE saved login (username + password) to a LOCAL caller on the desktop, gated by a sticky consent toast the user must click. One host per call, never bulk. A relayed (cloud container) call is refused with relay_forbidden: from a cloud thread use pup_login instead, which signs the site in inside a pup window without the secret ever leaving the vault. The secret is returned ONCE and must never be logged or echoed.\",\"input\":{\"host\":\"required str — the site, e.g. \\\"github.com\\\"\",\"reason\":\"required str (min 10 chars) — shown to the user on the consent toast; say what you will do with it\"},\"longRunning\":false,\"name\":\"pup_credential_reveal\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Reveal ONE saved login (username + password) to a LOCAL caller on the desktop, gated by a sticky consent toast the user must click. One host per call, never bulk. A relayed (cloud container) call is refused with relay_forbidden: from a cloud thread use pup_login instead, which signs the site in inside a pup window without the secret ever leaving the vault. The secret is returned ONCE and must never be logged or echoed.\",\"timeoutSeconds\":130},{\"example\":{},\"hint\":\"Store a payment card in the OS-keychain card vault under a nickname. Ask the USER for the details — never harvest them from a page. Validates Luhn + expiry + cvv. No verb ever returns the number or CVV afterward.\",\"input\":{\"cvv\":\"required 3-4 digits\",\"expiry\":\"required MM/YY\",\"name\":\"optional cardholder name\",\"nickname\":\"required str, e.g. \\\"adom-amex\\\"\",\"number\":\"required str\"},\"longRunning\":false,\"name\":\"pup_card_set\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Store a payment card in the OS-keychain card vault under a nickname. Ask the USER for the details — never harvest them from a page. Validates Luhn + expiry + cvv. No verb ever returns the number or CVV afterward.\",\"timeoutSeconds\":15},{\"example\":{},\"hint\":\"List saved payment cards: nickname, brand, last4, expiry, cardholder only. The number and CVV never leave the keychain.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_cards\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"List saved payment cards: nickname, brand, last4, expiry, cardholder only. The number and CVV never leave the keychain.\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"Remove a saved card from the keychain + index by nickname.\",\"input\":{\"nickname\":\"required str\"},\"longRunning\":false,\"name\":\"pup_card_delete\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Remove a saved card from the keychain + index by nickname.\",\"timeoutSeconds\":10},{\"example\":{\"amount\":\"$350\",\"merchant\":\"venturedallas.com\",\"nickname\":\"adom-amex\"},\"hint\":\"Fill a saved card into the checkout page of a pup window WITHOUT the digits ever reaching you: pup types them into the card fields (walking payment-processor iframes like Stripe) and returns booleans. EVERY fill is gated by a desktop approval toast naming merchant, amount and last4 — the user authorizes the specific charge in the moment. Pass merchant+amount so the toast is honest. Allowed from cloud threads (the human click is the gate). After ok:true, screenshot to verify, then submit.\",\"input\":{\"amount\":\"recommended str, e.g. \\\"$350\\\"\",\"merchant\":\"recommended str — shown on the approval toast\",\"nickname\":\"required str\",\"window\":\"optional (defaults to your thread's window)\"},\"longRunning\":false,\"name\":\"pup_fill_card\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Fill a saved card into the checkout page of a pup window WITHOUT the digits ever reaching you: pup types them into the card fields (walking payment-processor iframes like Stripe) and returns booleans. EVERY fill is gated by a desktop approval toast naming merchant, amount and last4 — the user authorizes the specific charge in the moment. Pass merchant+amount so the toast is honest. Allowed from cloud threads (the human click is the gate). After ok:true, screenshot to verify, then submit.\",\"timeoutSeconds\":130},{\"example\":{\"hostFilter\":[\"snapeda\",\"ultralibrarian\",\"digikey\"]},\"hint\":\"Seed pup's vault from the user's OWN saved Chrome/Edge/Brave passwords, so pup can sign in as them on sites they already use (vendor CAD portals, etc). Runs the SYSTEM-elevated decrypt LOCALLY — the user approves ONE consent dialog + ONE Windows UAC prompt on the desktop (a cloud/relay caller cannot do this; only pup, a local bridge, can ask). Merges the identity-tagged rows into the keychain vault and DROPS the plaintext. Returns COUNTS ONLY. hostFilter narrows the import to matching hosts (surgical, e.g. [\\\"snapeda\\\",\\\"digikey\\\"]); omit to import everything saved. Pair with pup_import_scan (read-only preview of how many logins exist).\",\"input\":{\"browsers\":\"optional str[] subset of [\\\"chrome\\\",\\\"edge\\\",\\\"brave\\\"] (default: all found)\",\"hostFilter\":\"optional str or str[] — only import logins whose host contains one of these (surgical import)\"},\"longRunning\":false,\"name\":\"pup_import_browser_logins\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Seed pup's vault from the user's OWN saved Chrome/Edge/Brave passwords, so pup can sign in as them on sites they already use (vendor CAD portals, etc). Runs the SYSTEM-elevated decrypt LOCALLY — the user approves ONE consent dialog + ONE Windows UAC prompt on the desktop (a cloud/relay caller cannot do this; only pup, a local bridge, can ask). Merges the identity-tagged rows into the keychain vault and DROPS the plaintext. Returns COUNTS ONLY. hostFilter narrows the import to matching hosts (surgical, e.g. [\\\"snapeda\\\",\\\"digikey\\\"]); omit to import everything saved. Pair with pup_import_scan (read-only preview of how many logins exist).\",\"timeoutSeconds\":190},{\"example\":{\"dryRun\":true},\"hint\":\"Delete LEAKED isolated profile directories — the iso-* throwaway jars minted by isolated:true opens (and by wikiView:public before 2.0.132, when the public view moved to the server-side ?view=public param) whose window is long gone (they used to pile up, 100s per machine). Only removes an iso-* dir that no live session or session file owns, that no Chrome is holding, and that is >15 min old; durable jars (adom-you, named profiles) are NEVER touched. Runs automatically every 15 min too. dryRun:true previews the list without deleting.\",\"input\":{\"dryRun\":\"optional bool — preview which iso-* profiles would be removed, delete nothing\"},\"longRunning\":false,\"name\":\"pup_reap_profiles\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Delete LEAKED isolated profile directories — the iso-* throwaway jars minted by isolated:true opens (and by wikiView:public before 2.0.132, when the public view moved to the server-side ?view=public param) whose window is long gone (they used to pile up, 100s per machine). Only removes an iso-* dir that no live session or session file owns, that no Chrome is holding, and that is >15 min old; durable jars (adom-you, named profiles) are NEVER touched. Runs automatically every 15 min too. dryRun:true previews the list without deleting.\",\"timeoutSeconds\":20},{\"example\":{},\"hint\":\"MOVE this pup window's page into the user's Hydrogen workspace: the active tab's URL is handed to Hydrogen (ah) on this machine via its Browser Picker (webview by default, honoring the user's per-domain choice), then the pup window closes — its owner initiated the move. keepWindow:true keeps the pup window open too. Needs Hydrogen running locally (hydrogen_unreachable otherwise; the window is left untouched on failure). Cloud Hydrogen (hc) is not yet supported.\",\"input\":{\"keepWindow\":\"optional bool — hand the URL over but keep the pup window open\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_move_to_workspace\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"MOVE this pup window's page into the user's Hydrogen workspace: the active tab's URL is handed to Hydrogen (ah) on this machine via its Browser Picker (webview by default, honoring the user's per-domain choice), then the pup window closes — its owner initiated the move. keepWindow:true keeps the pup window open too. Needs Hydrogen running locally (hydrogen_unreachable otherwise; the window is left untouched on failure). Cloud Hydrogen (hc) is not yet supported.\",\"timeoutSeconds\":25},{\"example\":{\"dryRun\":true},\"hint\":\"DESTRUCTIVE — cleanly remove pup's WHOLE footprint from this machine: the HKCU AppUserModelId Adom.Pup registry keys, all staged extensions, ALL pup profiles + sessions, the OS-keychain credential vault, pup-settings.json, the badge-debug temp dir, and the jump-list launcher. ALWAYS preview first with dryRun:true (removes nothing, returns the plan). To actually remove, pass confirm:\\\"uninstall\\\". keepCredentials:true preserves the saved-login vault; keepProfiles:true preserves profiles/sessions. Chrome-for-Testing + firewall rules are SHARED and left alone unless removeChrome:true / removeFirewallRules:true. Closes every window + quits every browser first to release profile locks. (The bridge itself is managed by Adom Bridge — remove pup from Bridge to stop it re-seeding.)\",\"input\":{\"confirm\":\"required str \\\"uninstall\\\" to actually remove\",\"dryRun\":\"optional bool — preview the removal plan without removing anything (do this first)\",\"keepCredentials\":\"optional bool — keep the saved-login vault\",\"keepProfiles\":\"optional bool — keep pup profiles + sessions\",\"removeChrome\":\"optional bool — also delete the Chrome-for-Testing install (shared; default keep)\",\"removeFirewallRules\":\"optional bool — also remove the CfT firewall rules (needs admin)\"},\"longRunning\":false,\"name\":\"pup_uninstall\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"DESTRUCTIVE — cleanly remove pup's WHOLE footprint from this machine: the HKCU AppUserModelId Adom.Pup registry keys, all staged extensions, ALL pup profiles + sessions, the OS-keychain credential vault, pup-settings.json, the badge-debug temp dir, and the jump-list launcher. ALWAYS preview first with dryRun:true (removes nothing, returns the plan). To actually remove, pass confirm:\\\"uninstall\\\". keepCredentials:true preserves the saved-login vault; keepProfiles:true preserves profiles/sessions. Chrome-for-Testing + firewall rules are SHARED and left alone unless removeChrome:true / removeFirewallRules:true. Closes every window + quits every browser first to release profile locks. (The bridge itself is managed by Adom Bridge — remove pup from Bridge to stop it re-seeding.)\",\"timeoutSeconds\":60},{\"example\":{},\"hint\":\"Nudge the user about a pup window WITHOUT stealing focus — on Windows it flashes the taskbar button; on macOS (no taskbar, and no API to bounce another app's Dock tile) it unhides the window at its z-position and posts an AD toast whose click focuses it. Same contract on both, so call it identically; just never tell a Mac user to look for a flashing icon. NOTE (v1.8.23): mutating verbs already AUTO-FLASH (debounced, one per ~5s burst per window) so the user always knows the agent touched a window — use this for an explicit end-of-task \\\"it's ready\\\" nudge on top of that. STRONGLY prefer this (or the auto-flash) over pup_raise_os_window, which steals focus and can leak a mid-typed keystroke into the page.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"stop\":\"optional bool — CLEAR the highlight instead of flashing\"},\"longRunning\":false,\"name\":\"pup_alert_window\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Nudge the user about a pup window WITHOUT stealing focus — on Windows it flashes the taskbar button; on macOS (no taskbar, and no API to bounce another app's Dock tile) it unhides the window at its z-position and posts an AD toast whose click focuses it. Same contract on both, so call it identically; just never tell a Mac user to look for a flashing icon. NOTE (v1.8.23): mutating verbs already AUTO-FLASH (debounced, one per ~5s burst per window) so the user always knows the agent touched a window — use this for an explicit end-of-task \\\"it's ready\\\" nudge on top of that. STRONGLY prefer this (or the auto-flash) over pup_raise_os_window, which steals focus and can leak a mid-typed keystroke into the page.\",\"timeoutSeconds\":15},{\"example\":{\"html\":\"<h1>Café</h1>\",\"sessionId\":\"work\"},\"hint\":\"Render a local HTML string in the tab via page.setContent — UTF-8-correct (a data: URL mojibakes accented chars without an explicit charset). Great for previewing generated markup without a temp file. Auto-flashes the window.\",\"input\":{\"html\":\"required HTML string\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"silent\":\"optional bool — suppress the auto-flash\",\"updateNote\":\"optional note for lastAgentUpdate\",\"waitUntil\":\"optional (domcontentloaded default)\"},\"longRunning\":false,\"name\":\"pup_render_html\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Render a local HTML string in the tab via page.setContent — UTF-8-correct (a data: URL mojibakes accented chars without an explicit charset). Great for previewing generated markup without a temp file. Auto-flashes the window.\",\"timeoutSeconds\":30},{\"example\":{},\"hint\":\"List all open pup sessions + their tabs (NOT a readiness check — use pup_readiness for that).\",\"input\":{},\"longRunning\":false,\"name\":\"pup_status\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"List all open pup sessions + their tabs (NOT a readiness check — use pup_readiness for that).\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"List every open session/window with its tabs.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_list_windows\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"List every open session/window with its tabs.\",\"timeoutSeconds\":10},{\"example\":{\"expr\":\"document.querySelector(\\\"#userId\\\").value\",\"frame\":\"logonbox\",\"sessionId\":\"work\"},\"hint\":\"pup_eval accepts frame:\\\"<name|url-substring|index>\\\" to run inside an IFRAME (login forms usually live in one). Cross-origin frames work. Omit for the top document; a bad value returns frame_not_found WITH the list of frames in the tab.\",\"input\":{\"expr\":\"required str\",\"frame\":\"optional str\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_eval_frame_note\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"pup_eval accepts frame:\\\"<name|url-substring|index>\\\" to run inside an IFRAME (login forms usually live in one). Cross-origin frames work. Omit for the top document; a bad value returns frame_not_found WITH the list of frames in the tab.\",\"timeoutSeconds\":20},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"Make a session the active one (for verbs that default to active).\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_switch_window\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Make a session the active one (for verbs that default to active).\",\"timeoutSeconds\":10},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"List the tabs in a session.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_list_tabs\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"List the tabs in a session.\",\"timeoutSeconds\":10},{\"example\":{\"sessionId\":\"work\",\"tabId\":\"tab-2\"},\"hint\":\"Activate a tab WITHIN its session/window (idempotent — safe to call when the tab is already active). Does NOT raise a background window to the user's screen: the tab becomes the window's visible tab wherever the window is, and the taskbar auto-flash tells the user something changed. Also self-heals the window (re-park if a bug ever stranded it off-screen) and refreshes the Adom taskbar badge — good citizenship for long-lived shared windows.\",\"input\":{\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"silent\":\"optional bool\",\"tabId\":\"required str\",\"updateNote\":\"optional str\"},\"longRunning\":false,\"name\":\"pup_switch_tab\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Activate a tab WITHIN its session/window (idempotent — safe to call when the tab is already active). Does NOT raise a background window to the user's screen: the tab becomes the window's visible tab wherever the window is, and the taskbar auto-flash tells the user something changed. Also self-heals the window (re-park if a bug ever stranded it off-screen) and refreshes the Adom taskbar badge — good citizenship for long-lived shared windows.\",\"timeoutSeconds\":10},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"FULL-resolution page screenshot (NOT downscaled — for saving to disk, NOT for Read: it can exceed Claude's image limit). Use pup_screenshot for AI-readable shots.\",\"input\":{\"fullPage\":\"optional bool\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_screenshot_full_res\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"FULL-resolution page screenshot (NOT downscaled — for saving to disk, NOT for Read: it can exceed Claude's image limit). Use pup_screenshot for AI-readable shots.\",\"timeoutSeconds\":30},{\"example\":{\"sessionId\":\"work\"},\"hint\":\"Console errors + failed network requests for a session/tab (clears by default).\",\"input\":{\"clear\":\"optional bool (default true)\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\",\"tabId\":\"optional str\"},\"longRunning\":false,\"name\":\"pup_errors\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Console errors + failed network requests for a session/tab (clears by default).\",\"timeoutSeconds\":10},{\"example\":{\"ms\":500,\"sessionId\":\"work\"},\"hint\":\"Wait N ms (or for a selector) before the next step.\",\"input\":{\"ms\":\"optional int\",\"selector\":\"optional str\",\"sessionId\":\"optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)\"},\"longRunning\":false,\"name\":\"pup_wait\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Wait N ms (or for a selector) before the next step.\",\"timeoutSeconds\":60},{\"example\":{},\"hint\":\"Recover orphaned sessions: reconnect dropped CDP sockets + rebuild sessions from window titles. Pass adoptOrphans:true to also adopt untagged tabs.\",\"input\":{\"adoptOrphans\":\"optional bool\"},\"longRunning\":false,\"name\":\"pup_rescan\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Recover orphaned sessions: reconnect dropped CDP sockets + rebuild sessions from window titles. Pass adoptOrphans:true to also adopt untagged tabs.\",\"timeoutSeconds\":30},{\"example\":{},\"hint\":\"Close ALL pup sessions + windows at once (destructive). NOTE: `{}` here does NOT mean \\\"the active session\\\" the way it does on other session-scoped verbs — with no args this closes EVERY window, across every AI thread on the machine, with no confirmation. To close ONE window use pup_close_window {sessionId}. Pass {sessionId} here only if you genuinely mean that one session.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_close\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Close ALL pup sessions + windows at once (destructive). NOTE: `{}` here does NOT mean \\\"the active session\\\" the way it does on other session-scoped verbs — with no args this closes EVERY window, across every AI thread on the machine, with no confirmation. To close ONE window use pup_close_window {sessionId}. Pass {sessionId} here only if you genuinely mean that one session.\",\"timeoutSeconds\":20},{\"example\":{},\"hint\":\"ALIAS of pup_screen_record_status.\",\"input\":{},\"longRunning\":false,\"name\":\"desktop_record_status\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"ALIAS of pup_screen_record_status.\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"ALIAS of pup_screen_record_list.\",\"input\":{},\"longRunning\":false,\"name\":\"desktop_record_list\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"ALIAS of pup_screen_record_list.\",\"timeoutSeconds\":10},{\"example\":{},\"hint\":\"ALIAS of pup_recorder_close.\",\"input\":{},\"longRunning\":false,\"name\":\"desktop_recorder_close\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"ALIAS of pup_recorder_close.\",\"timeoutSeconds\":15},{\"example\":{\"taskbarGrouping\":\"grouped\"},\"hint\":\"Get/set user-facing pup preferences (persisted across bridge updates). taskbarGrouping: \\\"split\\\" (default — one taskbar button PER WINDOW, each badged with its own tab count; best for telling AI threads apart) | \\\"grouped\\\" (all pup windows stack under ONE \\\"Adom Pup\\\" button, badge shows window count; tidy taskbar). Applies to live windows immediately. Ask the USER which they prefer before changing it — this is their taskbar. WINDOWS ONLY: macOS has no taskbar, so the setting is stored but INERT there; the reply carries platform + taskbarSupported so branch on those, not on this text.\",\"input\":{\"autoLogin\":\"optional \\\"on\\\"|\\\"off\\\" — auto-fill a vault-matched login form on page load (fill only, never submits), on by default\",\"overlaySize\":\"optional \\\"50\\\"|\\\"100\\\" — how big the favicon badge is drawn on the taskbar button. \\\"50\\\" (the DEFAULT) draws it at half size so it stays clear of the thread tile's bottom line of text; \\\"100\\\" is the older, larger badge\",\"reportIssues\":\"optional \\\"on\\\"|\\\"off\\\" — pup's bug-report invitation (_reportIssues), on by default\",\"taskbarActivity\":\"optional \\\"progress\\\"|\\\"flash\\\"|\\\"off\\\" — how pup signals it is working on a window, on that window's taskbar button: a determinate progress bar sized to the operation's running-average time (default), the old orange flash, or nothing. Replaces the former openFlash/autoFlash/agentActivity toggles.\",\"taskbarGrouping\":\"optional \\\"split\\\"|\\\"grouped\\\"\"},\"longRunning\":false,\"name\":\"pup_configure\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[],\"statusVerb\":null,\"summary\":\"Get/set user-facing pup preferences (persisted across bridge updates). taskbarGrouping: \\\"split\\\" (default — one taskbar button PER WINDOW, each badged with its own tab count; best for telling AI threads apart) | \\\"grouped\\\" (all pup windows stack under ONE \\\"Adom Pup\\\" button, badge shows window count; tidy taskbar). Applies to live windows immediately. Ask the USER which they prefer before changing it — this is their taskbar. WINDOWS ONLY: macOS has no taskbar, so the setting is stored but INERT there; the reply carries platform + taskbarSupported so branch on those, not on this text.\",\"timeoutSeconds\":15},{\"example\":{},\"hint\":\"This list — the bridge's verbs + schemas + hints, for AD's Verbs tab. Read it once to learn the surface.\",\"input\":{},\"longRunning\":false,\"name\":\"pup_describe\",\"output\":{\"success\":\"bool\"},\"pitfalls\":[],\"related\":[\"pup_status\"],\"statusVerb\":null,\"summary\":\"This list — the bridge's verbs + schemas, for AD's Verbs tab.\",\"timeoutSeconds\":10}]}",
  "progressContract": {
    "activeKey": "active",
    "blockedByPhases": [
      "consent",
      "dialog"
    ],
    "blockedOnUser": {
      "errorCode": "blocked_on_user",
      "inVerbWaitSec": 45,
      "promptLifetimeSec": 120,
      "rule": "ab BRIDGE_SDK 2.1.30: a verb parked on a HUMAN never bare-timeouts; it answers this shape",
      "stillRunning": "true = the wait continues in the background: re-call the SAME verb with the SAME args to re-attach (no second prompt) or watch pup_readiness.active[]; false = the human must act first, then re-issue the verb"
    },
    "slowVerbs": [
      "pup_open_window",
      "pup_prewarm",
      "pup_use"
    ],
    "statusVerb": "pup_readiness",
    "timings": {
      "open_window_warm": {
        "confidence": "measured",
        "estimatedSec": 11,
        "samples": 20
      }
    }
  },
  "related": [
    "pup_status"
  ],
  "status": "ok",
  "statusVerb": "pup_readiness",
  "success": true,
  "timeoutSeconds": 60,
  "verbs": [
    {
      "example": {},
      "hint": "START HERE for window management: everything YOUR thread owns — windows, tabs, urls, titles, state — with ready-to-run next steps. Zero args. You NEVER need an hwnd, desktop_find_window, or desktop_screenshot_window for a pup window: pup keys every window to its owning --ai-thread name and resolves ids for you — omit sessionId in any pup verb to target your own window, or pass \"ai-thread\" to address a thread by name (the CLI's --ai-thread flag, same spelling). pup_screenshot {} screenshots it; pup_reload {} refreshes it.",
      "input": {
        "ai-thread": "optional str — inspect another thread's windows (read-only listing); default = the calling thread. The CLI flag's exact spelling; aiThread also accepted"
      },
      "longRunning": false,
      "name": "pup_my_windows",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "START HERE for window management: everything YOUR thread owns — windows, tabs, urls, titles, state — with ready-to-run next steps. Zero args. You NEVER need an hwnd, desktop_find_window, or desktop_screenshot_window for a pup window: pup keys every window to its owning --ai-thread name and resolves ids for you — omit sessionId in any pup verb to target your own window, or pass \"ai-thread\" to address a thread by name (the CLI's --ai-thread flag, same spelling). pup_screenshot {} screenshots it; pup_reload {} refreshes it.",
      "timeoutSeconds": 10
    },
    {
      "example": {
        "height": 540,
        "owner": "mytask",
        "sessionId": "mytask-web",
        "url": "https://example.com",
        "width": 960
      },
      "hint": "Opens a generic, fully-controllable pup window (a fresh isolated Chrome/Edge process — never your real signed-in browser) that you then drive by sessionId. To drive the user's REAL Chrome/Edge, use the Adom browser extension's nbrowser_* verbs instead.",
      "input": {
        "appIconB64": "optional base64 PNG — override the app icon worn in the taskbar overlay. Usually UNNECESSARY: pup auto-fetches the page's own <link rel=\"icon\"> favicon (the adom-ui-design standard artifact every app must serve) and wears it automatically. An app-looking URL with NO favicon gets a reprimand hint.",
        "appName": "optional str — the APP this window is driving (e.g. \"shotlog\"); shown in the hover tooltip",
        "autoFlash": "optional bool (default true) — mutating verbs auto-flash this window's taskbar (debounced, never steals focus) so the user notices the agent touched it; pass false to make this window silent by default",
        "foreground": "optional bool — request showing the window on the user's screen. GATED (v1.8.70): requires foregroundReason too, else the open succeeds but stays BACKGROUND with foregroundDenied set. Only when the USER explicitly asked to watch.",
        "foregroundReason": "required WITH foreground:true — quote/paraphrase what the user said that justifies putting a window on their screen (min 10 chars; logged + recorded in lastAgentUpdate, auditable)",
        "height": "optional int px",
        "isolated": "optional bool — private throwaway profile: fresh-login tests, acting as a different user. REASON-GATED (v2.0.101): requires isolationReason or the open is refused — every window defaults to the shared adom-you profile",
        "isolationReason": "required WITH isolated:true — why this window must NOT ride the shared adom-you profile (min 10 chars; logged, auditable). webSecurity:false and wikiView:public carry their own built-in reason",
        "owner": "optional str — your thread/task label; lets pup protect this window from other threads",
        "profile": "optional str — a named durable jar; DEFAULT is the shared \"adom-you\" profile (signed-in state shared across windows). isolated:true overrides to a throwaway",
        "sessionId": "optional str — OMIT IT (recommended): your thread gets its OWN window keyed on your --ai-thread name; the first open creates it, later opens become TABS in it, and no other thread can touch it. Pass an explicit id only when you need a SEPARATE window (task-prefix it, e.g. \"mytask-web\")",
        "silent": "optional bool — suppress the auto-flash for just this call",
        "takeover": "optional bool — claim a window owned by another thread (only when the user explicitly asks)",
        "updateNote": "optional str — a short \"what I did\" note, surfaced back in list_tabs/list_windows as lastAgentUpdate so the user knows what changed",
        "url": "optional str",
        "webSecurity": "optional false — dev escape hatch for cross-origin eval; FORCES isolation so insecure flags never touch the credentialed profile",
        "width": "optional int px — sizes for screenshot framing, stays background",
        "wikiView": "optional \"authed\"|\"public\" — for wiki.adom.inc URLs. THREE distinct cases: (1) OMIT = the shared adom-you profile, LOGGED IN as the user if they have signed into the wiki (the usual case); this is NOT anonymous. (2) \"public\" = the SERVER renders the page exactly as a signed-out visitor sees it via the ?view=public param (adom/wiki#126: request user nulled, byte-identical to logged-out, private pages 404) — the window STAYS on the shared profile, session untouched, no isolated jar; use this to verify a publish did not leak private source. (3) \"authed\" = the explicit logged-in view (30-day SSO; first use may need a one-time login — response says wikiLoginNeeded). To compare \"what I see\" vs \"what the world sees\", open one \"authed\" (or omit) AND one \"public\" tab — do NOT rely on omit for the public view.",
        "x": "optional int px",
        "y": "optional int px"
      },
      "longRunning": false,
      "name": "pup_open_window",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "sessionId is OPTIONAL: omit it and your thread gets its OWN window (keyed on your --ai-thread name; later opens become tabs in it). Pass one only for a deliberate separate window — it is then your handle for every later call",
        "profile defaults to the durable shared 'adom-you' profile (logins/localStorage persist + are shared across all pup windows); isolated:true for a private throwaway — omit it for a plain \"open in pup\"",
        "sessionIds are SHARED across all AI threads on this desktop — a generic id (\"wiki\", \"test\") may collide with another thread's window and navigating it away steals their work. Use a task-prefixed sessionId + pass owner:\"<your-task>\" so pup can protect it",
        "reusing an existing sessionId with a new url NAVIGATES that window — check pup_status (shows owner per window) first if unsure"
      ],
      "related": [
        "pup_navigate",
        "pup_list_windows",
        "pup_close_window"
      ],
      "statusVerb": null,
      "summary": "Open a generic pup window — a fresh isolated Chrome/Edge process (never your real signed-in browser), fully drivable via CDP. ALWAYS opens in the BACKGROUND (does not steal focus; never disturbs the user's main work; still fully screenshottable/drivable) UNLESS you pass foreground:true — do that ONLY when the user explicitly wants to watch. Pass width+height (+ optional x,y, screen px) to place it at a specific size/position for screenshot framing — this NO LONGER foregrounds it (sizing stays in the background too; default unsized is maximized). profile defaults to the durable shared 'adom-you' profile (logins/localStorage persist + are shared across all pup windows); isolated:true for a private throwaway. OWNERSHIP: sessionIds are shared across ALL AI threads — use a task-prefixed sessionId + owner:\"<your-task>\" so pup can refuse other threads stealing your window (reusing an existing id with a new url navigates it away; declared cross-owner reuse errors with session_owned_by_another_thread unless takeover:true). (For the user's REAL Chrome/Edge, use the Adom extension's nbrowser_* verbs.)",
      "timeoutSeconds": 60
    },
    {
      "example": {
        "sessionId": "work",
        "url": "https://example.com"
      },
      "hint": "Adds a tab to an existing session; returns the new tabId.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "silent": "optional bool — suppress the auto-flash for this call",
        "updateNote": "optional str — short \"what I did\" note surfaced in list_tabs as lastAgentUpdate",
        "url": "optional str"
      },
      "longRunning": false,
      "name": "pup_open_tab",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "the session must already exist (pup_open_window first)"
      ],
      "related": [
        "pup_switch_tab",
        "pup_list_tabs",
        "pup_close_tab"
      ],
      "statusVerb": null,
      "summary": "Open a new tab in an EXISTING session/window (returns {tabId, tabCount, activeTabId} — no need to diff list_tabs). This is the right verb for multi-URL work: ONE window with many tabs (one taskbar button), not many windows. The window stays in the background; the tab auto-flashes the taskbar (debounced) so the user notices. The USER can click the window's taskbar button at any time to view it — pup never pulls it back down.",
      "timeoutSeconds": 30
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "Closes one tab; the session stays open.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "tabId": "optional str (default active)"
      },
      "longRunning": false,
      "name": "pup_close_tab",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "omit tabId to close the active tab — closing the last tab may close the window"
      ],
      "related": [
        "pup_close_window",
        "pup_list_tabs"
      ],
      "statusVerb": null,
      "summary": "Close a tab.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "Closes the whole session and all its tabs. Destructive.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_close_window",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "this ends the session — its sessionId is no longer valid afterward"
      ],
      "related": [
        "pup_list_windows"
      ],
      "statusVerb": null,
      "summary": "Close a window/session (its tabs go too).",
      "timeoutSeconds": 20
    },
    {
      "example": {},
      "hint": "Everything about ONE pup window as JSON — owner AI thread, container, profile, tabs, age, last agent action, and the window's hwnd (for desktop_screenshot_window when you need the browser chrome in frame). For an AI caller this is a PURE DATA query: nothing is drawn on the user's screen. Visual surfaces are user-initiated only — a jump-list click shows the native taskbar caption, a toolbar-popup click shows the in-page floaty card. showCaption:true opts an AI caller into the caption ONLY when the user asked to have the window identified on screen. Read-only, never owner-gated.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "showCaption": "optional bool — draw the ~12s taskbar caption too; ONLY when the user asked to see which window this is"
      },
      "longRunning": false,
      "name": "pup_window_info",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Everything about ONE pup window as JSON — owner AI thread, container, profile, tabs, age, last agent action, and the window's hwnd (for desktop_screenshot_window when you need the browser chrome in frame). For an AI caller this is a PURE DATA query: nothing is drawn on the user's screen. Visual surfaces are user-initiated only — a jump-list click shows the native taskbar caption, a toolbar-popup click shows the in-page floaty card. showCaption:true opts an AI caller into the caption ONLY when the user asked to have the window identified on screen. Read-only, never owner-gated.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "sessionId": "wiki-bmv080",
        "view": "authed"
      },
      "hint": "Flip a WIKI pup window between the logged-in and public view IN PLACE: every wiki tab reloads with the server-side ?view=public param appended (public) or stripped (authed) — adom/wiki#126 renders the request exactly as a signed-out visitor while the session stays untouched, so there is no relaunch, no cookie wipe, no profile switch (the legacy jar relaunch survives only as a fallback for servers that ignore the param). This is the callback for the per-window taskbar jump-list task (WINDOWS ONLY) — a USER-initiated action. AI threads should NOT call this; pass wikiView:\"authed\"|\"public\" on pup_open_window instead.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "view": "required \"authed\"|\"public\"|\"toggle\" — toggle flips whatever the window currently shows (the Alt+Shift+V hotkey form)"
      },
      "longRunning": false,
      "name": "pup_wiki_set_view",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Flip a WIKI pup window between the logged-in and public view IN PLACE: every wiki tab reloads with the server-side ?view=public param appended (public) or stripped (authed) — adom/wiki#126 renders the request exactly as a signed-out visitor while the session stays untouched, so there is no relaunch, no cookie wipe, no profile switch (the legacy jar relaunch survives only as a fallback for servers that ignore the param). This is the callback for the per-window taskbar jump-list task (WINDOWS ONLY) — a USER-initiated action. AI threads should NOT call this; pass wikiView:\"authed\"|\"public\" on pup_open_window instead.",
      "timeoutSeconds": 45
    },
    {
      "example": {
        "sessionId": "work",
        "url": "https://example.com"
      },
      "hint": "Drives the active tab to url and waits for load. Verify with a screenshot before asserting success.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "url": "required str"
      },
      "longRunning": false,
      "name": "pup_navigate",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "navigation can race SPA routing — confirm with pup_screenshot",
        "some sites need pup_wait for a selector after navigate"
      ],
      "related": [
        "pup_screenshot",
        "pup_wait",
        "pup_reload"
      ],
      "statusVerb": null,
      "summary": "Navigate the active tab to a URL.",
      "timeoutSeconds": 45
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "History back on the active tab.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_back",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [
        "pup_forward",
        "pup_navigate"
      ],
      "statusVerb": null,
      "summary": "History back.",
      "timeoutSeconds": 20
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "History forward on the active tab.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_forward",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [
        "pup_back",
        "pup_navigate"
      ],
      "statusVerb": null,
      "summary": "History forward.",
      "timeoutSeconds": 20
    },
    {
      "example": {},
      "hint": "Paint the Windows taskbar PROGRESS BAR on your window during a LONG multi-stage task (crawling a site, login->search->download loops, batch harvesting datasheets/STEP files) so the user sees work happening at a glance. mode:\"indeterminate\" (pulsing) to start, mode:\"value\" with value:0-100 as stages complete, mode:\"off\" when done or aborted (always clear!). Optional note:\"12/40 datasheets\" shows on the button hover tooltip. YOUR judgment: a single quick page open does NOT warrant a progress bar. See the pup-progress skill.",
      "input": {
        "mode": "\"indeterminate\" | \"value\" | \"off\"",
        "note": "optional short stage label for the hover tooltip",
        "sessionId": "optional — defaults to your thread's own window",
        "value": "optional 0-100 (mode:\"value\")"
      },
      "longRunning": false,
      "name": "pup_progress",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Paint the Windows taskbar PROGRESS BAR on your window during a LONG multi-stage task (crawling a site, login->search->download loops, batch harvesting datasheets/STEP files) so the user sees work happening at a glance. mode:\"indeterminate\" (pulsing) to start, mode:\"value\" with value:0-100 as stages complete, mode:\"off\" when done or aborted (always clear!). Optional note:\"12/40 datasheets\" shows on the button hover tooltip. YOUR judgment: a single quick page open does NOT warrant a progress bar. See the pup-progress skill.",
      "timeoutSeconds": 8
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "Reloads the active tab.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_reload",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "A page with unsaved changes raises a native \"Reload site?\" dialog that BLOCKS the window: the reload appears to time out and so does everything else. Answer it with pup_dialog."
      ],
      "related": [
        "pup_navigate",
        "pup_wait",
        "pup_dialog"
      ],
      "statusVerb": null,
      "summary": "Reload the active tab.",
      "timeoutSeconds": 30
    },
    {
      "example": {
        "selector": "button#go",
        "sessionId": "work"
      },
      "hint": "Clicks by CSS selector (preferred) or by x,y coords. Selector is more robust across layouts.",
      "input": {
        "button": "optional \"left\"|\"right\"|\"middle\"",
        "clickCount": "optional int 1-3",
        "domClick": "optional bool — dispatch a synthetic element.click() instead of a trusted CDP click; for React controls that ignore trusted clicks",
        "selector": "optional str",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "x": "optional int",
        "y": "optional int"
      },
      "longRunning": false,
      "name": "pup_click",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "selector must match exactly one visible element — verify with pup_evaluate first",
        "coords are viewport-relative; a scrolled element may be off-screen"
      ],
      "related": [
        "pup_type",
        "pup_input_dispatch",
        "pup_screenshot"
      ],
      "statusVerb": null,
      "summary": "Click an element (by selector or coords). Selector clicks LOCATE the element once then click by its center coordinates (fast on huge/animated DOMs, where page.click used to hit the 15s wall). Response includes method. If a React toggle/like/heart does NOT change state after a normal click, that control ignores trusted clicks — retry with domClick:true to fire a synthetic element.click().",
      "timeoutSeconds": 20
    },
    {
      "example": {
        "label": "your Google account",
        "reason": "clicking your Google account to finish signing into Autodesk",
        "sessionId": "adsk",
        "x": 900,
        "y": 379
      },
      "hint": "RESPECTFUL real-cursor click for a surface pup CDP cannot drive (a NATIVE OS dialog, or a cross-origin FedCM \"Sign in with Google\" account chooser that rejects every in-page click). Do NOT hand-roll raise+desktop_click for these — use THIS. It: captions the reason + toasts BEFORE touching the screen; foregrounds; then WAITS, detecting if the user alt-tabbed away and holding (captioning \"Adom is waiting — click back when ready\") until the user is actually on the window; then runs the TIGHT real-cursor hover->click that FedCM accepts (interleaving any screenshot/eval between raise and click makes the click silently no-op); captions each step. Times out as user_not_ready clicking NOTHING if they never return. First take a desktop_screenshot_window of the session to read the target's WINDOW-pixel x,y.",
      "input": {
        "label": "required str — WHAT you are clicking (e.g. \"your Google account\")",
        "maxWaitMs": "optional int — how long to wait for the user (default 120000)",
        "reason": "required str — WHY you must click (shown to the user as a caption)",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "x": "required int — WINDOW-image pixel of the target (from desktop_screenshot_window)",
        "y": "required int"
      },
      "longRunning": false,
      "name": "pup_assisted_click",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "RESPECTFUL real-cursor click for a surface pup CDP cannot drive (a NATIVE OS dialog, or a cross-origin FedCM \"Sign in with Google\" account chooser that rejects every in-page click). Do NOT hand-roll raise+desktop_click for these — use THIS. It: captions the reason + toasts BEFORE touching the screen; foregrounds; then WAITS, detecting if the user alt-tabbed away and holding (captioning \"Adom is waiting — click back when ready\") until the user is actually on the window; then runs the TIGHT real-cursor hover->click that FedCM accepts (interleaving any screenshot/eval between raise and click makes the click silently no-op); captions each step. Times out as user_not_ready clicking NOTHING if they never return. First take a desktop_screenshot_window of the session to read the target's WINDOW-pixel x,y.",
      "timeoutSeconds": 130
    },
    {
      "example": {
        "clear": true,
        "selector": "#user",
        "sessionId": "work",
        "text": "adominc1"
      },
      "hint": "Types into the focused or selector-targeted field.",
      "input": {
        "clear": "optional bool — empty the field first (replace, not append)",
        "selector": "optional str",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "text": "required str"
      },
      "longRunning": false,
      "name": "pup_type",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "focus the field first (pup_click the input) or pass selector",
        "does not clear existing text — select-all + delete if you need a clean field"
      ],
      "related": [
        "pup_click",
        "pup_press_key"
      ],
      "statusVerb": null,
      "summary": "Type text into a field via real CDP keystrokes (isTrusted). Reads the value back and returns valueLanded — real keystrokes only register in a FOREGROUNDED window, so if valueLanded:false the field stayed empty (the silent no-op): use pup_fill (background-safe) for a non-React input, or pup_login {realKeystrokes:true} for a login form. Pass clear:true to REPLACE instead of appending.",
      "timeoutSeconds": 20
    },
    {
      "example": {
        "selector": "#email",
        "sessionId": "work",
        "text": "[email protected]"
      },
      "hint": "Set a field's value in the BACKGROUND (no foreground, no keystrokes): writes .value via the native setter and fires input+change so React/Vue/Angular controlled inputs pick it up. The fix for pup_type's silent no-op on a backgrounded window. Reads the value back and returns valueLanded. For React-MASKED password fields that reject programmatic writes, use pup_login {realKeystrokes:true} instead.",
      "input": {
        "selector": "required str",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "text": "required str"
      },
      "longRunning": false,
      "name": "pup_fill",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Set a field's value in the BACKGROUND (no foreground, no keystrokes): writes .value via the native setter and fires input+change so React/Vue/Angular controlled inputs pick it up. The fix for pup_type's silent no-op on a backgrounded window. Reads the value back and returns valueLanded. For React-MASKED password fields that reject programmatic writes, use pup_login {realKeystrokes:true} instead.",
      "timeoutSeconds": 20
    },
    {
      "example": {
        "key": "a",
        "modifiers": [
          "Control"
        ],
        "sessionId": "work"
      },
      "hint": "Presses a key or chord (Enter, Ctrl+A, Tab).",
      "input": {
        "key": "required str",
        "modifiers": "optional array — any of [\"Control\",\"Shift\",\"Alt\",\"Meta\"] (aliases ctrl/cmd/command/option accepted); held down around the key press",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_press_key",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "chord syntax is \"Ctrl+A\" — verify the page has focus on the intended element"
      ],
      "related": [
        "pup_type",
        "pup_input_dispatch"
      ],
      "statusVerb": null,
      "summary": "Press a key, optionally with modifier chords held (Ctrl+A, Ctrl+V, Shift+Tab).",
      "timeoutSeconds": 15
    },
    {
      "example": {},
      "hint": "⛔ READ BEFORE USING AD's desktop_click / desktop_type / desktop_press_key ON A PUP WINDOW. Native OS input does NOT target a window — it goes to WHATEVER WINDOW HAS OS FOCUS at that instant. This user runs many AI threads and alt-tabs away from a foregrounded window almost immediately. If you fire native input without warning them, your keystrokes land in THEIR document (this happened: a username was typed into the user's own window). REQUIRED: notify_user toast + desktop_caption FIRST, tell them explicitly \"don't type or click until I say done\", wait until the window is genuinely foreground, re-verify immediately before EACH event, and caption when done. pup_assisted_click already does all of this — use it. And ALWAYS prefer CDP input (pup_click/pup_type/pup_hover): it needs no foreground and disturbs nobody. A native verb returning ok:true means the event was dispatched to the OS, NOT that it reached your window.",
      "input": {},
      "longRunning": false,
      "name": "pup_NATIVE_INPUT_WARNING",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "⛔ READ BEFORE USING AD's desktop_click / desktop_type / desktop_press_key ON A PUP WINDOW. Native OS input does NOT target a window — it goes to WHATEVER WINDOW HAS OS FOCUS at that instant. This user runs many AI threads and alt-tabs away from a foregrounded window almost immediately. If you fire native input without warning them, your keystrokes land in THEIR document (this happened: a username was typed into the user's own window). REQUIRED: notify_user toast + desktop_caption FIRST, tell them explicitly \"don't type or click until I say done\", wait until the window is genuinely foreground, re-verify immediately before EACH event, and caption when done. pup_assisted_click already does all of this — use it. And ALWAYS prefer CDP input (pup_click/pup_type/pup_hover): it needs no foreground and disturbs nobody. A native verb returning ok:true means the event was dispatched to the OS, NOT that it reached your window.",
      "timeoutSeconds": 0
    },
    {
      "example": {
        "reset": true,
        "sessionId": "work"
      },
      "hint": "Pin the page viewport (CDP device-metrics) to an exact size for deterministic screenshots — OR clear that pin. ⚠ A pin PERSISTS: it survives navigation and hard reload, and while set the window stops tracking OS resizing (a human resizing it sees no reflow, which looks exactly like an app layout bug). ALWAYS clear it when done. Reported as emulatedViewport in pup_status / pup_list_windows.",
      "input": {
        "deviceScaleFactor": "optional number (default 1)",
        "height": "int — required unless reset",
        "reset": "optional bool — CLEAR the override and track the OS window again (width/height not needed)",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "width": "int — required unless reset"
      },
      "longRunning": false,
      "name": "pup_set_viewport",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Pin the page viewport (CDP device-metrics) to an exact size for deterministic screenshots — OR clear that pin. ⚠ A pin PERSISTS: it survives navigation and hard reload, and while set the window stops tracking OS resizing (a human resizing it sees no reflow, which looks exactly like an app layout bug). ALWAYS clear it when done. Reported as emulatedViewport in pup_status / pup_list_windows.",
      "timeoutSeconds": 15
    },
    {
      "example": {},
      "hint": "Status/trigger for the toolbar extension, which AUTO-INSTALLS invisibly at every profile launch (transient pipe-launch + CDP Extensions.loadUnpacked; persists in the profile). Running profiles pick it up on their next launch; cold profiles install immediately.",
      "input": {
        "profile": "optional, default adom-you"
      },
      "longRunning": false,
      "name": "pup_install_toolbar",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Status/trigger for the toolbar extension, which AUTO-INSTALLS invisibly at every profile launch (transient pipe-launch + CDP Extensions.loadUnpacked; persists in the profile). Running profiles pick it up on their next launch; cold profiles install immediately.",
      "timeoutSeconds": 30
    },
    {
      "example": {},
      "hint": "TEST SEAM: simulate a user click on the floaty pencil (fires the same host click handler a mouse does; the sweep then starts annotate within ~4s). Built for the recurring floaty ralph — assert the annotate overlay appears after calling this.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "tabId": "optional tab"
      },
      "longRunning": false,
      "name": "pup_floaty_click",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "TEST SEAM: simulate a user click on the floaty pencil (fires the same host click handler a mouse does; the sweep then starts annotate within ~4s). Built for the recurring floaty ralph — assert the annotate overlay appears after calling this.",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "Start the HUMAN annotation overlay on a window's active tab (pen/arrow/box/text toolbar injected in-page; also on every window's taskbar jump list as \"Annotate this page\"). Two capture modes the user can also flip in the toolbar: \"auto\" (default) captures the instant the mouse lifts — the one-red-circle case; \"multi\" accumulates shapes (color swatches: red/blue/yellow one click, more in a flyout) and captures ONCE on Done. Done captures a PNG AND leaves the drawing in the DOM, so the owning thread's next pup_screenshot shows exactly what the user marked — check session.lastAnnotation via pup_list_windows. action:\"cancel\" removes the overlay.",
      "input": {
        "action": "optional \"cancel\"",
        "mode": "optional \"auto\"|\"multi\"",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_annotate",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Start the HUMAN annotation overlay on a window's active tab (pen/arrow/box/text toolbar injected in-page; also on every window's taskbar jump list as \"Annotate this page\"). Two capture modes the user can also flip in the toolbar: \"auto\" (default) captures the instant the mouse lifts — the one-red-circle case; \"multi\" accumulates shapes (color swatches: red/blue/yellow one click, more in a flyout) and captures ONCE on Done. Done captures a PNG AND leaves the drawing in the DOM, so the owning thread's next pup_screenshot shows exactly what the user marked — check session.lastAnnotation via pup_list_windows. action:\"cancel\" removes the overlay.",
      "timeoutSeconds": 15
    },
    {
      "example": {},
      "hint": "Open the LIVE pup management dashboard in its OWN window (its own profile, so its own taskbar icon). Shows every window pup is driving as taskbar button -> window(s) -> tabs with each tab favicon, owning AI thread, foreground/background + the reason given to foreground it, highFps lease, uptime, and WHY each overlay icon was chosen. Live over SSE. Reuses the one window on repeat calls; backgrounded by default like any pup window.",
      "input": {},
      "longRunning": false,
      "name": "pup_dashboard",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Open the LIVE pup management dashboard in its OWN window (its own profile, so its own taskbar icon). Shows every window pup is driving as taskbar button -> window(s) -> tabs with each tab favicon, owning AI thread, foreground/background + the reason given to foreground it, highFps lease, uptime, and WHY each overlay icon was chosen. Live over SSE. Reuses the one window on repeat calls; backgrounded by default like any pup window.",
      "timeoutSeconds": 30
    },
    {
      "example": {},
      "hint": "Report pup dependency health (wiki issue #15): depsPresent, selfInstalledThisBoot, lastError. Use this to answer \"is pup broken?\" without reading spawn logs.",
      "input": {},
      "longRunning": false,
      "name": "pup_deps",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Report pup dependency health (wiki issue #15): depsPresent, selfInstalledThisBoot, lastError. Use this to answer \"is pup broken?\" without reading spawn logs.",
      "timeoutSeconds": 10
    },
    {
      "example": {
        "selector": "#menu",
        "sessionId": "work"
      },
      "hint": "Move the pointer over a target WITHOUT clicking (reveals tooltips / hover menus). Glides the visible Adom cursor there too.",
      "input": {
        "intent": "optional str — narrated on the cursor label",
        "selector": "optional str",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "steps": "optional int (default 8)",
        "x": "optional int",
        "y": "optional int"
      },
      "longRunning": false,
      "name": "pup_hover",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Move the pointer over a target WITHOUT clicking (reveals tooltips / hover menus). Glides the visible Adom cursor there too.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "Maximize (or restore/fullscreen/minimize) a pup window via CDP — no AD desktop verb required. Does NOT foreground it.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "state": "optional \"maximized\"|\"normal\"|\"minimized\"|\"fullscreen\" (default maximized)"
      },
      "longRunning": false,
      "name": "pup_maximize",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Maximize (or restore/fullscreen/minimize) a pup window via CDP — no AD desktop verb required. Does NOT foreground it.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "avatarB64": "<base64 png>",
        "name": "John Lauer"
      },
      "hint": "Set the Adom identity shown in the floating owner chip on every pup window (avatar + name). Chrome's own profile chip cannot take a custom local image (Google sign-in only), so the user's Adom avatar lives here instead. Pass a pre-circle-cropped PNG as base64. Applies to live windows immediately + persists.",
      "input": {
        "avatarB64": "optional str — base64 PNG (ideally ~48px, circle-cropped); the leading data: prefix is stripped if present",
        "clear": "optional bool — remove the stored avatar + name",
        "enabled": "optional bool — turn the whole owner chip on/off",
        "name": "optional str — display name shown in the chip tooltip"
      },
      "longRunning": false,
      "name": "pup_set_identity",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Set the Adom identity shown in the floating owner chip on every pup window (avatar + name). Chrome's own profile chip cannot take a custom local image (Google sign-in only), so the user's Adom avatar lives here instead. Pass a pre-circle-cropped PNG as base64. Applies to live windows immediately + persists.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "PNG of the page. Your primary way to SEE state — call it after navigate/click to confirm.",
      "input": {
        "fullPage": "optional bool",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_screenshot",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "default is the viewport; pass fullPage:true for the whole scroll height"
      ],
      "related": [
        "pup_screenshot_full_res",
        "pup_navigate"
      ],
      "statusVerb": null,
      "summary": "Screenshot the page (PNG; fullPage optional). NOTE: fullPage only covers DOCUMENT-level scroll — on SPAs that scroll inside a nested container it returns just the viewport + a nestedScroll hint; use pup_screenshot_element or pup_scroll for those.",
      "timeoutSeconds": 30
    },
    {
      "example": {
        "selector": ".download-card",
        "sessionId": "work"
      },
      "hint": "Screenshot ONE element, resolved by CSS selector OR visible text (pierces shadow DOM), scrolled into view first. The clean way to grab a single card/widget on a component-heavy page. Text matches the TIGHTEST text node — to capture the enclosing CARD, add closest (e.g. {text:\"Download…\", closest:\".download-card\"}); with closest, an ambiguous phrase still lands on the real widget (skips prose that has no such ancestor). Returns base64 + filePath like pup_screenshot.",
      "input": {
        "closest": "optional selector — climb to the nearest ancestor matching it (the card container)",
        "deep": "optional bool — pierce shadow DOM (default true)",
        "padding": "optional int px around the element",
        "selector": "CSS selector (or use text)",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "text": "visible text to match (or use selector)"
      },
      "longRunning": false,
      "name": "pup_screenshot_element",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Screenshot ONE element, resolved by CSS selector OR visible text (pierces shadow DOM), scrolled into view first. The clean way to grab a single card/widget on a component-heavy page. Text matches the TIGHTEST text node — to capture the enclosing CARD, add closest (e.g. {text:\"Download…\", closest:\".download-card\"}); with closest, an ambiguous phrase still lands on the real widget (skips prose that has no such ancestor). Returns base64 + filePath like pup_screenshot.",
      "timeoutSeconds": 30
    },
    {
      "example": {
        "sessionId": "work",
        "toText": "Download"
      },
      "hint": "Scroll the ACTUAL scrolling element (nearest ancestor whose scrollHeight>clientHeight, NOT just window — window.scrollTo no-ops on nested-scroll SPAs). Scroll by delta {dy,dx} OR to an element {toSelector|toText} (pierces shadow DOM). Returns {scrollElement, scrollTop, scrollHeight, clientHeight} so you can confirm it landed.",
      "input": {
        "behavior": "optional auto|smooth",
        "block": "optional start|center|end (for scroll-to; default center)",
        "dx": "optional int px",
        "dy": "optional int px (down+/up-)",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "toSelector": "optional CSS selector to scroll to",
        "toText": "optional visible text to scroll to"
      },
      "longRunning": false,
      "name": "pup_scroll",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Scroll the ACTUAL scrolling element (nearest ancestor whose scrollHeight>clientHeight, NOT just window — window.scrollTo no-ops on nested-scroll SPAs). Scroll by delta {dy,dx} OR to an element {toSelector|toText} (pierces shadow DOM). Returns {scrollElement, scrollTop, scrollHeight, clientHeight} so you can confirm it landed.",
      "timeoutSeconds": 30
    },
    {
      "example": {
        "height": 900,
        "sessionId": "work",
        "width": 1280
      },
      "hint": "Set the page viewport (CDP device-metrics) deterministically, independent of the OS window size — fixes a too-small innerWidth so fullPage/element shots render at a known width. width+height required.",
      "input": {
        "deviceScaleFactor": "optional number (default 1)",
        "height": "required int px",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "width": "required int px"
      },
      "longRunning": false,
      "name": "pup_set_viewport",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Set the page viewport (CDP device-metrics) deterministically, independent of the OS window size — fixes a too-small innerWidth so fullPage/element shots render at a known width. width+height required.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "expression": "document.title",
        "sessionId": "work"
      },
      "hint": "Runs JS in the page and returns the result — use it to read DOM state or verify selectors before acting.",
      "input": {
        "expression": "required str — aliases accepted: expr, script, js, code",
        "frame": "optional str — run inside this iframe instead of the top document",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_evaluate",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "the expression must be serializable JSON in its return value",
        "runs in the page context, not Node"
      ],
      "related": [
        "pup_click",
        "pup_fetch_url"
      ],
      "statusVerb": null,
      "summary": "Evaluate JS in the page and return the result — THE verb for reading DOM state / asserting on a page (same handler as pup_eval). Add frame:\"<name|url-substring|index>\" to run inside an iframe.",
      "timeoutSeconds": 30
    },
    {
      "example": {
        "sessionId": "work",
        "url": "https://api.example.com"
      },
      "hint": "Fetches a URL using the tab's live cookies/session — for authed APIs the bare CLI can't reach. Returns bodyBase64.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "url": "required str"
      },
      "longRunning": false,
      "name": "pup_fetch_url",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "for session-scoped URLs pass the tabId whose cookies you need",
        "returns base64 — decode it caller-side"
      ],
      "related": [
        "pup_navigate",
        "pup_evaluate"
      ],
      "statusVerb": null,
      "summary": "Fetch a URL's content via the browser (cookies/session intact).",
      "timeoutSeconds": 45
    },
    {
      "example": {
        "selector": "button.download",
        "sessionId": "work"
      },
      "hint": "Download a file THROUGH THE BROWSER, exactly as the user clicking it would — real session, real cookies, real anti-bot cookies — and Chrome saves it to the Downloads folder. This is the right verb for vendor files (datasheets, KiCad/Altium libraries, STEP 3D models) that a server-side fetch/curl can never get past the site's bot wall. Pass selector to click the actual download button (authentic), or url to force-download via an in-page a[download]. Confirms completion via Chrome's download events and returns the ACTUAL saved path + byte count + file magic. For a gated file, log in on the window first (pup_login).",
      "input": {
        "saveAs": "optional str — filename override",
        "saveDir": "optional str — default the user's Downloads folder",
        "selector": "optional str — the real download control to click",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "url": "optional str — download this URL via an in-page a[download] click"
      },
      "longRunning": false,
      "name": "pup_download",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Download a file THROUGH THE BROWSER, exactly as the user clicking it would — real session, real cookies, real anti-bot cookies — and Chrome saves it to the Downloads folder. This is the right verb for vendor files (datasheets, KiCad/Altium libraries, STEP 3D models) that a server-side fetch/curl can never get past the site's bot wall. Pass selector to click the actual download button (authentic), or url to force-download via an in-page a[download]. Confirms completion via Chrome's download events and returns the ACTUAL saved path + byte count + file magic. For a gated file, log in on the window first (pup_login).",
      "timeoutSeconds": 100
    },
    {
      "example": {
        "sessionId": "work",
        "type": "mousePressed",
        "x": 100,
        "y": 200
      },
      "hint": "Low-level CDP mouse/keyboard input at coords — beats some overlays/iframes that swallow synthetic clicks.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "type": "required str",
        "x": "optional int",
        "y": "optional int"
      },
      "longRunning": false,
      "name": "pup_input_dispatch",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "coords are viewport pixels",
        "last-resort when pup_click can't reach the element — still cannot pass Cloudflare interactive challenges"
      ],
      "related": [
        "pup_click",
        "pup_press_key"
      ],
      "statusVerb": null,
      "summary": "Low-level input (mouse/keyboard) at coords — beats some overlays.",
      "timeoutSeconds": 20
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "Starts video recording of the page for this session.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_record_start",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "one recording per session — stop the current one before starting another"
      ],
      "related": [
        "pup_record_stop",
        "pup_record_status"
      ],
      "statusVerb": null,
      "summary": "Start recording the page (video).",
      "timeoutSeconds": 20
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "Stops recording and returns the saved file path.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_record_stop",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "no-op if nothing is recording for this session"
      ],
      "related": [
        "pup_record_start",
        "pup_record_list"
      ],
      "statusVerb": null,
      "summary": "Stop recording; returns the saved file.",
      "timeoutSeconds": 30
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "Whether a recording is active for the session.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_record_status",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [
        "pup_record_start",
        "pup_record_stop"
      ],
      "statusVerb": null,
      "summary": "Recording status for a session.",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "Lists saved page recordings.",
      "input": {},
      "longRunning": false,
      "name": "pup_record_list",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [
        "pup_record_start"
      ],
      "statusVerb": null,
      "summary": "List recordings.",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "Open pup's Chrome screen-share recorder HUD (WebM; consent = the visible HUD). Canonical name (pup-bridge#94).",
      "input": {
        "reason": "str (required)"
      },
      "longRunning": false,
      "name": "pup_recorder_open",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Open pup's Chrome screen-share recorder HUD (WebM; consent = the visible HUD). Canonical name (pup-bridge#94).",
      "timeoutSeconds": 20
    },
    {
      "example": {},
      "hint": "Start a whole-screen recording through Chrome screen-share (WebM VP9, system audio + mic). Canonical name; for a background no-browser MP4 of one window use ab-core desktop_record_window_start.",
      "input": {
        "audio": "bool",
        "confirmDesktopNotTabRecording": "true",
        "fps": "int",
        "maxDurationMs": "int",
        "reason": "str (required)"
      },
      "longRunning": false,
      "name": "pup_screen_record_start",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Start a whole-screen recording through Chrome screen-share (WebM VP9, system audio + mic). Canonical name; for a background no-browser MP4 of one window use ab-core desktop_record_window_start.",
      "timeoutSeconds": 20
    },
    {
      "example": {},
      "hint": "Stop the Chrome screen recording; returns the .webm path.",
      "input": {},
      "longRunning": false,
      "name": "pup_screen_record_stop",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Stop the Chrome screen recording; returns the .webm path.",
      "timeoutSeconds": 30
    },
    {
      "example": {},
      "hint": "Status of the Chrome screen recorder + any active clip.",
      "input": {},
      "longRunning": false,
      "name": "pup_screen_record_status",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Status of the Chrome screen recorder + any active clip.",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "List completed Chrome screen recordings on disk.",
      "input": {},
      "longRunning": false,
      "name": "pup_screen_record_list",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "List completed Chrome screen recordings on disk.",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "Close the Chrome screen-recorder HUD (auto-stops a clip).",
      "input": {},
      "longRunning": false,
      "name": "pup_recorder_close",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Close the Chrome screen-recorder HUD (auto-stops a clip).",
      "timeoutSeconds": 15
    },
    {
      "example": {},
      "hint": "Opens the desktop screen-recorder UI window. OWNERSHIP: the desktop_ namespace is ab-core's; pup serves these on ab's behalf only until ab-core's native whole-desktop recorder lands (adom-bridge#143), then they leave pup. Tab recording (pup_record_*) is pup's own.",
      "input": {},
      "longRunning": false,
      "name": "desktop_recorder_open",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [
        "desktop_record_start",
        "desktop_recorder_close"
      ],
      "statusVerb": null,
      "summary": "ALIAS of pup_recorder_open (routes to ab-core once its native recorder lands, adom-bridge#143).",
      "timeoutSeconds": 20
    },
    {
      "example": {},
      "hint": "Starts a full desktop screen recording (served by pup for ab-core until adom-bridge#143 lands; needs ffmpeg on the box for the duration header).",
      "input": {
        "outPath": "optional str"
      },
      "longRunning": false,
      "name": "desktop_record_start",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "only one desktop recording at a time"
      ],
      "related": [
        "desktop_record_stop",
        "desktop_record_status"
      ],
      "statusVerb": null,
      "summary": "ALIAS of pup_screen_record_start (routes to ab-core once its native recorder lands, adom-bridge#143).",
      "timeoutSeconds": 20
    },
    {
      "example": {},
      "hint": "Stops the desktop recording and returns the file.",
      "input": {},
      "longRunning": false,
      "name": "desktop_record_stop",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [
        "desktop_record_start",
        "desktop_record_list"
      ],
      "statusVerb": null,
      "summary": "ALIAS of pup_screen_record_stop.",
      "timeoutSeconds": 30
    },
    {
      "example": {},
      "hint": "Cold-start readiness probe: {ready, chromeForTestingInstalled, installing, installProgressPct}. On a fresh PC, poll this until ready:true before pup_open_window — the bridge auto-installs Chrome for Testing on its own.",
      "input": {},
      "longRunning": false,
      "name": "pup_readiness",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "ready:false with installing:true just means Chrome for Testing is still downloading — wait + poll, do NOT treat it as an error",
        "installPhase:\"failed\" → surface lastError to the user (usually network/proxy blocking the download, or low disk)"
      ],
      "related": [
        "pup_prewarm",
        "pup_open_window"
      ],
      "statusVerb": null,
      "summary": "Readiness + which browser pup will drive (installed Chrome/Edge, or cached Chrome for Testing) + the full candidate list and current default. READ-ONLY; never downloads.",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "Installs Chrome for Testing (the browser pup drives) WITHOUT opening a window — the warm-before-first-use path. Returns fast; poll pup_readiness for completion.",
      "input": {
        "setDefault": "optional bool (default true) — pin CfT as the default",
        "wait": "optional bool — block until installed"
      },
      "longRunning": false,
      "name": "pup_prewarm",
      "output": {
        "success": "bool"
      },
      "pitfalls": [
        "the ~150 MB download needs network access to storage.googleapis.com",
        "does not open a window — call pup_open_window once readiness reports ready:true"
      ],
      "related": [
        "pup_readiness",
        "pup_open_window"
      ],
      "statusVerb": null,
      "summary": "Install Chrome for Testing WITHOUT opening a window, and pin it as the default. Use when you specifically want CfT rather than the machine's installed Chrome/Edge.",
      "timeoutSeconds": 240
    },
    {
      "example": {},
      "hint": "Pin (or clear) the browser pup drives by default: chrome | edge | cft | auto (or an explicit executablePath). \"cft\" fetches Chrome for Testing then pins it. With {browser:\"chrome\", install:true} it DOWNLOADS & INSTALLS real Google Chrome on an Edge-only box, then pins it — SILENT on a normal PC; on a locked-down box (VM/managed device) it needs a Windows approval, so the bridge pops a native \"click YES on the UAC\" notification and, if it expires, re-notifies with a one-tap \"Approve now\" (all autonomous — no AI turn). Poll pup_readiness.chromeStablePhase: installing → awaiting_uac → ready. Persists across restarts; launch still spawn-verifies + falls back.",
      "input": {
        "browser": "\"chrome\" | \"edge\" | \"cft\" | \"auto\"",
        "elevate": "optional \"auto\"(default)|true|false — auto: quiet install, prompt only if it needs admin; false: never prompt; true: go straight to the prompt",
        "executablePath": "optional — pin an exact browser binary",
        "install": "optional bool — with browser:\"chrome\", install real Chrome if missing"
      },
      "longRunning": false,
      "name": "pup_use",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Pin (or clear) the browser pup drives by default: chrome | edge | cft | auto (or an explicit executablePath). \"cft\" fetches Chrome for Testing then pins it. With {browser:\"chrome\", install:true} it DOWNLOADS & INSTALLS real Google Chrome on an Edge-only box, then pins it — SILENT on a normal PC; on a locked-down box (VM/managed device) it needs a Windows approval, so the bridge pops a native \"click YES on the UAC\" notification and, if it expires, re-notifies with a one-tap \"Approve now\" (all autonomous — no AI turn). Poll pup_readiness.chromeStablePhase: installing → awaiting_uac → ready. Persists across restarts; launch still spawn-verifies + falls back.",
      "timeoutSeconds": 240
    },
    {
      "example": {},
      "hint": "Send a pup window to the BACKGROUND (behind the user's windows) without stealing focus — still fully drivable. The default for open; use this to re-hide a window you foregrounded.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_lower_os_window",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Send a pup window to the BACKGROUND (behind the user's windows) without stealing focus — still fully drivable. The default for open; use this to re-hide a window you foregrounded.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "foregroundReason": "user said \"show me the wiki page\""
      },
      "hint": "Bring a pup window to the FOREGROUND (user's screen). GATED (v1.8.70): REFUSED with foreground_reason_required unless you pass foregroundReason — a quote/paraphrase of what the user said that justifies it (min 10 chars; logged, recorded in lastAgentUpdate, auditable). Allowed ONLY when the user EXPLICITLY must SEE it (a demo, recording, \"show me\"). It STEALS focus — to just signal \"I updated this window\", use pup_alert_window (or the auto-flash), NOT raise. After the show-me: pup_lower_os_window to return it to the background. Alias: pup_focus_window. IMPORTANT: if you are foregrounding in order to CLICK a native dialog or a cross-origin FedCM/Google account chooser, do NOT raise-then-click yourself — use pup_assisted_click, which waits for the user to actually be on the window (alt-tab aware) and narrates via captions, so you never act while they are not ready.",
      "input": {
        "foregroundReason": "REQUIRED — why the user asked to see this window",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_raise_os_window",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Bring a pup window to the FOREGROUND (user's screen). GATED (v1.8.70): REFUSED with foreground_reason_required unless you pass foregroundReason — a quote/paraphrase of what the user said that justifies it (min 10 chars; logged, recorded in lastAgentUpdate, auditable). Allowed ONLY when the user EXPLICITLY must SEE it (a demo, recording, \"show me\"). It STEALS focus — to just signal \"I updated this window\", use pup_alert_window (or the auto-flash), NOT raise. After the show-me: pup_lower_os_window to return it to the background. Alias: pup_focus_window. IMPORTANT: if you are foregrounding in order to CLICK a native dialog or a cross-origin FedCM/Google account chooser, do NOT raise-then-click yourself — use pup_assisted_click, which waits for the user to actually be on the window (alt-tab aware) and narrates via captions, so you never act while they are not ready.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "sessionId": "work",
        "submit": true,
        "submitReason": "confirmed the tab is on the real vendor domain I intended to sign into"
      },
      "hint": "Fill (and optionally submit) an HTML login form in the CURRENT tab, in the BACKGROUND — no Chrome autofill dropdown, no foregrounding, React/Vue-safe. Creds from the keychain vault (matched on the tab URL; captured automatically as you log in, or stored via credential_set / save:true) or passed explicitly. Passwords are NEVER echoed back. Vault-matched pages AUTO-FILL on load (_autoLogin on the response). SUBMIT IS REASON-GATED: submit:true requires submitReason AND makes you confirm the live domain (the refusal regurgitates the exact host so a lookalike/phishing site is caught before the secret is sent). pup_configure {autoLogin:\"off\"} disables auto-fill; {captureLogins:\"off\"} stops auto-capture.",
      "input": {
        "host": "optional str — override the vault host key when saving",
        "password": "optional str — with username, fills these instead of the vault",
        "realKeystrokes": "optional bool — type with REAL key events instead of a background .value-set. Needed for React-controlled MASKED fields (Gusto/Keycloak SSO) that ignore .value and would submit an empty password. It briefly FOREGROUNDS the window (real keystrokes only register on-screen). Use when a normal fill returned filledPassword:false / reactMaskedFieldSuspected, or when the login-recipe for the site says so.",
        "save": "optional bool — with explicit creds, store them (OS keychain) so next time is automatic",
        "sessionId": "optional str — omit to target the window your own thread owns",
        "submit": "optional bool — submit after filling; REQUIRES submitReason",
        "submitReason": "required WITH submit:true — why you are confident the CURRENT domain is the correct, intended site to send these credentials to (min 10 chars; the refusal shows you the live host to confirm; logged, auditable)",
        "username": "optional str"
      },
      "longRunning": false,
      "name": "pup_login",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Fill (and optionally submit) an HTML login form in the CURRENT tab, in the BACKGROUND — no Chrome autofill dropdown, no foregrounding, React/Vue-safe. Creds from the keychain vault (matched on the tab URL; captured automatically as you log in, or stored via credential_set / save:true) or passed explicitly. Passwords are NEVER echoed back. Vault-matched pages AUTO-FILL on load (_autoLogin on the response). SUBMIT IS REASON-GATED: submit:true requires submitReason AND makes you confirm the live domain (the refusal regurgitates the exact host so a lookalike/phishing site is caught before the secret is sent). pup_configure {autoLogin:\"off\"} disables auto-fill; {captureLogins:\"off\"} stops auto-capture.",
      "timeoutSeconds": 20
    },
    {
      "example": {},
      "hint": "List saved logins (host + username only; passwords are in the OS keychain and NEVER returned). pup captures these automatically as you sign into sites and auto-fills them in the background on return visits.",
      "input": {},
      "longRunning": false,
      "name": "pup_credentials",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "List saved logins (host + username only; passwords are in the OS keychain and NEVER returned). pup captures these automatically as you sign into sites and auto-fills them in the background on return visits.",
      "timeoutSeconds": 10
    },
    {
      "example": {
        "host": "github.com",
        "reason": "signing into GitHub in my own browser to open a PR for the user"
      },
      "hint": "Reveal ONE saved login (username + password) to a LOCAL caller on the desktop, gated by a sticky consent toast the user must click. One host per call, never bulk. A relayed (cloud container) call is refused with relay_forbidden: from a cloud thread use pup_login instead, which signs the site in inside a pup window without the secret ever leaving the vault. The secret is returned ONCE and must never be logged or echoed.",
      "input": {
        "host": "required str — the site, e.g. \"github.com\"",
        "reason": "required str (min 10 chars) — shown to the user on the consent toast; say what you will do with it"
      },
      "longRunning": false,
      "name": "pup_credential_reveal",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Reveal ONE saved login (username + password) to a LOCAL caller on the desktop, gated by a sticky consent toast the user must click. One host per call, never bulk. A relayed (cloud container) call is refused with relay_forbidden: from a cloud thread use pup_login instead, which signs the site in inside a pup window without the secret ever leaving the vault. The secret is returned ONCE and must never be logged or echoed.",
      "timeoutSeconds": 130
    },
    {
      "example": {},
      "hint": "Store a payment card in the OS-keychain card vault under a nickname. Ask the USER for the details — never harvest them from a page. Validates Luhn + expiry + cvv. No verb ever returns the number or CVV afterward.",
      "input": {
        "cvv": "required 3-4 digits",
        "expiry": "required MM/YY",
        "name": "optional cardholder name",
        "nickname": "required str, e.g. \"adom-amex\"",
        "number": "required str"
      },
      "longRunning": false,
      "name": "pup_card_set",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Store a payment card in the OS-keychain card vault under a nickname. Ask the USER for the details — never harvest them from a page. Validates Luhn + expiry + cvv. No verb ever returns the number or CVV afterward.",
      "timeoutSeconds": 15
    },
    {
      "example": {},
      "hint": "List saved payment cards: nickname, brand, last4, expiry, cardholder only. The number and CVV never leave the keychain.",
      "input": {},
      "longRunning": false,
      "name": "pup_cards",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "List saved payment cards: nickname, brand, last4, expiry, cardholder only. The number and CVV never leave the keychain.",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "Remove a saved card from the keychain + index by nickname.",
      "input": {
        "nickname": "required str"
      },
      "longRunning": false,
      "name": "pup_card_delete",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Remove a saved card from the keychain + index by nickname.",
      "timeoutSeconds": 10
    },
    {
      "example": {
        "amount": "$350",
        "merchant": "venturedallas.com",
        "nickname": "adom-amex"
      },
      "hint": "Fill a saved card into the checkout page of a pup window WITHOUT the digits ever reaching you: pup types them into the card fields (walking payment-processor iframes like Stripe) and returns booleans. EVERY fill is gated by a desktop approval toast naming merchant, amount and last4 — the user authorizes the specific charge in the moment. Pass merchant+amount so the toast is honest. Allowed from cloud threads (the human click is the gate). After ok:true, screenshot to verify, then submit.",
      "input": {
        "amount": "recommended str, e.g. \"$350\"",
        "merchant": "recommended str — shown on the approval toast",
        "nickname": "required str",
        "window": "optional (defaults to your thread's window)"
      },
      "longRunning": false,
      "name": "pup_fill_card",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Fill a saved card into the checkout page of a pup window WITHOUT the digits ever reaching you: pup types them into the card fields (walking payment-processor iframes like Stripe) and returns booleans. EVERY fill is gated by a desktop approval toast naming merchant, amount and last4 — the user authorizes the specific charge in the moment. Pass merchant+amount so the toast is honest. Allowed from cloud threads (the human click is the gate). After ok:true, screenshot to verify, then submit.",
      "timeoutSeconds": 130
    },
    {
      "example": {
        "hostFilter": [
          "snapeda",
          "ultralibrarian",
          "digikey"
        ]
      },
      "hint": "Seed pup's vault from the user's OWN saved Chrome/Edge/Brave passwords, so pup can sign in as them on sites they already use (vendor CAD portals, etc). Runs the SYSTEM-elevated decrypt LOCALLY — the user approves ONE consent dialog + ONE Windows UAC prompt on the desktop (a cloud/relay caller cannot do this; only pup, a local bridge, can ask). Merges the identity-tagged rows into the keychain vault and DROPS the plaintext. Returns COUNTS ONLY. hostFilter narrows the import to matching hosts (surgical, e.g. [\"snapeda\",\"digikey\"]); omit to import everything saved. Pair with pup_import_scan (read-only preview of how many logins exist).",
      "input": {
        "browsers": "optional str[] subset of [\"chrome\",\"edge\",\"brave\"] (default: all found)",
        "hostFilter": "optional str or str[] — only import logins whose host contains one of these (surgical import)"
      },
      "longRunning": false,
      "name": "pup_import_browser_logins",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Seed pup's vault from the user's OWN saved Chrome/Edge/Brave passwords, so pup can sign in as them on sites they already use (vendor CAD portals, etc). Runs the SYSTEM-elevated decrypt LOCALLY — the user approves ONE consent dialog + ONE Windows UAC prompt on the desktop (a cloud/relay caller cannot do this; only pup, a local bridge, can ask). Merges the identity-tagged rows into the keychain vault and DROPS the plaintext. Returns COUNTS ONLY. hostFilter narrows the import to matching hosts (surgical, e.g. [\"snapeda\",\"digikey\"]); omit to import everything saved. Pair with pup_import_scan (read-only preview of how many logins exist).",
      "timeoutSeconds": 190
    },
    {
      "example": {
        "dryRun": true
      },
      "hint": "Delete LEAKED isolated profile directories — the iso-* throwaway jars minted by isolated:true opens (and by wikiView:public before 2.0.132, when the public view moved to the server-side ?view=public param) whose window is long gone (they used to pile up, 100s per machine). Only removes an iso-* dir that no live session or session file owns, that no Chrome is holding, and that is >15 min old; durable jars (adom-you, named profiles) are NEVER touched. Runs automatically every 15 min too. dryRun:true previews the list without deleting.",
      "input": {
        "dryRun": "optional bool — preview which iso-* profiles would be removed, delete nothing"
      },
      "longRunning": false,
      "name": "pup_reap_profiles",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Delete LEAKED isolated profile directories — the iso-* throwaway jars minted by isolated:true opens (and by wikiView:public before 2.0.132, when the public view moved to the server-side ?view=public param) whose window is long gone (they used to pile up, 100s per machine). Only removes an iso-* dir that no live session or session file owns, that no Chrome is holding, and that is >15 min old; durable jars (adom-you, named profiles) are NEVER touched. Runs automatically every 15 min too. dryRun:true previews the list without deleting.",
      "timeoutSeconds": 20
    },
    {
      "example": {},
      "hint": "MOVE this pup window's page into the user's Hydrogen workspace: the active tab's URL is handed to Hydrogen (ah) on this machine via its Browser Picker (webview by default, honoring the user's per-domain choice), then the pup window closes — its owner initiated the move. keepWindow:true keeps the pup window open too. Needs Hydrogen running locally (hydrogen_unreachable otherwise; the window is left untouched on failure). Cloud Hydrogen (hc) is not yet supported.",
      "input": {
        "keepWindow": "optional bool — hand the URL over but keep the pup window open",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_move_to_workspace",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "MOVE this pup window's page into the user's Hydrogen workspace: the active tab's URL is handed to Hydrogen (ah) on this machine via its Browser Picker (webview by default, honoring the user's per-domain choice), then the pup window closes — its owner initiated the move. keepWindow:true keeps the pup window open too. Needs Hydrogen running locally (hydrogen_unreachable otherwise; the window is left untouched on failure). Cloud Hydrogen (hc) is not yet supported.",
      "timeoutSeconds": 25
    },
    {
      "example": {
        "dryRun": true
      },
      "hint": "DESTRUCTIVE — cleanly remove pup's WHOLE footprint from this machine: the HKCU AppUserModelId Adom.Pup registry keys, all staged extensions, ALL pup profiles + sessions, the OS-keychain credential vault, pup-settings.json, the badge-debug temp dir, and the jump-list launcher. ALWAYS preview first with dryRun:true (removes nothing, returns the plan). To actually remove, pass confirm:\"uninstall\". keepCredentials:true preserves the saved-login vault; keepProfiles:true preserves profiles/sessions. Chrome-for-Testing + firewall rules are SHARED and left alone unless removeChrome:true / removeFirewallRules:true. Closes every window + quits every browser first to release profile locks. (The bridge itself is managed by Adom Bridge — remove pup from Bridge to stop it re-seeding.)",
      "input": {
        "confirm": "required str \"uninstall\" to actually remove",
        "dryRun": "optional bool — preview the removal plan without removing anything (do this first)",
        "keepCredentials": "optional bool — keep the saved-login vault",
        "keepProfiles": "optional bool — keep pup profiles + sessions",
        "removeChrome": "optional bool — also delete the Chrome-for-Testing install (shared; default keep)",
        "removeFirewallRules": "optional bool — also remove the CfT firewall rules (needs admin)"
      },
      "longRunning": false,
      "name": "pup_uninstall",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "DESTRUCTIVE — cleanly remove pup's WHOLE footprint from this machine: the HKCU AppUserModelId Adom.Pup registry keys, all staged extensions, ALL pup profiles + sessions, the OS-keychain credential vault, pup-settings.json, the badge-debug temp dir, and the jump-list launcher. ALWAYS preview first with dryRun:true (removes nothing, returns the plan). To actually remove, pass confirm:\"uninstall\". keepCredentials:true preserves the saved-login vault; keepProfiles:true preserves profiles/sessions. Chrome-for-Testing + firewall rules are SHARED and left alone unless removeChrome:true / removeFirewallRules:true. Closes every window + quits every browser first to release profile locks. (The bridge itself is managed by Adom Bridge — remove pup from Bridge to stop it re-seeding.)",
      "timeoutSeconds": 60
    },
    {
      "example": {},
      "hint": "Nudge the user about a pup window WITHOUT stealing focus — on Windows it flashes the taskbar button; on macOS (no taskbar, and no API to bounce another app's Dock tile) it unhides the window at its z-position and posts an AD toast whose click focuses it. Same contract on both, so call it identically; just never tell a Mac user to look for a flashing icon. NOTE (v1.8.23): mutating verbs already AUTO-FLASH (debounced, one per ~5s burst per window) so the user always knows the agent touched a window — use this for an explicit end-of-task \"it's ready\" nudge on top of that. STRONGLY prefer this (or the auto-flash) over pup_raise_os_window, which steals focus and can leak a mid-typed keystroke into the page.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "stop": "optional bool — CLEAR the highlight instead of flashing"
      },
      "longRunning": false,
      "name": "pup_alert_window",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Nudge the user about a pup window WITHOUT stealing focus — on Windows it flashes the taskbar button; on macOS (no taskbar, and no API to bounce another app's Dock tile) it unhides the window at its z-position and posts an AD toast whose click focuses it. Same contract on both, so call it identically; just never tell a Mac user to look for a flashing icon. NOTE (v1.8.23): mutating verbs already AUTO-FLASH (debounced, one per ~5s burst per window) so the user always knows the agent touched a window — use this for an explicit end-of-task \"it's ready\" nudge on top of that. STRONGLY prefer this (or the auto-flash) over pup_raise_os_window, which steals focus and can leak a mid-typed keystroke into the page.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "html": "<h1>Café</h1>",
        "sessionId": "work"
      },
      "hint": "Render a local HTML string in the tab via page.setContent — UTF-8-correct (a data: URL mojibakes accented chars without an explicit charset). Great for previewing generated markup without a temp file. Auto-flashes the window.",
      "input": {
        "html": "required HTML string",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "silent": "optional bool — suppress the auto-flash",
        "updateNote": "optional note for lastAgentUpdate",
        "waitUntil": "optional (domcontentloaded default)"
      },
      "longRunning": false,
      "name": "pup_render_html",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Render a local HTML string in the tab via page.setContent — UTF-8-correct (a data: URL mojibakes accented chars without an explicit charset). Great for previewing generated markup without a temp file. Auto-flashes the window.",
      "timeoutSeconds": 30
    },
    {
      "example": {},
      "hint": "List all open pup sessions + their tabs (NOT a readiness check — use pup_readiness for that).",
      "input": {},
      "longRunning": false,
      "name": "pup_status",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "List all open pup sessions + their tabs (NOT a readiness check — use pup_readiness for that).",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "List every open session/window with its tabs.",
      "input": {},
      "longRunning": false,
      "name": "pup_list_windows",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "List every open session/window with its tabs.",
      "timeoutSeconds": 10
    },
    {
      "example": {
        "expr": "document.querySelector(\"#userId\").value",
        "frame": "logonbox",
        "sessionId": "work"
      },
      "hint": "pup_eval accepts frame:\"<name|url-substring|index>\" to run inside an IFRAME (login forms usually live in one). Cross-origin frames work. Omit for the top document; a bad value returns frame_not_found WITH the list of frames in the tab.",
      "input": {
        "expr": "required str",
        "frame": "optional str",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_eval_frame_note",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "pup_eval accepts frame:\"<name|url-substring|index>\" to run inside an IFRAME (login forms usually live in one). Cross-origin frames work. Omit for the top document; a bad value returns frame_not_found WITH the list of frames in the tab.",
      "timeoutSeconds": 20
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "Make a session the active one (for verbs that default to active).",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_switch_window",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Make a session the active one (for verbs that default to active).",
      "timeoutSeconds": 10
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "List the tabs in a session.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_list_tabs",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "List the tabs in a session.",
      "timeoutSeconds": 10
    },
    {
      "example": {
        "sessionId": "work",
        "tabId": "tab-2"
      },
      "hint": "Activate a tab WITHIN its session/window (idempotent — safe to call when the tab is already active). Does NOT raise a background window to the user's screen: the tab becomes the window's visible tab wherever the window is, and the taskbar auto-flash tells the user something changed. Also self-heals the window (re-park if a bug ever stranded it off-screen) and refreshes the Adom taskbar badge — good citizenship for long-lived shared windows.",
      "input": {
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "silent": "optional bool",
        "tabId": "required str",
        "updateNote": "optional str"
      },
      "longRunning": false,
      "name": "pup_switch_tab",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Activate a tab WITHIN its session/window (idempotent — safe to call when the tab is already active). Does NOT raise a background window to the user's screen: the tab becomes the window's visible tab wherever the window is, and the taskbar auto-flash tells the user something changed. Also self-heals the window (re-park if a bug ever stranded it off-screen) and refreshes the Adom taskbar badge — good citizenship for long-lived shared windows.",
      "timeoutSeconds": 10
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "FULL-resolution page screenshot (NOT downscaled — for saving to disk, NOT for Read: it can exceed Claude's image limit). Use pup_screenshot for AI-readable shots.",
      "input": {
        "fullPage": "optional bool",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_screenshot_full_res",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "FULL-resolution page screenshot (NOT downscaled — for saving to disk, NOT for Read: it can exceed Claude's image limit). Use pup_screenshot for AI-readable shots.",
      "timeoutSeconds": 30
    },
    {
      "example": {
        "sessionId": "work"
      },
      "hint": "Console errors + failed network requests for a session/tab (clears by default).",
      "input": {
        "clear": "optional bool (default true)",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)",
        "tabId": "optional str"
      },
      "longRunning": false,
      "name": "pup_errors",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Console errors + failed network requests for a session/tab (clears by default).",
      "timeoutSeconds": 10
    },
    {
      "example": {
        "ms": 500,
        "sessionId": "work"
      },
      "hint": "Wait N ms (or for a selector) before the next step.",
      "input": {
        "ms": "optional int",
        "selector": "optional str",
        "sessionId": "optional str — OMIT IT: zero-id addressing resolves your --ai-thread name to your own window. Pass a window label only when one thread runs several windows (`window` is the new name for this param; sessionId is the legacy alias)"
      },
      "longRunning": false,
      "name": "pup_wait",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Wait N ms (or for a selector) before the next step.",
      "timeoutSeconds": 60
    },
    {
      "example": {},
      "hint": "Recover orphaned sessions: reconnect dropped CDP sockets + rebuild sessions from window titles. Pass adoptOrphans:true to also adopt untagged tabs.",
      "input": {
        "adoptOrphans": "optional bool"
      },
      "longRunning": false,
      "name": "pup_rescan",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Recover orphaned sessions: reconnect dropped CDP sockets + rebuild sessions from window titles. Pass adoptOrphans:true to also adopt untagged tabs.",
      "timeoutSeconds": 30
    },
    {
      "example": {},
      "hint": "Close ALL pup sessions + windows at once (destructive). NOTE: `{}` here does NOT mean \"the active session\" the way it does on other session-scoped verbs — with no args this closes EVERY window, across every AI thread on the machine, with no confirmation. To close ONE window use pup_close_window {sessionId}. Pass {sessionId} here only if you genuinely mean that one session.",
      "input": {},
      "longRunning": false,
      "name": "pup_close",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Close ALL pup sessions + windows at once (destructive). NOTE: `{}` here does NOT mean \"the active session\" the way it does on other session-scoped verbs — with no args this closes EVERY window, across every AI thread on the machine, with no confirmation. To close ONE window use pup_close_window {sessionId}. Pass {sessionId} here only if you genuinely mean that one session.",
      "timeoutSeconds": 20
    },
    {
      "example": {},
      "hint": "ALIAS of pup_screen_record_status.",
      "input": {},
      "longRunning": false,
      "name": "desktop_record_status",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "ALIAS of pup_screen_record_status.",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "ALIAS of pup_screen_record_list.",
      "input": {},
      "longRunning": false,
      "name": "desktop_record_list",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "ALIAS of pup_screen_record_list.",
      "timeoutSeconds": 10
    },
    {
      "example": {},
      "hint": "ALIAS of pup_recorder_close.",
      "input": {},
      "longRunning": false,
      "name": "desktop_recorder_close",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "ALIAS of pup_recorder_close.",
      "timeoutSeconds": 15
    },
    {
      "example": {
        "taskbarGrouping": "grouped"
      },
      "hint": "Get/set user-facing pup preferences (persisted across bridge updates). taskbarGrouping: \"split\" (default — one taskbar button PER WINDOW, each badged with its own tab count; best for telling AI threads apart) | \"grouped\" (all pup windows stack under ONE \"Adom Pup\" button, badge shows window count; tidy taskbar). Applies to live windows immediately. Ask the USER which they prefer before changing it — this is their taskbar. WINDOWS ONLY: macOS has no taskbar, so the setting is stored but INERT there; the reply carries platform + taskbarSupported so branch on those, not on this text.",
      "input": {
        "autoLogin": "optional \"on\"|\"off\" — auto-fill a vault-matched login form on page load (fill only, never submits), on by default",
        "overlaySize": "optional \"50\"|\"100\" — how big the favicon badge is drawn on the taskbar button. \"50\" (the DEFAULT) draws it at half size so it stays clear of the thread tile's bottom line of text; \"100\" is the older, larger badge",
        "reportIssues": "optional \"on\"|\"off\" — pup's bug-report invitation (_reportIssues), on by default",
        "taskbarActivity": "optional \"progress\"|\"flash\"|\"off\" — how pup signals it is working on a window, on that window's taskbar button: a determinate progress bar sized to the operation's running-average time (default), the old orange flash, or nothing. Replaces the former openFlash/autoFlash/agentActivity toggles.",
        "taskbarGrouping": "optional \"split\"|\"grouped\""
      },
      "longRunning": false,
      "name": "pup_configure",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [],
      "statusVerb": null,
      "summary": "Get/set user-facing pup preferences (persisted across bridge updates). taskbarGrouping: \"split\" (default — one taskbar button PER WINDOW, each badged with its own tab count; best for telling AI threads apart) | \"grouped\" (all pup windows stack under ONE \"Adom Pup\" button, badge shows window count; tidy taskbar). Applies to live windows immediately. Ask the USER which they prefer before changing it — this is their taskbar. WINDOWS ONLY: macOS has no taskbar, so the setting is stored but INERT there; the reply carries platform + taskbarSupported so branch on those, not on this text.",
      "timeoutSeconds": 15
    },
    {
      "example": {},
      "hint": "This list — the bridge's verbs + schemas + hints, for AD's Verbs tab. Read it once to learn the surface.",
      "input": {},
      "longRunning": false,
      "name": "pup_describe",
      "output": {
        "success": "bool"
      },
      "pitfalls": [],
      "related": [
        "pup_status"
      ],
      "statusVerb": null,
      "summary": "This list — the bridge's verbs + schemas, for AD's Verbs tab.",
      "timeoutSeconds": 10
    }
  ]
}