pi-agent-browser-native 0.9.3 → 0.9.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (394) hide show
  1. package/CHANGELOG.md +106 -5
  2. package/README.md +58 -791
  3. package/dist/extensions/agent-browser/index.js +43101 -2031
  4. package/dist/extensions/agent-browser/lib/argv-descriptor.js +49 -26
  5. package/dist/extensions/agent-browser/lib/argv-grammar.js +82 -93
  6. package/dist/extensions/agent-browser/lib/bash-guard.js +129 -126
  7. package/dist/extensions/agent-browser/lib/batch-lifecycle.js +112 -51
  8. package/dist/extensions/agent-browser/lib/browser-execution-claim-codec.js +61 -0
  9. package/dist/extensions/agent-browser/lib/browser-execution-claim-storage.js +232 -0
  10. package/dist/extensions/agent-browser/lib/browser-execution-claims.js +202 -0
  11. package/dist/extensions/agent-browser/lib/browser-execution-identity.js +77 -0
  12. package/dist/extensions/agent-browser/lib/browser-journal-branch.js +98 -0
  13. package/dist/extensions/agent-browser/lib/browser-journal-contracts.js +1 -0
  14. package/dist/extensions/agent-browser/lib/browser-journal-projection.js +221 -0
  15. package/dist/extensions/agent-browser/lib/browser-journal-reader.js +89 -0
  16. package/dist/extensions/agent-browser/lib/browser-journal-replay.js +246 -0
  17. package/dist/extensions/agent-browser/lib/browser-journal.js +103 -394
  18. package/dist/extensions/agent-browser/lib/browser-legacy-pages.js +220 -0
  19. package/dist/extensions/agent-browser/lib/browser-legacy-projection.js +282 -0
  20. package/dist/extensions/agent-browser/lib/browser-legacy-types.js +1 -0
  21. package/dist/extensions/agent-browser/lib/browser-session-conversion-stream.js +217 -0
  22. package/dist/extensions/agent-browser/lib/browser-session-conversion.js +80 -335
  23. package/dist/extensions/agent-browser/lib/browser-transcript-contracts.js +35 -0
  24. package/dist/extensions/agent-browser/lib/browser-transcript-validation.js +166 -0
  25. package/dist/extensions/agent-browser/lib/browser-transcript.js +137 -82
  26. package/dist/extensions/agent-browser/lib/browser-value-parsing.js +15 -0
  27. package/dist/extensions/agent-browser/lib/command-capabilities.js +340 -0
  28. package/dist/extensions/agent-browser/lib/command-policy.js +107 -88
  29. package/dist/extensions/agent-browser/lib/command-taxonomy.js +49 -322
  30. package/dist/extensions/agent-browser/lib/config-policy.js +138 -343
  31. package/dist/extensions/agent-browser/lib/config-providers.js +71 -0
  32. package/dist/extensions/agent-browser/lib/config-validation.js +231 -0
  33. package/dist/extensions/agent-browser/lib/config.js +20 -8
  34. package/dist/extensions/agent-browser/lib/electron/cdp.js +20 -8
  35. package/dist/extensions/agent-browser/lib/electron/cleanup.js +128 -83
  36. package/dist/extensions/agent-browser/lib/electron/discovery-darwin.js +109 -0
  37. package/dist/extensions/agent-browser/lib/electron/discovery-desktop.js +136 -0
  38. package/dist/extensions/agent-browser/lib/electron/discovery-evidence.js +90 -0
  39. package/dist/extensions/agent-browser/lib/electron/discovery-linux.js +93 -0
  40. package/dist/extensions/agent-browser/lib/electron/discovery-packages.js +162 -0
  41. package/dist/extensions/agent-browser/lib/electron/discovery-types.js +2 -0
  42. package/dist/extensions/agent-browser/lib/electron/discovery.js +140 -549
  43. package/dist/extensions/agent-browser/lib/electron/launch-monitor.js +102 -0
  44. package/dist/extensions/agent-browser/lib/electron/launch-process.js +209 -0
  45. package/dist/extensions/agent-browser/lib/electron/launch-types.js +2 -0
  46. package/dist/extensions/agent-browser/lib/electron/launch.js +261 -355
  47. package/dist/extensions/agent-browser/lib/executable-path.js +21 -12
  48. package/dist/extensions/agent-browser/lib/execution-cwd.js +35 -18
  49. package/dist/extensions/agent-browser/lib/fs-utils.js +1 -9
  50. package/dist/extensions/agent-browser/lib/input-modes/electron.js +162 -121
  51. package/dist/extensions/agent-browser/lib/input-modes/job.js +123 -317
  52. package/dist/extensions/agent-browser/lib/input-modes/lookup-network-evidence.js +116 -0
  53. package/dist/extensions/agent-browser/lib/input-modes/lookup-plan.js +132 -0
  54. package/dist/extensions/agent-browser/lib/input-modes/lookup-redaction.js +57 -0
  55. package/dist/extensions/agent-browser/lib/input-modes/lookup-source-evidence.js +151 -0
  56. package/dist/extensions/agent-browser/lib/input-modes/lookup-workspace.js +142 -0
  57. package/dist/extensions/agent-browser/lib/input-modes/lookups.js +58 -412
  58. package/dist/extensions/agent-browser/lib/input-modes/params.js +86 -40
  59. package/dist/extensions/agent-browser/lib/input-modes/qa-analysis.js +268 -0
  60. package/dist/extensions/agent-browser/lib/input-modes/qa-presentation.js +117 -0
  61. package/dist/extensions/agent-browser/lib/input-modes/script-child.js +396 -0
  62. package/dist/extensions/agent-browser/lib/input-modes/script-protocol.js +86 -0
  63. package/dist/extensions/agent-browser/lib/input-modes/script-types.js +1 -0
  64. package/dist/extensions/agent-browser/lib/input-modes/script-validation.js +60 -0
  65. package/dist/extensions/agent-browser/lib/input-modes/script.js +60 -409
  66. package/dist/extensions/agent-browser/lib/input-modes/semantic-action.js +218 -128
  67. package/dist/extensions/agent-browser/lib/input-modes/shared.js +15 -4
  68. package/dist/extensions/agent-browser/lib/input-modes/types.js +56 -7
  69. package/dist/extensions/agent-browser/lib/json-schema.js +22 -10
  70. package/dist/extensions/agent-browser/lib/launch-scoped-flags.js +17 -5
  71. package/dist/extensions/agent-browser/lib/managed-session-policy-lock.js +92 -425
  72. package/dist/extensions/agent-browser/lib/managed-session-posix-storage.js +58 -0
  73. package/dist/extensions/agent-browser/lib/managed-session-project-identity.js +244 -0
  74. package/dist/extensions/agent-browser/lib/managed-session-restore-context.js +84 -0
  75. package/dist/extensions/agent-browser/lib/managed-session-restore-policy.js +119 -0
  76. package/dist/extensions/agent-browser/lib/managed-session-restore-state.js +83 -0
  77. package/dist/extensions/agent-browser/lib/managed-session-restore.js +168 -300
  78. package/dist/extensions/agent-browser/lib/managed-session-snapshot-records.js +277 -0
  79. package/dist/extensions/agent-browser/lib/managed-session-snapshots.js +128 -305
  80. package/dist/extensions/agent-browser/lib/managed-session-storage.js +56 -253
  81. package/dist/extensions/agent-browser/lib/native-confirmation.js +140 -0
  82. package/dist/extensions/agent-browser/lib/native-output.js +43 -9
  83. package/dist/extensions/agent-browser/lib/orchestration/batch-stdin.js +106 -59
  84. package/dist/extensions/agent-browser/lib/orchestration/browser-run/artifact-merge.js +14 -6
  85. package/dist/extensions/agent-browser/lib/orchestration/browser-run/artifact-paths.js +109 -57
  86. package/dist/extensions/agent-browser/lib/orchestration/browser-run/browser-observation-result.js +82 -0
  87. package/dist/extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.js +164 -60
  88. package/dist/extensions/agent-browser/lib/orchestration/browser-run/diagnostic-values.js +31 -0
  89. package/dist/extensions/agent-browser/lib/orchestration/browser-run/diagnostics.js +152 -781
  90. package/dist/extensions/agent-browser/lib/orchestration/browser-run/electron-observation.js +203 -0
  91. package/dist/extensions/agent-browser/lib/orchestration/browser-run/electron-text-diagnostics.js +109 -0
  92. package/dist/extensions/agent-browser/lib/orchestration/browser-run/fill-diagnostics.js +119 -0
  93. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-action-recovery.js +147 -0
  94. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-actions.js +144 -0
  95. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-content.js +123 -0
  96. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-contracts.js +1 -0
  97. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-details.js +156 -0
  98. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-electron.js +187 -0
  99. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-evidence.js +39 -0
  100. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-missing-binary.js +89 -0
  101. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-recovery.js +97 -0
  102. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-redaction.js +106 -0
  103. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-timeout.js +110 -0
  104. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result.js +41 -538
  105. package/dist/extensions/agent-browser/lib/orchestration/browser-run/index.js +199 -154
  106. package/dist/extensions/agent-browser/lib/orchestration/browser-run/interaction-diagnostics.js +290 -0
  107. package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-close.js +167 -0
  108. package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-daemon-inspection.js +108 -0
  109. package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-daemon-policy.js +127 -205
  110. package/dist/extensions/agent-browser/lib/orchestration/browser-run/native-helper-observation.js +65 -0
  111. package/dist/extensions/agent-browser/lib/orchestration/browser-run/observation-types.js +1 -0
  112. package/dist/extensions/agent-browser/lib/orchestration/browser-run/overlay-diagnostics.js +120 -0
  113. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/network-page-filter.js +113 -30
  114. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/scroll-shims.js +109 -28
  115. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/snapshot-filter-data.js +150 -0
  116. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/snapshot-filter.js +147 -253
  117. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/snapshot-rendered-text.js +147 -0
  118. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/wait-timeouts.js +59 -24
  119. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-artifacts.js +159 -0
  120. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-command.js +131 -0
  121. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-contracts.js +1 -0
  122. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-daemon.js +93 -0
  123. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-failure.js +42 -0
  124. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-guards.js +242 -0
  125. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-input.js +75 -0
  126. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-observations.js +92 -0
  127. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-page-selection.js +254 -0
  128. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-page-state.js +121 -0
  129. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-refs.js +130 -0
  130. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-resources.js +114 -0
  131. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-semantic.js +121 -0
  132. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-session-plan.js +222 -0
  133. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-timeouts.js +68 -0
  134. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare.js +176 -1123
  135. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-analysis.js +191 -0
  136. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-confirmation.js +152 -0
  137. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-diagnostics.js +182 -0
  138. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-electron.js +150 -0
  139. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle-contracts.js +1 -0
  140. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle-phase-contracts.js +1 -0
  141. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle-phase.js +115 -0
  142. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle.js +256 -0
  143. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-managed-contracts.js +1 -0
  144. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-managed.js +256 -0
  145. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-native-phase-contracts.js +1 -0
  146. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-native-phase.js +93 -0
  147. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-native.js +113 -0
  148. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-navigation-contracts.js +1 -0
  149. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-navigation.js +316 -0
  150. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-ownership.js +28 -0
  151. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-page-phase-contracts.js +1 -0
  152. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-page-phase.js +142 -0
  153. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-presentation-contracts.js +1 -0
  154. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-presentation.js +333 -0
  155. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-publication-phase-contracts.js +1 -0
  156. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-publication-phase.js +71 -0
  157. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-publication.js +201 -0
  158. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-receipts.js +183 -0
  159. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-refs.js +200 -0
  160. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-tabs.js +142 -0
  161. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output.js +18 -968
  162. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prompt-guards.js +23 -13
  163. package/dist/extensions/agent-browser/lib/orchestration/browser-run/recording-receipt-reconciliation.js +198 -0
  164. package/dist/extensions/agent-browser/lib/orchestration/browser-run/recording-recovery-contracts.js +1 -0
  165. package/dist/extensions/agent-browser/lib/orchestration/browser-run/recording-recovery-presentation.js +154 -0
  166. package/dist/extensions/agent-browser/lib/orchestration/browser-run/recording-recovery.js +68 -151
  167. package/dist/extensions/agent-browser/lib/orchestration/browser-run/screenshot-capture.js +14 -0
  168. package/dist/extensions/agent-browser/lib/orchestration/browser-run/screenshot-observation.js +169 -46
  169. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-commands.js +130 -0
  170. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-electron.js +212 -0
  171. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-observations.js +61 -0
  172. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-outcomes.js +187 -0
  173. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-refs.js +169 -0
  174. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-tabs.js +228 -0
  175. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state.js +77 -765
  176. package/dist/extensions/agent-browser/lib/orchestration/browser-run/text-visibility-diagnostics.js +182 -0
  177. package/dist/extensions/agent-browser/lib/orchestration/browser-run/timeout-diagnostics.js +256 -0
  178. package/dist/extensions/agent-browser/lib/orchestration/browser-run/timeout-progress.js +108 -0
  179. package/dist/extensions/agent-browser/lib/orchestration/code-artifact-observation.js +39 -0
  180. package/dist/extensions/agent-browser/lib/orchestration/code-image-observation.js +119 -0
  181. package/dist/extensions/agent-browser/lib/orchestration/electron-host/branch.js +93 -0
  182. package/dist/extensions/agent-browser/lib/orchestration/electron-host/cleanup-result.js +58 -0
  183. package/dist/extensions/agent-browser/lib/orchestration/electron-host/cleanup.js +78 -0
  184. package/dist/extensions/agent-browser/lib/orchestration/electron-host/contracts.js +1 -0
  185. package/dist/extensions/agent-browser/lib/orchestration/electron-host/discovery.js +106 -0
  186. package/dist/extensions/agent-browser/lib/orchestration/electron-host/index.js +48 -821
  187. package/dist/extensions/agent-browser/lib/orchestration/electron-host/policy.js +86 -0
  188. package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe-collection.js +68 -0
  189. package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe-data.js +169 -0
  190. package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe-presentation.js +182 -0
  191. package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe.js +161 -0
  192. package/dist/extensions/agent-browser/lib/orchestration/electron-host/status.js +167 -0
  193. package/dist/extensions/agent-browser/lib/orchestration/execution-queue.js +22 -10
  194. package/dist/extensions/agent-browser/lib/orchestration/extension-artifact-preflight.js +211 -0
  195. package/dist/extensions/agent-browser/lib/orchestration/extension-artifacts.js +23 -0
  196. package/dist/extensions/agent-browser/lib/orchestration/extension-attachment-replay.js +99 -0
  197. package/dist/extensions/agent-browser/lib/orchestration/extension-branch-restore.js +275 -0
  198. package/dist/extensions/agent-browser/lib/orchestration/extension-code.js +280 -0
  199. package/dist/extensions/agent-browser/lib/orchestration/extension-command-admission.js +303 -0
  200. package/dist/extensions/agent-browser/lib/orchestration/extension-command-output.js +36 -0
  201. package/dist/extensions/agent-browser/lib/orchestration/extension-command-result.js +335 -0
  202. package/dist/extensions/agent-browser/lib/orchestration/extension-command-run.js +227 -0
  203. package/dist/extensions/agent-browser/lib/orchestration/extension-command-state.js +1 -0
  204. package/dist/extensions/agent-browser/lib/orchestration/extension-electron-ownership.js +204 -0
  205. package/dist/extensions/agent-browser/lib/orchestration/extension-execution-locks.js +139 -0
  206. package/dist/extensions/agent-browser/lib/orchestration/extension-execution-queue.js +24 -0
  207. package/dist/extensions/agent-browser/lib/orchestration/extension-host-coordination.js +98 -0
  208. package/dist/extensions/agent-browser/lib/orchestration/extension-host-run.js +295 -0
  209. package/dist/extensions/agent-browser/lib/orchestration/extension-intent-replay.js +41 -0
  210. package/dist/extensions/agent-browser/lib/orchestration/extension-invocation.js +7 -0
  211. package/dist/extensions/agent-browser/lib/orchestration/extension-lifecycle.js +102 -0
  212. package/dist/extensions/agent-browser/lib/orchestration/extension-managed-ownership.js +133 -0
  213. package/dist/extensions/agent-browser/lib/orchestration/extension-observation.js +120 -0
  214. package/dist/extensions/agent-browser/lib/orchestration/extension-prompt.js +180 -0
  215. package/dist/extensions/agent-browser/lib/orchestration/extension-recording.js +290 -0
  216. package/dist/extensions/agent-browser/lib/orchestration/extension-resource-contracts.js +1 -0
  217. package/dist/extensions/agent-browser/lib/orchestration/extension-resource-replay.js +269 -0
  218. package/dist/extensions/agent-browser/lib/orchestration/extension-result-state.js +113 -0
  219. package/dist/extensions/agent-browser/lib/orchestration/extension-runtime.js +146 -0
  220. package/dist/extensions/agent-browser/lib/orchestration/extension-script-leases.js +58 -0
  221. package/dist/extensions/agent-browser/lib/orchestration/extension-tool-boundary.js +62 -0
  222. package/dist/extensions/agent-browser/lib/orchestration/extension-version-check.js +54 -0
  223. package/dist/extensions/agent-browser/lib/orchestration/input-plan-types.js +1 -0
  224. package/dist/extensions/agent-browser/lib/orchestration/input-plan.js +261 -185
  225. package/dist/extensions/agent-browser/lib/orchestration/input-redaction.js +62 -0
  226. package/dist/extensions/agent-browser/lib/orchestration/native-config.js +144 -0
  227. package/dist/extensions/agent-browser/lib/orchestration/native-root-launch.js +77 -0
  228. package/dist/extensions/agent-browser/lib/orchestration/native-session-defaults.js +210 -157
  229. package/dist/extensions/agent-browser/lib/orchestration/operation-paths.js +124 -58
  230. package/dist/extensions/agent-browser/lib/orchestration/output-file.js +197 -99
  231. package/dist/extensions/agent-browser/lib/orchestration/script-mode.js +199 -96
  232. package/dist/extensions/agent-browser/lib/owned-managed-session-context.js +55 -0
  233. package/dist/extensions/agent-browser/lib/page-target-batch.js +118 -0
  234. package/dist/extensions/agent-browser/lib/page-target-guards.js +50 -0
  235. package/dist/extensions/agent-browser/lib/page-target-navigation.js +104 -0
  236. package/dist/extensions/agent-browser/lib/page-target-validation.js +55 -246
  237. package/dist/extensions/agent-browser/lib/parsing.js +13 -4
  238. package/dist/extensions/agent-browser/lib/pi-tool-rendering.js +133 -68
  239. package/dist/extensions/agent-browser/lib/playbook.js +16 -12
  240. package/dist/extensions/agent-browser/lib/process-child.js +284 -0
  241. package/dist/extensions/agent-browser/lib/process-environment.js +13 -6
  242. package/dist/extensions/agent-browser/lib/process-errors.js +23 -0
  243. package/dist/extensions/agent-browser/lib/process-identity.js +47 -15
  244. package/dist/extensions/agent-browser/lib/process-socket-storage.js +256 -0
  245. package/dist/extensions/agent-browser/lib/process-stdout.js +74 -0
  246. package/dist/extensions/agent-browser/lib/process.js +145 -536
  247. package/dist/extensions/agent-browser/lib/prompt-artifacts.js +287 -0
  248. package/dist/extensions/agent-browser/lib/prompt-policy.js +15 -194
  249. package/dist/extensions/agent-browser/lib/read-command.js +41 -0
  250. package/dist/extensions/agent-browser/lib/read-confirmation.js +131 -68
  251. package/dist/extensions/agent-browser/lib/recording-reservations.js +118 -45
  252. package/dist/extensions/agent-browser/lib/redaction-fields.js +75 -0
  253. package/dist/extensions/agent-browser/lib/redaction-json.js +149 -0
  254. package/dist/extensions/agent-browser/lib/redaction-url.js +88 -0
  255. package/dist/extensions/agent-browser/lib/results/action-contracts.js +1 -0
  256. package/dist/extensions/agent-browser/lib/results/action-recommendations.js +28 -271
  257. package/dist/extensions/agent-browser/lib/results/artifact-contracts.js +1 -0
  258. package/dist/extensions/agent-browser/lib/results/artifact-manifest-validation.js +133 -0
  259. package/dist/extensions/agent-browser/lib/results/artifact-manifest.js +96 -94
  260. package/dist/extensions/agent-browser/lib/results/artifact-recommendations.js +73 -0
  261. package/dist/extensions/agent-browser/lib/results/categories.js +111 -54
  262. package/dist/extensions/agent-browser/lib/results/confirmation.js +29 -13
  263. package/dist/extensions/agent-browser/lib/results/editable-ref-evidence.js +62 -27
  264. package/dist/extensions/agent-browser/lib/results/electron-recommendations.js +83 -0
  265. package/dist/extensions/agent-browser/lib/results/envelope-decoding.js +48 -0
  266. package/dist/extensions/agent-browser/lib/results/envelope.js +90 -67
  267. package/dist/extensions/agent-browser/lib/results/evidence-contracts.js +1 -0
  268. package/dist/extensions/agent-browser/lib/results/failure-recommendations.js +180 -0
  269. package/dist/extensions/agent-browser/lib/results/network-routes.js +86 -45
  270. package/dist/extensions/agent-browser/lib/results/network.js +35 -12
  271. package/dist/extensions/agent-browser/lib/results/next-actions.js +49 -19
  272. package/dist/extensions/agent-browser/lib/results/presentation/artifact-files.js +320 -0
  273. package/dist/extensions/agent-browser/lib/results/presentation/artifact-format.js +138 -0
  274. package/dist/extensions/agent-browser/lib/results/presentation/artifact-images.js +113 -0
  275. package/dist/extensions/agent-browser/lib/results/presentation/artifact-verification.js +145 -0
  276. package/dist/extensions/agent-browser/lib/results/presentation/artifacts.js +99 -555
  277. package/dist/extensions/agent-browser/lib/results/presentation/batch-contracts.js +1 -0
  278. package/dist/extensions/agent-browser/lib/results/presentation/batch-recording.js +118 -0
  279. package/dist/extensions/agent-browser/lib/results/presentation/batch-redaction.js +68 -0
  280. package/dist/extensions/agent-browser/lib/results/presentation/batch-rendering.js +135 -0
  281. package/dist/extensions/agent-browser/lib/results/presentation/batch-step.js +227 -0
  282. package/dist/extensions/agent-browser/lib/results/presentation/batch-summary.js +91 -0
  283. package/dist/extensions/agent-browser/lib/results/presentation/batch.js +91 -460
  284. package/dist/extensions/agent-browser/lib/results/presentation/browser-profile-recovery.js +9 -5
  285. package/dist/extensions/agent-browser/lib/results/presentation/command-presenters.js +216 -0
  286. package/dist/extensions/agent-browser/lib/results/presentation/common.js +26 -9
  287. package/dist/extensions/agent-browser/lib/results/presentation/content.js +86 -29
  288. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-a11y.js +67 -0
  289. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-health.js +79 -0
  290. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-identity.js +199 -0
  291. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-logs.js +75 -0
  292. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-network-actions.js +216 -0
  293. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-network.js +124 -0
  294. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-redaction.js +64 -0
  295. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-storage.js +209 -0
  296. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-stream.js +69 -0
  297. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-summary.js +222 -0
  298. package/dist/extensions/agent-browser/lib/results/presentation/diagnostics.js +103 -1052
  299. package/dist/extensions/agent-browser/lib/results/presentation/early-result.js +70 -0
  300. package/dist/extensions/agent-browser/lib/results/presentation/errors.js +130 -60
  301. package/dist/extensions/agent-browser/lib/results/presentation/input-contracts.js +1 -0
  302. package/dist/extensions/agent-browser/lib/results/presentation/large-output.js +60 -145
  303. package/dist/extensions/agent-browser/lib/results/presentation/navigation.js +147 -88
  304. package/dist/extensions/agent-browser/lib/results/presentation/notices.js +75 -0
  305. package/dist/extensions/agent-browser/lib/results/presentation/observation-contracts.js +1 -0
  306. package/dist/extensions/agent-browser/lib/results/presentation/observation-rendering.js +127 -0
  307. package/dist/extensions/agent-browser/lib/results/presentation/outcomes.js +120 -0
  308. package/dist/extensions/agent-browser/lib/results/presentation/output-completion.js +77 -0
  309. package/dist/extensions/agent-browser/lib/results/presentation/output-spill.js +51 -0
  310. package/dist/extensions/agent-browser/lib/results/presentation/registry.js +116 -240
  311. package/dist/extensions/agent-browser/lib/results/presentation/semantic-action.js +35 -21
  312. package/dist/extensions/agent-browser/lib/results/presentation/skills.js +109 -73
  313. package/dist/extensions/agent-browser/lib/results/presentation/source.js +109 -0
  314. package/dist/extensions/agent-browser/lib/results/presentation.js +17 -261
  315. package/dist/extensions/agent-browser/lib/results/recommendation-contracts.js +1 -0
  316. package/dist/extensions/agent-browser/lib/results/recording.js +52 -14
  317. package/dist/extensions/agent-browser/lib/results/recovery-actions.js +14 -5
  318. package/dist/extensions/agent-browser/lib/results/recovery-next-actions.js +30 -22
  319. package/dist/extensions/agent-browser/lib/results/selector-recovery-target.js +83 -0
  320. package/dist/extensions/agent-browser/lib/results/selector-recovery.js +119 -119
  321. package/dist/extensions/agent-browser/lib/results/snapshot-compact.js +266 -0
  322. package/dist/extensions/agent-browser/lib/results/snapshot-content.js +32 -0
  323. package/dist/extensions/agent-browser/lib/results/snapshot-high-value-controls.js +104 -71
  324. package/dist/extensions/agent-browser/lib/results/snapshot-refs.js +31 -11
  325. package/dist/extensions/agent-browser/lib/results/snapshot-segments.js +125 -66
  326. package/dist/extensions/agent-browser/lib/results/snapshot-spill.js +26 -7
  327. package/dist/extensions/agent-browser/lib/results/snapshot.js +28 -248
  328. package/dist/extensions/agent-browser/lib/results/text.js +16 -5
  329. package/dist/extensions/agent-browser/lib/runtime-args-validation.js +133 -0
  330. package/dist/extensions/agent-browser/lib/runtime-compatibility.js +81 -0
  331. package/dist/extensions/agent-browser/lib/runtime-contracts.js +1 -0
  332. package/dist/extensions/agent-browser/lib/runtime-redaction.js +118 -0
  333. package/dist/extensions/agent-browser/lib/runtime-replay-events.js +144 -0
  334. package/dist/extensions/agent-browser/lib/runtime-session-identity.js +76 -0
  335. package/dist/extensions/agent-browser/lib/runtime-session-plan.js +114 -0
  336. package/dist/extensions/agent-browser/lib/runtime-session-replay.js +123 -0
  337. package/dist/extensions/agent-browser/lib/runtime-tab-correction.js +65 -0
  338. package/dist/extensions/agent-browser/lib/runtime-timeouts.js +28 -0
  339. package/dist/extensions/agent-browser/lib/runtime.js +137 -1041
  340. package/dist/extensions/agent-browser/lib/session-identity.js +51 -0
  341. package/dist/extensions/agent-browser/lib/session-page-observation.js +357 -0
  342. package/dist/extensions/agent-browser/lib/session-page-state.js +178 -333
  343. package/dist/extensions/agent-browser/lib/session-page-types.js +1 -0
  344. package/dist/extensions/agent-browser/lib/temp-artifact-budget.js +81 -0
  345. package/dist/extensions/agent-browser/lib/temp-mutation-queue.js +7 -0
  346. package/dist/extensions/agent-browser/lib/temp-root-ownership.js +234 -0
  347. package/dist/extensions/agent-browser/lib/temp-root.js +211 -0
  348. package/dist/extensions/agent-browser/lib/temp.js +33 -446
  349. package/dist/extensions/agent-browser/lib/tool-surface.js +94 -24
  350. package/dist/extensions/agent-browser/lib/upstream-version.js +3 -2
  351. package/dist/extensions/agent-browser/lib/web-search-providers.js +193 -0
  352. package/dist/extensions/agent-browser/lib/web-search-request.js +102 -0
  353. package/dist/extensions/agent-browser/lib/web-search-results.js +281 -0
  354. package/dist/extensions/agent-browser/lib/web-search-schema.js +82 -0
  355. package/dist/extensions/agent-browser/lib/web-search.js +124 -614
  356. package/dist/extensions/agent-browser/lib/webmcp-observation.js +13 -6
  357. package/dist/extensions/agent-browser/lib/windows-stock-launcher.js +63 -37
  358. package/dist/extensions/agent-browser/script-worker.js +80 -43
  359. package/dist/scripts/agent-browser-target.mjs +4 -2
  360. package/docs/ARCHITECTURE.md +19 -6
  361. package/docs/CODE_QUALITY.md +267 -0
  362. package/docs/COMMAND_REFERENCE.md +272 -241
  363. package/docs/ELECTRON.md +77 -46
  364. package/docs/REFERENCE.md +869 -0
  365. package/docs/RELEASE.md +25 -22
  366. package/docs/REQUIREMENTS.md +2 -1
  367. package/docs/SUPPORT_MATRIX.md +81 -79
  368. package/docs/TOOL_CONTRACT.md +158 -125
  369. package/docs/platform-smoke.md +8 -8
  370. package/package.json +144 -120
  371. package/scripts/agent-browser-capability-baseline.mjs +361 -957
  372. package/scripts/agent-browser-target.mjs +6 -2
  373. package/scripts/build.mjs +37 -8
  374. package/scripts/capability-core-commands.mjs +193 -0
  375. package/scripts/capability-options.mjs +283 -0
  376. package/scripts/capability-samples.mjs +133 -0
  377. package/scripts/capability-section.mjs +11 -0
  378. package/scripts/config.mjs +235 -132
  379. package/scripts/convert-browser-session.mjs +30 -9
  380. package/scripts/doctor-sources.mjs +195 -0
  381. package/scripts/doctor.mjs +94 -249
  382. package/scripts/platform-smoke/artifacts.mjs +38 -11
  383. package/scripts/platform-smoke/commands.mjs +104 -0
  384. package/scripts/platform-smoke/crabbox-runner.mjs +167 -80
  385. package/scripts/platform-smoke/doctor-support.mjs +157 -0
  386. package/scripts/platform-smoke/doctor-windows.mjs +230 -0
  387. package/scripts/platform-smoke/doctor.mjs +212 -320
  388. package/scripts/platform-smoke/lease-evidence.mjs +132 -0
  389. package/scripts/platform-smoke/linux-image/Dockerfile +8 -2
  390. package/scripts/platform-smoke/suite-checks.mjs +98 -0
  391. package/scripts/platform-smoke/suite-evidence.mjs +281 -0
  392. package/scripts/platform-smoke/targets.mjs +154 -472
  393. package/scripts/platform-smoke.mjs +55 -40
  394. package/scripts/prepare.mjs +16 -7
