machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

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 (473) hide show
  1. package/CHANGELOG.md +1142 -0
  2. package/CONTRIBUTING.md +23 -25
  3. package/GOVERNANCE.md +2 -2
  4. package/README.md +58 -20
  5. package/SECURITY.md +161 -120
  6. package/SUPPORT.md +1 -1
  7. package/browser-extension/broker-auth.js +83 -0
  8. package/browser-extension/broker-liveness.js +35 -0
  9. package/browser-extension/browser-error-boundary.js +96 -0
  10. package/browser-extension/browser-operations.js +1456 -101
  11. package/browser-extension/devtools-input.js +195 -34
  12. package/browser-extension/devtools-observation.js +429 -0
  13. package/browser-extension/devtools-session.js +48 -0
  14. package/browser-extension/manifest.json +4 -3
  15. package/browser-extension/page-automation.js +578 -118
  16. package/browser-extension/pairing-bootstrap.js +42 -0
  17. package/browser-extension/pairing.js +28 -12
  18. package/browser-extension/service-worker.js +126 -106
  19. package/docs/AGENT_CONTEXT.md +13 -10
  20. package/docs/ARCHITECTURE.md +159 -67
  21. package/docs/AUDIT.md +1302 -4
  22. package/docs/CLIENTS.md +19 -6
  23. package/docs/COMPUTER_USE.md +297 -0
  24. package/docs/ENGINEERING.md +72 -13
  25. package/docs/GETTING_STARTED.md +18 -20
  26. package/docs/LOCAL_AUTHORIZATION.md +115 -72
  27. package/docs/LOCAL_AUTOMATION.md +27 -21
  28. package/docs/LOGGING.md +40 -19
  29. package/docs/MANAGED_JOBS.md +37 -34
  30. package/docs/MULTI_ACCOUNT.md +98 -37
  31. package/docs/OPERATIONS.md +145 -51
  32. package/docs/OVERVIEW.md +14 -11
  33. package/docs/POLICY_REFERENCE.md +71 -3
  34. package/docs/PRIVACY.md +41 -2
  35. package/docs/PROJECT_STANDARDS.md +29 -6
  36. package/docs/RELEASING.md +238 -64
  37. package/docs/TESTING.md +150 -39
  38. package/docs/THREAT_MODEL.md +164 -67
  39. package/docs/TOOL_REFERENCE.md +653 -60
  40. package/docs/UPGRADING.md +78 -18
  41. package/native/macos/MachineBridgeBackgroundInput.swift +1051 -0
  42. package/native/macos/MachineBridgeBackgroundInputSmokeFixture.swift +295 -0
  43. package/native/macos/MachineBridgeTrustBroker.swift +233 -0
  44. package/package.json +94 -16
  45. package/scripts/accepted-candidate-tarball.mjs +77 -0
  46. package/scripts/candidate-runtime-store.mjs +93 -0
  47. package/scripts/check-plan.mjs +73 -3
  48. package/scripts/check-runner.mjs +129 -17
  49. package/scripts/commit-message-check.mjs +5 -2
  50. package/scripts/consumer-package-security.mjs +293 -0
  51. package/scripts/coverage-check.mjs +251 -15
  52. package/scripts/coverage-generation.mjs +41 -0
  53. package/scripts/coverage-range-merge.mjs +41 -0
  54. package/scripts/foreground-daemon-recovery.mjs +88 -0
  55. package/scripts/generate-policy-reference.mjs +28 -5
  56. package/scripts/generate-tool-reference.mjs +1 -1
  57. package/scripts/generate-worker-types.mjs +21 -11
  58. package/scripts/github-backlog.mjs +11 -10
  59. package/scripts/github-push.mjs +62 -16
  60. package/scripts/github-release-asset.mjs +58 -0
  61. package/scripts/github-release.mjs +241 -132
  62. package/scripts/global-package-installation.mjs +68 -0
  63. package/scripts/hardened-npm-session.mjs +42 -0
  64. package/scripts/install-published-prerelease.mjs +198 -0
  65. package/scripts/local-release-acceptance.mjs +103 -45
  66. package/scripts/macos-background-input-smoke.mjs +515 -0
  67. package/scripts/network-retry.mjs +8 -1
  68. package/scripts/npm-global-prefix.mjs +27 -0
  69. package/scripts/npm-publication-policy.mjs +17 -0
  70. package/scripts/official-mcp-conformance.mjs +267 -0
  71. package/scripts/persistent-activation-process.mjs +101 -0
  72. package/scripts/prepare-pinned-npm.mjs +12 -69
  73. package/scripts/prerelease-activation.mjs +160 -0
  74. package/scripts/privacy-check.mjs +14 -6
  75. package/scripts/promotion-digest.mjs +128 -0
  76. package/scripts/publish-npm.mjs +260 -0
  77. package/scripts/published-release.mjs +132 -0
  78. package/scripts/release-acceptance.mjs +62 -54
  79. package/scripts/release-browser-extension-store.mjs +172 -0
  80. package/scripts/release-candidate-manifest.mjs +52 -0
  81. package/scripts/release-channel.mjs +106 -0
  82. package/scripts/release-diagnostic.mjs +41 -0
  83. package/scripts/release-impact-check.mjs +12 -22
  84. package/scripts/release-oauth-canary-core.mjs +325 -0
  85. package/scripts/release-oauth-canary-evidence.mjs +100 -0
  86. package/scripts/release-oauth-canary.mjs +127 -0
  87. package/scripts/release-publication-guard.mjs +67 -0
  88. package/scripts/release-soak.mjs +284 -0
  89. package/scripts/release-state.mjs +1 -1
  90. package/scripts/run-checks.mjs +44 -7
  91. package/scripts/run-worker-dry-run.mjs +21 -0
  92. package/scripts/sarif-security-gate.mjs +2 -1
  93. package/scripts/sbom-check.mjs +106 -0
  94. package/scripts/start-release-candidate.mjs +267 -44
  95. package/scripts/syntax-check.mjs +36 -14
  96. package/scripts/verification-generation-guard.mjs +15 -0
  97. package/scripts/verification-idle-sleep-guard.mjs +37 -0
  98. package/scripts/verification-state.mjs +108 -0
  99. package/scripts/wrangler-command-lifecycle.mjs +115 -0
  100. package/src/local/account-access.mjs +13 -1
  101. package/src/local/account-admin-response.mjs +92 -0
  102. package/src/local/account-admin.mjs +52 -19
  103. package/src/local/agent-context-projection.mjs +26 -7
  104. package/src/local/agent-context.mjs +88 -49
  105. package/src/local/agent-skill-discovery.mjs +16 -5
  106. package/src/local/app-automation-macos-jxa.mjs +350 -0
  107. package/src/local/app-automation.mjs +873 -163
  108. package/src/local/application-capability-projection.mjs +24 -0
  109. package/src/local/authority-context.mjs +106 -0
  110. package/src/local/autostart-log-maintenance.mjs +36 -0
  111. package/src/local/browser-bridge-http.mjs +5 -3
  112. package/src/local/browser-bridge.mjs +109 -31
  113. package/src/local/browser-broker-auth-http.mjs +67 -0
  114. package/src/local/browser-broker-auth.mjs +98 -0
  115. package/src/local/browser-broker-routes.mjs +63 -20
  116. package/src/local/browser-broker-server.mjs +17 -7
  117. package/src/local/browser-command.mjs +79 -30
  118. package/src/local/browser-computer-observation-service.mjs +266 -0
  119. package/src/local/browser-extension-identity.mjs +50 -0
  120. package/src/local/browser-extension-path.mjs +22 -0
  121. package/src/local/browser-extension-protocol.mjs +50 -11
  122. package/src/local/browser-operation-service.mjs +147 -117
  123. package/src/local/browser-pairing-grant.mjs +109 -0
  124. package/src/local/browser-pairing-http.mjs +36 -0
  125. package/src/local/browser-pairing-launch.mjs +58 -0
  126. package/src/local/browser-pairing-store.mjs +85 -48
  127. package/src/local/browser-request-registry.mjs +40 -14
  128. package/src/local/browser-request-settlement.mjs +78 -0
  129. package/src/local/browser-resource-input.mjs +74 -0
  130. package/src/local/browser-trusted-input-health.mjs +63 -0
  131. package/src/local/call-authority.mjs +21 -0
  132. package/src/local/call-capacity.mjs +45 -0
  133. package/src/local/call-registry-drain.mjs +54 -0
  134. package/src/local/call-registry.mjs +30 -15
  135. package/src/local/capability-observer.mjs +5 -0
  136. package/src/local/capability-ranking.mjs +3 -2
  137. package/src/local/child-process-settlement.mjs +132 -0
  138. package/src/local/cli-account-admin.mjs +40 -6
  139. package/src/local/cli-activate.mjs +162 -0
  140. package/src/local/cli-local-admin.mjs +20 -45
  141. package/src/local/cli-options.mjs +12 -13
  142. package/src/local/cli-ready-output.mjs +52 -0
  143. package/src/local/cli-service.mjs +91 -11
  144. package/src/local/cli.mjs +232 -150
  145. package/src/local/computer-use-application-observation.mjs +224 -0
  146. package/src/local/computer-use-arguments.mjs +270 -0
  147. package/src/local/computer-use-deadline.mjs +50 -0
  148. package/src/local/computer-use-dispatch-settlement.mjs +40 -0
  149. package/src/local/computer-use-expectation.mjs +171 -0
  150. package/src/local/computer-use-observation.mjs +769 -0
  151. package/src/local/computer-use-recovery.mjs +82 -0
  152. package/src/local/computer-use-result-budget.mjs +145 -0
  153. package/src/local/computer-use-snapshot-store.mjs +67 -0
  154. package/src/local/computer-use.mjs +2255 -0
  155. package/src/local/daemon-http-relay-auth.mjs +26 -0
  156. package/src/local/daemon-http-relay-connection.mjs +298 -0
  157. package/src/local/daemon-http-relay-request.mjs +64 -0
  158. package/src/local/daemon-http-relay-sequence.mjs +49 -0
  159. package/src/local/daemon-process.mjs +40 -7
  160. package/src/local/delegated-process-sandbox.mjs +148 -0
  161. package/src/local/device-identity.mjs +156 -49
  162. package/src/local/device-root-provider.mjs +81 -0
  163. package/src/local/directory-metadata.mjs +47 -0
  164. package/src/local/doctor-reporting.mjs +23 -0
  165. package/src/local/durable-process-spec.mjs +80 -0
  166. package/src/local/errors.mjs +25 -15
  167. package/src/local/exclusive-file.mjs +74 -26
  168. package/src/local/execution-limits.mjs +9 -0
  169. package/src/local/execution-routing.mjs +276 -0
  170. package/src/local/execution-surface.mjs +23 -0
  171. package/src/local/file-mutation-coordinator.mjs +47 -0
  172. package/src/local/file-snapshot-preservation.mjs +24 -0
  173. package/src/local/filesystem-identity.mjs +54 -0
  174. package/src/local/fixed-process-environment.mjs +21 -0
  175. package/src/local/full-access-test.mjs +31 -13
  176. package/src/local/git-commit.mjs +69 -0
  177. package/src/local/git-config-safety.mjs +55 -0
  178. package/src/local/git-log-parser.mjs +41 -0
  179. package/src/local/git-metadata-boundary.mjs +77 -0
  180. package/src/local/git-metadata-tree-safety.mjs +59 -0
  181. package/src/local/git-operation-state.mjs +19 -0
  182. package/src/local/git-service.mjs +165 -30
  183. package/src/local/hardened-npm-download-timeout.mjs +46 -0
  184. package/src/local/hardened-npm-download.mjs +109 -0
  185. package/src/local/hardened-npm-extract.mjs +20 -0
  186. package/src/local/hardened-npm-verification.mjs +104 -0
  187. package/src/local/hardened-npm.mjs +199 -0
  188. package/src/local/job-runner.mjs +244 -89
  189. package/src/local/lifecycle.mjs +6 -0
  190. package/src/local/log.mjs +19 -45
  191. package/src/local/macos-background-input.mjs +398 -0
  192. package/src/local/macos-idle-sleep-assertion.mjs +65 -0
  193. package/src/local/macos-trust-broker.mjs +404 -0
  194. package/src/local/managed-job-cancellation.mjs +42 -0
  195. package/src/local/managed-job-capacity.mjs +16 -0
  196. package/src/local/managed-job-directory-generation.mjs +60 -0
  197. package/src/local/managed-job-directory.mjs +75 -0
  198. package/src/local/managed-job-durable-process.mjs +49 -0
  199. package/src/local/managed-job-lock.mjs +46 -14
  200. package/src/local/managed-job-plan.mjs +38 -14
  201. package/src/local/managed-job-projection.mjs +23 -15
  202. package/src/local/managed-job-retention.mjs +128 -0
  203. package/src/local/managed-job-runner-claim.mjs +70 -0
  204. package/src/local/managed-job-runner.mjs +35 -10
  205. package/src/local/managed-job-storage.mjs +22 -6
  206. package/src/local/managed-job-terminal-maintenance.mjs +40 -0
  207. package/src/local/managed-job-terminal.mjs +150 -0
  208. package/src/local/managed-jobs.mjs +424 -287
  209. package/src/local/npm-cli.mjs +42 -0
  210. package/src/local/npm-environment.mjs +37 -0
  211. package/src/local/operation-authorization.mjs +68 -324
  212. package/src/local/operation-risk.mjs +51 -4
  213. package/src/local/owner-state-lock.mjs +118 -0
  214. package/src/local/package-identity.mjs +9 -0
  215. package/src/local/patch.mjs +20 -18
  216. package/src/local/path-inspection.mjs +23 -0
  217. package/src/local/policy.mjs +19 -0
  218. package/src/local/private-toolchain-integrity.mjs +54 -0
  219. package/src/local/process-execution.mjs +87 -75
  220. package/src/local/process-foreground-timeout.mjs +50 -0
  221. package/src/local/process-identity.mjs +41 -7
  222. package/src/local/process-nonreplayable-settlement.mjs +50 -0
  223. package/src/local/process-result-projection.mjs +22 -0
  224. package/src/local/process-session-events.mjs +47 -0
  225. package/src/local/process-session-remote-activity.mjs +10 -0
  226. package/src/local/process-session-termination.mjs +73 -0
  227. package/src/local/process-sessions.mjs +144 -112
  228. package/src/local/process-tracker.mjs +140 -13
  229. package/src/local/process-tree-ownership-types.d.ts +37 -0
  230. package/src/local/process-tree-ownership.mjs +57 -0
  231. package/src/local/process-tree-signal.mjs +34 -0
  232. package/src/local/process-tree-snapshot.mjs +77 -0
  233. package/src/local/process-tree-supervisor.mjs +69 -0
  234. package/src/local/process-tree.mjs +11 -53
  235. package/src/local/project-metadata.mjs +19 -6
  236. package/src/local/relay-call-recovery.mjs +58 -38
  237. package/src/local/relay-connection-classification.mjs +131 -0
  238. package/src/local/relay-connection-support.mjs +91 -0
  239. package/src/local/relay-connection.mjs +179 -272
  240. package/src/local/relay-diagnostics.mjs +91 -0
  241. package/src/local/relay-heartbeat.mjs +119 -0
  242. package/src/local/relay-liveness.mjs +109 -0
  243. package/src/local/relay-peer-diagnostics.mjs +29 -0
  244. package/src/local/release-runtime-lock.mjs +18 -0
  245. package/src/local/remote-activity-idle-sleep-guard.mjs +77 -0
  246. package/src/local/remote-configuration.mjs +48 -0
  247. package/src/local/resilient-relay-connection.mjs +178 -0
  248. package/src/local/resource-admission-diagnostics.mjs +52 -0
  249. package/src/local/resource-admission-policy.mjs +115 -0
  250. package/src/local/resource-admission.mjs +339 -0
  251. package/src/local/resource-build-root.mjs +83 -0
  252. package/src/local/resource-cargo-concurrency.mjs +38 -0
  253. package/src/local/resource-cmake-concurrency.mjs +42 -0
  254. package/src/local/resource-command-concurrency.mjs +37 -0
  255. package/src/local/resource-command-profile.mjs +176 -0
  256. package/src/local/resource-coordinator-accounting.mjs +21 -0
  257. package/src/local/resource-cpu-window.mjs +20 -0
  258. package/src/local/resource-disk-headroom.mjs +13 -0
  259. package/src/local/resource-elastic-memory.mjs +19 -0
  260. package/src/local/resource-elastic-request.mjs +36 -0
  261. package/src/local/resource-foreground-wait.mjs +29 -0
  262. package/src/local/resource-go-concurrency.mjs +43 -0
  263. package/src/local/resource-gradle-concurrency.mjs +57 -0
  264. package/src/local/resource-host-cache.mjs +39 -0
  265. package/src/local/resource-host-darwin.mjs +54 -0
  266. package/src/local/resource-host-linux.mjs +35 -0
  267. package/src/local/resource-host-sample-file.mjs +23 -0
  268. package/src/local/resource-host-snapshot.mjs +99 -0
  269. package/src/local/resource-lease-accounting.mjs +119 -0
  270. package/src/local/resource-light-command.mjs +6 -0
  271. package/src/local/resource-make-concurrency.mjs +42 -0
  272. package/src/local/resource-maven-concurrency.mjs +38 -0
  273. package/src/local/resource-ninja-command-concurrency.mjs +20 -0
  274. package/src/local/resource-ninja-concurrency.mjs +28 -0
  275. package/src/local/resource-operations.mjs +26 -10
  276. package/src/local/resource-pressure.mjs +67 -0
  277. package/src/local/resource-probe-command.mjs +35 -0
  278. package/src/local/resource-process-admission.mjs +59 -0
  279. package/src/local/resource-process-ancestry-cache.mjs +43 -0
  280. package/src/local/resource-process-ancestry.mjs +32 -0
  281. package/src/local/resource-process-priority.mjs +15 -0
  282. package/src/local/resource-project-key.mjs +53 -0
  283. package/src/local/resource-pytest-concurrency.mjs +33 -0
  284. package/src/local/resource-release-control-classification.mjs +14 -0
  285. package/src/local/resource-release-control-executable.mjs +70 -0
  286. package/src/local/resource-release-control-workspace.mjs +41 -0
  287. package/src/local/resource-request-contract.mjs +30 -0
  288. package/src/local/resource-script-classification.mjs +44 -0
  289. package/src/local/resource-shell-analysis.mjs +58 -0
  290. package/src/local/resource-staging-recovery.mjs +97 -0
  291. package/src/local/resource-swift-concurrency.mjs +31 -0
  292. package/src/local/resource-transaction-lock.mjs +189 -0
  293. package/src/local/resource-wait.mjs +48 -0
  294. package/src/local/resource-waiters.mjs +139 -0
  295. package/src/local/resource-xcode-command.mjs +7 -0
  296. package/src/local/resource-xcode-concurrency.mjs +34 -0
  297. package/src/local/resource-xcode-non-build.mjs +19 -0
  298. package/src/local/runtime-activation.mjs +700 -0
  299. package/src/local/runtime-activity-projection.mjs +48 -0
  300. package/src/local/runtime-capabilities.mjs +48 -15
  301. package/src/local/runtime-diagnostic-state.mjs +14 -0
  302. package/src/local/runtime-diagnostics.mjs +40 -13
  303. package/src/local/runtime-info-projection.mjs +60 -0
  304. package/src/local/runtime-info-relay-projection.mjs +21 -0
  305. package/src/local/runtime-paths.mjs +2 -1
  306. package/src/local/runtime-process-routing.mjs +33 -0
  307. package/src/local/runtime-relay-connection-options.mjs +44 -0
  308. package/src/local/runtime-relay-control.mjs +98 -0
  309. package/src/local/runtime-relay.mjs +26 -50
  310. package/src/local/runtime-reporting.mjs +37 -21
  311. package/src/local/runtime-resource-service.mjs +77 -0
  312. package/src/local/runtime-tool-handlers.mjs +13 -10
  313. package/src/local/runtime.mjs +244 -208
  314. package/src/local/secure-file.mjs +73 -20
  315. package/src/local/security-audit-dispatch.mjs +35 -0
  316. package/src/local/security-audit-log.mjs +215 -0
  317. package/src/local/security-audit-state.mjs +139 -0
  318. package/src/local/security-audit-storage.mjs +135 -0
  319. package/src/local/security-audit-warning.mjs +31 -0
  320. package/src/local/security-audit-worker.mjs +87 -0
  321. package/src/local/service-convergence.mjs +42 -1
  322. package/src/local/service-definition.mjs +24 -0
  323. package/src/local/service-environment.mjs +18 -10
  324. package/src/local/service-owner.mjs +146 -0
  325. package/src/local/service-ownership.mjs +17 -0
  326. package/src/local/service-restart-handoff.mjs +64 -0
  327. package/src/local/service-restart-scheduler.mjs +49 -0
  328. package/src/local/service-runtime-convergence.mjs +52 -0
  329. package/src/local/service-runtime.mjs +105 -0
  330. package/src/local/service-status.mjs +60 -0
  331. package/src/local/service.mjs +385 -92
  332. package/src/local/shell.mjs +39 -19
  333. package/src/local/ssh-key.mjs +158 -42
  334. package/src/local/state-inventory.mjs +50 -24
  335. package/src/local/state-owner-lock-inventory.mjs +23 -0
  336. package/src/local/state-root-owned-namespaces.mjs +83 -0
  337. package/src/local/state-root-retirement.mjs +89 -0
  338. package/src/local/state.mjs +386 -96
  339. package/src/local/stdio.mjs +96 -66
  340. package/src/local/support-state-projection.mjs +30 -0
  341. package/src/local/system-network-route.mjs +76 -0
  342. package/src/local/systemd-removal.mjs +20 -0
  343. package/src/local/tool-executor.mjs +85 -20
  344. package/src/local/tool-result-boundary.mjs +51 -0
  345. package/src/local/toolchain-operation-lock.mjs +41 -0
  346. package/src/local/tools.mjs +7 -5
  347. package/src/local/trusted-executable.mjs +53 -0
  348. package/src/local/trusted-git-executable.mjs +34 -0
  349. package/src/local/trusted-github-cli.mjs +24 -0
  350. package/src/local/windows-service-convergence.mjs +49 -0
  351. package/src/local/windows-service.mjs +52 -45
  352. package/src/local/worker-deployment-fingerprint.mjs +102 -0
  353. package/src/local/worker-deployment.mjs +48 -60
  354. package/src/local/worker-health.mjs +12 -4
  355. package/src/local/worker-secret-file.mjs +37 -17
  356. package/src/local/workspace-file-service.mjs +156 -239
  357. package/src/local/workspace-file-transaction.mjs +189 -0
  358. package/src/local/workspace-search.mjs +55 -0
  359. package/src/local/wrangler-toolchain/package-lock.json +1505 -0
  360. package/src/local/wrangler-toolchain/package.json +23 -0
  361. package/src/local/wrangler-toolchain-verification.mjs +135 -0
  362. package/src/local/wrangler-toolchain.mjs +188 -0
  363. package/src/shared/access-contract.json +7 -1
  364. package/src/shared/activation-recovery.mjs +49 -0
  365. package/src/shared/admin-auth.d.mts +2 -1
  366. package/src/shared/admin-auth.mjs +3 -3
  367. package/src/shared/authority-revocation.d.mts +9 -0
  368. package/src/shared/authority-revocation.mjs +28 -0
  369. package/src/shared/daemon-auth.d.mts +11 -0
  370. package/src/shared/daemon-auth.mjs +17 -0
  371. package/src/shared/device-session-auth.d.mts +20 -0
  372. package/src/shared/device-session-auth.mjs +51 -0
  373. package/src/shared/foreground-timeout.d.mts +15 -0
  374. package/src/shared/foreground-timeout.mjs +70 -0
  375. package/src/shared/log-redaction.d.mts +9 -0
  376. package/src/shared/log-redaction.mjs +51 -0
  377. package/src/shared/mcp-protocol.d.mts +27 -0
  378. package/src/shared/mcp-protocol.mjs +275 -0
  379. package/src/shared/project-overview-projection.d.mts +4 -0
  380. package/src/shared/project-overview-projection.mjs +96 -0
  381. package/src/shared/relay-contract.json +28 -0
  382. package/src/shared/result-projection.d.mts +2 -1
  383. package/src/shared/result-projection.mjs +13 -2
  384. package/src/shared/server-metadata.json +15 -9
  385. package/src/shared/tool-argument-validation.d.mts +17 -0
  386. package/src/shared/tool-argument-validation.mjs +325 -0
  387. package/src/shared/tool-call-capacity.d.mts +41 -0
  388. package/src/shared/tool-call-capacity.mjs +59 -0
  389. package/src/shared/tool-catalog.json +626 -57
  390. package/src/worker/access.ts +12 -0
  391. package/src/worker/account-admin.ts +55 -33
  392. package/src/worker/authority-revocations.ts +174 -0
  393. package/src/worker/authority.ts +52 -6
  394. package/src/worker/daemon-auth.ts +49 -68
  395. package/src/worker/daemon-channel.ts +36 -0
  396. package/src/worker/daemon-http-auth.ts +63 -0
  397. package/src/worker/daemon-http-channel.ts +120 -0
  398. package/src/worker/daemon-http-controller.ts +163 -0
  399. package/src/worker/daemon-http-protocol.ts +62 -0
  400. package/src/worker/daemon-http-registry.ts +82 -0
  401. package/src/worker/daemon-last-observation.ts +30 -0
  402. package/src/worker/daemon-liveness.ts +8 -6
  403. package/src/worker/daemon-ready-dispatch.ts +17 -0
  404. package/src/worker/daemon-ready-messages.ts +73 -0
  405. package/src/worker/daemon-ready-waiters.ts +79 -0
  406. package/src/worker/daemon-recovery-budget.ts +13 -0
  407. package/src/worker/daemon-registry.ts +58 -0
  408. package/src/worker/daemon-relay-diagnostics.ts +127 -0
  409. package/src/worker/daemon-socket-attachment.ts +55 -0
  410. package/src/worker/daemon-sockets.ts +72 -62
  411. package/src/worker/daemon-status.ts +38 -0
  412. package/src/worker/device-session-verifier.ts +129 -0
  413. package/src/worker/dpop.ts +157 -0
  414. package/src/worker/durable-process-timeout.ts +29 -0
  415. package/src/worker/errors.ts +57 -0
  416. package/src/worker/http.ts +112 -26
  417. package/src/worker/index.ts +446 -440
  418. package/src/worker/mcp-access.ts +57 -0
  419. package/src/worker/mcp-controller.ts +188 -0
  420. package/src/worker/mcp-http-accept.ts +11 -0
  421. package/src/worker/mcp-http-contract.ts +322 -0
  422. package/src/worker/mcp-initialization-compat.ts +141 -0
  423. package/src/worker/mcp-jsonrpc.ts +11 -29
  424. package/src/worker/mcp-removed-protocol.ts +17 -0
  425. package/src/worker/mcp-response-proxy.ts +135 -0
  426. package/src/worker/mcp-response-stream.ts +65 -0
  427. package/src/worker/mcp-stale-schema-compat.ts +57 -0
  428. package/src/worker/mcp-stream-proxy-contract.ts +48 -0
  429. package/src/worker/mcp-tool-call-input.ts +23 -0
  430. package/src/worker/nonce-store.ts +33 -35
  431. package/src/worker/oauth-authorization-page.ts +21 -1
  432. package/src/worker/oauth-client-admin.ts +52 -0
  433. package/src/worker/oauth-client-contract.ts +38 -0
  434. package/src/worker/oauth-controller.ts +107 -47
  435. package/src/worker/oauth-field-contract.ts +31 -0
  436. package/src/worker/oauth-record-contract.ts +7 -0
  437. package/src/worker/oauth-refresh-authority.ts +27 -0
  438. package/src/worker/oauth-refresh-exchange.ts +162 -0
  439. package/src/worker/oauth-refresh-families.ts +130 -27
  440. package/src/worker/oauth-refresh-persistence.ts +116 -0
  441. package/src/worker/oauth-state.ts +33 -18
  442. package/src/worker/oauth-store-validation.ts +131 -0
  443. package/src/worker/oauth-token-derivation.ts +33 -0
  444. package/src/worker/oauth-token-issuance.ts +119 -0
  445. package/src/worker/oauth-tokens.ts +56 -190
  446. package/src/worker/observability.ts +38 -5
  447. package/src/worker/pending-admission.ts +15 -0
  448. package/src/worker/pending-call-capacity.ts +108 -0
  449. package/src/worker/pending-call-contract.ts +42 -5
  450. package/src/worker/pending-call-deadlines.ts +75 -0
  451. package/src/worker/pending-calls.ts +131 -125
  452. package/src/worker/runtime-alarm-storage.ts +37 -0
  453. package/src/worker/runtime-alarm.ts +136 -0
  454. package/src/worker/server-info-activity.ts +36 -0
  455. package/src/worker/server-info-tool-delivery.ts +15 -0
  456. package/src/worker/server-info.ts +168 -0
  457. package/src/worker/tool-catalog.ts +47 -1
  458. package/src/worker/tool-timeout.ts +75 -14
  459. package/src/worker/websocket-protocol.ts +26 -2
  460. package/src/worker/worker-edge-guard.ts +90 -0
  461. package/src/worker/worker-edge-log.ts +65 -0
  462. package/src/worker/worker-entry.ts +52 -0
  463. package/src/worker/worker-mcp-config.ts +23 -0
  464. package/src/worker/worker-metadata.ts +48 -0
  465. package/src/worker/worker-rate-limit-key.ts +30 -0
  466. package/src/worker/worker-runtime-config.ts +20 -0
  467. package/src/worker/worker-static-routes.ts +54 -0
  468. package/src/worker/worker-task-lifetime.ts +18 -0
  469. package/tsconfig.local.json +17 -1
  470. package/wrangler.jsonc +13 -0
  471. package/src/local/cli-approval.mjs +0 -117
  472. package/src/local/operation-state-lock.mjs +0 -92
  473. package/src/worker/mcp-session.ts +0 -72
