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.
- package/CHANGELOG.md +1142 -0
- package/CONTRIBUTING.md +23 -25
- package/GOVERNANCE.md +2 -2
- package/README.md +58 -20
- package/SECURITY.md +161 -120
- package/SUPPORT.md +1 -1
- package/browser-extension/broker-auth.js +83 -0
- package/browser-extension/broker-liveness.js +35 -0
- package/browser-extension/browser-error-boundary.js +96 -0
- package/browser-extension/browser-operations.js +1456 -101
- package/browser-extension/devtools-input.js +195 -34
- package/browser-extension/devtools-observation.js +429 -0
- package/browser-extension/devtools-session.js +48 -0
- package/browser-extension/manifest.json +4 -3
- package/browser-extension/page-automation.js +578 -118
- package/browser-extension/pairing-bootstrap.js +42 -0
- package/browser-extension/pairing.js +28 -12
- package/browser-extension/service-worker.js +126 -106
- package/docs/AGENT_CONTEXT.md +13 -10
- package/docs/ARCHITECTURE.md +159 -67
- package/docs/AUDIT.md +1302 -4
- package/docs/CLIENTS.md +19 -6
- package/docs/COMPUTER_USE.md +297 -0
- package/docs/ENGINEERING.md +72 -13
- package/docs/GETTING_STARTED.md +18 -20
- package/docs/LOCAL_AUTHORIZATION.md +115 -72
- package/docs/LOCAL_AUTOMATION.md +27 -21
- package/docs/LOGGING.md +40 -19
- package/docs/MANAGED_JOBS.md +37 -34
- package/docs/MULTI_ACCOUNT.md +98 -37
- package/docs/OPERATIONS.md +145 -51
- package/docs/OVERVIEW.md +14 -11
- package/docs/POLICY_REFERENCE.md +71 -3
- package/docs/PRIVACY.md +41 -2
- package/docs/PROJECT_STANDARDS.md +29 -6
- package/docs/RELEASING.md +238 -64
- package/docs/TESTING.md +150 -39
- package/docs/THREAT_MODEL.md +164 -67
- package/docs/TOOL_REFERENCE.md +653 -60
- package/docs/UPGRADING.md +78 -18
- package/native/macos/MachineBridgeBackgroundInput.swift +1051 -0
- package/native/macos/MachineBridgeBackgroundInputSmokeFixture.swift +295 -0
- package/native/macos/MachineBridgeTrustBroker.swift +233 -0
- package/package.json +94 -16
- package/scripts/accepted-candidate-tarball.mjs +77 -0
- package/scripts/candidate-runtime-store.mjs +93 -0
- package/scripts/check-plan.mjs +73 -3
- package/scripts/check-runner.mjs +129 -17
- package/scripts/commit-message-check.mjs +5 -2
- package/scripts/consumer-package-security.mjs +293 -0
- package/scripts/coverage-check.mjs +251 -15
- package/scripts/coverage-generation.mjs +41 -0
- package/scripts/coverage-range-merge.mjs +41 -0
- package/scripts/foreground-daemon-recovery.mjs +88 -0
- package/scripts/generate-policy-reference.mjs +28 -5
- package/scripts/generate-tool-reference.mjs +1 -1
- package/scripts/generate-worker-types.mjs +21 -11
- package/scripts/github-backlog.mjs +11 -10
- package/scripts/github-push.mjs +62 -16
- package/scripts/github-release-asset.mjs +58 -0
- package/scripts/github-release.mjs +241 -132
- package/scripts/global-package-installation.mjs +68 -0
- package/scripts/hardened-npm-session.mjs +42 -0
- package/scripts/install-published-prerelease.mjs +198 -0
- package/scripts/local-release-acceptance.mjs +103 -45
- package/scripts/macos-background-input-smoke.mjs +515 -0
- package/scripts/network-retry.mjs +8 -1
- package/scripts/npm-global-prefix.mjs +27 -0
- package/scripts/npm-publication-policy.mjs +17 -0
- package/scripts/official-mcp-conformance.mjs +267 -0
- package/scripts/persistent-activation-process.mjs +101 -0
- package/scripts/prepare-pinned-npm.mjs +12 -69
- package/scripts/prerelease-activation.mjs +160 -0
- package/scripts/privacy-check.mjs +14 -6
- package/scripts/promotion-digest.mjs +128 -0
- package/scripts/publish-npm.mjs +260 -0
- package/scripts/published-release.mjs +132 -0
- package/scripts/release-acceptance.mjs +62 -54
- package/scripts/release-browser-extension-store.mjs +172 -0
- package/scripts/release-candidate-manifest.mjs +52 -0
- package/scripts/release-channel.mjs +106 -0
- package/scripts/release-diagnostic.mjs +41 -0
- package/scripts/release-impact-check.mjs +12 -22
- package/scripts/release-oauth-canary-core.mjs +325 -0
- package/scripts/release-oauth-canary-evidence.mjs +100 -0
- package/scripts/release-oauth-canary.mjs +127 -0
- package/scripts/release-publication-guard.mjs +67 -0
- package/scripts/release-soak.mjs +284 -0
- package/scripts/release-state.mjs +1 -1
- package/scripts/run-checks.mjs +44 -7
- package/scripts/run-worker-dry-run.mjs +21 -0
- package/scripts/sarif-security-gate.mjs +2 -1
- package/scripts/sbom-check.mjs +106 -0
- package/scripts/start-release-candidate.mjs +267 -44
- package/scripts/syntax-check.mjs +36 -14
- package/scripts/verification-generation-guard.mjs +15 -0
- package/scripts/verification-idle-sleep-guard.mjs +37 -0
- package/scripts/verification-state.mjs +108 -0
- package/scripts/wrangler-command-lifecycle.mjs +115 -0
- package/src/local/account-access.mjs +13 -1
- package/src/local/account-admin-response.mjs +92 -0
- package/src/local/account-admin.mjs +52 -19
- package/src/local/agent-context-projection.mjs +26 -7
- package/src/local/agent-context.mjs +88 -49
- package/src/local/agent-skill-discovery.mjs +16 -5
- package/src/local/app-automation-macos-jxa.mjs +350 -0
- package/src/local/app-automation.mjs +873 -163
- package/src/local/application-capability-projection.mjs +24 -0
- package/src/local/authority-context.mjs +106 -0
- package/src/local/autostart-log-maintenance.mjs +36 -0
- package/src/local/browser-bridge-http.mjs +5 -3
- package/src/local/browser-bridge.mjs +109 -31
- package/src/local/browser-broker-auth-http.mjs +67 -0
- package/src/local/browser-broker-auth.mjs +98 -0
- package/src/local/browser-broker-routes.mjs +63 -20
- package/src/local/browser-broker-server.mjs +17 -7
- package/src/local/browser-command.mjs +79 -30
- package/src/local/browser-computer-observation-service.mjs +266 -0
- package/src/local/browser-extension-identity.mjs +50 -0
- package/src/local/browser-extension-path.mjs +22 -0
- package/src/local/browser-extension-protocol.mjs +50 -11
- package/src/local/browser-operation-service.mjs +147 -117
- package/src/local/browser-pairing-grant.mjs +109 -0
- package/src/local/browser-pairing-http.mjs +36 -0
- package/src/local/browser-pairing-launch.mjs +58 -0
- package/src/local/browser-pairing-store.mjs +85 -48
- package/src/local/browser-request-registry.mjs +40 -14
- package/src/local/browser-request-settlement.mjs +78 -0
- package/src/local/browser-resource-input.mjs +74 -0
- package/src/local/browser-trusted-input-health.mjs +63 -0
- package/src/local/call-authority.mjs +21 -0
- package/src/local/call-capacity.mjs +45 -0
- package/src/local/call-registry-drain.mjs +54 -0
- package/src/local/call-registry.mjs +30 -15
- package/src/local/capability-observer.mjs +5 -0
- package/src/local/capability-ranking.mjs +3 -2
- package/src/local/child-process-settlement.mjs +132 -0
- package/src/local/cli-account-admin.mjs +40 -6
- package/src/local/cli-activate.mjs +162 -0
- package/src/local/cli-local-admin.mjs +20 -45
- package/src/local/cli-options.mjs +12 -13
- package/src/local/cli-ready-output.mjs +52 -0
- package/src/local/cli-service.mjs +91 -11
- package/src/local/cli.mjs +232 -150
- package/src/local/computer-use-application-observation.mjs +224 -0
- package/src/local/computer-use-arguments.mjs +270 -0
- package/src/local/computer-use-deadline.mjs +50 -0
- package/src/local/computer-use-dispatch-settlement.mjs +40 -0
- package/src/local/computer-use-expectation.mjs +171 -0
- package/src/local/computer-use-observation.mjs +769 -0
- package/src/local/computer-use-recovery.mjs +82 -0
- package/src/local/computer-use-result-budget.mjs +145 -0
- package/src/local/computer-use-snapshot-store.mjs +67 -0
- package/src/local/computer-use.mjs +2255 -0
- package/src/local/daemon-http-relay-auth.mjs +26 -0
- package/src/local/daemon-http-relay-connection.mjs +298 -0
- package/src/local/daemon-http-relay-request.mjs +64 -0
- package/src/local/daemon-http-relay-sequence.mjs +49 -0
- package/src/local/daemon-process.mjs +40 -7
- package/src/local/delegated-process-sandbox.mjs +148 -0
- package/src/local/device-identity.mjs +156 -49
- package/src/local/device-root-provider.mjs +81 -0
- package/src/local/directory-metadata.mjs +47 -0
- package/src/local/doctor-reporting.mjs +23 -0
- package/src/local/durable-process-spec.mjs +80 -0
- package/src/local/errors.mjs +25 -15
- package/src/local/exclusive-file.mjs +74 -26
- package/src/local/execution-limits.mjs +9 -0
- package/src/local/execution-routing.mjs +276 -0
- package/src/local/execution-surface.mjs +23 -0
- package/src/local/file-mutation-coordinator.mjs +47 -0
- package/src/local/file-snapshot-preservation.mjs +24 -0
- package/src/local/filesystem-identity.mjs +54 -0
- package/src/local/fixed-process-environment.mjs +21 -0
- package/src/local/full-access-test.mjs +31 -13
- package/src/local/git-commit.mjs +69 -0
- package/src/local/git-config-safety.mjs +55 -0
- package/src/local/git-log-parser.mjs +41 -0
- package/src/local/git-metadata-boundary.mjs +77 -0
- package/src/local/git-metadata-tree-safety.mjs +59 -0
- package/src/local/git-operation-state.mjs +19 -0
- package/src/local/git-service.mjs +165 -30
- package/src/local/hardened-npm-download-timeout.mjs +46 -0
- package/src/local/hardened-npm-download.mjs +109 -0
- package/src/local/hardened-npm-extract.mjs +20 -0
- package/src/local/hardened-npm-verification.mjs +104 -0
- package/src/local/hardened-npm.mjs +199 -0
- package/src/local/job-runner.mjs +244 -89
- package/src/local/lifecycle.mjs +6 -0
- package/src/local/log.mjs +19 -45
- package/src/local/macos-background-input.mjs +398 -0
- package/src/local/macos-idle-sleep-assertion.mjs +65 -0
- package/src/local/macos-trust-broker.mjs +404 -0
- package/src/local/managed-job-cancellation.mjs +42 -0
- package/src/local/managed-job-capacity.mjs +16 -0
- package/src/local/managed-job-directory-generation.mjs +60 -0
- package/src/local/managed-job-directory.mjs +75 -0
- package/src/local/managed-job-durable-process.mjs +49 -0
- package/src/local/managed-job-lock.mjs +46 -14
- package/src/local/managed-job-plan.mjs +38 -14
- package/src/local/managed-job-projection.mjs +23 -15
- package/src/local/managed-job-retention.mjs +128 -0
- package/src/local/managed-job-runner-claim.mjs +70 -0
- package/src/local/managed-job-runner.mjs +35 -10
- package/src/local/managed-job-storage.mjs +22 -6
- package/src/local/managed-job-terminal-maintenance.mjs +40 -0
- package/src/local/managed-job-terminal.mjs +150 -0
- package/src/local/managed-jobs.mjs +424 -287
- package/src/local/npm-cli.mjs +42 -0
- package/src/local/npm-environment.mjs +37 -0
- package/src/local/operation-authorization.mjs +68 -324
- package/src/local/operation-risk.mjs +51 -4
- package/src/local/owner-state-lock.mjs +118 -0
- package/src/local/package-identity.mjs +9 -0
- package/src/local/patch.mjs +20 -18
- package/src/local/path-inspection.mjs +23 -0
- package/src/local/policy.mjs +19 -0
- package/src/local/private-toolchain-integrity.mjs +54 -0
- package/src/local/process-execution.mjs +87 -75
- package/src/local/process-foreground-timeout.mjs +50 -0
- package/src/local/process-identity.mjs +41 -7
- package/src/local/process-nonreplayable-settlement.mjs +50 -0
- package/src/local/process-result-projection.mjs +22 -0
- package/src/local/process-session-events.mjs +47 -0
- package/src/local/process-session-remote-activity.mjs +10 -0
- package/src/local/process-session-termination.mjs +73 -0
- package/src/local/process-sessions.mjs +144 -112
- package/src/local/process-tracker.mjs +140 -13
- package/src/local/process-tree-ownership-types.d.ts +37 -0
- package/src/local/process-tree-ownership.mjs +57 -0
- package/src/local/process-tree-signal.mjs +34 -0
- package/src/local/process-tree-snapshot.mjs +77 -0
- package/src/local/process-tree-supervisor.mjs +69 -0
- package/src/local/process-tree.mjs +11 -53
- package/src/local/project-metadata.mjs +19 -6
- package/src/local/relay-call-recovery.mjs +58 -38
- package/src/local/relay-connection-classification.mjs +131 -0
- package/src/local/relay-connection-support.mjs +91 -0
- package/src/local/relay-connection.mjs +179 -272
- package/src/local/relay-diagnostics.mjs +91 -0
- package/src/local/relay-heartbeat.mjs +119 -0
- package/src/local/relay-liveness.mjs +109 -0
- package/src/local/relay-peer-diagnostics.mjs +29 -0
- package/src/local/release-runtime-lock.mjs +18 -0
- package/src/local/remote-activity-idle-sleep-guard.mjs +77 -0
- package/src/local/remote-configuration.mjs +48 -0
- package/src/local/resilient-relay-connection.mjs +178 -0
- package/src/local/resource-admission-diagnostics.mjs +52 -0
- package/src/local/resource-admission-policy.mjs +115 -0
- package/src/local/resource-admission.mjs +339 -0
- package/src/local/resource-build-root.mjs +83 -0
- package/src/local/resource-cargo-concurrency.mjs +38 -0
- package/src/local/resource-cmake-concurrency.mjs +42 -0
- package/src/local/resource-command-concurrency.mjs +37 -0
- package/src/local/resource-command-profile.mjs +176 -0
- package/src/local/resource-coordinator-accounting.mjs +21 -0
- package/src/local/resource-cpu-window.mjs +20 -0
- package/src/local/resource-disk-headroom.mjs +13 -0
- package/src/local/resource-elastic-memory.mjs +19 -0
- package/src/local/resource-elastic-request.mjs +36 -0
- package/src/local/resource-foreground-wait.mjs +29 -0
- package/src/local/resource-go-concurrency.mjs +43 -0
- package/src/local/resource-gradle-concurrency.mjs +57 -0
- package/src/local/resource-host-cache.mjs +39 -0
- package/src/local/resource-host-darwin.mjs +54 -0
- package/src/local/resource-host-linux.mjs +35 -0
- package/src/local/resource-host-sample-file.mjs +23 -0
- package/src/local/resource-host-snapshot.mjs +99 -0
- package/src/local/resource-lease-accounting.mjs +119 -0
- package/src/local/resource-light-command.mjs +6 -0
- package/src/local/resource-make-concurrency.mjs +42 -0
- package/src/local/resource-maven-concurrency.mjs +38 -0
- package/src/local/resource-ninja-command-concurrency.mjs +20 -0
- package/src/local/resource-ninja-concurrency.mjs +28 -0
- package/src/local/resource-operations.mjs +26 -10
- package/src/local/resource-pressure.mjs +67 -0
- package/src/local/resource-probe-command.mjs +35 -0
- package/src/local/resource-process-admission.mjs +59 -0
- package/src/local/resource-process-ancestry-cache.mjs +43 -0
- package/src/local/resource-process-ancestry.mjs +32 -0
- package/src/local/resource-process-priority.mjs +15 -0
- package/src/local/resource-project-key.mjs +53 -0
- package/src/local/resource-pytest-concurrency.mjs +33 -0
- package/src/local/resource-release-control-classification.mjs +14 -0
- package/src/local/resource-release-control-executable.mjs +70 -0
- package/src/local/resource-release-control-workspace.mjs +41 -0
- package/src/local/resource-request-contract.mjs +30 -0
- package/src/local/resource-script-classification.mjs +44 -0
- package/src/local/resource-shell-analysis.mjs +58 -0
- package/src/local/resource-staging-recovery.mjs +97 -0
- package/src/local/resource-swift-concurrency.mjs +31 -0
- package/src/local/resource-transaction-lock.mjs +189 -0
- package/src/local/resource-wait.mjs +48 -0
- package/src/local/resource-waiters.mjs +139 -0
- package/src/local/resource-xcode-command.mjs +7 -0
- package/src/local/resource-xcode-concurrency.mjs +34 -0
- package/src/local/resource-xcode-non-build.mjs +19 -0
- package/src/local/runtime-activation.mjs +700 -0
- package/src/local/runtime-activity-projection.mjs +48 -0
- package/src/local/runtime-capabilities.mjs +48 -15
- package/src/local/runtime-diagnostic-state.mjs +14 -0
- package/src/local/runtime-diagnostics.mjs +40 -13
- package/src/local/runtime-info-projection.mjs +60 -0
- package/src/local/runtime-info-relay-projection.mjs +21 -0
- package/src/local/runtime-paths.mjs +2 -1
- package/src/local/runtime-process-routing.mjs +33 -0
- package/src/local/runtime-relay-connection-options.mjs +44 -0
- package/src/local/runtime-relay-control.mjs +98 -0
- package/src/local/runtime-relay.mjs +26 -50
- package/src/local/runtime-reporting.mjs +37 -21
- package/src/local/runtime-resource-service.mjs +77 -0
- package/src/local/runtime-tool-handlers.mjs +13 -10
- package/src/local/runtime.mjs +244 -208
- package/src/local/secure-file.mjs +73 -20
- package/src/local/security-audit-dispatch.mjs +35 -0
- package/src/local/security-audit-log.mjs +215 -0
- package/src/local/security-audit-state.mjs +139 -0
- package/src/local/security-audit-storage.mjs +135 -0
- package/src/local/security-audit-warning.mjs +31 -0
- package/src/local/security-audit-worker.mjs +87 -0
- package/src/local/service-convergence.mjs +42 -1
- package/src/local/service-definition.mjs +24 -0
- package/src/local/service-environment.mjs +18 -10
- package/src/local/service-owner.mjs +146 -0
- package/src/local/service-ownership.mjs +17 -0
- package/src/local/service-restart-handoff.mjs +64 -0
- package/src/local/service-restart-scheduler.mjs +49 -0
- package/src/local/service-runtime-convergence.mjs +52 -0
- package/src/local/service-runtime.mjs +105 -0
- package/src/local/service-status.mjs +60 -0
- package/src/local/service.mjs +385 -92
- package/src/local/shell.mjs +39 -19
- package/src/local/ssh-key.mjs +158 -42
- package/src/local/state-inventory.mjs +50 -24
- package/src/local/state-owner-lock-inventory.mjs +23 -0
- package/src/local/state-root-owned-namespaces.mjs +83 -0
- package/src/local/state-root-retirement.mjs +89 -0
- package/src/local/state.mjs +386 -96
- package/src/local/stdio.mjs +96 -66
- package/src/local/support-state-projection.mjs +30 -0
- package/src/local/system-network-route.mjs +76 -0
- package/src/local/systemd-removal.mjs +20 -0
- package/src/local/tool-executor.mjs +85 -20
- package/src/local/tool-result-boundary.mjs +51 -0
- package/src/local/toolchain-operation-lock.mjs +41 -0
- package/src/local/tools.mjs +7 -5
- package/src/local/trusted-executable.mjs +53 -0
- package/src/local/trusted-git-executable.mjs +34 -0
- package/src/local/trusted-github-cli.mjs +24 -0
- package/src/local/windows-service-convergence.mjs +49 -0
- package/src/local/windows-service.mjs +52 -45
- package/src/local/worker-deployment-fingerprint.mjs +102 -0
- package/src/local/worker-deployment.mjs +48 -60
- package/src/local/worker-health.mjs +12 -4
- package/src/local/worker-secret-file.mjs +37 -17
- package/src/local/workspace-file-service.mjs +156 -239
- package/src/local/workspace-file-transaction.mjs +189 -0
- package/src/local/workspace-search.mjs +55 -0
- package/src/local/wrangler-toolchain/package-lock.json +1505 -0
- package/src/local/wrangler-toolchain/package.json +23 -0
- package/src/local/wrangler-toolchain-verification.mjs +135 -0
- package/src/local/wrangler-toolchain.mjs +188 -0
- package/src/shared/access-contract.json +7 -1
- package/src/shared/activation-recovery.mjs +49 -0
- package/src/shared/admin-auth.d.mts +2 -1
- package/src/shared/admin-auth.mjs +3 -3
- package/src/shared/authority-revocation.d.mts +9 -0
- package/src/shared/authority-revocation.mjs +28 -0
- package/src/shared/daemon-auth.d.mts +11 -0
- package/src/shared/daemon-auth.mjs +17 -0
- package/src/shared/device-session-auth.d.mts +20 -0
- package/src/shared/device-session-auth.mjs +51 -0
- package/src/shared/foreground-timeout.d.mts +15 -0
- package/src/shared/foreground-timeout.mjs +70 -0
- package/src/shared/log-redaction.d.mts +9 -0
- package/src/shared/log-redaction.mjs +51 -0
- package/src/shared/mcp-protocol.d.mts +27 -0
- package/src/shared/mcp-protocol.mjs +275 -0
- package/src/shared/project-overview-projection.d.mts +4 -0
- package/src/shared/project-overview-projection.mjs +96 -0
- package/src/shared/relay-contract.json +28 -0
- package/src/shared/result-projection.d.mts +2 -1
- package/src/shared/result-projection.mjs +13 -2
- package/src/shared/server-metadata.json +15 -9
- package/src/shared/tool-argument-validation.d.mts +17 -0
- package/src/shared/tool-argument-validation.mjs +325 -0
- package/src/shared/tool-call-capacity.d.mts +41 -0
- package/src/shared/tool-call-capacity.mjs +59 -0
- package/src/shared/tool-catalog.json +626 -57
- package/src/worker/access.ts +12 -0
- package/src/worker/account-admin.ts +55 -33
- package/src/worker/authority-revocations.ts +174 -0
- package/src/worker/authority.ts +52 -6
- package/src/worker/daemon-auth.ts +49 -68
- package/src/worker/daemon-channel.ts +36 -0
- package/src/worker/daemon-http-auth.ts +63 -0
- package/src/worker/daemon-http-channel.ts +120 -0
- package/src/worker/daemon-http-controller.ts +163 -0
- package/src/worker/daemon-http-protocol.ts +62 -0
- package/src/worker/daemon-http-registry.ts +82 -0
- package/src/worker/daemon-last-observation.ts +30 -0
- package/src/worker/daemon-liveness.ts +8 -6
- package/src/worker/daemon-ready-dispatch.ts +17 -0
- package/src/worker/daemon-ready-messages.ts +73 -0
- package/src/worker/daemon-ready-waiters.ts +79 -0
- package/src/worker/daemon-recovery-budget.ts +13 -0
- package/src/worker/daemon-registry.ts +58 -0
- package/src/worker/daemon-relay-diagnostics.ts +127 -0
- package/src/worker/daemon-socket-attachment.ts +55 -0
- package/src/worker/daemon-sockets.ts +72 -62
- package/src/worker/daemon-status.ts +38 -0
- package/src/worker/device-session-verifier.ts +129 -0
- package/src/worker/dpop.ts +157 -0
- package/src/worker/durable-process-timeout.ts +29 -0
- package/src/worker/errors.ts +57 -0
- package/src/worker/http.ts +112 -26
- package/src/worker/index.ts +446 -440
- package/src/worker/mcp-access.ts +57 -0
- package/src/worker/mcp-controller.ts +188 -0
- package/src/worker/mcp-http-accept.ts +11 -0
- package/src/worker/mcp-http-contract.ts +322 -0
- package/src/worker/mcp-initialization-compat.ts +141 -0
- package/src/worker/mcp-jsonrpc.ts +11 -29
- package/src/worker/mcp-removed-protocol.ts +17 -0
- package/src/worker/mcp-response-proxy.ts +135 -0
- package/src/worker/mcp-response-stream.ts +65 -0
- package/src/worker/mcp-stale-schema-compat.ts +57 -0
- package/src/worker/mcp-stream-proxy-contract.ts +48 -0
- package/src/worker/mcp-tool-call-input.ts +23 -0
- package/src/worker/nonce-store.ts +33 -35
- package/src/worker/oauth-authorization-page.ts +21 -1
- package/src/worker/oauth-client-admin.ts +52 -0
- package/src/worker/oauth-client-contract.ts +38 -0
- package/src/worker/oauth-controller.ts +107 -47
- package/src/worker/oauth-field-contract.ts +31 -0
- package/src/worker/oauth-record-contract.ts +7 -0
- package/src/worker/oauth-refresh-authority.ts +27 -0
- package/src/worker/oauth-refresh-exchange.ts +162 -0
- package/src/worker/oauth-refresh-families.ts +130 -27
- package/src/worker/oauth-refresh-persistence.ts +116 -0
- package/src/worker/oauth-state.ts +33 -18
- package/src/worker/oauth-store-validation.ts +131 -0
- package/src/worker/oauth-token-derivation.ts +33 -0
- package/src/worker/oauth-token-issuance.ts +119 -0
- package/src/worker/oauth-tokens.ts +56 -190
- package/src/worker/observability.ts +38 -5
- package/src/worker/pending-admission.ts +15 -0
- package/src/worker/pending-call-capacity.ts +108 -0
- package/src/worker/pending-call-contract.ts +42 -5
- package/src/worker/pending-call-deadlines.ts +75 -0
- package/src/worker/pending-calls.ts +131 -125
- package/src/worker/runtime-alarm-storage.ts +37 -0
- package/src/worker/runtime-alarm.ts +136 -0
- package/src/worker/server-info-activity.ts +36 -0
- package/src/worker/server-info-tool-delivery.ts +15 -0
- package/src/worker/server-info.ts +168 -0
- package/src/worker/tool-catalog.ts +47 -1
- package/src/worker/tool-timeout.ts +75 -14
- package/src/worker/websocket-protocol.ts +26 -2
- package/src/worker/worker-edge-guard.ts +90 -0
- package/src/worker/worker-edge-log.ts +65 -0
- package/src/worker/worker-entry.ts +52 -0
- package/src/worker/worker-mcp-config.ts +23 -0
- package/src/worker/worker-metadata.ts +48 -0
- package/src/worker/worker-rate-limit-key.ts +30 -0
- package/src/worker/worker-runtime-config.ts +20 -0
- package/src/worker/worker-static-routes.ts +54 -0
- package/src/worker/worker-task-lifetime.ts +18 -0
- package/tsconfig.local.json +17 -1
- package/wrangler.jsonc +13 -0
- package/src/local/cli-approval.mjs +0 -117
- package/src/local/operation-state-lock.mjs +0 -92
- package/src/worker/mcp-session.ts +0 -72
package/docs/RELEASING.md
CHANGED
|
@@ -1,124 +1,298 @@
|
|
|
1
1
|
# Release process
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Machine Bridge uses a mandatory prerelease-and-soak process. A release candidate is not a stable release, and a green automated suite is not evidence that a real Worker, daemon, browser extension, service manager, and ordinary client remain healthy over time.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
- the current package produces the same SHA-1 and SHA-512 integrity values as that accepted tarball;
|
|
7
|
-
- `main` points to the release commit, and that exact commit has completed successful push-triggered CI, CodeQL, Governance, and OpenSSF Scorecard runs;
|
|
8
|
-
- `v<package version>` points to that same commit locally and on GitHub;
|
|
9
|
-
- a final GitHub Release exists for the tag and contains the accepted npm tarball;
|
|
10
|
-
- `package.json`, `package-lock.json`, the Worker-reported version, and `browser-extension/manifest.json` (`version`/`version_name`) agree;
|
|
11
|
-
- every npm-package change since the prior version tag has a higher package version and matching CHANGELOG section;
|
|
12
|
-
- the same accepted package content is present on GitHub and in a new npm version.
|
|
5
|
+
The invariant for version 3 and later is:
|
|
13
6
|
|
|
14
|
-
|
|
7
|
+
1. every package change is first assigned a `dev`, `beta`, or `rc` semantic version;
|
|
8
|
+
2. the exact npm tarball is activated on the owner machine with one command that updates the same-name Worker and persistently replaces the login daemon;
|
|
9
|
+
3. the coding agent verifies the connected candidate through Machine Bridge before recording package acceptance;
|
|
10
|
+
4. the accepted prerelease is published under a non-`latest` npm dist-tag and as a GitHub Prerelease;
|
|
11
|
+
5. the owner installs that exact published prerelease and uses it for the required soak period;
|
|
12
|
+
6. every blocking defect produces a new prerelease version and restarts the soak clock;
|
|
13
|
+
7. stable promotion is allowed only when the packaged functional content matches the soaked prerelease; only synchronized version metadata may differ;
|
|
14
|
+
8. the exact stable commit must pass cross-platform CI, CodeQL, Governance, Workflow Policy Gate, and OpenSSF Scorecard before the stable tag and final GitHub Release are created.
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## Release channels
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
Supported versions and registry channels are:
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
| Version form | npm dist-tag | GitHub release type | Purpose |
|
|
21
|
+
|---|---|---|---|
|
|
22
|
+
| `x.y.z-dev.n` | `dev` | Prerelease | short-lived development integration |
|
|
23
|
+
| `x.y.z-beta.n` | `beta` | Prerelease | normal real-world testing channel |
|
|
24
|
+
| `x.y.z-rc.n` | `next` | Prerelease | optional final candidate after beta |
|
|
25
|
+
| `x.y.z` | `latest` | final release | stable users only |
|
|
21
26
|
|
|
22
|
-
|
|
27
|
+
Do not assign the final `x.y.z` version while implementation is still under candidate testing. A major or behaviorally risky change normally starts at `beta.1`. A release candidate may use `rc.n` after beta when a final freeze checkpoint is useful.
|
|
23
28
|
|
|
24
|
-
|
|
29
|
+
Minimum published-prerelease soak periods are:
|
|
25
30
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
31
|
+
- major release: seven days;
|
|
32
|
+
- minor release: three days;
|
|
33
|
+
- patch release: one day.
|
|
29
34
|
|
|
30
|
-
|
|
31
|
-
3. Run the required dependency, privacy, Worker, and package checks while iterating.
|
|
32
|
-
4. Inspect the complete diff.
|
|
33
|
-
5. Generate the final candidate:
|
|
35
|
+
These are lower bounds, not automatic approval. Continue the soak when use has been too light to exercise the changed behavior.
|
|
34
36
|
|
|
35
|
-
|
|
36
|
-
npm run release:candidate
|
|
37
|
-
```
|
|
37
|
+
## 1. Prepare an exact prerelease candidate
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
Complete implementation, tests, documentation, audit notes, and changelog. Set the prerelease version without creating a Git tag:
|
|
40
40
|
|
|
41
|
-
|
|
41
|
+
```sh
|
|
42
|
+
npm version 3.0.0-beta.1 --no-git-tag-version
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The version hook synchronizes package metadata, Worker version, and browser-extension metadata.
|
|
46
|
+
|
|
47
|
+
When MCP protocol behavior changes, an official conformance checkout may be run without adding the alpha runner to the package dependency graph:
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
MBM_OFFICIAL_CONFORMANCE_CHECKOUT=/path/to/modelcontextprotocol-conformance \
|
|
51
|
+
MBM_OFFICIAL_CONFORMANCE_SCENARIOS=http-header-validation,caching,server-stateless \
|
|
52
|
+
MBM_OFFICIAL_CONFORMANCE_TIMEOUT_MS=75000 \
|
|
53
|
+
npm run worker:integration-test
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
The test-only loopback proxy injects the integration account's short-lived bearer token; it must never be enabled in production. Expected failures are check-scoped in `tests/mcp-conformance-baseline.yml` and may cover only intentionally absent capabilities. A new failure or stale baseline blocks release.
|
|
57
|
+
|
|
58
|
+
Run the complete local gate and inspect the diff:
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
npm run check
|
|
62
|
+
npm audit --audit-level=high
|
|
63
|
+
npm audit --omit=dev --audit-level=high
|
|
64
|
+
npm audit signatures
|
|
65
|
+
npm run sbom:test
|
|
66
|
+
npm run worker:dry-run
|
|
67
|
+
npm pack --dry-run
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
A successful `npm run check` / `check:full` writes an ignored owner-local `.project-local/full-verification.json` receipt after the stable-generation guard completes. It records only synthetic verification metadata: the exact source-generation digest, package name/version, Node version, platform/architecture, and verification timestamp. The receipt is valid for at most six hours. Starting another full run deletes the prior receipt before any test executes, and any source/package/runtime drift makes it unusable. This is a local execution cache, not acceptance or publication authority.
|
|
71
|
+
|
|
72
|
+
When the frozen full gate is launched remotely through Machine Bridge, do not make the 600-second durable-process ceiling an accidental release deadline. A real install/integration phase can make `check:full` exceed that duration even when every test passes. Owner-authorized remote verification should run the single `npm run check:full` step through detached `start_job` with a larger explicit step timeout and then inspect `read_job`; local terminal execution remains `npm run check:full` directly. The full-verification receipt is written by the suite only after the exact-tree run succeeds, independent of which valid execution carrier launched it.
|
|
73
|
+
|
|
74
|
+
Generate the exact tarball. The prepare/record/verify commands bootstrap ephemeral hardened npm and do not regenerate acceptance bytes through the ambient npm bundle:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
npm run release:candidate
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`release:candidate` consumes the current full-verification receipt instead of running the complete suite a second time. If the receipt is missing, stale, or does not match the frozen tree and runtime, preparation stops before `npm pack` and instructs the agent to run `npm run check:full`. Do not bypass this by calling a lower-level pack command; regenerate full evidence for the current tree.
|
|
42
81
|
|
|
43
|
-
The
|
|
82
|
+
The candidate manifest records npm SHA-1/SHA-512 values and a promotion-content digest. Any packaged-file change invalidates the candidate. Every candidate start or activation recomputes the current digest and compares package identity before tarball verification, npm installation, Worker deployment, or service mutation; a stale but internally self-consistent tarball cannot be installed. Preparing or testing a candidate never authorizes npm publication; only the repository owner may invoke a publication command. An existing tag, GitHub Release, or npm version is immutable and must never be reused after source changes.
|
|
83
|
+
|
|
84
|
+
Immediately before crossing the live activation boundary, the coding agent must run the non-live candidate preflight:
|
|
44
85
|
|
|
45
86
|
```sh
|
|
46
|
-
|
|
87
|
+
node scripts/start-release-candidate.mjs --install-only
|
|
47
88
|
```
|
|
48
89
|
|
|
49
|
-
|
|
90
|
+
This direct-Node path deliberately bypasses npm lifecycle execution and reuses the activation wrapper with `--install-only`. It resolves a validated npm CLI only from the running Node installation layout (not lifecycle `npm_execpath` or unrelated fallback locations), recomputes current package identity and promotion content, verifies the exact tarball, performs a disposable local install, removes that install, and does not deploy the Worker, change the login service, or write prerelease activation evidence. It exists specifically to catch source drift, unexpected package file modes, and installability failures after candidate preparation without mutating live state. If it fails, fix the tree and regenerate `npm run release:candidate`; do not repair the old manifest/tarball in place. The verify command is only a preflight and does not itself authorize live activation.
|
|
91
|
+
|
|
92
|
+
A blocking external CI or CodeQL result discovered after local acceptance is still a candidate defect. When its repair changes any packaged file, increment the prerelease number, remove the old acceptance record, regenerate the candidate, repeat owner activation, rerun the candidate-bound deployed OAuth canary, repeat observed live verification, and record a new acceptance before guarded push. Do not preserve an old acceptance or canary evidence merely because the runtime behavior under investigation is unchanged, and do not weaken a platform or security gate to keep the old candidate valid.
|
|
93
|
+
|
|
94
|
+
Platform fidelity is evidence from the provider environment, not an inference from local success. In particular, Windows filesystem/process semantics and hosted security analyzers must pass on the exact candidate head; local simulations may diagnose or prevent regressions but cannot close those provider gates.
|
|
50
95
|
|
|
51
|
-
|
|
52
|
-
- the remote health route succeeds without redirect;
|
|
53
|
-
- the connected runtime reports the candidate package version;
|
|
54
|
-
- relay readiness is healthy through the deployed Worker for the intended transport;
|
|
55
|
-
- one representative read-only operation succeeds;
|
|
56
|
-
- representative changed functionality succeeds, including browser, application, service, proxy, credential, or platform-specific behavior when relevant.
|
|
96
|
+
## 2. Owner authorizes activation of the exact candidate
|
|
57
97
|
|
|
58
|
-
|
|
98
|
+
After the repository owner explicitly authorizes live activation for the current task, the owner or an authorized agent runs exactly:
|
|
59
99
|
|
|
60
100
|
```sh
|
|
61
|
-
npm run release:
|
|
101
|
+
npm run release:candidate:activate -- --allow-worker-deploy
|
|
62
102
|
```
|
|
63
103
|
|
|
64
|
-
|
|
104
|
+
A TTY is not required. Conversational authorization is sufficient when it is explicit and current-task-specific. If the owner says they will execute the command themselves, the agent must not race that operation.
|
|
105
|
+
|
|
106
|
+
The **execution carrier is part of the safety contract**. This command intentionally stops and replaces the currently running Machine Bridge login daemon. Do not launch persistent activation through `run_process`, `exec_command`, `run_local_command`, or `start_process`: those children/process sessions belong to the current daemon and are terminated when that daemon drains its process tree. The packaged activation guard rejects those surfaces before Worker or service mutation. An authorized coding agent that executes activation through Machine Bridge must use a detached `start_job` step and inspect it with `read_job`; the managed-job runner is independent of the daemon and continues across the handoff. Running the exact command directly in an ordinary owner terminal is also valid.
|
|
107
|
+
|
|
108
|
+
Cloudflare Wrangler authentication is also a **pre-handoff** requirement. The release wrapper performs a captured `wrangler whoami` before it enters the persistent release-runtime/service transaction. A detached managed job never starts interactive Wrangler login: if the preflight is unauthenticated it fails before Worker or service mutation and the owner completes Wrangler authentication in an ordinary terminal before retrying. An ordinary owner-terminal activation may open Wrangler login at this outer preflight boundary, while the existing login daemon is still untouched, and then requires a second captured `whoami`. Once the inner `machine-mcp activate --json` transaction begins, machine-readable Worker deployment will not open an interactive login; authentication loss at that point fails into the existing rollback path instead of holding the service offline or contaminating the JSON result channel.
|
|
65
109
|
|
|
66
|
-
The command
|
|
110
|
+
The command:
|
|
67
111
|
|
|
68
|
-
|
|
112
|
+
- verifies that the pending manifest still matches the current packaged source, then verifies the exact pending tarball;
|
|
113
|
+
- verifies Wrangler authentication before entering the release-runtime/service transaction; managed-job activation fails before live mutation rather than attempting interactive login, while an ordinary owner terminal may authenticate and must pass a post-login `whoami` recheck;
|
|
114
|
+
- installs it under the owner-only ordinary Machine Bridge profile state root, separate from both the normal global installation and the machine-service control root;
|
|
115
|
+
- acquires the machine-global service lock before the workspace startup lock and rejects a foreground or unverifiable daemon before changing the service manager;
|
|
116
|
+
- stops only a verified existing service daemon;
|
|
117
|
+
- updates the configured same-name Worker;
|
|
118
|
+
- starts the candidate in-process and verifies device authentication plus relay readiness;
|
|
119
|
+
- if that current-version candidate receives an explicit device-authentication rejection, redeploys the same Worker once with the unchanged selected identity and retries through ten bounded fresh starts with exponential delay;
|
|
120
|
+
- installs the candidate as the login service runtime and atomically commits the canonical workspace/state/entrypoint/version owner record;
|
|
121
|
+
- performs a controlled foreground-to-service handoff;
|
|
122
|
+
- accepts the background runtime only after its matching daemon lock publishes the post-authentication, post-relay-probe `ready_ack` checkpoint;
|
|
123
|
+
- verifies that both the Worker and verified background daemon report the candidate version;
|
|
124
|
+
- publishes the exact installed candidate browser extension into the owner-only stable release-channel extension directory, with `manifest.json` committed last, before pruning any prior versioned candidate runtime or writing activation evidence;
|
|
125
|
+
- exits while the background daemon continues running.
|
|
69
126
|
|
|
70
|
-
|
|
127
|
+
Service replacement is fail-closed but rollback-aware. If stopping an existing verified provider cannot be conclusively observed, activation does not proceed into candidate takeover. A stop mutation against a previously active service nevertheless creates a rollback obligation because launchd/system service-manager effects may settle after the command response. The activation settlement repeatedly re-establishes and verifies the exact previous service runtime before returning the candidate failure; it must not leave an ambiguous stop as an inactive login daemon. On macOS the launchd stop observer allows a bounded settle window before declaring the stop inconclusive, and previous-service recovery retries idempotent provider start/bootstrap rather than relying on one call that can race a delayed `bootout`.
|
|
128
|
+
|
|
129
|
+
It may request one macOS user-presence or Touch ID operation to certify the daemon session key. It does not ask for per-tool approval. The wrapper does not impose a transaction-wide hard kill: each internal deployment, health, relay, service-manager, and convergence stage is independently bounded so lock release and compensation cannot be skipped.
|
|
130
|
+
|
|
131
|
+
The private candidate runtime is not stored under the Git checkout, so cleaning `.release-candidate/`, switching branches, or regenerating a candidate cannot delete the daemon currently under test. The activation wrapper checks `--allow-worker-deploy` before downloads/install, reads the previous global installation while hardened npm is still live, uses the persistent release-channel prefix only for an actual service activation, and prunes only canonical real contained inactive runtime directories after the stable browser-extension copy has converged. `--install-only` uses the disposable foreground prefix. The stable browser-extension path is intentionally outside the versioned runtime directory so Chrome's unpacked-extension source path survives candidate pruning. The previous global installation remains available as recovery information.
|
|
132
|
+
|
|
133
|
+
## 3. Coding agent runs the deployed OAuth canary and verifies the live candidate
|
|
134
|
+
|
|
135
|
+
After the authorized activation command completes, the coding agent first runs the candidate-bound synthetic canary:
|
|
136
|
+
|
|
137
|
+
```sh
|
|
138
|
+
node <activated-runtime-package>/scripts/release-oauth-canary.mjs --allow-live-oauth-canary
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
`<activated-runtime-package>` is the package directory containing the activation record's absolute `runtime_entry` (take the parent of its `bin/` directory). The coding agent must execute that packaged canary path as direct Node argv while keeping the Git checkout as the child cwd. This makes the code and all relative imports come from the exact activated package; the checkout is only the candidate/evidence data root. A workspace-relative `node scripts/release-oauth-canary.mjs ...` command and the package script `npm run release:oauth-canary -- --allow-live-oauth-canary` remain source/developer entrypoints with ordinary accounting, but they are not valid prerelease-evidence paths. For prereleases the canary additionally canonicalizes its own package root and requires it to equal the package root containing the activation record's `runtime_entry`; a checkout copy therefore fails before live OAuth mutation even when its source bytes match. The npm form can also be redirected by `script-shell`, and the workspace form would otherwise execute mutable checkout imports before admission could prove their full transitive identity. The canary also refuses Node/native debugging, profiling, TLS, loader, key-log, and resource-startup environment overrides before candidate validation or live OAuth mutation; use a clean process environment.
|
|
142
|
+
|
|
143
|
+
The command accepts exactly the single `--allow-live-oauth-canary` argument and requires empty `process.execArgv`; Node preload, loader, debugger, profiler, and other runtime CLI options are not valid release evidence. `--state-dir`, `--workspace`, and every other extra argv are refused before state access because canary evidence does not encode alternate local-state identity. It requires the current startup-ready service daemon to pass the hardened daemon-owner identity check with the candidate version, an `entryScript` canonically equal to the executing canary package's `bin/machine-mcp.mjs`, and a canonical Node executable equal to the canary's `process.execPath`, and private daemon-lock Node runtime metadata equal to `process.versions.node`; this requirement applies to stable candidates too. It refuses stale source/candidate identity and the wrong recorded Worker version. For prereleases it also binds to the exact activation record. It creates one random temporary `reviewer` account and one DCR client, performs authorization-code exchange, an authenticated `server_info` MCP call, refresh-token rotation, and a second authenticated MCP call, then revokes the temporary client and removes the temporary account before it writes evidence. Credentials, authorization codes, client/account identifiers, and access/refresh tokens exist only in process memory and are never printed or stored in canary evidence. A main-path failure still attempts both cleanup operations; cleanup failure makes the canary fail closed and prevents evidence creation.
|
|
144
|
+
|
|
145
|
+
The coding agent then verifies through Machine Bridge:
|
|
146
|
+
|
|
147
|
+
- `server_info` reports the exact candidate version;
|
|
148
|
+
- Worker health reports the same version and deployment identity;
|
|
149
|
+
- the connected daemon is the verified login-service process;
|
|
150
|
+
- relay readiness succeeds through the deployed Worker;
|
|
151
|
+
- a representative read succeeds;
|
|
152
|
+
- changed functionality and relevant failure paths succeed;
|
|
153
|
+
- browser, application, proxy, credential, service, and platform-specific behavior are tested when affected;
|
|
154
|
+
- logs contain no sensitive arguments, output, tokens, or raw user paths.
|
|
155
|
+
|
|
156
|
+
Only observed live evidence counts. A green unit suite, prepared tarball, unobserved process, or ambiguous response does not count. `release:accept` also requires the `.release-candidate/oauth-canary.json` evidence to match the pending candidate; regenerating the candidate removes the evidence and forces a new deployed canary.
|
|
157
|
+
|
|
158
|
+
After successful canary and live verification, the coding agent records acceptance using the exact phrase emitted by `release:candidate`:
|
|
159
|
+
|
|
160
|
+
```sh
|
|
161
|
+
npm run release:accept -- --confirm "I VERIFIED machine-bridge-mcp <version> CANDIDATE ON THE OWNER MACHINE AND IT WORKS"
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
The resulting `release-acceptance/v<version>.json` binds the exact tarball hashes, portable Git package digest, promotion-content digest, timestamp, and fixed verification marker. It contains no personal machine path, command output, account credential, or user content.
|
|
165
|
+
|
|
166
|
+
## 4. Review and publish the prerelease
|
|
167
|
+
|
|
168
|
+
Commit the prerelease changes and acceptance record. Push only through:
|
|
71
169
|
|
|
72
170
|
```sh
|
|
73
171
|
npm run github:push
|
|
74
172
|
```
|
|
75
173
|
|
|
76
|
-
|
|
174
|
+
Create/update the pull request, satisfy required checks, squash-merge, fetch, and fast-forward local `main`.
|
|
77
175
|
|
|
78
|
-
|
|
176
|
+
After the repository owner explicitly authorizes source publication, the owner or an authorized agent creates the annotated prerelease tag, GitHub Prerelease, and exact tarball asset through the local control plane:
|
|
79
177
|
|
|
80
|
-
|
|
178
|
+
```sh
|
|
179
|
+
npm run prerelease:release -- --owner-confirm
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
`--owner-confirm` is an explicit anti-accident acknowledgement, not a terminal-presence proof. A TTY is optional, so an explicitly authorized Machine Bridge call or other local automation may run the command. The command still fails closed on dirty state, wrong branch/version channel, missing exact acceptance, incomplete exact-commit CI, digest mismatch, conflicting tags/releases, or concurrent publication. One common-Git-dir publication lock serializes tag/Release writes across the main checkout and linked worktrees. Stronger adversarial user-presence guarantees require an external isolated release environment and are outside this repository's workflow contract.
|
|
81
183
|
|
|
82
|
-
|
|
184
|
+
The command resolves trusted absolute git and GitHub CLI executables, creates a private staging copy of the accepted candidate, and never runs a new `npm pack` for the Release asset. After upload it queries the GitHub REST asset record and requires its SHA-256 digest to equal the current accepted artifact before reporting success.
|
|
185
|
+
|
|
186
|
+
Historical GitHub Release backfill uses the same explicit-authorization boundary:
|
|
83
187
|
|
|
84
188
|
```sh
|
|
85
|
-
npm run release
|
|
189
|
+
npm run release:backfill -- --owner-confirm
|
|
86
190
|
```
|
|
87
191
|
|
|
88
|
-
|
|
192
|
+
Publish npm through the repository-controlled channel command only after a separate explicit owner authorization:
|
|
89
193
|
|
|
90
|
-
|
|
194
|
+
```sh
|
|
195
|
+
npm run prerelease:publish
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
The command derives `dev`, `beta`, or `next` from the package version. It constructs an ephemeral integrity-pinned hardened npm for the actual publication; the ambient npm process only launches the repository script. `prepublishOnly` rejects an incorrect or implicit `latest` tag and rechecks the package, GitHub prerelease, exact commit, and candidate acceptance. npm then dry-runs publication of the private staged candidate and requires the reported name, version, SHA-1, and SRI to match acceptance before uploading that same tarball with lifecycle scripts disabled. Before upload it refuses a conflicting immutable registry object; after every upload result it waits for exact version/SHA-1/SRI/dist-tag/timestamp convergence. A matching preexisting object is idempotent, while an unresolved outcome is explicitly ambiguous: inspect registry state and do not rerun publication blindly. GitHub Release creation follows the same rule using release metadata and REST SHA-256 asset convergence.
|
|
199
|
+
|
|
200
|
+
The release checks also perform an ordinary install of the exact tarball into an empty consumer project, including optional production dependencies, run a zero-vulnerability production audit, validate that deployment-only Wrangler/Miniflare packages are absent from the published runtime tree, and generate a CycloneDX SBOM with a complete closed dependency record for every component. Root-workspace overrides, workspace audit output, and the workspace SBOM do not satisfy this consumer-artifact gate. CI npm execution uses the same integrity-pinned hardened npm bootstrap as runtime deployment, with fixed replacements for the vulnerable stock undici and brace-expansion bundles. Nested npm operations remove dry-run, workspace, global/prefix, save, omit/include, package-lock-only, and script-control modes case-insensitively. Critical pack/install/publish commands also pass explicit non-dry-run/non-workspace flags, so parent lifecycle variables or user npm execution modes cannot produce a false success.
|
|
201
|
+
|
|
202
|
+
## 5. Activate the published prerelease and begin soak
|
|
203
|
+
|
|
204
|
+
From the exact accepted source checkout, run the following only after a separate explicit owner authorization for published-package installation/activation:
|
|
91
205
|
|
|
92
206
|
```sh
|
|
93
|
-
npm run
|
|
207
|
+
npm run prerelease:install -- --allow-worker-deploy
|
|
94
208
|
```
|
|
95
209
|
|
|
96
|
-
|
|
210
|
+
This command verifies that the GitHub Prerelease asset SHA-256 and npm registry tarball SHA-1/SHA-512/dist-tag all match the locally accepted candidate, resolves the owner's current global npm prefix, creates a temporary hardened npm, installs that exact published version into the same global prefix, updates the Worker and login daemon, verifies both versions, and writes an owner-only `npm-prerelease` activation record. Schema 2 may preserve recovered-activation evidence only as an allowlisted reason plus its fixed canonical detail; lower-layer exception text is neither required nor persisted by the current writer. The record names any retained fallback explicitly as `global_package_rollback_baseline`: it identifies the globally installed npm package and entrypoint available for operator-directed disaster recovery, not the service runtime that was active immediately before activation. The activation transaction captures and verifies that previous service identity separately while the handoff is in progress. The current activation reader accepts schema 2 only; older schema-1 `previous` records are historical evidence, not a supported operational input to current release commands. The formal soak clock starts from this activation record, not from a local unpublished candidate.
|
|
211
|
+
|
|
212
|
+
Use the prerelease normally. Exercise the changed areas under real workloads. A crash, authorization anomaly, data-loss risk, repeated relay failure, incorrect service lifecycle, significant compatibility regression, or security/privacy defect is blocking.
|
|
213
|
+
|
|
214
|
+
When a blocking problem is found:
|
|
215
|
+
|
|
216
|
+
1. fix it on a new branch;
|
|
217
|
+
2. increment `beta.n` or `rc.n`;
|
|
218
|
+
3. regenerate and reactivate the exact candidate;
|
|
219
|
+
4. repeat live verification and prerelease publication;
|
|
220
|
+
5. install the new published prerelease;
|
|
221
|
+
6. restart the full minimum soak interval.
|
|
222
|
+
|
|
223
|
+
Never edit or replace an already published prerelease version.
|
|
224
|
+
|
|
225
|
+
## 6. Record successful soak
|
|
226
|
+
|
|
227
|
+
After the minimum interval and adequate real use, the owner reports that no blocking issue remains. The coding agent records that explicit result with the exact phrase printed by the command, for example:
|
|
228
|
+
|
|
229
|
+
```sh
|
|
230
|
+
npm run prerelease:soak:accept -- --confirm "I SOAK-TESTED machine-bridge-mcp 3.0.0-beta.1 FOR AT LEAST 7d WITH NO BLOCKING ISSUES"
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
The command verifies:
|
|
234
|
+
|
|
235
|
+
- the installed activation came from the published npm prerelease, not a local candidate;
|
|
236
|
+
- the published npm hashes and dist-tag match the accepted tarball;
|
|
237
|
+
- the GitHub release is marked prerelease;
|
|
238
|
+
- the required elapsed time has passed;
|
|
239
|
+
- the promotion-content digest still matches;
|
|
240
|
+
- no blocking issue is recorded.
|
|
241
|
+
|
|
242
|
+
It writes `release-soak/v<stable-version>.json`. This record is reviewable, contains no private machine path, and is excluded from the npm package.
|
|
243
|
+
|
|
244
|
+
## 7. Promote to stable
|
|
245
|
+
|
|
246
|
+
Create a stable-promotion branch. Change only synchronized release metadata from `x.y.z-beta.n` or `x.y.z-rc.n` to `x.y.z`, retain the same functional package content, add the tracked soak record, and update release wording only where it is normalized by the promotion digest.
|
|
247
|
+
|
|
248
|
+
Any source, runtime, dependency, packaged documentation, script, policy, browser-extension behavior, or Worker behavior change causes `release:soak:verify` to fail. Such a change requires a new prerelease and a new soak period.
|
|
249
|
+
|
|
250
|
+
Verify the promotion:
|
|
97
251
|
|
|
98
252
|
```sh
|
|
99
|
-
npm run release:
|
|
253
|
+
npm run release:soak:verify
|
|
254
|
+
npm run check
|
|
255
|
+
npm run release:candidate
|
|
256
|
+
node scripts/start-release-candidate.mjs --install-only
|
|
100
257
|
```
|
|
101
258
|
|
|
102
|
-
|
|
259
|
+
After explicit owner authorization, activate the exact stable candidate with the same persistent command:
|
|
103
260
|
|
|
104
|
-
|
|
261
|
+
```sh
|
|
262
|
+
npm run release:candidate:activate -- --allow-worker-deploy
|
|
263
|
+
```
|
|
105
264
|
|
|
106
|
-
|
|
265
|
+
The coding agent reruns `node <activated-runtime-package>/scripts/release-oauth-canary.mjs --allow-live-oauth-canary`, verifies the live stable candidate, and records its exact acceptance only after both succeed. Then commit, push with `npm run github:push`, and merge. After explicit owner authorization for each external mutation, run:
|
|
107
266
|
|
|
108
267
|
```sh
|
|
109
|
-
npm
|
|
268
|
+
npm run release -- --owner-confirm
|
|
269
|
+
npm run stable:publish
|
|
110
270
|
```
|
|
111
271
|
|
|
112
|
-
`
|
|
272
|
+
`npm run release -- --owner-confirm` creates the final annotated tag and GitHub Release only after the soak record, promotion digest, exact candidate acceptance, exact `origin/main`, and all required push-triggered checks pass. `stable:publish` always uses `latest` and repeats the same gates.
|
|
273
|
+
|
|
274
|
+
## Rollback and recovery
|
|
275
|
+
|
|
276
|
+
Candidate and prerelease activation retain the previous global installation metadata, but rollback across a state or protocol migration is not assumed safe. If activation fails:
|
|
277
|
+
|
|
278
|
+
- preserve the state root and service logs;
|
|
279
|
+
- do not delete locks or edit versions by hand;
|
|
280
|
+
- inspect `machine-mcp service status`, `machine-mcp status`, and `machine-mcp doctor` using the intended runtime;
|
|
281
|
+
- fix forward when Worker/state protocol has changed;
|
|
282
|
+
- restore a complete pre-upgrade backup only when package, Worker, browser extension, service definition, and local state can be restored as one unit.
|
|
283
|
+
|
|
284
|
+
The activation state machine verifies candidate relay readiness before service handoff and cleans up its temporary runtime and locks on failure. Candidate and published-prerelease activation operate on an existing deployment, so their remote-preparation path deliberately skips first-run initial-owner provisioning; normal interactive startup remains responsible for checking account inventory and creating the first owner. Do not add account-list/create probes to candidate activation as a substitute for relay readiness: account administration is an independent authenticated control plane and can fail before the candidate daemon has been observed ready. Before remote preparation changes or verifies the candidate deployment, a provider whose verified stop result requires restoration is restarted after lock cleanup and its prior runtime identity must reconverge. After remote preparation, activation never revives a daemon known to be incompatible with the current Worker: cleanup installs the compatible candidate definition and starts the platform provider without the strict normal-start helper immediately stopping it after an initial readiness miss. Recovery then independently requires the exact candidate service daemon, post-`ready_ack` checkpoint, and Worker version. This is forward recovery, not a fabricated distributed rollback. If the foreground candidate never completed readiness, the owner command remains nonzero even when compensation restores control. If readiness had already been proven and a later handoff-stage failure is completely recovered, the command exits zero with explicit recovered-activation metadata and warning. Any installation, provider-start, daemon-readiness, Worker-version, cleanup, or lock-release failure is aggregated and remains nonzero. An owner command that exits unsuccessfully or writes no activation record cannot be accepted even when an operator later restores service manually.
|
|
113
285
|
|
|
114
|
-
##
|
|
286
|
+
## External credentials and controls
|
|
115
287
|
|
|
116
|
-
|
|
288
|
+
Live npm publication, global installation, and Worker/service replacement require explicit owner authorization. Repository automation does not infer that authorization from a version change.
|
|
117
289
|
|
|
118
|
-
|
|
119
|
-
- an authenticated GitHub CLI session with pull-request and release permission;
|
|
120
|
-
- an npm account that owns the package or has maintainer permission for the separate registry publication step.
|
|
290
|
+
Required external controls remain:
|
|
121
291
|
|
|
122
|
-
|
|
292
|
+
- authenticated local `git`/`gh` access;
|
|
293
|
+
- npm package-owner or maintainer access;
|
|
294
|
+
- Cloudflare account protection;
|
|
295
|
+
- successful exact-commit CI, CodeQL, Governance, Workflow Policy Gate, and Scorecard;
|
|
296
|
+
- protected npm publication credentials or trusted publishing when configured.
|
|
123
297
|
|
|
124
|
-
|
|
298
|
+
Never place npm, GitHub, Cloudflare, OAuth, account, or device credentials in source files, workflow YAML, acceptance/soak records, logs, screenshots, or project notes.
|