@@ -5,9 +5,18 @@ const CONFIRMATION_REQUIRED_FIELD_NAMES = [
5
5
  "requires_confirmation",
6
6
  "requiresConfirmation",
7
7
  ];
8
- const CONFIRMATION_REQUIRED_RECORD_FIELD_NAMES = ["confirmation", "pendingConfirmation", "pending_confirmation"];
8
+ const CONFIRMATION_REQUIRED_RECORD_FIELD_NAMES = [
9
+ "confirmation",
10
+ "pendingConfirmation",
11
+ "pending_confirmation",
12
+ ];
9
13
  const CONFIRMATION_ID_FIELD_NAMES = ["confirmation_id", "confirmationId", "id"];
10
- const CONFIRMATION_ACTION_TEXT_FIELD_NAMES = ["action", "description", "message", "summary"];
14
+ const CONFIRMATION_ACTION_TEXT_FIELD_NAMES = [
15
+ "action",
16
+ "description",
17
+ "message",
18
+ "summary",
19
+ ];
11
20
  const CONFIRMATION_REQUIRED_MARKER = "confirmation_required";
12
21
  function getTrimmedStringField(data, fieldNames) {
13
22
  for (const fieldName of fieldNames) {
@@ -19,10 +28,10 @@ function getTrimmedStringField(data, fieldNames) {
19
28
  return undefined;
20
29
  }
21
30
  function hasConfirmationRequiredMarker(data) {
22
- return CONFIRMATION_REQUIRED_FIELD_NAMES.some((fieldName) => data[fieldName] === true)
23
- || data.type === CONFIRMATION_REQUIRED_MARKER
24
- || data.status === CONFIRMATION_REQUIRED_MARKER
25
- || data.kind === CONFIRMATION_REQUIRED_MARKER;
31
+ return (CONFIRMATION_REQUIRED_FIELD_NAMES.some((fieldName) => data[fieldName] === true) ||
32
+ data.type === CONFIRMATION_REQUIRED_MARKER ||
33
+ data.status === CONFIRMATION_REQUIRED_MARKER ||
34
+ data.kind === CONFIRMATION_REQUIRED_MARKER);
26
35
  }
27
36
  function getNestedConfirmationRecord(data) {
28
37
  for (const fieldName of CONFIRMATION_REQUIRED_RECORD_FIELD_NAMES) {
@@ -33,21 +42,28 @@ function getNestedConfirmationRecord(data) {
33
42
  }
34
43
  return undefined;
35
44
  }
36
- export function detectConfirmationRequired(data) {
45
+ function getConfirmationPayload(data) {
37
46
  // Native confirm can acknowledge one action while its original compound command remains pending.
38
- if (isRecord(data) && data.confirmed === true && isRecord(data.result) && data.result.success === true)
39
- data = data.result.data;
40
- if (!isRecord(data)) {
47
+ return isRecord(data) &&
48
+ data.confirmed === true &&
49
+ isRecord(data.result) &&
50
+ data.result.success === true
51
+ ? data.result.data
52
+ : data;
53
+ }
54
+ export function detectConfirmationRequired(data) {
55
+ const payload = getConfirmationPayload(data);
56
+ if (!isRecord(payload)) {
41
57
  return undefined;
42
58
  }
43
- const nestedRecord = getNestedConfirmationRecord(data);
44
- const candidateRecords = nestedRecord ? [data, nestedRecord] : [data];
59
+ const nestedRecord = getNestedConfirmationRecord(payload);
60
+ const candidateRecords = nestedRecord ? [payload, nestedRecord] : [payload];
45
61
  if (!candidateRecords.some(hasConfirmationRequiredMarker)) {
46
62
  return undefined;
47
63
  }
48
64
  for (const record of candidateRecords) {
49
65
  const id = getTrimmedStringField(record, CONFIRMATION_ID_FIELD_NAMES);
50
- if (!id) {
66
+ if (id === undefined || id.length === 0) {
51
67
  continue;
52
68
  }
53
69
  return {
@@ -1,64 +1,99 @@
1
- const EDITABLE_REF_EVIDENCE_KEYS = ["editable", "contentEditable", "contenteditable", "isContentEditable"];
1
+ const EDITABLE_REF_EVIDENCE_KEYS = [
2
+ "editable",
3
+ "contentEditable",
4
+ "contenteditable",
5
+ "isContentEditable",
6
+ ];
2
7
  const EDITABLE_FALSE_TEXT_PATTERN = /\b(?:contenteditable|editable)\s*=\s*["']?(?:false|0)["']?/i;
3
8
  const EDITABLE_ASSIGNMENT_TEXT_PATTERN = /\b(contenteditable|editable)\s*=\s*("[^"]*"|'[^']*'|[^\s,\]]+)/gi;
4
9
  const EDITABLE_BARE_TEXT_PATTERN = /\b(?:contenteditable|editable)\b(?!\s*=)/i;
5
10
  function parseEditableEvidenceValue(value) {
6
- if (typeof value === "boolean")
11
+ if (typeof value === "boolean") {
7
12
  return value;
13
+ }
8
14
  if (typeof value === "number") {
9
- if (value === 1)
15
+ if (value === 1) {
10
16
  return true;
11
- if (value === 0)
17
+ }
18
+ if (value === 0) {
12
19
  return false;
20
+ }
13
21
  return undefined;
14
22
  }
15
- if (typeof value !== "string")
23
+ if (typeof value !== "string") {
16
24
  return undefined;
17
- const normalized = value.trim().replace(/^["']|["']$/g, "").toLowerCase();
18
- if (["false", "0", "no"].includes(normalized))
25
+ }
26
+ const normalized = value
27
+ .trim()
28
+ .replace(/^["']|["']$/g, "")
29
+ .toLowerCase();
30
+ if (["false", "0", "no"].includes(normalized)) {
19
31
  return false;
20
- if (["", "true", "1", "yes", "plaintext-only"].includes(normalized))
32
+ }
33
+ if (["", "true", "1", "yes", "plaintext-only"].includes(normalized)) {
21
34
  return true;
35
+ }
22
36
  return undefined;
23
37
  }
24
38
  function stripLeadingSnapshotAccessibleName(text) {
25
39
  return text.replace(/^(\s*[-*]\s+\S+\s+)(?:"[^"]*"|'[^']*')/, "$1");
26
40
  }
27
- function parseEditableEvidenceText(text) {
28
- if (!text)
29
- return undefined;
30
- const markerText = stripLeadingSnapshotAccessibleName(text);
31
- if (EDITABLE_FALSE_TEXT_PATTERN.test(markerText))
32
- return false;
41
+ function parseEditableAssignments(markerText) {
33
42
  let hasPositiveAssignment = false;
34
43
  for (const match of markerText.matchAll(EDITABLE_ASSIGNMENT_TEXT_PATTERN)) {
35
44
  const key = match[1]?.toLowerCase();
36
45
  const evidence = parseEditableEvidenceValue(match[2]);
37
- if (evidence === false)
46
+ if (evidence === false) {
38
47
  return false;
48
+ }
39
49
  if (evidence === true && (key === "contenteditable" || key === "editable")) {
40
50
  hasPositiveAssignment = true;
41
51
  }
42
52
  }
43
- if (hasPositiveAssignment)
44
- return true;
53
+ return hasPositiveAssignment ? true : undefined;
54
+ }
55
+ function parseEditableEvidenceText(text) {
56
+ if (text === undefined || text.length === 0) {
57
+ return undefined;
58
+ }
59
+ const markerText = stripLeadingSnapshotAccessibleName(text);
60
+ if (EDITABLE_FALSE_TEXT_PATTERN.test(markerText)) {
61
+ return false;
62
+ }
63
+ const assignment = parseEditableAssignments(markerText);
64
+ if (assignment !== undefined) {
65
+ return assignment;
66
+ }
45
67
  return EDITABLE_BARE_TEXT_PATTERN.test(markerText) ? true : undefined;
46
68
  }
47
- export function getEditableRefEvidence(options) {
69
+ function getStructuredEditableEvidence(ref) {
70
+ if (!ref) {
71
+ return undefined;
72
+ }
48
73
  let hasPositiveEvidence = false;
49
- if (options.ref) {
50
- for (const key of EDITABLE_REF_EVIDENCE_KEYS) {
51
- const evidence = parseEditableEvidenceValue(options.ref[key]);
52
- if (evidence === false)
53
- return false;
54
- if (evidence === true)
55
- hasPositiveEvidence = true;
74
+ for (const key of EDITABLE_REF_EVIDENCE_KEYS) {
75
+ const evidence = parseEditableEvidenceValue(ref[key]);
76
+ if (evidence === false) {
77
+ return false;
56
78
  }
79
+ if (evidence === true) {
80
+ hasPositiveEvidence = true;
81
+ }
82
+ }
83
+ return hasPositiveEvidence ? true : undefined;
84
+ }
85
+ export function getEditableRefEvidence(options) {
86
+ const structuredEvidence = getStructuredEditableEvidence(options.ref);
87
+ if (structuredEvidence === false) {
88
+ return false;
57
89
  }
90
+ let hasPositiveEvidence = structuredEvidence === true;
58
91
  const textEvidence = parseEditableEvidenceText(options.text);
59
- if (textEvidence === false)
92
+ if (textEvidence === false) {
60
93
  return false;
61
- if (textEvidence === true)
94
+ }
95
+ if (textEvidence === true) {
62
96
  hasPositiveEvidence = true;
97
+ }
63
98
  return hasPositiveEvidence ? true : undefined;
64
99
  }
@@ -0,0 +1,83 @@
1
+ import { buildNextToolAction } from "./next-actions.js";
2
+ function buildElectronToolAction(options) {
3
+ return {
4
+ id: options.id,
5
+ params: { action: options.action, launchId: options.launchId },
6
+ reason: options.reason,
7
+ ...(options.safety !== undefined && options.safety.length > 0
8
+ ? { safety: options.safety }
9
+ : {}),
10
+ tool: "agent_browser_electron",
11
+ };
12
+ }
13
+ function buildActiveLaunchActions(launchId) {
14
+ return [
15
+ buildElectronToolAction({
16
+ action: "status",
17
+ id: "status-electron-launch",
18
+ launchId,
19
+ reason: "Check the wrapper-tracked Electron launch liveness and current CDP targets without mutating the app.",
20
+ }),
21
+ buildElectronToolAction({
22
+ action: "probe",
23
+ id: "probe-electron-launch",
24
+ launchId,
25
+ reason: "Probe the attached Electron managed session and carry the wrapper launchId for follow-up diagnostics.",
26
+ }),
27
+ buildElectronToolAction({
28
+ action: "cleanup",
29
+ id: "cleanup-electron-launch",
30
+ launchId,
31
+ reason: "Clean the wrapper-owned Electron process and isolated userDataDir when the run is complete.",
32
+ safety: "Only operates on the launchId created by electron.launch; explicit artifacts and manually launched apps remain host-owned.",
33
+ }),
34
+ ];
35
+ }
36
+ function buildElectronSessionActions(sessionName) {
37
+ if (sessionName === undefined || sessionName.length === 0) {
38
+ return [];
39
+ }
40
+ return [
41
+ buildNextToolAction({
42
+ args: ["--session", sessionName, "tab", "list"],
43
+ id: "list-electron-tabs",
44
+ reason: "Inspect attached Electron page/webview targets before choosing the active tab.",
45
+ }),
46
+ buildNextToolAction({
47
+ args: ["--session", sessionName, "snapshot", "-i"],
48
+ id: "snapshot-electron-session",
49
+ reason: "Refresh interactive refs for the attached Electron session.",
50
+ safety: "Use current Electron refs only after a fresh snapshot for this session.",
51
+ }),
52
+ ];
53
+ }
54
+ export function buildElectronNextActions(options) {
55
+ const launchId = options.electron?.launchId;
56
+ if (launchId === undefined || launchId.length === 0) {
57
+ return [];
58
+ }
59
+ if (options.resultCategory === "success" && options.electron?.status !== "cleaned") {
60
+ return [
61
+ ...buildActiveLaunchActions(launchId),
62
+ ...buildElectronSessionActions(options.electron?.sessionName),
63
+ ];
64
+ }
65
+ if (options.resultCategory === "failure" && options.failureCategory === "cleanup-failed") {
66
+ return [
67
+ buildElectronToolAction({
68
+ action: "status",
69
+ id: "status-electron-launch",
70
+ launchId,
71
+ reason: "Inspect which wrapper-tracked Electron resources remain after partial cleanup.",
72
+ }),
73
+ buildElectronToolAction({
74
+ action: "cleanup",
75
+ id: "retry-electron-cleanup",
76
+ launchId,
77
+ reason: "Retry cleanup for the same wrapper-owned Electron launch after reviewing remaining resources.",
78
+ safety: "Only retry for the same launchId; do not use cleanup for manually launched Electron apps.",
79
+ }),
80
+ ];
81
+ }
82
+ return [];
83
+ }
@@ -0,0 +1,48 @@
1
+ import { isRecord } from "../parsing.js";
2
+ function decodePluginList(value) {
3
+ const keys = Object.keys(value);
4
+ if (keys.length !== 1) {
5
+ return undefined;
6
+ }
7
+ if (keys[0] === "plugins" && Array.isArray(value.plugins)) {
8
+ return { success: true, data: { plugins: value.plugins } };
9
+ }
10
+ if (keys[0] === "plugin" && isRecord(value.plugin) && !Array.isArray(value.plugin)) {
11
+ return { success: true, data: { plugin: value.plugin } };
12
+ }
13
+ return undefined;
14
+ }
15
+ export function decodeAgentBrowserEnvelope(value) {
16
+ if (Array.isArray(value)) {
17
+ return {
18
+ envelope: {
19
+ success: value.every((item) => !isRecord(item) || item.success !== false),
20
+ data: value,
21
+ },
22
+ };
23
+ }
24
+ if (!isRecord(value)) {
25
+ return { parseError: "agent-browser returned JSON, but it was not an object envelope." };
26
+ }
27
+ const plugin = decodePluginList(value);
28
+ if (plugin) {
29
+ return { envelope: plugin };
30
+ }
31
+ if (!("success" in value)) {
32
+ return {
33
+ parseError: "agent-browser returned an invalid JSON envelope: missing boolean success field.",
34
+ };
35
+ }
36
+ if (typeof value.success !== "boolean") {
37
+ return {
38
+ parseError: "agent-browser returned an invalid JSON envelope: success field must be boolean.",
39
+ };
40
+ }
41
+ if (!Object.hasOwn(value, "data")) {
42
+ const { success, error, ...topLevelData } = value;
43
+ if (Object.keys(topLevelData).length > 0) {
44
+ return { envelope: { error, success, data: topLevelData } };
45
+ }
46
+ }
47
+ return { envelope: { ...value, success: value.success } };
48
+ }
@@ -1,94 +1,86 @@
1
1
  import { readFile } from "node:fs/promises";
2
2
  import { isRecord } from "../parsing.js";
3
3
  import { detectConfirmationRequired } from "./confirmation.js";
4
+ import { decodeAgentBrowserEnvelope } from "./envelope-decoding.js";
4
5
  import { stringifyUnknown } from "./text.js";
5
6
  function hasStructuredBatchStepFailure(data) {
6
7
  return Array.isArray(data) && data.some((item) => isRecord(item) && item.success === false);
7
8
  }
8
9
  async function readEnvelopeSource(options) {
9
- if (!options.stdoutPath) {
10
+ if (options.stdoutPath === undefined || options.stdoutPath.length === 0) {
10
11
  return options.stdout;
11
12
  }
12
13
  try {
13
14
  return await readFile(options.stdoutPath, "utf8");
14
15
  }
15
16
  catch (error) {
16
- const message = error instanceof Error ? error.message : String(error);
17
- throw new Error(`agent-browser output spill file could not be read: ${message}`);
17
+ const message = error instanceof Error ? error.message : stringifyUnknown(error);
18
+ throw new Error(`agent-browser output spill file could not be read: ${message}`, {
19
+ cause: error,
20
+ });
18
21
  }
19
22
  }
20
23
  export function extractEnvelopeErrorText(error) {
21
24
  if (typeof error === "string") {
22
- return error.trim() || undefined;
25
+ const trimmed = error.trim();
26
+ return trimmed.length > 0 ? trimmed : undefined;
23
27
  }
24
28
  if (typeof error === "number" || typeof error === "boolean") {
25
29
  return String(error);
26
30
  }
27
31
  if (Array.isArray(error)) {
28
- const parts = error.map((item) => extractEnvelopeErrorText(item) ?? stringifyUnknown(item)).filter((item) => item.length > 0);
32
+ const parts = error
33
+ .map((item) => extractEnvelopeErrorText(item) ?? stringifyUnknown(item))
34
+ .filter((item) => item.length > 0);
29
35
  return parts.length > 0 ? parts.join("\n") : undefined;
30
36
  }
31
37
  if (!isRecord(error)) {
32
- return error == null ? undefined : stringifyUnknown(error);
38
+ return error === null || error === undefined ? undefined : stringifyUnknown(error);
33
39
  }
40
+ return extractStructuredEnvelopeErrorText(error);
41
+ }
42
+ function extractStructuredEnvelopeErrorText(error) {
34
43
  for (const key of ["message", "error", "details", "cause", "stderr"]) {
35
44
  const value = extractEnvelopeErrorText(error[key]);
36
- if (value)
45
+ if ((value ?? "") !== "") {
37
46
  return value;
47
+ }
38
48
  }
39
49
  const fallback = stringifyUnknown(error).trim();
40
50
  return fallback.length > 0 && fallback !== "{}" ? fallback : undefined;
41
51
  }
52
+ function getEnvelopeOutputMode(options) {
53
+ return typeof options === "string"
54
+ ? { plainText: false, textOutput: false }
55
+ : { plainText: options.plainText === true, textOutput: options.textOutput === true };
56
+ }
42
57
  export async function parseAgentBrowserEnvelope(options) {
43
58
  let stdout;
44
59
  try {
45
60
  stdout = typeof options === "string" ? options : await readEnvelopeSource(options);
46
61
  }
47
62
  catch (error) {
48
- return { parseError: error instanceof Error ? error.message : String(error) };
63
+ return { parseError: error instanceof Error ? error.message : stringifyUnknown(error) };
49
64
  }
50
65
  // ponytail: native text has no machine receipts; use JSON mode for structured evidence.
51
66
  // JSON-looking page text must never become an envelope, confirmation, or batch row.
52
- if (typeof options !== "string" && options.textOutput)
67
+ const { plainText, textOutput } = getEnvelopeOutputMode(options);
68
+ if (textOutput) {
53
69
  return { envelope: { success: true, data: stdout } };
70
+ }
54
71
  const trimmed = stdout.trim();
55
- const plainText = typeof options !== "string" && options.plainText === true;
56
72
  if (trimmed.length === 0 && !plainText) {
57
73
  return { parseError: "agent-browser returned no JSON output." };
58
74
  }
59
75
  try {
60
76
  const parsed = JSON.parse(trimmed);
61
- if (Array.isArray(parsed)) {
62
- return { envelope: { success: parsed.every((item) => !isRecord(item) || item.success !== false), data: parsed } };
63
- }
64
- if (!isRecord(parsed)) {
65
- return { parseError: "agent-browser returned JSON, but it was not an object envelope." };
66
- }
67
- const keys = Object.keys(parsed);
68
- if (keys.length === 1 && keys[0] === "plugins" && Array.isArray(parsed.plugins)) {
69
- return { envelope: { success: true, data: { plugins: parsed.plugins } } };
70
- }
71
- if (keys.length === 1 && keys[0] === "plugin" && isRecord(parsed.plugin) && !Array.isArray(parsed.plugin)) {
72
- return { envelope: { success: true, data: { plugin: parsed.plugin } } };
73
- }
74
- if (!("success" in parsed)) {
75
- return { parseError: "agent-browser returned an invalid JSON envelope: missing boolean success field." };
76
- }
77
- if (typeof parsed.success !== "boolean") {
78
- return { parseError: "agent-browser returned an invalid JSON envelope: success field must be boolean." };
79
- }
80
- if (!Object.hasOwn(parsed, "data")) {
81
- const { success, error, ...topLevelData } = parsed;
82
- if (Object.keys(topLevelData).length > 0) {
83
- return { envelope: { error, success, data: topLevelData } };
84
- }
85
- }
86
- return { envelope: parsed };
77
+ return decodeAgentBrowserEnvelope(parsed);
87
78
  }
88
79
  catch (error) {
89
- if (plainText)
80
+ if (plainText) {
90
81
  return { envelope: { success: true, data: trimmed } };
91
- const message = error instanceof Error ? error.message : String(error);
82
+ }
83
+ const message = error instanceof Error ? error.message : stringifyUnknown(error);
92
84
  return { parseError: `agent-browser returned invalid JSON: ${message}` };
93
85
  }
94
86
  }
@@ -96,14 +88,14 @@ function buildInvocationLabel(options) {
96
88
  if (options.effectiveArgs && options.effectiveArgs.length > 0) {
97
89
  return `agent-browser ${options.effectiveArgs.join(" ")}`;
98
90
  }
99
- if (options.command && options.command.trim().length > 0) {
91
+ if (options.command !== undefined && options.command.trim().length > 0) {
100
92
  return `agent-browser ${options.command.trim()}`;
101
93
  }
102
94
  return "agent-browser";
103
95
  }
104
96
  function appendWrapperRecoveryHint(message, wrapperRecoveryHint) {
105
97
  const hint = wrapperRecoveryHint?.trim();
106
- return hint ? `${message}\n${hint}` : message;
98
+ return hint !== undefined && hint.length > 0 ? `${message}\n${hint}` : message;
107
99
  }
108
100
  function buildFailureFallback(options) {
109
101
  const invocation = buildInvocationLabel(options);
@@ -115,7 +107,9 @@ function buildExitCodeFallback(options) {
115
107
  return appendWrapperRecoveryHint(`${invocation} exited with code ${options.exitCode}.`, options.wrapperRecoveryHint);
116
108
  }
117
109
  function buildWatchdogTimeoutMessage(options) {
118
- const timeoutText = options.timeoutMs === undefined ? "the wrapper watchdog" : `the ${options.timeoutMs}ms wrapper watchdog`;
110
+ const timeoutText = options.timeoutMs === undefined
111
+ ? "the wrapper watchdog"
112
+ : `the ${options.timeoutMs}ms wrapper watchdog`;
119
113
  const ipcTiming = options.timeoutMs !== undefined && options.timeoutMs <= 30_000
120
114
  ? "before the upstream CLI entered its 30s IPC retry path"
121
115
  : "after waiting beyond the upstream CLI's 30s IPC retry window";
@@ -130,7 +124,7 @@ function isUpstreamIpcReadTimeoutMessage(message) {
130
124
  function buildUpstreamIpcReadTimeoutMessage() {
131
125
  return [
132
126
  "agent-browser hit the upstream CLI 30s IPC read timeout while waiting for the daemon response.",
133
- "The daemon may still be alive; do not blindly retry a non-idempotent command. Prefer a shorter command, split long waits, or retry with sessionMode: \"fresh\" after checking tab list.",
127
+ 'The daemon may still be alive; do not blindly retry a non-idempotent command. Prefer a shorter command, split long waits, or retry with sessionMode: "fresh" after checking tab list.',
134
128
  ].join(" ");
135
129
  }
136
130
  function maybeAppendStaleRefHint(message, args) {
@@ -140,36 +134,65 @@ function maybeAppendStaleRefHint(message, args) {
140
134
  }
141
135
  return [
142
136
  message,
143
- "This @ref may be stale after navigation, scrolling, or a DOM update. Run `agent_browser` with `{ \"args\": [\"snapshot\", \"-i\"] }` again and retry with a current ref, or use a stable `find` locator.",
137
+ 'This @ref may be stale after navigation, scrolling, or a DOM update. Run `agent_browser` with `{ "args": ["snapshot", "-i"] }` again and retry with a current ref, or use a stable `find` locator.',
144
138
  ].join("\n");
145
139
  }
146
- export function getAgentBrowserErrorText(options) {
147
- const { aborted, envelope, exitCode, parseError, plainTextInspection, spawnError, stderr, timedOut } = options;
148
- if (plainTextInspection)
149
- return undefined;
150
- if (timedOut)
140
+ function getTransportErrorText(options) {
141
+ if (options.timedOut === true) {
151
142
  return buildWatchdogTimeoutMessage(options);
152
- if (aborted)
143
+ }
144
+ if (options.aborted) {
153
145
  return "agent-browser was aborted.";
154
- if (spawnError)
155
- return spawnError.message;
156
- if (parseError)
157
- return exitCode !== 0 && stderr.trim() ? stderr.trim() : parseError;
158
- if (envelope?.success === false) {
159
- const explicitErrorText = extractEnvelopeErrorText(envelope.error);
160
- if ((hasStructuredBatchStepFailure(envelope.data) || detectConfirmationRequired(envelope.data)) && explicitErrorText === undefined) {
161
- return undefined;
162
- }
163
- const envelopeErrorText = explicitErrorText
164
- ?? extractEnvelopeErrorText(typeof envelope.data === "string" ? envelope.data : isRecord(envelope.data) ? envelope.data.error : undefined);
165
- if (envelopeErrorText && isUpstreamIpcReadTimeoutMessage(envelopeErrorText)) {
166
- return buildUpstreamIpcReadTimeoutMessage();
167
- }
168
- const fallback = envelopeErrorText ?? (stderr.trim() || buildFailureFallback(options));
169
- return maybeAppendStaleRefHint(fallback, options.staleRefArgs ?? options.effectiveArgs);
170
146
  }
171
- if (exitCode !== 0) {
172
- return stderr.trim() || buildExitCodeFallback(options);
147
+ if (options.spawnError) {
148
+ return options.spawnError.message;
149
+ }
150
+ if ((options.parseError ?? "") !== "") {
151
+ return options.exitCode !== 0 && options.stderr.trim().length > 0
152
+ ? options.stderr.trim()
153
+ : options.parseError;
154
+ }
155
+ return undefined;
156
+ }
157
+ function getEnvelopeDataError(data) {
158
+ if (typeof data === "string") {
159
+ return data;
160
+ }
161
+ return isRecord(data) ? data.error : undefined;
162
+ }
163
+ function getFailedEnvelopeFallback(options, errorText) {
164
+ const stderr = options.stderr.trim();
165
+ return errorText ?? (stderr.length > 0 ? stderr : buildFailureFallback(options));
166
+ }
167
+ function getFailedEnvelopeErrorText(options, envelope) {
168
+ const explicitErrorText = extractEnvelopeErrorText(envelope.error);
169
+ if ((hasStructuredBatchStepFailure(envelope.data) || detectConfirmationRequired(envelope.data)) &&
170
+ explicitErrorText === undefined) {
171
+ return undefined;
172
+ }
173
+ const envelopeErrorText = explicitErrorText ?? extractEnvelopeErrorText(getEnvelopeDataError(envelope.data));
174
+ if (envelopeErrorText !== undefined &&
175
+ envelopeErrorText.length > 0 &&
176
+ isUpstreamIpcReadTimeoutMessage(envelopeErrorText)) {
177
+ return buildUpstreamIpcReadTimeoutMessage();
178
+ }
179
+ const fallback = getFailedEnvelopeFallback(options, envelopeErrorText);
180
+ return maybeAppendStaleRefHint(fallback, options.staleRefArgs ?? options.effectiveArgs);
181
+ }
182
+ export function getAgentBrowserErrorText(options) {
183
+ if (options.plainTextInspection) {
184
+ return undefined;
185
+ }
186
+ const transportErrorText = getTransportErrorText(options);
187
+ if (transportErrorText !== undefined) {
188
+ return transportErrorText;
189
+ }
190
+ if (options.envelope?.success === false) {
191
+ return getFailedEnvelopeErrorText(options, options.envelope);
192
+ }
193
+ if (options.exitCode !== 0) {
194
+ const stderr = options.stderr.trim();
195
+ return stderr.length > 0 ? stderr : buildExitCodeFallback(options);
173
196
  }
174
197
  return undefined;
175
198
  }