@@ -6,6 +6,9 @@ const ERROR_CODES = new Set([
6
6
  ]);
7
7
 
8
8
  const RETRYABLE_CODES = new Set(["timeout", "network_error", "unavailable"]);
9
+ const MAX_PUBLIC_ERROR_MESSAGE_CHARS = 2000;
10
+ const MAX_PUBLIC_ERROR_DETAILS_BYTES = 512 * 1024;
11
+ const UNSAFE_ERROR_CONTROLS = /[\u0000-\u001f\u007f\u200B-\u200F\u202A-\u202E\u2066-\u2069\uFEFF]/g;
9
12
 
10
13
  export class BridgeError extends Error {
11
14
  constructor(code, message, options = {}) {
@@ -29,7 +32,7 @@ export function normalizeBridgeError(error, options = {}) {
29
32
  : safeFallbackMessage(error, code);
30
33
  return new BridgeError(code, message, {
31
34
  cause: error instanceof Error ? error : undefined,
32
- expose: options.expose !== false,
35
+ expose: options.expose === true,
33
36
  retryable: options.retryable,
34
37
  });
35
38
  }
@@ -50,26 +53,15 @@ export function errorCode(error, fallback = "execution_failed") {
50
53
 
51
54
  export function publicError(error, options = {}) {
52
55
  const normalized = normalizeBridgeError(error, options);
56
+ const details = normalized.expose ? publicErrorDetails(normalized.details) : undefined;
53
57
  return {
54
58
  code: normalized.code,
55
- message: normalized.expose ? normalized.message : defaultMessage(normalized.code),
59
+ message: publicErrorMessage(normalized.expose ? normalized.message : defaultMessage(normalized.code)),
56
60
  retryable: normalized.retryable,
57
- ...(normalized.expose && normalized.details ? { details: normalized.details } : {}),
61
+ ...(details ? { details } : {}),
58
62
  };
59
63
  }
60
64
 
61
- export function remoteBridgeError(value, fallbackMessage = "remote operation failed") {
62
- if (isRecord(value)) {
63
- const code = normalizeErrorCode(value.code);
64
- const message = typeof value.message === "string" && value.message ? value.message : fallbackMessage;
65
- return new BridgeError(code, message, {
66
- retryable: value.retryable === true,
67
- details: isRecord(value.details) ? value.details : undefined,
68
- });
69
- }
70
- return new BridgeError("execution_failed", fallbackMessage);
71
- }
72
-
73
65
  function normalizeErrorCode(value, fallback = "execution_failed") {
74
66
  const code = String(value || "").trim().toLowerCase().replace(/[^a-z0-9_-]/g, "_").slice(0, 64);
75
67
  return ERROR_CODES.has(code) ? code : fallback;
@@ -106,3 +98,21 @@ function defaultMessage(code) {
106
98
  function isRecord(value) {
107
99
  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
108
100
  }
101
+
102
+ function publicErrorMessage(value) {
103
+ const normalized = String(value || "").replace(UNSAFE_ERROR_CONTROLS, " ").replace(/\s+/g, " ").trim();
104
+ return (normalized || "operation failed").slice(0, MAX_PUBLIC_ERROR_MESSAGE_CHARS);
105
+ }
106
+
107
+ function publicErrorDetails(value) {
108
+ if (!isRecord(value)) return undefined;
109
+ try {
110
+ const serialized = JSON.stringify(value, (_key, current) => {
111
+ if (["bigint", "function", "symbol", "undefined"].includes(typeof current)) throw new TypeError("unsupported error detail");
112
+ if (typeof current === "number" && !Number.isFinite(current)) throw new TypeError("unsupported error detail");
113
+ return current;
114
+ });
115
+ if (!serialized || Buffer.byteLength(serialized) > MAX_PUBLIC_ERROR_DETAILS_BYTES) return undefined;
116
+ return JSON.parse(serialized);
117
+ } catch { return undefined; }
118
+ }
@@ -11,50 +11,96 @@ import {
11
11
  } from "node:fs";
12
12
  import { basename, dirname, join } from "node:path";
13
13
  import { replaceFileSync } from "./atomic-fs.mjs";
14
- import { readBoundedRegularFileSync } from "./secure-file.mjs";
14
+ import { readBoundedRegularFileWithInfoSync } from "./secure-file.mjs";
15
+ import { filesystemIdentity, sameFilesystemIdentity } from "./filesystem-identity.mjs";
15
16
 
16
17
  export function createExclusiveFileSync(target, content, options = {}) {
17
18
  const mode = Number.isInteger(options.mode) ? options.mode : 0o600;
19
+ const createLink = options.link || linkSync;
20
+ const remove = options.unlink || unlinkSync;
18
21
  const temporary = join(dirname(target), `.${basename(target)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
19
22
  let fd;
23
+ let ownsTemporary = false;
20
24
  let linked = false;
25
+ let primaryError = null;
26
+ const cleanupErrors = [];
21
27
  try {
22
28
  fd = openSync(temporary, "wx", mode);
29
+ ownsTemporary = true;
23
30
  writeFileSync(fd, content);
24
31
  setDescriptorMode(fd, mode);
25
32
  fsyncSync(fd);
26
33
  closeSync(fd);
27
34
  fd = undefined;
28
- linkSync(temporary, target);
35
+ createLink(temporary, target);
29
36
  linked = true;
30
- return { created: true, path: target };
31
- } finally {
32
- if (fd !== undefined) try { closeSync(fd); } catch {}
33
- try { unlinkSync(temporary); } catch {}
34
- if (!linked && options.cleanupTargetOnFailure === true) {
35
- try { unlinkSync(target); } catch {}
37
+ } catch (error) {
38
+ primaryError = error;
39
+ }
40
+
41
+ if (fd !== undefined) {
42
+ try { closeSync(fd); } catch (error) { cleanupErrors.push(error); }
43
+ }
44
+ let stagingCleanupError = null;
45
+ if (ownsTemporary) {
46
+ try { remove(temporary); } catch (error) {
47
+ if (error?.code !== "ENOENT") {
48
+ stagingCleanupError = error;
49
+ cleanupErrors.push(error);
50
+ }
36
51
  }
37
52
  }
53
+
54
+ if (primaryError) {
55
+ if (cleanupErrors.length) {
56
+ throw new AggregateError([primaryError, ...cleanupErrors], "exclusive file creation failed and cleanup was incomplete");
57
+ }
58
+ throw primaryError;
59
+ }
60
+ if (!linked) throw new Error("exclusive file creation did not settle");
61
+ const result = { created: true, path: target, warnings: [] };
62
+ if (stagingCleanupError) {
63
+ result.warnings.push("Exclusive file committed, but its internal staging file could not be removed.");
64
+ Object.defineProperties(result, {
65
+ cleanupError: { value: stagingCleanupError, enumerable: false },
66
+ cleanupArtifact: { value: temporary, enumerable: false },
67
+ });
68
+ }
69
+ return result;
38
70
  }
39
71
 
40
72
  export function replaceFileAtomicallySync(target, content, options = {}) {
41
73
  const mode = Number.isInteger(options.mode) ? options.mode : 0o600;
74
+ const remove = options.unlink || unlinkSync;
75
+ const replace = options.replace || replaceFileSync;
42
76
  const temporary = join(dirname(target), `.${basename(target)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
43
77
  let fd;
78
+ let ownsTemporary = false;
79
+ let primaryError = null;
80
+ const cleanupErrors = [];
44
81
  try {
45
82
  fd = openSync(temporary, "wx", mode);
83
+ ownsTemporary = true;
46
84
  writeFileSync(fd, content);
47
85
  setDescriptorMode(fd, mode);
48
86
  fsyncSync(fd);
49
87
  closeSync(fd);
50
88
  fd = undefined;
51
- replaceFileSync(temporary, target);
89
+ replace(temporary, target);
52
90
  return { replaced: true, path: target };
53
91
  } catch (error) {
54
- if (fd !== undefined) try { closeSync(fd); } catch {}
55
- try { unlinkSync(temporary); } catch {}
56
- throw error;
92
+ primaryError = error;
57
93
  }
94
+ if (fd !== undefined) {
95
+ try { closeSync(fd); } catch (error) { cleanupErrors.push(error); }
96
+ }
97
+ if (ownsTemporary) {
98
+ try { remove(temporary); } catch (error) { if (error?.code !== "ENOENT") cleanupErrors.push(error); }
99
+ }
100
+ if (cleanupErrors.length) {
101
+ throw new AggregateError([primaryError, ...cleanupErrors], "atomic file replacement failed and cleanup was incomplete");
102
+ }
103
+ throw primaryError;
58
104
  }
59
105
 
60
106
  export function removeOwnedJsonFileSync(target, expected = {}, options = {}) {
@@ -62,24 +108,29 @@ export function removeOwnedJsonFileSync(target, expected = {}, options = {}) {
62
108
  const snapshot = ownedJsonSnapshot(target, maxBytes);
63
109
  if (!snapshot || !matchesExpected(snapshot.value, expected)) return false;
64
110
  let current;
65
- try { current = lstatSync(target); } catch (error) { return error?.code === "ENOENT"; }
66
- if (current.isSymbolicLink() || !current.isFile() || !sameIdentity(snapshot.info, current)) return false;
111
+ try { current = lstatSync(target, { bigint: true }); } catch (error) { return error?.code === "ENOENT"; }
112
+ if (current.isSymbolicLink() || !current.isFile() || current.nlink !== 1n || !sameIdentity(snapshot.info, current)) return false;
67
113
  const currentSnapshot = ownedJsonSnapshot(target, maxBytes);
68
114
  if (!currentSnapshot || !sameIdentity(snapshot.info, currentSnapshot.info) || !matchesExpected(currentSnapshot.value, expected)) return false;
69
115
  try { unlinkSync(target); return true; } catch (error) { return error?.code === "ENOENT"; }
70
116
  }
71
117
 
72
118
  function ownedJsonSnapshot(target, maxBytes) {
73
- let info;
74
- try { info = lstatSync(target); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
75
- if (info.isSymbolicLink() || !info.isFile()) return null;
119
+ let opened;
76
120
  try {
77
- const value = JSON.parse(readBoundedRegularFileSync(target, maxBytes).toString("utf8"));
78
- if (!value || typeof value !== "object" || Array.isArray(value)) return null;
79
- return { value, info };
80
- } catch {
81
- return null;
121
+ opened = readBoundedRegularFileWithInfoSync(target, maxBytes, "owned JSON snapshot", {
122
+ verifyPathIdentity: true,
123
+ rejectMultipleLinks: true,
124
+ });
125
+ } catch (error) {
126
+ if (error?.code === "ENOENT" || error?.cause?.code === "ENOENT") return null;
127
+ throw error;
82
128
  }
129
+ try {
130
+ const value = JSON.parse(opened.buffer.toString("utf8"));
131
+ if (!value || typeof value !== "object" || Array.isArray(value)) return null;
132
+ return { value, info: opened.identityInfo };
133
+ } catch { return null; }
83
134
  }
84
135
 
85
136
  function matchesExpected(value, expected) {
@@ -87,10 +138,7 @@ function matchesExpected(value, expected) {
87
138
  }
88
139
 
89
140
  function sameIdentity(left, right) {
90
- return Number(left.dev) === Number(right.dev)
91
- && Number(left.ino) === Number(right.ino)
92
- && Number(left.size) === Number(right.size)
93
- && Number(left.mtimeMs) === Number(right.mtimeMs);
141
+ return sameFilesystemIdentity(filesystemIdentity(left, "owned JSON snapshot"), filesystemIdentity(right, "owned JSON snapshot"));
94
142
  }
95
143
 
96
144
  function setDescriptorMode(fd, mode) {
@@ -1,4 +1,9 @@
1
+ import { CONTROL_PLANE_TOOL_NAMES } from "../shared/tool-call-capacity.mjs";
2
+ import { resourceAdmissionGuardrailSnapshot } from "./resource-admission-diagnostics.mjs";
3
+
4
+ export { CONTROL_PLANE_TOOL_NAMES };
1
5
  export const MAX_CONCURRENT_TOOL_CALLS = 16;
6
+ export const RESERVED_CONTROL_TOOL_CALLS = 2;
2
7
  export const MAX_PROCESS_SESSIONS = 8;
3
8
  export const MIN_PROCESS_TIMEOUT_SECONDS = 1;
4
9
  export const MAX_PROCESS_TIMEOUT_SECONDS = 600;
@@ -13,6 +18,9 @@ export function executionGuardrailsSnapshot() {
13
18
  return {
14
19
  tool_calls: {
15
20
  maximum_concurrent: MAX_CONCURRENT_TOOL_CALLS,
21
+ ordinary_capacity: MAX_CONCURRENT_TOOL_CALLS - RESERVED_CONTROL_TOOL_CALLS,
22
+ reserved_control_capacity: RESERVED_CONTROL_TOOL_CALLS,
23
+ reserved_control_tools: [...CONTROL_PLANE_TOOL_NAMES],
16
24
  },
17
25
  one_shot_processes: {
18
26
  timeout_seconds: { minimum: MIN_PROCESS_TIMEOUT_SECONDS, maximum: MAX_PROCESS_TIMEOUT_SECONDS },
@@ -31,6 +39,7 @@ export function executionGuardrailsSnapshot() {
31
39
  exited_retention_ms: PROCESS_SESSION_RETENTION_MS,
32
40
  process_tree_termination: "sigterm-then-sigkill",
33
41
  },
42
+ resource_admission: resourceAdmissionGuardrailSnapshot(),
34
43
  operating_system_enforcement: {
35
44
  cpu_quota: "not-enforced",
36
45
  memory_quota: "not-enforced",
@@ -0,0 +1,276 @@
1
+ // @ts-check
2
+
3
+ import { relevanceScore } from "./capability-ranking.mjs";
4
+ import { toolDefinition, toolNamesForPolicy } from "./policy.mjs";
5
+
6
+ const MAX_ROUTES = 6;
7
+ const MAX_RANKED_TOOLS = 12;
8
+ const MAX_RECOMMENDED_TOOLS = 18;
9
+
10
+ const ROUTES = Object.freeze([
11
+ route("guided-workflow", "Guided workflow", [
12
+ "load_local_skill", "agent_context", "list_local_skills",
13
+ ], "Use a project or user skill when a repeatable domain workflow already exists.", [
14
+ "skill", "workflow", "instructions", "playbook", "guide", "技能", "工作流", "规范", "流程",
15
+ ]),
16
+ route("registered-command", "Registered command", [
17
+ "run_local_command", "list_local_commands",
18
+ ], "Use a fixed argv/cwd command when the repository already defines the operation.", [
19
+ "package script", "registered command", "repeatable command", "npm script", "构建脚本", "项目命令", "重复执行",
20
+ ]),
21
+ route("shell", "Direct shell", [
22
+ "exec_command", "run_process",
23
+ ], "Use Bash or direct argv for efficient ad hoc composition, investigation, and ordinary CLI work when the effective authority exposes those tools. This is the general unsandboxed escape hatch inside that authority, not a way around it.", [
24
+ "bash", "shell", "terminal", "cli", "command", "script", "debug", "diagnose", "benchmark", "audit", "probe",
25
+ "命令", "终端", "脚本", "排查", "调试", "基准", "审查", "测试", "构建",
26
+ ]),
27
+ route("process-session", "Interactive process", [
28
+ "start_process", "read_process", "write_process", "kill_process",
29
+ ], "Use a retained process session for interactive stdin, incremental output, servers, watchers, and REPL-style work.", [
30
+ "interactive", "stdin", "repl", "watch", "tail", "stream output", "dev server", "long output", "交互", "实时日志", "输入", "常驻进程",
31
+ ]),
32
+ route("managed-job", "Durable managed job", [
33
+ "stage_job", "start_job", "read_job", "list_jobs", "cancel_job",
34
+ ], "Use a durable job for long-running or multi-step work that must survive relay interruption and still attempt cleanup.", [
35
+ "background", "detached", "durable", "long running", "resume", "cleanup", "finally", "overnight", "continuous", "retry",
36
+ "后台", "持久", "断线", "恢复", "清理", "长时间", "持续", "重试", "多步骤",
37
+ ]),
38
+ route("workspace-edit", "Workspace files", [
39
+ "search_text", "read_file", "list_files", "list_dir", "edit_file", "apply_patch", "write_file", "view_image",
40
+ ], "Use bounded structured file operations for inspection and precise repository edits; combine with shell when a CLI is more efficient.", [
41
+ "file", "source", "code", "edit", "write", "patch", "refactor", "search", "inspect", "repository",
42
+ "文件", "源码", "代码", "修改", "写入", "补丁", "重构", "搜索", "仓库",
43
+ ]),
44
+ route("git-review", "Git repository", [
45
+ "git_status", "git_diff", "git_log", "git_show", "git_commit",
46
+ ], "Use Git-specific structured surfaces for bounded inspection and local commits from an already-staged index; prefer git_commit over generic process execution when creating a commit.", [
47
+ "git", "commit", "diff", "branch", "history", "revision", "提交", "分支", "差异", "历史", "版本",
48
+ ]),
49
+ route("computer-use", "Verified computer use", [
50
+ "computer_observe", "computer_act",
51
+ ], "Use snapshot-bound observe-act-verify for GUI work. Prefer this over separate low-level browser/application calls when the task needs state validation or recovery from ambiguous outcomes.", [
52
+ "computer use", "gui agent", "screen grounding", "verify action", "电脑操作", "界面操作", "视觉定位", "验证结果",
53
+ ]),
54
+ route("browser", "Existing browser profile", [
55
+ "browser_status", "browser_list_tabs", "browser_manage_tabs", "browser_get_source", "browser_inspect_page",
56
+ "browser_wait", "browser_action", "browser_fill_form", "browser_screenshot", "browser_upload_files",
57
+ ], "Use the paired daily browser for authenticated websites, complex forms, DOM inspection, and actions that depend on the user's existing session.", [
58
+ "browser", "website", "web page", "tab", "dom", "form", "login", "authenticated", "chrome", "网页", "浏览器", "网站", "标签页", "表单", "登录",
59
+ ]),
60
+ route("application-discovery", "Installed application inventory", [
61
+ "list_local_applications",
62
+ ], "Use read-only local application discovery to identify installed apps and launchers without implying authority to open, inspect, or operate them.", [
63
+ "installed app", "application inventory", "application discovery", "launcher", "已安装应用", "应用清单", "应用发现", "启动器",
64
+ ]),
65
+ route("application", "Desktop application", [
66
+ "open_local_application", "inspect_local_application", "operate_local_application",
67
+ ], "Use structured desktop automation for installed applications and macOS Accessibility surfaces.", [
68
+ "application", "desktop", "gui", "window", "accessibility", "mac app", "应用", "桌面", "界面", "窗口", "软件",
69
+ ]),
70
+ route("protected-resource", "Protected local resource", [
71
+ "list_local_resources", "generate_ssh_key_resource",
72
+ ], "Use registered resource aliases for secrets or files that should not be copied into MCP arguments.", [
73
+ "credential", "secret", "token", "private key", "ssh key", "password", "resource alias", "凭据", "密钥", "令牌", "密码", "资源别名",
74
+ ]),
75
+ route("diagnostics", "Runtime diagnostics", [
76
+ "server_info", "project_overview", "diagnose_runtime",
77
+ ], "Use fixed diagnostics to distinguish authorization, relay, filesystem, process, shell, and runtime failures.", [
78
+ "status", "health", "diagnose", "runtime", "relay", "policy", "authorization", "状态", "健康", "诊断", "运行时", "权限", "连接",
79
+ ]),
80
+ ]);
81
+
82
+ const ROUTE_FALLBACKS = Object.freeze({
83
+ "guided-workflow": ["registered-command", "shell"],
84
+ "registered-command": ["shell", "process-session"],
85
+ shell: ["process-session", "managed-job"],
86
+ "process-session": ["shell", "managed-job"],
87
+ "managed-job": ["process-session", "shell"],
88
+ "workspace-edit": ["shell", "git-review"],
89
+ "git-review": ["workspace-edit", "shell"],
90
+ "computer-use": ["browser", "application", "diagnostics"],
91
+ browser: ["computer-use", "diagnostics", "shell"],
92
+ "application-discovery": ["application", "diagnostics"],
93
+ application: ["computer-use", "diagnostics", "shell"],
94
+ "protected-resource": ["diagnostics"],
95
+ diagnostics: ["shell"],
96
+ });
97
+
98
+ /**
99
+ * Build advisory, set-level routing for the current task. It never hides tools,
100
+ * changes policy, or makes shell execution conditional on the recommendation.
101
+ * @param {unknown} task
102
+ * @param {{
103
+ * policy?: Record<string, unknown>,
104
+ * availableTools?: Iterable<unknown> | null,
105
+ * seedTools?: unknown[],
106
+ * commandRelevant?: boolean,
107
+ * skillRelevant?: boolean,
108
+ * applicationMatches?: unknown[],
109
+ * browserAvailable?: boolean,
110
+ * }} [options]
111
+ */
112
+ export function buildExecutionRouting(task, options = {}) {
113
+ const text = String(task || "");
114
+ const availableNames = options.availableTools === null || options.availableTools === undefined
115
+ ? new Set(toolNamesForPolicy(options.policy || {}))
116
+ : new Set([...options.availableTools].map((tool) => String(tool || "")).filter(Boolean));
117
+ const toolScores = [...availableNames]
118
+ .map((name) => toolDefinition(name))
119
+ .filter(Boolean)
120
+ .map((tool) => ({
121
+ tool: String(tool.name),
122
+ score: relevanceScore(text, `${tool.title || ""} ${tool.description || ""}`, tool.name),
123
+ }))
124
+ .filter((item) => item.score > 0)
125
+ .sort((left, right) => right.score - left.score || left.tool.localeCompare(right.tool));
126
+ const scoreByTool = new Map(toolScores.map((item) => [item.tool, item.score]));
127
+
128
+ const scoredRoutes = ROUTES
129
+ .map((definition) => scoreRoute(definition, text, availableNames, scoreByTool, options))
130
+ .filter(Boolean)
131
+ .sort((left, right) => right.score - left.score || left.id.localeCompare(right.id));
132
+
133
+ if (!scoredRoutes.length) {
134
+ const fallback = ROUTES.find((item) => item.id === "shell" && item.tools.some((tool) => availableNames.has(tool)))
135
+ || ROUTES.find((item) => item.id === "diagnostics" && item.tools.some((tool) => availableNames.has(tool)));
136
+ if (fallback) scoredRoutes.push(scoreRoute(fallback, text, availableNames, scoreByTool, options, 1));
137
+ }
138
+
139
+ const availableRouteIds = new Set(ROUTES
140
+ .filter((definition) => routeUsable(definition, text, availableNames))
141
+ .map((definition) => definition.id));
142
+ const routes = selectRoutes(scoredRoutes, availableRouteIds);
143
+ const primary = routes[0] || null;
144
+ const second = routes[1] || null;
145
+ const scoreGap = primary && second ? primary.score - second.score : primary ? primary.score : 0;
146
+ const ambiguity = !primary
147
+ ? "none"
148
+ : second && scoreGap <= 2
149
+ ? "high"
150
+ : second && scoreGap <= 5
151
+ ? "medium"
152
+ : "low";
153
+
154
+ const recommendedTools = unique([
155
+ ...routes.slice(0, 3).flatMap((item) => rankedRouteTools(item, scoreByTool, 5)),
156
+ ...(Array.isArray(options.seedTools) ? options.seedTools : []),
157
+ ...toolScores.slice(0, MAX_RANKED_TOOLS).map((item) => item.tool),
158
+ ]).filter((tool) => availableNames.has(tool)).slice(0, MAX_RECOMMENDED_TOOLS);
159
+
160
+ return {
161
+ schema_version: 1,
162
+ strategy: "set-level advisory routing; direct shell is an escape hatch only inside the effective authority",
163
+ score_semantics: "deterministic relative ranking within this response; scores are not probabilities and are not comparable across versions",
164
+ effective_tool_count: availableNames.size,
165
+ policy_effective_tool_count: toolNamesForPolicy(options.policy || {}).length,
166
+ primary_route: primary ? publicRoute(primary, availableRouteIds) : null,
167
+ routes: routes.map((routeValue) => publicRoute(routeValue, availableRouteIds)),
168
+ ranked_tools: toolScores.slice(0, MAX_RANKED_TOOLS),
169
+ ambiguity: {
170
+ level: ambiguity,
171
+ score_gap: scoreGap,
172
+ competing_routes: ambiguity === "none" ? [] : routes.slice(0, ambiguity === "high" ? 3 : 2).map((item) => item.id),
173
+ },
174
+ recommended_tools: recommendedTools,
175
+ recovery_guidance: [
176
+ "Diagnose policy, relay, or runtime failures before changing execution surfaces.",
177
+ "After an ambiguous mutation failure, inspect stable state before retrying; do not assume the side effect did not occur.",
178
+ "A fallback route is an alternative execution surface, not permission to bypass host or effective-authority denial.",
179
+ ],
180
+ enforcement: "advisory_only; the MCP host may choose only tools allowed by the effective authority",
181
+ };
182
+ }
183
+
184
+ function selectRoutes(scoredRoutes, availableRouteIds) {
185
+ const routes = scoredRoutes.slice(0, MAX_ROUTES);
186
+ if (!availableRouteIds.has("shell") || routes.some((routeValue) => routeValue.id === "shell")) return routes;
187
+ const shell = scoredRoutes.find((routeValue) => routeValue.id === "shell");
188
+ if (!shell) return routes;
189
+ if (routes.length < MAX_ROUTES) return [...routes, shell];
190
+ return [...routes.slice(0, MAX_ROUTES - 1), shell];
191
+ }
192
+
193
+ function rankedRouteTools(routeValue, scoreByTool, maximum) {
194
+ return routeValue.tools
195
+ .map((tool, index) => ({ tool, index, score: scoreByTool.get(tool) || 0 }))
196
+ .sort((left, right) => right.score - left.score || left.index - right.index)
197
+ .slice(0, maximum)
198
+ .map((item) => item.tool);
199
+ }
200
+
201
+ function route(id, title, tools, guidance, keywords) {
202
+ return Object.freeze({ id, title, tools: Object.freeze(tools), guidance, keywords: Object.freeze(keywords) });
203
+ }
204
+
205
+ function routeUsable(definition, task, availableNames) {
206
+ if (!definition.tools.some((tool) => availableNames.has(tool))) return false;
207
+ return definition.id !== "managed-job" || !managedJobCreationIntent(task)
208
+ || availableNames.has("start_job") || availableNames.has("stage_job");
209
+ }
210
+
211
+ function scoreRoute(definition, task, availableNames, scoreByTool, options, fallbackScore = 0) {
212
+ if (!routeUsable(definition, task, availableNames)) return null;
213
+ const tools = definition.tools.filter((tool) => availableNames.has(tool));
214
+ let score = relevanceScore(task, `${definition.title} ${definition.guidance} ${definition.keywords.join(" ")}`, definition.id);
215
+ const reasons = [];
216
+ const boost = dynamicBoost(definition.id, task, options);
217
+ score += boost.score;
218
+ reasons.push(...boost.reasons);
219
+ const memberScores = tools.map((tool) => scoreByTool.get(tool) || 0).sort((left, right) => right - left);
220
+ score += Math.min(6, (memberScores[0] || 0) + Math.floor((memberScores[1] || 0) / 2));
221
+ if (definition.id === "shell") {
222
+ score += 2;
223
+ reasons.push("general_escape_hatch_available");
224
+ }
225
+ score = Math.max(score, fallbackScore);
226
+ if (score <= 0) return null;
227
+ return {
228
+ id: definition.id,
229
+ title: definition.title,
230
+ score,
231
+ tools,
232
+ guidance: definition.guidance,
233
+ reasons: unique(reasons),
234
+ };
235
+ }
236
+
237
+ function managedJobCreationIntent(task) {
238
+ return /background|detached|durable|long[- ]?running|overnight|continuous|multi[- ]?step|后台|持久|长时间|持续|多步骤/i.test(String(task || ""));
239
+ }
240
+
241
+ function dynamicBoost(id, task, options) {
242
+ const lower = String(task || "").toLowerCase();
243
+ const reasons = [];
244
+ let score = 0;
245
+ const add = (amount, reason) => { score += amount; reasons.push(reason); };
246
+ if (id === "guided-workflow" && options.skillRelevant === true) add(18, "relevant_skill_found");
247
+ if (id === "registered-command" && options.commandRelevant === true) add(20, "relevant_registered_command_found");
248
+ if (id === "application" && Array.isArray(options.applicationMatches) && options.applicationMatches.length > 0) add(20, "installed_application_match");
249
+ if (id === "computer-use" && /computer use|gui agent|screen grounding|电脑操作|界面操作|视觉定位/.test(lower)) add(18, "computer_use_intent");
250
+ if (id === "browser" && options.browserAvailable === true && /browser|chrome|edge|brave|网页|浏览器|表单|网站|登录/.test(lower)) add(14, "browser_intent");
251
+ if (id === "application-discovery" && Array.isArray(options.applicationMatches) && options.applicationMatches.length > 0) add(8, "installed_application_inventory_match");
252
+ if (id === "managed-job" && /background|detached|durable|long[- ]?running|resume|cleanup|finally|overnight|continuous|后台|持久|断线|清理|长时间|持续|重试|多步骤/.test(lower)) add(14, "durability_or_cleanup_intent");
253
+ if (id === "process-session" && /interactive|stdin|repl|watch|tail|stream|dev server|交互|实时日志|输入|常驻进程/.test(lower)) add(12, "interactive_process_intent");
254
+ if (id === "shell" && /bash|shell|terminal|cli|command|script|debug|diagnos|benchmark|audit|probe|命令|终端|脚本|排查|调试|基准|审查|测试|构建/.test(lower)) add(10, "shell_or_cli_intent");
255
+ if (id === "workspace-edit" && /file|source|code|edit|write|patch|refactor|repository|文件|源码|代码|修改|写入|补丁|重构|仓库/.test(lower)) add(10, "workspace_change_intent");
256
+ if (id === "git-review" && /git|commit|diff|branch|history|revision|提交|分支|差异|历史|版本/.test(lower)) add(12, "git_intent");
257
+ if (id === "protected-resource" && /credential|secret|token|private key|ssh key|password|凭据|密钥|令牌|密码/.test(lower)) add(14, "protected_data_intent");
258
+ if (id === "diagnostics" && /status|health|diagnos|runtime|relay|policy|authorization|状态|健康|诊断|运行时|权限|连接/.test(lower)) add(10, "runtime_diagnostic_intent");
259
+ return { score, reasons };
260
+ }
261
+
262
+ function publicRoute(routeValue, availableRouteIds) {
263
+ return {
264
+ id: routeValue.id,
265
+ title: routeValue.title,
266
+ score: routeValue.score,
267
+ tools: [...routeValue.tools],
268
+ guidance: routeValue.guidance,
269
+ reasons: [...routeValue.reasons],
270
+ fallback_routes: (ROUTE_FALLBACKS[routeValue.id] || []).filter((id) => availableRouteIds.has(id)),
271
+ };
272
+ }
273
+
274
+ function unique(values) {
275
+ return [...new Set(values.map((value) => String(value || "")).filter(Boolean))];
276
+ }
@@ -0,0 +1,23 @@
1
+ export const EXECUTION_SURFACE_ENV = "MBM_EXECUTION_SURFACE";
2
+
3
+ export const EXECUTION_SURFACE = Object.freeze({
4
+ foregroundProcess: "foreground_process",
5
+ processSession: "process_session",
6
+ managedJob: "managed_job",
7
+ });
8
+
9
+ const KNOWN_SURFACES = new Set(Object.values(EXECUTION_SURFACE));
10
+
11
+ export function withExecutionSurface(environment, surface) {
12
+ if (!environment || typeof environment !== "object" || Array.isArray(environment)) {
13
+ throw new TypeError("execution surface requires an environment record");
14
+ }
15
+ if (!KNOWN_SURFACES.has(surface)) throw new TypeError("execution surface is invalid");
16
+ return { ...environment, [EXECUTION_SURFACE_ENV]: surface };
17
+ }
18
+
19
+ export function executionSurface(environment = process.env) {
20
+ const value = String(environment?.[EXECUTION_SURFACE_ENV] || "");
21
+ if (!value) return "";
22
+ return KNOWN_SURFACES.has(value) ? value : "unknown";
23
+ }
@@ -0,0 +1,47 @@
1
+ // @ts-check
2
+
3
+ import { isAbsolute, resolve } from "node:path";
4
+
5
+ /**
6
+ * Process-local coordinator for filesystem mutations that already resolved their target paths.
7
+ * Reservations are registered for every path before waiting, so overlapping multi-path mutations
8
+ * cannot deadlock while unrelated paths remain concurrent.
9
+ */
10
+ export class FileMutationCoordinator {
11
+ constructor() {
12
+ /** @type {Map<string, Promise<void>>} */
13
+ this.queues = new Map();
14
+ }
15
+
16
+ /** @template T @param {string[]} paths @param {() => Promise<T>} callback @returns {Promise<T>} */
17
+ async withPaths(paths, callback) {
18
+ if (!Array.isArray(paths) || paths.length === 0) throw new TypeError("file mutation requires at least one resolved path");
19
+ if (typeof callback !== "function") throw new TypeError("file mutation callback is required");
20
+ const keys = [...new Set(paths.map((value) => fileMutationPathKey(value)))].sort();
21
+ const reservations = keys.map((key) => {
22
+ const current = this.queues.get(key) ?? Promise.resolve();
23
+ const { promise: gate, resolve: release } = Promise.withResolvers();
24
+ const tail = current.then(() => gate);
25
+ this.queues.set(key, tail);
26
+ return { key, current, tail, release };
27
+ });
28
+
29
+ await Promise.all(reservations.map((reservation) => reservation.current));
30
+ try {
31
+ return await callback();
32
+ } finally {
33
+ for (const reservation of reservations) reservation.release();
34
+ for (const reservation of reservations) {
35
+ if (this.queues.get(reservation.key) === reservation.tail) this.queues.delete(reservation.key);
36
+ }
37
+ }
38
+ }
39
+ }
40
+
41
+ /** @param {unknown} value @param {string} [platform] */
42
+ export function fileMutationPathKey(value, platform = process.platform) {
43
+ const raw = String(value || "");
44
+ if (!raw || raw.includes("\0") || !isAbsolute(raw)) throw new TypeError("file mutation paths must be absolute and NUL-free");
45
+ const absolute = resolve(raw);
46
+ return platform === "win32" || platform === "darwin" ? absolute.toLowerCase() : absolute;
47
+ }
@@ -0,0 +1,24 @@
1
+ import { unlinkSync } from "node:fs";
2
+ import { createExclusiveFileSync } from "./exclusive-file.mjs";
3
+ import { unlinkRegularFileIfIdentitySync } from "./secure-file.mjs";
4
+
5
+ export function preserveFileSnapshotSync(source, target, content, expectedIdentity, options = {}) {
6
+ const label = String(options.label || "file snapshot source");
7
+ const create = options.create || createExclusiveFileSync;
8
+ const unlinkSource = options.unlinkSource || unlinkRegularFileIfIdentitySync;
9
+ const unlinkBackup = options.unlinkBackup || unlinkSync;
10
+ const created = create(target, content, { mode: Number.isInteger(options.mode) ? options.mode : 0o600 });
11
+ let primaryError = null;
12
+ try {
13
+ if (!unlinkSource(source, expectedIdentity, label)) {
14
+ primaryError = new Error(`${label} changed before snapshot preservation completed`);
15
+ }
16
+ } catch (error) { primaryError = error; }
17
+ if (!primaryError) return created;
18
+ try { unlinkBackup(target); } catch (cleanupError) {
19
+ if (cleanupError?.code !== "ENOENT") {
20
+ throw new AggregateError([primaryError, cleanupError], `${label} changed and snapshot cleanup was incomplete`);
21
+ }
22
+ }
23
+ throw primaryError;
24
+ }