pi-agent-browser-native 0.9.3 → 0.9.4

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 (391) hide show
  1. package/CHANGELOG.md +77 -5
  2. package/README.md +103 -81
  3. package/dist/extensions/agent-browser/index.js +43057 -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 +218 -0
  33. package/dist/extensions/agent-browser/lib/config.js +19 -7
  34. package/dist/extensions/agent-browser/lib/electron/cdp.js +15 -7
  35. package/dist/extensions/agent-browser/lib/electron/cleanup.js +134 -55
  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 +89 -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 +249 -354
  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/input-modes/electron.js +162 -121
  50. package/dist/extensions/agent-browser/lib/input-modes/job.js +116 -313
  51. package/dist/extensions/agent-browser/lib/input-modes/lookup-network-evidence.js +104 -0
  52. package/dist/extensions/agent-browser/lib/input-modes/lookup-plan.js +132 -0
  53. package/dist/extensions/agent-browser/lib/input-modes/lookup-redaction.js +57 -0
  54. package/dist/extensions/agent-browser/lib/input-modes/lookup-source-evidence.js +151 -0
  55. package/dist/extensions/agent-browser/lib/input-modes/lookup-workspace.js +142 -0
  56. package/dist/extensions/agent-browser/lib/input-modes/lookups.js +57 -412
  57. package/dist/extensions/agent-browser/lib/input-modes/params.js +63 -17
  58. package/dist/extensions/agent-browser/lib/input-modes/qa-analysis.js +268 -0
  59. package/dist/extensions/agent-browser/lib/input-modes/qa-presentation.js +117 -0
  60. package/dist/extensions/agent-browser/lib/input-modes/script-child.js +396 -0
  61. package/dist/extensions/agent-browser/lib/input-modes/script-protocol.js +86 -0
  62. package/dist/extensions/agent-browser/lib/input-modes/script-types.js +1 -0
  63. package/dist/extensions/agent-browser/lib/input-modes/script-validation.js +60 -0
  64. package/dist/extensions/agent-browser/lib/input-modes/script.js +60 -409
  65. package/dist/extensions/agent-browser/lib/input-modes/semantic-action.js +218 -128
  66. package/dist/extensions/agent-browser/lib/input-modes/shared.js +15 -4
  67. package/dist/extensions/agent-browser/lib/input-modes/types.js +56 -7
  68. package/dist/extensions/agent-browser/lib/json-schema.js +22 -10
  69. package/dist/extensions/agent-browser/lib/launch-scoped-flags.js +17 -5
  70. package/dist/extensions/agent-browser/lib/managed-session-policy-lock.js +92 -425
  71. package/dist/extensions/agent-browser/lib/managed-session-posix-storage.js +58 -0
  72. package/dist/extensions/agent-browser/lib/managed-session-project-identity.js +244 -0
  73. package/dist/extensions/agent-browser/lib/managed-session-restore-context.js +84 -0
  74. package/dist/extensions/agent-browser/lib/managed-session-restore-policy.js +119 -0
  75. package/dist/extensions/agent-browser/lib/managed-session-restore-state.js +83 -0
  76. package/dist/extensions/agent-browser/lib/managed-session-restore.js +168 -300
  77. package/dist/extensions/agent-browser/lib/managed-session-snapshot-records.js +277 -0
  78. package/dist/extensions/agent-browser/lib/managed-session-snapshots.js +128 -305
  79. package/dist/extensions/agent-browser/lib/managed-session-storage.js +56 -253
  80. package/dist/extensions/agent-browser/lib/native-confirmation.js +140 -0
  81. package/dist/extensions/agent-browser/lib/native-output.js +43 -9
  82. package/dist/extensions/agent-browser/lib/orchestration/batch-stdin.js +106 -59
  83. package/dist/extensions/agent-browser/lib/orchestration/browser-run/artifact-merge.js +14 -6
  84. package/dist/extensions/agent-browser/lib/orchestration/browser-run/artifact-paths.js +109 -57
  85. package/dist/extensions/agent-browser/lib/orchestration/browser-run/browser-observation-result.js +82 -0
  86. package/dist/extensions/agent-browser/lib/orchestration/browser-run/click-dispatch.js +164 -60
  87. package/dist/extensions/agent-browser/lib/orchestration/browser-run/diagnostic-values.js +31 -0
  88. package/dist/extensions/agent-browser/lib/orchestration/browser-run/diagnostics.js +152 -781
  89. package/dist/extensions/agent-browser/lib/orchestration/browser-run/electron-observation.js +202 -0
  90. package/dist/extensions/agent-browser/lib/orchestration/browser-run/electron-text-diagnostics.js +109 -0
  91. package/dist/extensions/agent-browser/lib/orchestration/browser-run/fill-diagnostics.js +119 -0
  92. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-action-recovery.js +147 -0
  93. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-actions.js +144 -0
  94. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-content.js +123 -0
  95. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-contracts.js +1 -0
  96. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-details.js +156 -0
  97. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-electron.js +179 -0
  98. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-evidence.js +39 -0
  99. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-missing-binary.js +89 -0
  100. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-recovery.js +97 -0
  101. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-redaction.js +106 -0
  102. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result-timeout.js +110 -0
  103. package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result.js +41 -538
  104. package/dist/extensions/agent-browser/lib/orchestration/browser-run/index.js +199 -154
  105. package/dist/extensions/agent-browser/lib/orchestration/browser-run/interaction-diagnostics.js +290 -0
  106. package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-close.js +167 -0
  107. package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-daemon-inspection.js +108 -0
  108. package/dist/extensions/agent-browser/lib/orchestration/browser-run/managed-session-daemon-policy.js +127 -205
  109. package/dist/extensions/agent-browser/lib/orchestration/browser-run/native-helper-observation.js +65 -0
  110. package/dist/extensions/agent-browser/lib/orchestration/browser-run/observation-types.js +1 -0
  111. package/dist/extensions/agent-browser/lib/orchestration/browser-run/overlay-diagnostics.js +120 -0
  112. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/network-page-filter.js +113 -30
  113. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/scroll-shims.js +109 -28
  114. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/snapshot-filter-data.js +150 -0
  115. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/snapshot-filter.js +138 -253
  116. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/snapshot-rendered-text.js +147 -0
  117. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare/wait-timeouts.js +59 -24
  118. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-artifacts.js +159 -0
  119. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-command.js +131 -0
  120. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-contracts.js +1 -0
  121. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-daemon.js +93 -0
  122. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-failure.js +42 -0
  123. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-guards.js +242 -0
  124. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-input.js +75 -0
  125. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-observations.js +92 -0
  126. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-page-selection.js +254 -0
  127. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-page-state.js +121 -0
  128. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-refs.js +130 -0
  129. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-resources.js +114 -0
  130. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-semantic.js +121 -0
  131. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-session-plan.js +222 -0
  132. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare-timeouts.js +68 -0
  133. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prepare.js +176 -1123
  134. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-analysis.js +191 -0
  135. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-confirmation.js +152 -0
  136. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-diagnostics.js +182 -0
  137. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-electron.js +150 -0
  138. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle-contracts.js +1 -0
  139. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle-phase-contracts.js +1 -0
  140. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle-phase.js +115 -0
  141. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-lifecycle.js +256 -0
  142. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-managed-contracts.js +1 -0
  143. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-managed.js +256 -0
  144. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-native-phase-contracts.js +1 -0
  145. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-native-phase.js +93 -0
  146. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-native.js +113 -0
  147. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-navigation-contracts.js +1 -0
  148. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-navigation.js +316 -0
  149. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-ownership.js +28 -0
  150. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-page-phase-contracts.js +1 -0
  151. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-page-phase.js +142 -0
  152. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-presentation-contracts.js +1 -0
  153. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-presentation.js +333 -0
  154. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-publication-phase-contracts.js +1 -0
  155. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-publication-phase.js +71 -0
  156. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-publication.js +201 -0
  157. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-receipts.js +183 -0
  158. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-refs.js +200 -0
  159. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output-tabs.js +142 -0
  160. package/dist/extensions/agent-browser/lib/orchestration/browser-run/process-output.js +18 -968
  161. package/dist/extensions/agent-browser/lib/orchestration/browser-run/prompt-guards.js +23 -13
  162. package/dist/extensions/agent-browser/lib/orchestration/browser-run/recording-receipt-reconciliation.js +198 -0
  163. package/dist/extensions/agent-browser/lib/orchestration/browser-run/recording-recovery-contracts.js +1 -0
  164. package/dist/extensions/agent-browser/lib/orchestration/browser-run/recording-recovery-presentation.js +154 -0
  165. package/dist/extensions/agent-browser/lib/orchestration/browser-run/recording-recovery.js +68 -151
  166. package/dist/extensions/agent-browser/lib/orchestration/browser-run/screenshot-capture.js +14 -0
  167. package/dist/extensions/agent-browser/lib/orchestration/browser-run/screenshot-observation.js +169 -46
  168. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-commands.js +130 -0
  169. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-electron.js +210 -0
  170. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-observations.js +61 -0
  171. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-outcomes.js +187 -0
  172. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-refs.js +171 -0
  173. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state-tabs.js +228 -0
  174. package/dist/extensions/agent-browser/lib/orchestration/browser-run/session-state.js +77 -765
  175. package/dist/extensions/agent-browser/lib/orchestration/browser-run/text-visibility-diagnostics.js +182 -0
  176. package/dist/extensions/agent-browser/lib/orchestration/browser-run/timeout-diagnostics.js +256 -0
  177. package/dist/extensions/agent-browser/lib/orchestration/browser-run/timeout-progress.js +108 -0
  178. package/dist/extensions/agent-browser/lib/orchestration/code-artifact-observation.js +39 -0
  179. package/dist/extensions/agent-browser/lib/orchestration/code-image-observation.js +119 -0
  180. package/dist/extensions/agent-browser/lib/orchestration/electron-host/branch.js +92 -0
  181. package/dist/extensions/agent-browser/lib/orchestration/electron-host/cleanup-result.js +58 -0
  182. package/dist/extensions/agent-browser/lib/orchestration/electron-host/cleanup.js +78 -0
  183. package/dist/extensions/agent-browser/lib/orchestration/electron-host/contracts.js +1 -0
  184. package/dist/extensions/agent-browser/lib/orchestration/electron-host/discovery.js +106 -0
  185. package/dist/extensions/agent-browser/lib/orchestration/electron-host/index.js +48 -821
  186. package/dist/extensions/agent-browser/lib/orchestration/electron-host/policy.js +86 -0
  187. package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe-collection.js +69 -0
  188. package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe-data.js +167 -0
  189. package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe-presentation.js +164 -0
  190. package/dist/extensions/agent-browser/lib/orchestration/electron-host/probe.js +161 -0
  191. package/dist/extensions/agent-browser/lib/orchestration/electron-host/status.js +165 -0
  192. package/dist/extensions/agent-browser/lib/orchestration/execution-queue.js +21 -9
  193. package/dist/extensions/agent-browser/lib/orchestration/extension-artifact-preflight.js +211 -0
  194. package/dist/extensions/agent-browser/lib/orchestration/extension-artifacts.js +23 -0
  195. package/dist/extensions/agent-browser/lib/orchestration/extension-attachment-replay.js +99 -0
  196. package/dist/extensions/agent-browser/lib/orchestration/extension-branch-restore.js +275 -0
  197. package/dist/extensions/agent-browser/lib/orchestration/extension-code.js +280 -0
  198. package/dist/extensions/agent-browser/lib/orchestration/extension-command-admission.js +303 -0
  199. package/dist/extensions/agent-browser/lib/orchestration/extension-command-output.js +36 -0
  200. package/dist/extensions/agent-browser/lib/orchestration/extension-command-result.js +335 -0
  201. package/dist/extensions/agent-browser/lib/orchestration/extension-command-run.js +227 -0
  202. package/dist/extensions/agent-browser/lib/orchestration/extension-command-state.js +1 -0
  203. package/dist/extensions/agent-browser/lib/orchestration/extension-electron-ownership.js +204 -0
  204. package/dist/extensions/agent-browser/lib/orchestration/extension-execution-locks.js +139 -0
  205. package/dist/extensions/agent-browser/lib/orchestration/extension-execution-queue.js +24 -0
  206. package/dist/extensions/agent-browser/lib/orchestration/extension-host-coordination.js +98 -0
  207. package/dist/extensions/agent-browser/lib/orchestration/extension-host-run.js +295 -0
  208. package/dist/extensions/agent-browser/lib/orchestration/extension-intent-replay.js +41 -0
  209. package/dist/extensions/agent-browser/lib/orchestration/extension-invocation.js +7 -0
  210. package/dist/extensions/agent-browser/lib/orchestration/extension-lifecycle.js +102 -0
  211. package/dist/extensions/agent-browser/lib/orchestration/extension-managed-ownership.js +133 -0
  212. package/dist/extensions/agent-browser/lib/orchestration/extension-observation.js +120 -0
  213. package/dist/extensions/agent-browser/lib/orchestration/extension-prompt.js +180 -0
  214. package/dist/extensions/agent-browser/lib/orchestration/extension-recording.js +290 -0
  215. package/dist/extensions/agent-browser/lib/orchestration/extension-resource-contracts.js +1 -0
  216. package/dist/extensions/agent-browser/lib/orchestration/extension-resource-replay.js +269 -0
  217. package/dist/extensions/agent-browser/lib/orchestration/extension-result-state.js +113 -0
  218. package/dist/extensions/agent-browser/lib/orchestration/extension-runtime.js +146 -0
  219. package/dist/extensions/agent-browser/lib/orchestration/extension-script-leases.js +58 -0
  220. package/dist/extensions/agent-browser/lib/orchestration/extension-tool-boundary.js +62 -0
  221. package/dist/extensions/agent-browser/lib/orchestration/extension-version-check.js +54 -0
  222. package/dist/extensions/agent-browser/lib/orchestration/input-plan-types.js +1 -0
  223. package/dist/extensions/agent-browser/lib/orchestration/input-plan.js +261 -185
  224. package/dist/extensions/agent-browser/lib/orchestration/input-redaction.js +62 -0
  225. package/dist/extensions/agent-browser/lib/orchestration/native-config.js +144 -0
  226. package/dist/extensions/agent-browser/lib/orchestration/native-root-launch.js +77 -0
  227. package/dist/extensions/agent-browser/lib/orchestration/native-session-defaults.js +210 -157
  228. package/dist/extensions/agent-browser/lib/orchestration/operation-paths.js +124 -58
  229. package/dist/extensions/agent-browser/lib/orchestration/output-file.js +197 -99
  230. package/dist/extensions/agent-browser/lib/orchestration/script-mode.js +199 -96
  231. package/dist/extensions/agent-browser/lib/owned-managed-session-context.js +55 -0
  232. package/dist/extensions/agent-browser/lib/page-target-batch.js +118 -0
  233. package/dist/extensions/agent-browser/lib/page-target-guards.js +50 -0
  234. package/dist/extensions/agent-browser/lib/page-target-navigation.js +104 -0
  235. package/dist/extensions/agent-browser/lib/page-target-validation.js +55 -246
  236. package/dist/extensions/agent-browser/lib/parsing.js +13 -4
  237. package/dist/extensions/agent-browser/lib/pi-tool-rendering.js +133 -68
  238. package/dist/extensions/agent-browser/lib/playbook.js +16 -12
  239. package/dist/extensions/agent-browser/lib/process-child.js +284 -0
  240. package/dist/extensions/agent-browser/lib/process-environment.js +13 -6
  241. package/dist/extensions/agent-browser/lib/process-errors.js +23 -0
  242. package/dist/extensions/agent-browser/lib/process-identity.js +47 -15
  243. package/dist/extensions/agent-browser/lib/process-socket-storage.js +256 -0
  244. package/dist/extensions/agent-browser/lib/process-stdout.js +74 -0
  245. package/dist/extensions/agent-browser/lib/process.js +145 -536
  246. package/dist/extensions/agent-browser/lib/prompt-artifacts.js +287 -0
  247. package/dist/extensions/agent-browser/lib/prompt-policy.js +15 -194
  248. package/dist/extensions/agent-browser/lib/read-command.js +41 -0
  249. package/dist/extensions/agent-browser/lib/read-confirmation.js +131 -68
  250. package/dist/extensions/agent-browser/lib/recording-reservations.js +118 -45
  251. package/dist/extensions/agent-browser/lib/redaction-fields.js +75 -0
  252. package/dist/extensions/agent-browser/lib/redaction-json.js +149 -0
  253. package/dist/extensions/agent-browser/lib/redaction-url.js +88 -0
  254. package/dist/extensions/agent-browser/lib/results/action-contracts.js +1 -0
  255. package/dist/extensions/agent-browser/lib/results/action-recommendations.js +28 -271
  256. package/dist/extensions/agent-browser/lib/results/artifact-contracts.js +1 -0
  257. package/dist/extensions/agent-browser/lib/results/artifact-manifest-validation.js +133 -0
  258. package/dist/extensions/agent-browser/lib/results/artifact-manifest.js +96 -94
  259. package/dist/extensions/agent-browser/lib/results/artifact-recommendations.js +73 -0
  260. package/dist/extensions/agent-browser/lib/results/categories.js +111 -54
  261. package/dist/extensions/agent-browser/lib/results/confirmation.js +29 -13
  262. package/dist/extensions/agent-browser/lib/results/editable-ref-evidence.js +62 -27
  263. package/dist/extensions/agent-browser/lib/results/electron-recommendations.js +83 -0
  264. package/dist/extensions/agent-browser/lib/results/envelope-decoding.js +48 -0
  265. package/dist/extensions/agent-browser/lib/results/envelope.js +90 -67
  266. package/dist/extensions/agent-browser/lib/results/evidence-contracts.js +1 -0
  267. package/dist/extensions/agent-browser/lib/results/failure-recommendations.js +180 -0
  268. package/dist/extensions/agent-browser/lib/results/network-routes.js +86 -45
  269. package/dist/extensions/agent-browser/lib/results/network.js +35 -12
  270. package/dist/extensions/agent-browser/lib/results/next-actions.js +49 -19
  271. package/dist/extensions/agent-browser/lib/results/presentation/artifact-files.js +320 -0
  272. package/dist/extensions/agent-browser/lib/results/presentation/artifact-format.js +138 -0
  273. package/dist/extensions/agent-browser/lib/results/presentation/artifact-images.js +113 -0
  274. package/dist/extensions/agent-browser/lib/results/presentation/artifact-verification.js +145 -0
  275. package/dist/extensions/agent-browser/lib/results/presentation/artifacts.js +99 -555
  276. package/dist/extensions/agent-browser/lib/results/presentation/batch-contracts.js +1 -0
  277. package/dist/extensions/agent-browser/lib/results/presentation/batch-recording.js +118 -0
  278. package/dist/extensions/agent-browser/lib/results/presentation/batch-redaction.js +68 -0
  279. package/dist/extensions/agent-browser/lib/results/presentation/batch-rendering.js +135 -0
  280. package/dist/extensions/agent-browser/lib/results/presentation/batch-step.js +227 -0
  281. package/dist/extensions/agent-browser/lib/results/presentation/batch-summary.js +91 -0
  282. package/dist/extensions/agent-browser/lib/results/presentation/batch.js +91 -460
  283. package/dist/extensions/agent-browser/lib/results/presentation/browser-profile-recovery.js +9 -5
  284. package/dist/extensions/agent-browser/lib/results/presentation/command-presenters.js +216 -0
  285. package/dist/extensions/agent-browser/lib/results/presentation/common.js +26 -9
  286. package/dist/extensions/agent-browser/lib/results/presentation/content.js +86 -29
  287. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-a11y.js +67 -0
  288. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-health.js +79 -0
  289. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-identity.js +199 -0
  290. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-logs.js +75 -0
  291. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-network-actions.js +216 -0
  292. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-network.js +124 -0
  293. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-redaction.js +64 -0
  294. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-storage.js +209 -0
  295. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-stream.js +69 -0
  296. package/dist/extensions/agent-browser/lib/results/presentation/diagnostic-summary.js +222 -0
  297. package/dist/extensions/agent-browser/lib/results/presentation/diagnostics.js +103 -1052
  298. package/dist/extensions/agent-browser/lib/results/presentation/early-result.js +70 -0
  299. package/dist/extensions/agent-browser/lib/results/presentation/errors.js +130 -60
  300. package/dist/extensions/agent-browser/lib/results/presentation/input-contracts.js +1 -0
  301. package/dist/extensions/agent-browser/lib/results/presentation/large-output.js +60 -145
  302. package/dist/extensions/agent-browser/lib/results/presentation/navigation.js +147 -88
  303. package/dist/extensions/agent-browser/lib/results/presentation/notices.js +75 -0
  304. package/dist/extensions/agent-browser/lib/results/presentation/observation-contracts.js +1 -0
  305. package/dist/extensions/agent-browser/lib/results/presentation/observation-rendering.js +127 -0
  306. package/dist/extensions/agent-browser/lib/results/presentation/outcomes.js +120 -0
  307. package/dist/extensions/agent-browser/lib/results/presentation/output-completion.js +77 -0
  308. package/dist/extensions/agent-browser/lib/results/presentation/output-spill.js +51 -0
  309. package/dist/extensions/agent-browser/lib/results/presentation/registry.js +116 -240
  310. package/dist/extensions/agent-browser/lib/results/presentation/semantic-action.js +35 -21
  311. package/dist/extensions/agent-browser/lib/results/presentation/skills.js +104 -73
  312. package/dist/extensions/agent-browser/lib/results/presentation/source.js +109 -0
  313. package/dist/extensions/agent-browser/lib/results/presentation.js +17 -261
  314. package/dist/extensions/agent-browser/lib/results/recommendation-contracts.js +1 -0
  315. package/dist/extensions/agent-browser/lib/results/recording.js +52 -14
  316. package/dist/extensions/agent-browser/lib/results/recovery-actions.js +14 -5
  317. package/dist/extensions/agent-browser/lib/results/recovery-next-actions.js +30 -22
  318. package/dist/extensions/agent-browser/lib/results/selector-recovery-target.js +83 -0
  319. package/dist/extensions/agent-browser/lib/results/selector-recovery.js +119 -119
  320. package/dist/extensions/agent-browser/lib/results/snapshot-compact.js +266 -0
  321. package/dist/extensions/agent-browser/lib/results/snapshot-content.js +32 -0
  322. package/dist/extensions/agent-browser/lib/results/snapshot-high-value-controls.js +104 -71
  323. package/dist/extensions/agent-browser/lib/results/snapshot-refs.js +31 -11
  324. package/dist/extensions/agent-browser/lib/results/snapshot-segments.js +125 -66
  325. package/dist/extensions/agent-browser/lib/results/snapshot-spill.js +26 -7
  326. package/dist/extensions/agent-browser/lib/results/snapshot.js +28 -248
  327. package/dist/extensions/agent-browser/lib/results/text.js +16 -5
  328. package/dist/extensions/agent-browser/lib/runtime-args-validation.js +133 -0
  329. package/dist/extensions/agent-browser/lib/runtime-compatibility.js +81 -0
  330. package/dist/extensions/agent-browser/lib/runtime-contracts.js +1 -0
  331. package/dist/extensions/agent-browser/lib/runtime-redaction.js +118 -0
  332. package/dist/extensions/agent-browser/lib/runtime-replay-events.js +144 -0
  333. package/dist/extensions/agent-browser/lib/runtime-session-identity.js +76 -0
  334. package/dist/extensions/agent-browser/lib/runtime-session-plan.js +114 -0
  335. package/dist/extensions/agent-browser/lib/runtime-session-replay.js +123 -0
  336. package/dist/extensions/agent-browser/lib/runtime-tab-correction.js +65 -0
  337. package/dist/extensions/agent-browser/lib/runtime-timeouts.js +28 -0
  338. package/dist/extensions/agent-browser/lib/runtime.js +137 -1041
  339. package/dist/extensions/agent-browser/lib/session-identity.js +51 -0
  340. package/dist/extensions/agent-browser/lib/session-page-observation.js +357 -0
  341. package/dist/extensions/agent-browser/lib/session-page-state.js +178 -333
  342. package/dist/extensions/agent-browser/lib/session-page-types.js +1 -0
  343. package/dist/extensions/agent-browser/lib/temp-artifact-budget.js +78 -0
  344. package/dist/extensions/agent-browser/lib/temp-mutation-queue.js +7 -0
  345. package/dist/extensions/agent-browser/lib/temp-root-ownership.js +234 -0
  346. package/dist/extensions/agent-browser/lib/temp-root.js +207 -0
  347. package/dist/extensions/agent-browser/lib/temp.js +33 -446
  348. package/dist/extensions/agent-browser/lib/tool-surface.js +94 -24
  349. package/dist/extensions/agent-browser/lib/upstream-version.js +3 -2
  350. package/dist/extensions/agent-browser/lib/web-search-providers.js +229 -0
  351. package/dist/extensions/agent-browser/lib/web-search-request.js +108 -0
  352. package/dist/extensions/agent-browser/lib/web-search-results.js +281 -0
  353. package/dist/extensions/agent-browser/lib/web-search-schema.js +82 -0
  354. package/dist/extensions/agent-browser/lib/web-search.js +109 -617
  355. package/dist/extensions/agent-browser/lib/webmcp-observation.js +13 -6
  356. package/dist/extensions/agent-browser/lib/windows-stock-launcher.js +63 -37
  357. package/dist/extensions/agent-browser/script-worker.js +80 -43
  358. package/dist/scripts/agent-browser-target.mjs +4 -2
  359. package/docs/ARCHITECTURE.md +17 -5
  360. package/docs/CODE_QUALITY.md +242 -0
  361. package/docs/COMMAND_REFERENCE.md +251 -220
  362. package/docs/ELECTRON.md +53 -44
  363. package/docs/RELEASE.md +18 -15
  364. package/docs/REQUIREMENTS.md +1 -0
  365. package/docs/SUPPORT_MATRIX.md +76 -75
  366. package/docs/TOOL_CONTRACT.md +145 -116
  367. package/docs/platform-smoke.md +5 -5
  368. package/package.json +143 -120
  369. package/scripts/agent-browser-capability-baseline.mjs +361 -957
  370. package/scripts/agent-browser-target.mjs +6 -2
  371. package/scripts/build.mjs +37 -8
  372. package/scripts/capability-core-commands.mjs +193 -0
  373. package/scripts/capability-options.mjs +283 -0
  374. package/scripts/capability-samples.mjs +133 -0
  375. package/scripts/capability-section.mjs +11 -0
  376. package/scripts/config.mjs +213 -114
  377. package/scripts/convert-browser-session.mjs +30 -9
  378. package/scripts/doctor-sources.mjs +195 -0
  379. package/scripts/doctor.mjs +92 -247
  380. package/scripts/platform-smoke/artifacts.mjs +38 -11
  381. package/scripts/platform-smoke/commands.mjs +104 -0
  382. package/scripts/platform-smoke/crabbox-runner.mjs +167 -80
  383. package/scripts/platform-smoke/doctor-support.mjs +157 -0
  384. package/scripts/platform-smoke/doctor-windows.mjs +230 -0
  385. package/scripts/platform-smoke/doctor.mjs +212 -320
  386. package/scripts/platform-smoke/lease-evidence.mjs +134 -0
  387. package/scripts/platform-smoke/suite-checks.mjs +98 -0
  388. package/scripts/platform-smoke/suite-evidence.mjs +281 -0
  389. package/scripts/platform-smoke/targets.mjs +158 -472
  390. package/scripts/platform-smoke.mjs +55 -40
  391. 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
  }