machine-bridge-mcp 3.0.0-beta.20 → 3.0.0-beta.201
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 +12 -1089
- package/README.md +93 -31
- package/SECURITY.md +39 -16
- package/SUPPORT.md +3 -1
- package/bin/machine-mcp.mjs +2 -1
- package/browser-extension/broker-auth.js +85 -0
- package/browser-extension/broker-liveness.js +35 -0
- package/browser-extension/browser-error-boundary.js +51 -0
- package/browser-extension/browser-operation-contract.js +92 -0
- package/browser-extension/browser-operations.js +1386 -106
- 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 +2 -3
- package/browser-extension/page-automation.js +614 -132
- package/browser-extension/pairing-bootstrap.js +41 -0
- package/browser-extension/pairing.js +38 -12
- package/browser-extension/service-worker.js +93 -97
- package/cloudflare.config.ts +23 -0
- package/docs/AGENT_CONTEXT.md +27 -28
- package/docs/AUDIT.md +37 -542
- package/docs/CLIENTS.md +19 -15
- package/docs/COMPUTER_USE.md +297 -0
- package/docs/GETTING_STARTED.md +12 -24
- package/docs/LOCAL_AUTHORIZATION.md +4 -4
- package/docs/LOCAL_AUTOMATION.md +33 -23
- package/docs/LOGGING.md +47 -27
- package/docs/MANAGED_JOBS.md +60 -14
- package/docs/MULTI_ACCOUNT.md +12 -10
- package/docs/OPERATIONS.md +175 -66
- package/docs/OVERVIEW.md +12 -8
- package/docs/POLICY_REFERENCE.md +71 -3
- package/docs/PRIVACY.md +60 -6
- package/docs/THREAT_MODEL.md +46 -16
- package/docs/TOOL_REFERENCE.md +682 -63
- package/docs/UPGRADING.md +64 -96
- package/mbm.cmd +3 -3
- package/native/macos/MachineBridgeBackgroundInput.swift +1051 -0
- package/native/macos/MachineBridgeBackgroundInputSmokeFixture.swift +295 -0
- package/native/macos/MachineBridgeTrustBroker.swift +52 -8
- package/package.json +135 -28
- package/scripts/accepted-candidate-tarball.mjs +115 -0
- package/scripts/candidate-runtime-store.mjs +64 -9
- package/scripts/consumer-package-security.mjs +322 -0
- package/scripts/coverage-generation.mjs +41 -0
- package/scripts/foreground-daemon-recovery.mjs +88 -0
- package/scripts/github-backlog.mjs +43 -12
- package/scripts/github-push.mjs +58 -23
- package/scripts/github-release-asset.mjs +58 -0
- package/scripts/github-release.mjs +272 -165
- package/scripts/global-package-installation.mjs +68 -0
- package/scripts/hardened-npm-session.mjs +44 -0
- package/scripts/install-published-prerelease.mjs +109 -77
- package/scripts/local-release-acceptance.mjs +89 -42
- package/scripts/network-retry.mjs +10 -1
- package/scripts/npm-global-prefix.mjs +27 -0
- package/scripts/npm-publication-policy.mjs +2 -1
- package/scripts/persistent-activation-process.mjs +82 -0
- package/scripts/prerelease-activation.mjs +117 -23
- package/scripts/privacy-check.mjs +120 -21
- package/scripts/promotion-digest.mjs +21 -10
- package/scripts/publish-npm.mjs +314 -22
- package/scripts/published-release.mjs +65 -20
- package/scripts/release-acceptance.mjs +53 -70
- package/scripts/release-browser-extension-store.mjs +172 -0
- package/scripts/release-candidate-manifest.mjs +24 -9
- package/scripts/release-channel.mjs +1 -1
- package/scripts/release-ci.mjs +88 -9
- package/scripts/release-diagnostic.mjs +41 -0
- package/scripts/release-impact-check.mjs +2 -1
- package/scripts/release-oauth-canary-core.mjs +332 -0
- package/scripts/release-oauth-canary-evidence.mjs +102 -0
- package/scripts/release-oauth-canary.mjs +127 -0
- package/scripts/release-publication-guard.mjs +50 -0
- package/scripts/release-soak.mjs +81 -31
- package/scripts/release-state.mjs +1 -1
- package/scripts/sbom-check.mjs +106 -0
- package/scripts/source-dependency-tree.mjs +21 -0
- package/scripts/start-release-candidate.mjs +199 -83
- package/scripts/verification-state.mjs +109 -0
- package/src/local/account-access.mjs +9 -2
- package/src/local/account-admin-response.mjs +92 -0
- package/src/local/account-admin.mjs +42 -84
- package/src/local/agent-context-projection.mjs +37 -8
- package/src/local/agent-context.mjs +92 -20
- package/src/local/agent-contract.mjs +21 -1
- package/src/local/agent-skill-discovery.mjs +49 -14
- package/src/local/agent-text-file.mjs +38 -13
- package/src/local/app-automation-macos-jxa.mjs +350 -0
- package/src/local/app-automation.mjs +790 -154
- package/src/local/application-capability-match.mjs +15 -0
- package/src/local/application-capability-projection.mjs +24 -0
- package/src/local/atomic-fs.mjs +31 -3
- package/src/local/authority-context.mjs +10 -6
- package/src/local/autostart-log-maintenance.mjs +36 -0
- package/src/local/bounded-output.mjs +11 -14
- package/src/local/browser-bridge-http.mjs +1 -2
- package/src/local/browser-bridge.mjs +94 -27
- package/src/local/browser-broker-auth-http.mjs +67 -0
- package/src/local/browser-broker-auth.mjs +99 -0
- package/src/local/browser-broker-routes.mjs +60 -21
- package/src/local/browser-broker-server.mjs +27 -8
- package/src/local/browser-command.mjs +81 -30
- package/src/local/browser-computer-observation-service.mjs +209 -0
- package/src/local/browser-extension-identity.mjs +5 -3
- package/src/local/browser-extension-path.mjs +22 -0
- package/src/local/browser-extension-protocol.mjs +43 -9
- package/src/local/browser-operation-service.mjs +138 -123
- package/src/local/browser-pairing-grant.mjs +109 -0
- package/src/local/browser-pairing-http.mjs +4 -4
- package/src/local/browser-pairing-launch.mjs +58 -0
- package/src/local/browser-pairing-store.mjs +81 -56
- 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 +30 -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/cf-authentication.mjs +58 -0
- package/src/local/cf-network-integrity.mjs +68 -0
- package/src/local/cf-project.mjs +108 -0
- package/src/local/child-process-settlement.mjs +132 -0
- package/src/local/cli-account-admin.mjs +3 -4
- package/src/local/cli-activate.mjs +88 -12
- package/src/local/cli-idle-sleep.mjs +15 -0
- package/src/local/cli-local-admin.mjs +64 -43
- package/src/local/cli-options.mjs +10 -9
- package/src/local/cli-policy.mjs +1 -1
- package/src/local/cli-ready-output.mjs +52 -0
- package/src/local/cli-service.mjs +59 -7
- package/src/local/cli.mjs +174 -182
- package/src/local/computer-use-application-observation.mjs +224 -0
- package/src/local/computer-use-arguments.mjs +266 -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-contract.mjs +129 -0
- package/src/local/computer-use-observation.mjs +779 -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 +2163 -0
- package/src/local/daemon-http-relay-auth.mjs +26 -0
- package/src/local/daemon-http-relay-connection.mjs +406 -0
- package/src/local/daemon-http-relay-request.mjs +74 -0
- package/src/local/daemon-http-relay-sequence.mjs +51 -0
- package/src/local/daemon-http-retry-policy.mjs +23 -0
- package/src/local/daemon-process.mjs +54 -16
- package/src/local/default-instructions.mjs +11 -0
- package/src/local/delegated-process-sandbox.mjs +31 -8
- package/src/local/device-identity.mjs +45 -32
- package/src/local/device-root-provider.mjs +7 -7
- package/src/local/directory-metadata.mjs +47 -0
- package/src/local/doctor-reporting.mjs +23 -0
- package/src/local/durable-process-initial-settlement.mjs +40 -0
- package/src/local/durable-process-spec.mjs +76 -0
- package/src/local/errors.mjs +0 -12
- package/src/local/exclusive-file.mjs +82 -29
- package/src/local/exclusive-publication-recovery.mjs +113 -0
- package/src/local/execution-limits.mjs +9 -0
- package/src/local/execution-routing-intent.mjs +108 -0
- package/src/local/execution-routing.mjs +266 -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 +49 -20
- 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 +155 -21
- package/src/local/git-version.mjs +11 -0
- 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-launcher.mjs +48 -0
- package/src/local/hardened-npm-verification.mjs +104 -0
- package/src/local/hardened-npm.mjs +202 -0
- package/src/local/hosted-file-read-budget.mjs +53 -0
- package/src/local/idle-sleep-mode.mjs +9 -0
- package/src/local/job-runner.mjs +325 -164
- package/src/local/lifecycle.mjs +6 -0
- package/src/local/log.mjs +5 -6
- package/src/local/loopback-health.mjs +5 -0
- package/src/local/macos-background-input.mjs +398 -0
- package/src/local/macos-idle-sleep-assertion.mjs +79 -0
- package/src/local/macos-idle-sleep-recovery.mjs +52 -0
- package/src/local/macos-trust-broker.mjs +141 -52
- package/src/local/managed-job-acceptance.mjs +30 -0
- package/src/local/managed-job-active-child.mjs +154 -0
- package/src/local/managed-job-activity.mjs +27 -0
- package/src/local/managed-job-cancellation.mjs +42 -0
- package/src/local/managed-job-capacity.mjs +17 -0
- package/src/local/managed-job-dependencies.mjs +180 -0
- package/src/local/managed-job-dependency-admission.mjs +44 -0
- package/src/local/managed-job-dependency-metadata.mjs +16 -0
- package/src/local/managed-job-dependency-retention.mjs +38 -0
- package/src/local/managed-job-directory-generation.mjs +60 -0
- package/src/local/managed-job-directory.mjs +77 -0
- package/src/local/managed-job-durable-process.mjs +50 -0
- package/src/local/managed-job-hosted-reconcile.mjs +16 -0
- package/src/local/managed-job-hosted-status.mjs +35 -0
- package/src/local/managed-job-idempotency.mjs +29 -0
- package/src/local/managed-job-listing.mjs +57 -0
- package/src/local/managed-job-lock.mjs +46 -27
- package/src/local/managed-job-output-redaction.mjs +163 -0
- package/src/local/managed-job-plan-integrity.mjs +13 -0
- package/src/local/managed-job-plan.mjs +70 -15
- package/src/local/managed-job-projection.mjs +36 -20
- package/src/local/managed-job-read-policy.mjs +39 -0
- package/src/local/managed-job-read-wait.mjs +65 -0
- package/src/local/managed-job-recovery-history.mjs +49 -0
- package/src/local/managed-job-recovery-listing.mjs +27 -0
- package/src/local/managed-job-relaunch.mjs +53 -0
- package/src/local/managed-job-resource-context.mjs +17 -0
- package/src/local/managed-job-retention-policy.mjs +54 -0
- package/src/local/managed-job-retention.mjs +125 -0
- package/src/local/managed-job-runner-claim.mjs +107 -0
- package/src/local/managed-job-runner-exit-recovery.mjs +48 -0
- package/src/local/managed-job-runner-liveness.mjs +44 -0
- package/src/local/managed-job-runner.mjs +56 -43
- package/src/local/managed-job-state-validation.mjs +28 -0
- package/src/local/managed-job-storage.mjs +20 -5
- package/src/local/managed-job-terminal-maintenance.mjs +48 -0
- package/src/local/managed-job-terminal.mjs +17 -3
- package/src/local/managed-job-transient-recovery-capacity.mjs +141 -0
- package/src/local/managed-job-transient-recovery.mjs +30 -0
- package/src/local/managed-jobs.mjs +448 -367
- package/src/local/network-proxy.mjs +64 -4
- package/src/local/npm-audit-report.mjs +21 -0
- package/src/local/npm-cli.mjs +42 -0
- package/src/local/npm-environment.mjs +31 -0
- package/src/local/numbers.mjs +6 -0
- package/src/local/observability.mjs +4 -7
- package/src/local/operation-authorization.mjs +38 -130
- package/src/local/operation-risk.mjs +37 -6
- package/src/local/owner-state-lock.mjs +43 -18
- package/src/local/package-identity.mjs +9 -0
- package/src/local/patch.mjs +20 -18
- package/src/local/private-toolchain-integrity.mjs +54 -0
- package/src/local/process-contract.mjs +9 -0
- package/src/local/process-error-message.mjs +6 -0
- package/src/local/process-execution.mjs +89 -89
- package/src/local/process-foreground-timeout.mjs +50 -0
- package/src/local/process-identity.mjs +118 -11
- package/src/local/process-lock-read-retry.mjs +15 -0
- package/src/local/process-nonreplayable-settlement.mjs +50 -0
- package/src/local/process-output-stream.mjs +5 -7
- package/src/local/process-result-projection.mjs +22 -0
- package/src/local/process-session-events.mjs +42 -0
- package/src/local/process-session-read.mjs +65 -0
- package/src/local/process-session-remote-activity.mjs +10 -0
- package/src/local/process-session-remote-poll.mjs +37 -0
- package/src/local/process-session-termination.mjs +73 -0
- package/src/local/process-sessions.mjs +137 -125
- package/src/local/process-tracker.mjs +128 -13
- package/src/local/process-tree-force-settlement.mjs +44 -0
- package/src/local/process-tree-ownership-types.d.ts +37 -0
- package/src/local/process-tree-ownership.mjs +39 -41
- 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 +9 -54
- package/src/local/project-metadata.mjs +19 -6
- package/src/local/relay-call-recovery.mjs +75 -57
- package/src/local/relay-connect-timing.mjs +66 -0
- package/src/local/relay-connection-classification.mjs +142 -0
- package/src/local/relay-connection-support.mjs +101 -0
- package/src/local/relay-connection.mjs +199 -291
- package/src/local/relay-diagnostics.mjs +94 -6
- package/src/local/relay-heartbeat-options.mjs +16 -0
- package/src/local/relay-heartbeat-stall.mjs +47 -0
- package/src/local/relay-heartbeat-transport-state.mjs +30 -0
- package/src/local/relay-heartbeat.mjs +115 -0
- package/src/local/relay-inbound-state.mjs +41 -0
- package/src/local/relay-liveness-actions.mjs +66 -0
- package/src/local/relay-liveness.mjs +107 -0
- package/src/local/relay-peer-diagnostics.mjs +145 -0
- package/src/local/relay-probe-deadline.mjs +44 -0
- package/src/local/relay-probe-dispatch-metrics.mjs +22 -0
- package/src/local/relay-probe-dispatch.mjs +38 -0
- package/src/local/relay-reconnect.mjs +40 -0
- package/src/local/relay-recovery-admission.mjs +19 -0
- package/src/local/relay-recovery-capacity.mjs +29 -0
- package/src/local/relay-recovery-diagnostics.mjs +28 -0
- package/src/local/relay-redelivery-safety.mjs +43 -0
- package/src/local/relay-result-retention.mjs +66 -0
- package/src/local/relay-tool-schema-extension.mjs +31 -0
- package/src/local/relay-transport-confirmation.mjs +79 -0
- package/src/local/relay-transport-error-state.mjs +48 -0
- package/src/local/relay-transport-probe-send.mjs +27 -0
- package/src/local/relay-transport-probe.mjs +26 -0
- package/src/local/release-runtime-lock.mjs +18 -0
- package/src/local/remote-activity-idle-sleep-guard.mjs +79 -0
- package/src/local/remote-activity-idle-sleep-timeline.mjs +33 -0
- package/src/local/remote-configuration.mjs +6 -4
- package/src/local/remote-idle-sleep-assertions.mjs +41 -0
- package/src/local/resilient-relay-connection.mjs +332 -0
- package/src/local/resource-admission-diagnostic-error.mjs +21 -0
- package/src/local/resource-admission-diagnostics.mjs +50 -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 +44 -0
- package/src/local/resource-host-linux.mjs +35 -0
- package/src/local/resource-host-sample-file.mjs +7 -0
- package/src/local/resource-host-snapshot.mjs +81 -0
- package/src/local/resource-lease-accounting.mjs +119 -0
- package/src/local/resource-lease-liveness.mjs +31 -0
- package/src/local/resource-light-command.mjs +19 -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 +8 -21
- package/src/local/resource-pressure.mjs +86 -0
- package/src/local/resource-probe-command.mjs +27 -0
- package/src/local/resource-process-admission.mjs +59 -0
- package/src/local/resource-process-ancestry-cache.mjs +34 -0
- package/src/local/resource-process-ancestry.mjs +26 -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 +31 -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 +90 -0
- package/src/local/resource-state-file.mjs +22 -0
- package/src/local/resource-swift-concurrency.mjs +31 -0
- package/src/local/resource-transaction-lock.mjs +117 -0
- package/src/local/resource-wait.mjs +48 -0
- package/src/local/resource-waiter-diagnostics.mjs +42 -0
- package/src/local/resource-waiters.mjs +138 -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 +599 -33
- package/src/local/runtime-activity-projection.mjs +48 -0
- package/src/local/runtime-application-automation.mjs +26 -0
- package/src/local/runtime-capabilities.mjs +38 -22
- package/src/local/runtime-device-session.mjs +111 -0
- package/src/local/runtime-diagnostic-projection.mjs +44 -0
- package/src/local/runtime-diagnostic-state.mjs +34 -0
- package/src/local/runtime-diagnostics.mjs +35 -34
- package/src/local/runtime-info-projection.mjs +65 -0
- package/src/local/runtime-info-relay-projection.mjs +23 -0
- package/src/local/runtime-node-executable.mjs +84 -0
- package/src/local/runtime-package-identity.mjs +62 -0
- package/src/local/runtime-paths.mjs +2 -1
- package/src/local/runtime-process-routing.mjs +51 -0
- package/src/local/runtime-relay-acknowledgements.mjs +17 -0
- package/src/local/runtime-relay-connection-options.mjs +53 -0
- package/src/local/runtime-relay-control.mjs +203 -0
- package/src/local/runtime-relay-shutdown-drain.mjs +53 -0
- package/src/local/runtime-relay.mjs +26 -48
- package/src/local/runtime-reporting.mjs +39 -22
- package/src/local/runtime-resource-service.mjs +3 -3
- package/src/local/runtime-tool-handlers.mjs +19 -5
- package/src/local/runtime.mjs +183 -151
- package/src/local/secure-file.mjs +74 -25
- package/src/local/security-audit-activity.mjs +87 -0
- package/src/local/security-audit-beta198-migration.mjs +50 -0
- package/src/local/security-audit-dispatch.mjs +47 -0
- package/src/local/security-audit-gate.mjs +38 -0
- package/src/local/security-audit-log.mjs +186 -171
- package/src/local/security-audit-state.mjs +176 -0
- package/src/local/security-audit-storage.mjs +146 -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 +29 -4
- package/src/local/service-definition.mjs +24 -0
- package/src/local/service-environment.mjs +24 -14
- package/src/local/service-owner.mjs +146 -0
- package/src/local/service-ownership.mjs +1 -1
- package/src/local/service-restart-handoff.mjs +22 -8
- package/src/local/service-restartability.mjs +20 -0
- package/src/local/service-runtime-convergence.mjs +52 -0
- package/src/local/service-runtime.mjs +105 -0
- package/src/local/service-status.mjs +21 -8
- package/src/local/service.mjs +298 -87
- package/src/local/shell.mjs +115 -36
- package/src/local/short-identifiers.mjs +4 -0
- package/src/local/ssh-key.mjs +157 -45
- package/src/local/state-inventory.mjs +36 -28
- package/src/local/state-owner-lock-inventory.mjs +23 -0
- package/src/local/state-root-owned-namespaces.mjs +72 -0
- package/src/local/state-root-retirement.mjs +89 -0
- package/src/local/state.mjs +274 -116
- package/src/local/stdio.mjs +94 -69
- package/src/local/support-state-projection.mjs +30 -0
- package/src/local/system-network-route.mjs +76 -0
- package/src/local/system-sleep-diagnostics.mjs +190 -0
- package/src/local/systemd-removal.mjs +20 -0
- package/src/local/tool-executor.mjs +72 -40
- package/src/local/toolchain-operation-lock.mjs +41 -0
- package/src/local/tools.mjs +6 -5
- package/src/local/windows-service-convergence.mjs +49 -0
- package/src/local/windows-service.mjs +57 -64
- package/src/local/worker-deployment-fingerprint.mjs +146 -0
- package/src/local/worker-deployment.mjs +85 -80
- package/src/local/worker-health.mjs +33 -10
- package/src/local/worker-identity-contract.mjs +14 -0
- package/src/local/worker-secret-file.mjs +53 -21
- package/src/local/workspace-file-service.mjs +130 -235
- package/src/local/workspace-file-transaction.mjs +189 -0
- package/src/local/workspace-profile-migration.mjs +570 -0
- package/src/local/workspace-search.mjs +55 -0
- package/src/local/wrangler-toolchain/package-lock.json +1563 -0
- package/src/local/wrangler-toolchain/package.json +25 -0
- package/src/local/wrangler-toolchain-installed-tree.mjs +43 -0
- package/src/local/wrangler-toolchain-verification.mjs +121 -0
- package/src/local/wrangler-toolchain.mjs +206 -0
- package/src/shared/access-contract.json +7 -1
- package/src/shared/activation-recovery.mjs +49 -0
- package/src/shared/admin-auth.mjs +6 -7
- package/src/shared/authority-revocation.d.mts +9 -0
- package/src/shared/authority-revocation.mjs +29 -0
- package/src/shared/daemon-auth.d.mts +11 -0
- package/src/shared/daemon-auth.mjs +23 -7
- package/src/shared/device-session-auth.mjs +8 -7
- package/src/shared/foreground-timeout.d.mts +15 -0
- package/src/shared/foreground-timeout.mjs +70 -0
- package/src/shared/log-redaction.d.mts +2 -0
- package/src/shared/log-redaction.mjs +43 -14
- package/src/shared/mcp-protocol.d.mts +29 -0
- package/src/shared/mcp-protocol.mjs +300 -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 +47 -7
- package/src/shared/result-projection.d.mts +2 -1
- package/src/shared/result-projection.mjs +13 -2
- package/src/shared/sensitive-value-patterns.mjs +21 -0
- package/src/shared/server-metadata.json +16 -10
- 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 +655 -60
- package/src/worker/access.ts +14 -1
- package/src/worker/account-admin.ts +39 -14
- package/src/worker/authority-revocations.ts +208 -0
- package/src/worker/authority.ts +29 -2
- package/src/worker/daemon-auth.ts +13 -9
- package/src/worker/daemon-channel.ts +36 -0
- package/src/worker/daemon-http-auth.ts +63 -0
- package/src/worker/daemon-http-channel.ts +129 -0
- package/src/worker/daemon-http-controller.ts +185 -0
- package/src/worker/daemon-http-protocol.ts +67 -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 +16 -8
- package/src/worker/daemon-planned-drain.ts +28 -0
- package/src/worker/daemon-ready-dispatch.ts +25 -0
- package/src/worker/daemon-ready-messages.ts +78 -0
- package/src/worker/daemon-ready-waiter-policy.ts +55 -0
- package/src/worker/daemon-ready-waiter-state.ts +53 -0
- package/src/worker/daemon-ready-waiters.ts +62 -0
- package/src/worker/daemon-recovery-budget.ts +29 -0
- package/src/worker/daemon-registry.ts +69 -0
- package/src/worker/daemon-relay-diagnostics.ts +342 -0
- package/src/worker/daemon-resume-reconciliation.ts +43 -0
- package/src/worker/daemon-socket-attachment.ts +57 -0
- package/src/worker/daemon-sockets.ts +56 -52
- package/src/worker/daemon-status.ts +38 -0
- package/src/worker/daemon-tool-redelivery.ts +14 -0
- package/src/worker/device-session-verifier.ts +11 -7
- package/src/worker/dpop.ts +22 -11
- package/src/worker/durable-process-timeout.ts +29 -0
- package/src/worker/errors.ts +67 -0
- package/src/worker/hosted-browser-target-schema.ts +31 -0
- package/src/worker/hosted-result-budget.ts +28 -0
- package/src/worker/http.ts +71 -34
- package/src/worker/index.ts +440 -413
- package/src/worker/managed-job-capability.ts +61 -0
- package/src/worker/managed-job-hosted-authority.ts +129 -0
- package/src/worker/managed-job-hosted-schema.ts +64 -0
- package/src/worker/managed-job-read-timeout.ts +37 -0
- package/src/worker/mcp-access.ts +13 -2
- package/src/worker/mcp-controller.ts +219 -0
- package/src/worker/mcp-http-accept.ts +11 -0
- package/src/worker/mcp-http-contract.ts +322 -0
- package/src/worker/mcp-job-monitor-claims.ts +94 -0
- package/src/worker/mcp-job-monitor-status.ts +28 -0
- package/src/worker/mcp-job-monitor-store.ts +149 -0
- package/src/worker/mcp-job-monitor-tools.ts +89 -0
- package/src/worker/mcp-job-monitor-ui.ts +129 -0
- package/src/worker/mcp-jsonrpc.ts +11 -29
- package/src/worker/mcp-removed-protocol.ts +17 -0
- package/src/worker/mcp-request-cancellation.ts +112 -0
- package/src/worker/mcp-response-cancel.ts +25 -0
- package/src/worker/mcp-response-proxy.ts +130 -0
- package/src/worker/mcp-response-stream.ts +49 -0
- package/src/worker/mcp-stale-schema-guidance.ts +129 -0
- package/src/worker/mcp-stream-proxy-contract.ts +48 -0
- package/src/worker/mcp-streamed-tool-response.ts +19 -0
- package/src/worker/mcp-subscription-capacity.ts +47 -0
- package/src/worker/mcp-subscription-contract.ts +6 -0
- package/src/worker/mcp-subscription-registry.ts +122 -0
- package/src/worker/mcp-subscription-stream.ts +69 -0
- package/src/worker/mcp-tool-call-input.ts +23 -0
- package/src/worker/nonce-store.ts +32 -30
- package/src/worker/oauth-authorization-page.ts +21 -1
- package/src/worker/oauth-client-admin.ts +13 -8
- package/src/worker/oauth-client-contract.ts +37 -0
- package/src/worker/oauth-controller.ts +72 -91
- 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 +37 -15
- package/src/worker/oauth-refresh-families.ts +68 -10
- package/src/worker/oauth-refresh-persistence.ts +105 -0
- package/src/worker/oauth-state.ts +26 -52
- package/src/worker/oauth-store-validation.ts +135 -0
- package/src/worker/oauth-token-issuance.ts +27 -17
- package/src/worker/oauth-tokens.ts +84 -27
- package/src/worker/observability.ts +39 -43
- package/src/worker/pending-call-capacity.ts +122 -0
- package/src/worker/pending-call-contract.ts +32 -9
- package/src/worker/pending-call-deadlines.ts +8 -4
- package/src/worker/pending-call-reconnect-settlement.ts +13 -0
- package/src/worker/pending-call-registration.ts +43 -0
- package/src/worker/pending-calls.ts +69 -70
- package/src/worker/runtime-alarm-storage.ts +37 -0
- package/src/worker/runtime-alarm.ts +77 -80
- package/src/worker/server-info-activity.ts +36 -0
- package/src/worker/server-info-tool-delivery.ts +54 -0
- package/src/worker/server-info.ts +169 -0
- package/src/worker/tool-call-recovery.ts +29 -0
- package/src/worker/tool-catalog.ts +70 -4
- package/src/worker/tool-timeout.ts +73 -15
- package/src/worker/websocket-protocol.ts +18 -0
- package/src/worker/worker-continuity-evidence.ts +121 -0
- package/src/worker/worker-edge-guard.ts +10 -1
- package/src/worker/worker-edge-log.ts +11 -8
- package/src/worker/worker-entry.ts +52 -0
- package/src/worker/worker-mcp-config.ts +28 -0
- package/src/worker/worker-metadata.ts +7 -2
- package/src/worker/worker-rate-limit-key.ts +30 -0
- package/src/worker/worker-runtime-config.ts +20 -0
- package/src/worker/worker-socket-disconnect-evidence.ts +58 -0
- package/src/worker/worker-static-routes.ts +8 -2
- package/src/worker/worker-task-lifetime.ts +18 -0
- package/src/worker/worker-tool-authority.ts +31 -0
- package/tsconfig.local.json +17 -1
- package/wrangler.config.ts +5 -0
- package/wrangler.jsonc +5 -0
- package/CODE_OF_CONDUCT.md +0 -24
- package/CONTRIBUTING.md +0 -68
- package/GOVERNANCE.md +0 -50
- package/docs/ARCHITECTURE.md +0 -314
- package/docs/ENGINEERING.md +0 -210
- package/docs/PROJECT_STANDARDS.md +0 -153
- package/docs/RELEASING.md +0 -231
- package/docs/TESTING.md +0 -164
- package/scripts/check-plan.mjs +0 -116
- package/scripts/check-runner.mjs +0 -78
- package/scripts/commit-message-check.mjs +0 -66
- package/scripts/coverage-check.mjs +0 -206
- package/scripts/generate-policy-reference.mjs +0 -92
- package/scripts/generate-tool-reference.mjs +0 -87
- package/scripts/generate-worker-types.mjs +0 -19
- package/scripts/markdown.mjs +0 -9
- package/scripts/prepare-pinned-npm.mjs +0 -97
- package/scripts/run-checks.mjs +0 -19
- package/scripts/sarif-security-gate.mjs +0 -148
- package/scripts/syntax-check.mjs +0 -52
- package/src/local/cli-approval.mjs +0 -73
- package/src/local/operation-state-lock.mjs +0 -13
- package/src/worker/mcp-resumption-config.ts +0 -46
- package/src/worker/mcp-resumption-http.ts +0 -43
- package/src/worker/mcp-resumption-records.ts +0 -167
- package/src/worker/mcp-resumption.ts +0 -239
- package/src/worker/mcp-session.ts +0 -72
- package/src/worker/mcp-stream-channel.ts +0 -125
- package/src/worker/mcp-stream-dispatch.ts +0 -186
- package/src/worker/mcp-stream-proxy.ts +0 -114
- package/src/worker/mcp-stream-subscription.ts +0 -98
- package/src/worker/mcp-stream.ts +0 -129
|
@@ -1,153 +0,0 @@
|
|
|
1
|
-
# Project standards
|
|
2
|
-
|
|
3
|
-
This document defines the repository-wide engineering and collaboration standard. It complements the product and security invariants in [ENGINEERING.md](ENGINEERING.md). A rule is preferred only when it reduces material risk, makes review easier, or can be enforced consistently; ceremony without a credible failure mode is not a quality control.
|
|
4
|
-
|
|
5
|
-
## 1. Change flow
|
|
6
|
-
|
|
7
|
-
The repository uses **GitHub Flow**:
|
|
8
|
-
|
|
9
|
-
1. create a short-lived branch from current `main`;
|
|
10
|
-
2. make one coherent change, including tests and documentation;
|
|
11
|
-
3. open a pull request and let required checks complete;
|
|
12
|
-
4. resolve review conversations and rebase or update the branch when required;
|
|
13
|
-
5. squash-merge into `main` and delete the branch.
|
|
14
|
-
|
|
15
|
-
Permanent `develop`, `feature`, and `release` integration branches are not used. A supported maintenance line may use a temporary `release/x.y` branch only when an older published version must receive fixes independently of `main`.
|
|
16
|
-
|
|
17
|
-
Branch names use a short category and purpose, for example `feat/browser-downloads`, `fix/relay-timeout`, `docs/release-guide`, or `chore/dependency-policy`.
|
|
18
|
-
|
|
19
|
-
Direct pushes to `main`, force pushes, and branch deletion are blocked by repository protection. An exception requires an incident record and an explicit owner decision.
|
|
20
|
-
|
|
21
|
-
### Completion ownership, prerelease activation, and soak
|
|
22
|
-
|
|
23
|
-
Repository automation owns implementation, local validation, candidate preparation, observed verification, acceptance recording, and pull-request completion. Package work for version 3 or later must use a `dev`, `beta`, or `rc` version before stable promotion. Direct implementation-to-stable release is prohibited.
|
|
24
|
-
|
|
25
|
-
`npm run release:candidate` creates the exact tarball. The repository owner executes `npm run release:candidate:activate -- --allow-worker-deploy`; the command installs that tarball under the private state root, updates the same-name Worker, verifies candidate relay readiness, replaces the login daemon, verifies the background handoff, and exits. The coding agent then performs observed live verification through Machine Bridge and records acceptance only after that observed success. No per-operation terminal approval is involved.
|
|
26
|
-
|
|
27
|
-
The tracked `release-acceptance/v<version>.json` binds npm hashes, a portable package digest, and a version-normalized promotion digest. Any packaged change invalidates acceptance. `npm run github:push`, CI, and source-release commands verify the record. Raw pushes of package branches are prohibited.
|
|
28
|
-
|
|
29
|
-
The accepted prerelease is released with `npm run prerelease:release`; npm publication remains an explicit owner operation through `npm run prerelease:publish`. The owner installs the exact registry version with `npm run prerelease:install -- --allow-worker-deploy`. Formal soak begins only from this registry-verified activation. Minimum soak is seven days for major, three days for minor, and one day for patch releases. A blocking defect increments the prerelease number and restarts the soak interval.
|
|
30
|
-
|
|
31
|
-
Stable promotion requires a tracked `release-soak/v<stable>.json` and identical promotion-content digest. Only normalized release metadata may differ from the soaked prerelease. The stable candidate is activated and observed again before `npm run release`; npm stable publication remains an explicit owner operation through `npm run stable:publish`.
|
|
32
|
-
|
|
33
|
-
GitHub-only repository infrastructure changes that do not alter npm package contents do not require a synthetic version, candidate activation, or soak. They still require review and applicable checks.
|
|
34
|
-
|
|
35
|
-
### Local GitHub control plane
|
|
36
|
-
|
|
37
|
-
Before any GitHub read or mutation, repository automation must load the effective project instructions through Machine Bridge. It must then use local `git`, `gh`, and `gh api` commands executed through Machine Bridge for every GitHub read or mutation. A hosted GitHub connector, ChatGPT GitHub plugin, browser-side GitHub integration, or second remote control plane must not be used. If Machine Bridge or the local authenticated CLI is unavailable, the operation stops and reports that boundary rather than falling back. Mixing control planes can produce stale refs, unreviewed remote-only commits, ambiguous credentials, and recovery paths that cannot be reproduced from the maintainer's machine. Fetch before mutation and verify the remote result afterward.
|
|
38
|
-
|
|
39
|
-
## 2. Commits and pull requests
|
|
40
|
-
|
|
41
|
-
Commit and squash-merge subjects follow Conventional Commits:
|
|
42
|
-
|
|
43
|
-
```text
|
|
44
|
-
<type>[optional scope][optional !]: <imperative description>
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
Allowed types are `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `security`, `release`, and `revert`. `feat` and `fix` carry their normal semantic-version meaning. A breaking change uses `!` and explains upgrade impact in the body or a `BREAKING CHANGE:` footer.
|
|
48
|
-
|
|
49
|
-
A good change explains both **what changed and why**. Commits should be logically coherent, but intermediate branch history may be amended because the final pull request is squash-merged. Pull-request titles must satisfy the same format because they become the `main` commit subject.
|
|
50
|
-
|
|
51
|
-
Pull requests must state:
|
|
52
|
-
|
|
53
|
-
- the problem and causal mechanism;
|
|
54
|
-
- the chosen solution and important rejected alternatives;
|
|
55
|
-
- user-visible, compatibility, security, privacy, and operational risk;
|
|
56
|
-
- tests and manual verification performed;
|
|
57
|
-
- documentation, release, and rollback consequences.
|
|
58
|
-
|
|
59
|
-
Keep a pull request small enough to review as one argument. Generated files, mechanical renames, or dependency lockfile changes should be isolated when they obscure substantive behavior. Large changes should be split by a stable contract, not into dependent fragments that cannot be evaluated independently.
|
|
60
|
-
|
|
61
|
-
## 3. Architecture and dependency direction
|
|
62
|
-
|
|
63
|
-
The architectural dependency direction in [ENGINEERING.md](ENGINEERING.md) is normative. In addition:
|
|
64
|
-
|
|
65
|
-
- A module owns one coherent reason to change. Related state-machine transitions may stay together when ordering is part of the safety argument.
|
|
66
|
-
- Domain modules do not import CLI, transport, service, presentation, or deployment adapters.
|
|
67
|
-
- Cross-layer calls go through an explicit interface or orchestration boundary; no adapter reaches through another layer to mutate its internals.
|
|
68
|
-
- Policy, schemas, error codes, protocol metadata, and capability inventories have one authoritative source. Adapters translate them but do not maintain parallel copies.
|
|
69
|
-
- Side effects are isolated behind small interfaces so policy and lifecycle behavior can be tested deterministically.
|
|
70
|
-
- Dependency cycles are prohibited. Hidden global state and import-time operational side effects are avoided.
|
|
71
|
-
- Line-count and complexity thresholds are diagnostic guardrails, not design goals. A threshold may not be satisfied by moving incoherent code into a generic utility module.
|
|
72
|
-
- **High cohesion and low coupling:** one source file or function owns one coherent responsibility and reason to change; collaboration occurs through narrow explicit contracts rather than cross-layer reach-through.
|
|
73
|
-
- **KISS:** prefer the simplest explicit implementation that satisfies current requirements. Do not introduce factories, registries, inheritance, generic frameworks, or configuration layers without an observed variation that needs them.
|
|
74
|
-
- **DRY:** extract repeated business rules, validation, security boundaries, or lifecycle logic into one authoritative implementation. Do not merge merely similar code when its semantics or failure policy differ.
|
|
75
|
-
- **Exact key membership:** external string keys used for dispatch, enums, ACLs, forms, or registries use `Map`, `Set`, `Object.hasOwn`, or null-prototype records. Prototype-chain membership and truthy ordinary-object lookup are not contract validation.
|
|
76
|
-
- Design patterns are used only when they remove an observed variation or coupling. A direct function or small module is preferred over speculative abstractions.
|
|
77
|
-
|
|
78
|
-
Any deliberate boundary exception must document the dependency, reason, owner, test coverage, and removal condition.
|
|
79
|
-
|
|
80
|
-
## 4. Public contracts and generated documentation
|
|
81
|
-
|
|
82
|
-
The MCP tool catalog in `src/shared/tool-catalog.json` is the authoritative public API description. Tool names, availability, annotations, and JSON input schemas are rendered into [TOOL_REFERENCE.md](TOOL_REFERENCE.md); CI rejects stale generated documentation.
|
|
83
|
-
|
|
84
|
-
Swagger/OpenAPI is required only if the project later exposes a user-facing HTTP REST API. It is not a substitute for MCP tool schemas or end-to-end MCP protocol tests. Hand-maintained copies of generated contracts are prohibited.
|
|
85
|
-
|
|
86
|
-
A public contract change must address:
|
|
87
|
-
|
|
88
|
-
- backward and forward compatibility;
|
|
89
|
-
- bounded input and output behavior;
|
|
90
|
-
- authorization and destructive-operation annotations;
|
|
91
|
-
- stable error classification;
|
|
92
|
-
- protocol negotiation or versioning when peers may differ;
|
|
93
|
-
- documentation, tests, changelog, and semantic-version impact.
|
|
94
|
-
|
|
95
|
-
## 5. Testing and quality gates
|
|
96
|
-
|
|
97
|
-
Tests follow risk rather than a repository-wide aggregate percentage:
|
|
98
|
-
|
|
99
|
-
- Every defect fix includes a regression test that fails for the original causal reason.
|
|
100
|
-
- Pure policy and normalization logic is tested directly; adapters receive integration coverage proving that they use the policy correctly.
|
|
101
|
-
- Permission expansion includes denial tests. Bounded resources include over-limit tests. Multi-stage mutations include partial-failure and rollback tests.
|
|
102
|
-
- Concurrency, locking, process trees, persistence, cancellation, retry, and recovery require behavior-level or fault-injection coverage.
|
|
103
|
-
- Protocol changes include producer-consumer contract tests and malformed-input tests.
|
|
104
|
-
- Supported operating systems run the required suite in CI.
|
|
105
|
-
- Critical modules have explicit function and branch baselines. Thresholds may rise after better tests or extraction; lowering one requires an audit note explaining why the old measurement was misleading.
|
|
106
|
-
- High-risk JavaScript contract modules opt into strict TypeScript checking through `tsconfig.local.json`; implicit `any`, `@ts-ignore`, and untyped duplicate protocol/configuration shapes are not acceptable substitutes for a defined boundary.
|
|
107
|
-
|
|
108
|
-
An 80% aggregate coverage target is not a repository requirement: it can hide untested critical branches behind trivial files. New or materially changed pure business modules should normally achieve at least 80% function coverage and meaningful branch coverage, but risk-specific tests remain the acceptance criterion.
|
|
109
|
-
|
|
110
|
-
Flaky tests are defects. A retry may diagnose environmental instability but may not be used to make a nondeterministic test appear healthy.
|
|
111
|
-
|
|
112
|
-
## 6. Errors, retries, and logs
|
|
113
|
-
|
|
114
|
-
- Expected operational failures use typed stable error codes and concise operator messages.
|
|
115
|
-
- Unexpected programming errors remain distinguishable from ordinary unavailability.
|
|
116
|
-
- Request boundaries normalize errors once. Lower layers preserve causes and do not repeatedly translate them.
|
|
117
|
-
- Cleanup catches may be best effort only when the primary failure is retained and cleanup failure is observable where useful.
|
|
118
|
-
- Empty catches and catch-and-continue behavior are prohibited unless a comment explains why the event is intentionally irrelevant.
|
|
119
|
-
- Retries require positive transient classification, bounded attempts, backoff, and idempotency or authoritative state reconciliation.
|
|
120
|
-
- Unhandled process-level exceptions are logged with redaction and cause controlled termination; continuing in an unknown state is not a recovery strategy.
|
|
121
|
-
- Operational logs follow [LOGGING.md](LOGGING.md), remain structured, bounded, actionable, and free of secrets or user content.
|
|
122
|
-
|
|
123
|
-
## 7. Security and software supply chain
|
|
124
|
-
|
|
125
|
-
- GitHub workflow permissions default to read-only and are expanded per job only when required.
|
|
126
|
-
- Third-party Actions are pinned to immutable commit SHAs and reviewed when Dependabot updates them. GitHub Action updates are grouped into one atomic pull request so coupled suites such as CodeQL cannot be split across incompatible versions.
|
|
127
|
-
- npm dependencies use exact versions and a committed lockfile. Source bootstrap uses `npm ci`; the CI npm baseline itself is downloaded from an exact URL and verified against a pinned SHA-512 SRI before use. Registry signatures and attestations are verified in CI.
|
|
128
|
-
- Dependency review blocks newly introduced vulnerable dependencies. CodeQL performs JavaScript/TypeScript and workflow analysis. OpenSSF Scorecard audits supply-chain posture, and both SARIF streams are failing gates with exact, expiring exceptions rather than advisory-only uploads.
|
|
129
|
-
- CI generates and validates a CycloneDX SBOM. Release artifacts must match the repository-owner-tested tarball hash, be reproducible from a reviewed commit, and be tied to successful exact-commit CI, CodeQL, Governance, and Scorecard evidence.
|
|
130
|
-
- Secret scanning and push protection are enabled. Repository examples use synthetic identities and reserved domains; reachable history is scanned before release.
|
|
131
|
-
- Long-lived publication tokens should be replaced by npm trusted publishing with GitHub OIDC. Until that external registry configuration is completed, release credentials remain an explicit operator responsibility and must never be stored in the repository.
|
|
132
|
-
- Security reports follow [SECURITY.md](../SECURITY.md), not public issue templates.
|
|
133
|
-
|
|
134
|
-
## 8. Documentation and comments
|
|
135
|
-
|
|
136
|
-
- README covers supported setup, operation, major capabilities, limitations, and risk.
|
|
137
|
-
- Architecture, security, testing, operations, logging, policy, upgrade, support, governance, and release documents each own their designated concern; avoid repeating whole procedures across files.
|
|
138
|
-
- Documentation claims a guarantee only when code, configuration, or a test enforces it.
|
|
139
|
-
- Public behavior changes update the changelog and relevant user documentation in the same pull request.
|
|
140
|
-
- Comments explain non-obvious **why**, invariants, external constraints, and safety ordering. They do not narrate self-explanatory syntax.
|
|
141
|
-
- Temporary workarounds state the triggering condition and removal criterion; use an issue reference when one exists.
|
|
142
|
-
|
|
143
|
-
## 9. Review and ownership
|
|
144
|
-
|
|
145
|
-
`CODEOWNERS` identifies responsible areas and requests informed review. It does not prove independent review when author and owner are the same person.
|
|
146
|
-
|
|
147
|
-
Review examines correctness, causal completeness, security/privacy boundaries, compatibility, failure paths, observability, test evidence, and maintainability. Style preferences do not override a simpler correct design without a documented project rule.
|
|
148
|
-
|
|
149
|
-
This repository currently has one human maintainer. Requiring one independent approval would deadlock maintenance and therefore is not enabled. [GOVERNANCE.md](../GOVERNANCE.md) defines admission, succession, release authority, and the first mandatory control after another active maintainer is added: one non-author approval plus last-push approval for security-sensitive, release, policy, Worker, browser, state, and execution changes.
|
|
150
|
-
|
|
151
|
-
## 10. Exceptions and evolution
|
|
152
|
-
|
|
153
|
-
A standard may be changed when evidence shows that it creates more risk or cost than it removes. The change must update this document, relevant automation, and the changelog together. Silent exceptions and permanently waived failing checks are prohibited.
|
package/docs/RELEASING.md
DELETED
|
@@ -1,231 +0,0 @@
|
|
|
1
|
-
# Release process
|
|
2
|
-
|
|
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
|
-
|
|
5
|
-
The invariant for version 3 and later is:
|
|
6
|
-
|
|
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, and OpenSSF Scorecard before the stable tag and final GitHub Release are created.
|
|
15
|
-
|
|
16
|
-
## Release channels
|
|
17
|
-
|
|
18
|
-
Supported versions and registry channels are:
|
|
19
|
-
|
|
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 |
|
|
26
|
-
|
|
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.
|
|
28
|
-
|
|
29
|
-
Minimum published-prerelease soak periods are:
|
|
30
|
-
|
|
31
|
-
- major release: seven days;
|
|
32
|
-
- minor release: three days;
|
|
33
|
-
- patch release: one day.
|
|
34
|
-
|
|
35
|
-
These are lower bounds, not automatic approval. Continue the soak when use has been too light to exercise the changed behavior.
|
|
36
|
-
|
|
37
|
-
## 1. Prepare an exact prerelease candidate
|
|
38
|
-
|
|
39
|
-
Complete implementation, tests, documentation, audit notes, and changelog. Set the prerelease version without creating a Git tag:
|
|
40
|
-
|
|
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
|
-
Run the complete local gate and inspect the diff:
|
|
48
|
-
|
|
49
|
-
```sh
|
|
50
|
-
npm run check
|
|
51
|
-
npm audit --audit-level=high
|
|
52
|
-
npm audit --omit=dev --audit-level=high
|
|
53
|
-
npm run worker:dry-run
|
|
54
|
-
npm pack --dry-run
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
Generate the exact tarball:
|
|
58
|
-
|
|
59
|
-
```sh
|
|
60
|
-
npm run release:candidate
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
The candidate manifest records npm SHA-1/SHA-512 values and a promotion-content digest. Any packaged-file change invalidates the candidate.
|
|
64
|
-
|
|
65
|
-
## 2. Owner activates the exact candidate
|
|
66
|
-
|
|
67
|
-
The coding agent must stop and present this command. The repository owner executes it:
|
|
68
|
-
|
|
69
|
-
```sh
|
|
70
|
-
npm run release:candidate:activate -- --allow-worker-deploy
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
The command:
|
|
74
|
-
|
|
75
|
-
- verifies the exact pending tarball;
|
|
76
|
-
- installs it under the owner-only Machine Bridge state root, separate from the normal global installation;
|
|
77
|
-
- stops only a verified existing service daemon;
|
|
78
|
-
- updates the configured same-name Worker;
|
|
79
|
-
- starts the candidate in-process and verifies device authentication plus relay readiness;
|
|
80
|
-
- installs the candidate as the login service runtime;
|
|
81
|
-
- performs a controlled foreground-to-service handoff;
|
|
82
|
-
- verifies that both the Worker and verified background daemon report the candidate version;
|
|
83
|
-
- exits while the background daemon continues running.
|
|
84
|
-
|
|
85
|
-
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.
|
|
86
|
-
|
|
87
|
-
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 previous global installation remains available as recovery information.
|
|
88
|
-
|
|
89
|
-
## 3. Coding agent verifies the live candidate
|
|
90
|
-
|
|
91
|
-
After the owner command completes, the coding agent verifies through Machine Bridge:
|
|
92
|
-
|
|
93
|
-
- `server_info` reports the exact candidate version;
|
|
94
|
-
- Worker health reports the same version and deployment identity;
|
|
95
|
-
- the connected daemon is the verified login-service process;
|
|
96
|
-
- relay readiness succeeds through the deployed Worker;
|
|
97
|
-
- a representative read succeeds;
|
|
98
|
-
- changed functionality and relevant failure paths succeed;
|
|
99
|
-
- browser, application, proxy, credential, service, and platform-specific behavior are tested when affected;
|
|
100
|
-
- logs contain no sensitive arguments, output, tokens, or raw user paths.
|
|
101
|
-
|
|
102
|
-
Only observed live evidence counts. A green unit suite, prepared tarball, unobserved process, or ambiguous response does not count.
|
|
103
|
-
|
|
104
|
-
After successful verification, the coding agent records acceptance using the exact phrase emitted by `release:candidate`:
|
|
105
|
-
|
|
106
|
-
```sh
|
|
107
|
-
npm run release:accept -- --confirm "I VERIFIED machine-bridge-mcp <version> CANDIDATE ON THE OWNER MACHINE AND IT WORKS"
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
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.
|
|
111
|
-
|
|
112
|
-
## 4. Review and publish the prerelease
|
|
113
|
-
|
|
114
|
-
Commit the prerelease changes and acceptance record. Push only through:
|
|
115
|
-
|
|
116
|
-
```sh
|
|
117
|
-
npm run github:push
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
Create/update the pull request, satisfy required checks, squash-merge, fetch, and fast-forward local `main`.
|
|
121
|
-
|
|
122
|
-
Create the annotated prerelease tag, GitHub Prerelease, and exact tarball asset:
|
|
123
|
-
|
|
124
|
-
```sh
|
|
125
|
-
npm run prerelease:release
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
Publish npm through the repository-controlled channel command:
|
|
129
|
-
|
|
130
|
-
```sh
|
|
131
|
-
npm run prerelease:publish
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
The command derives `dev`, `beta`, or `next` from the package version. `prepublishOnly` rejects an incorrect or implicit `latest` tag and rechecks the package, GitHub prerelease, exact commit, and candidate acceptance.
|
|
135
|
-
|
|
136
|
-
## 5. Activate the published prerelease and begin soak
|
|
137
|
-
|
|
138
|
-
From the exact accepted source checkout, the owner runs:
|
|
139
|
-
|
|
140
|
-
```sh
|
|
141
|
-
npm run prerelease:install -- --allow-worker-deploy
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
This command verifies that the npm registry tarball SHA-1/SHA-512 and dist-tag match the locally accepted candidate, installs that exact published version globally, updates the Worker and login daemon, verifies both versions, and writes an owner-only `npm-prerelease` activation record. The formal soak clock starts from this activation record, not from a local unpublished candidate.
|
|
145
|
-
|
|
146
|
-
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.
|
|
147
|
-
|
|
148
|
-
When a blocking problem is found:
|
|
149
|
-
|
|
150
|
-
1. fix it on a new branch;
|
|
151
|
-
2. increment `beta.n` or `rc.n`;
|
|
152
|
-
3. regenerate and reactivate the exact candidate;
|
|
153
|
-
4. repeat live verification and prerelease publication;
|
|
154
|
-
5. install the new published prerelease;
|
|
155
|
-
6. restart the full minimum soak interval.
|
|
156
|
-
|
|
157
|
-
Never edit or replace an already published prerelease version.
|
|
158
|
-
|
|
159
|
-
## 6. Record successful soak
|
|
160
|
-
|
|
161
|
-
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:
|
|
162
|
-
|
|
163
|
-
```sh
|
|
164
|
-
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"
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
The command verifies:
|
|
168
|
-
|
|
169
|
-
- the installed activation came from the published npm prerelease, not a local candidate;
|
|
170
|
-
- the published npm hashes and dist-tag match the accepted tarball;
|
|
171
|
-
- the GitHub release is marked prerelease;
|
|
172
|
-
- the required elapsed time has passed;
|
|
173
|
-
- the promotion-content digest still matches;
|
|
174
|
-
- no blocking issue is recorded.
|
|
175
|
-
|
|
176
|
-
It writes `release-soak/v<stable-version>.json`. This record is reviewable, contains no private machine path, and is excluded from the npm package.
|
|
177
|
-
|
|
178
|
-
## 7. Promote to stable
|
|
179
|
-
|
|
180
|
-
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.
|
|
181
|
-
|
|
182
|
-
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.
|
|
183
|
-
|
|
184
|
-
Verify the promotion:
|
|
185
|
-
|
|
186
|
-
```sh
|
|
187
|
-
npm run release:soak:verify
|
|
188
|
-
npm run check
|
|
189
|
-
npm run release:candidate
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
The owner activates the exact stable candidate with the same persistent command:
|
|
193
|
-
|
|
194
|
-
```sh
|
|
195
|
-
npm run release:candidate:activate -- --allow-worker-deploy
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
The coding agent verifies the live stable candidate and records its exact acceptance. Then commit, push with `npm run github:push`, merge, and run:
|
|
199
|
-
|
|
200
|
-
```sh
|
|
201
|
-
npm run release
|
|
202
|
-
npm run stable:publish
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
`npm run release` 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.
|
|
206
|
-
|
|
207
|
-
## Rollback and recovery
|
|
208
|
-
|
|
209
|
-
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:
|
|
210
|
-
|
|
211
|
-
- preserve the state root and service logs;
|
|
212
|
-
- do not delete locks or edit versions by hand;
|
|
213
|
-
- inspect `machine-mcp service status`, `machine-mcp status`, and `machine-mcp doctor` using the intended runtime;
|
|
214
|
-
- fix forward when Worker/state protocol has changed;
|
|
215
|
-
- restore a complete pre-upgrade backup only when package, Worker, browser extension, service definition, and local state can be restored as one unit.
|
|
216
|
-
|
|
217
|
-
The activation state machine verifies candidate relay readiness before service handoff and cleans up its temporary runtime and locks on installation failure. A failure after the Worker has changed is reported explicitly rather than hidden by an unsafe automatic downgrade.
|
|
218
|
-
|
|
219
|
-
## External credentials and controls
|
|
220
|
-
|
|
221
|
-
Live npm publication, global installation, and Worker/service replacement require explicit owner authorization. Repository automation does not infer that authorization from a version change.
|
|
222
|
-
|
|
223
|
-
Required external controls remain:
|
|
224
|
-
|
|
225
|
-
- authenticated local `git`/`gh` access;
|
|
226
|
-
- npm package-owner or maintainer access;
|
|
227
|
-
- Cloudflare account protection;
|
|
228
|
-
- successful exact-commit CI, CodeQL, Governance, and Scorecard;
|
|
229
|
-
- protected npm publication credentials or trusted publishing when configured.
|
|
230
|
-
|
|
231
|
-
Never place npm, GitHub, Cloudflare, OAuth, account, or device credentials in source files, workflow YAML, acceptance/soak records, logs, screenshots, or project notes.
|
package/docs/TESTING.md
DELETED
|
@@ -1,164 +0,0 @@
|
|
|
1
|
-
# Testing strategy
|
|
2
|
-
|
|
3
|
-
The project treats transport, authorization, local authority, and state removal as separate failure domains.
|
|
4
|
-
|
|
5
|
-
## Required suites
|
|
6
|
-
|
|
7
|
-
```sh
|
|
8
|
-
npm run check:fast # static, unit, contract, and architecture feedback
|
|
9
|
-
npm run check:platform # fast plan plus cross-platform behavior and real-machine tests
|
|
10
|
-
npm run check # complete suite; equivalent to check:full
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
The explicit task lists live in `scripts/check-plan.mjs`. The fast plan retains static analysis, policy, architecture, contracts, and focused unit behavior. The platform plan adds process, service, browser/application, state, managed-job, cryptographic, and real-machine behavior tests needed on macOS and Windows. The full-only plan adds coverage, browser-broker integration, package/install, stdio, Worker/OAuth, and real-browser navigation suites. `npm run check` remains the authoritative complete gate.
|
|
14
|
-
|
|
15
|
-
Successful child-task stdout/stderr is intentionally suppressed so a long green plan does not overwhelm an MCP response or hide the final status behind host truncation. Progress and timing remain visible. A failed task returns bounded head/tail diagnostics for both streams. Set `MBM_CHECK_VERBOSE=1` only when an operator explicitly needs live child output; verbose mode can be large and should be run through a process session when used remotely.
|
|
16
|
-
|
|
17
|
-
The repository requires Node.js 26 and npm 12. `.node-version`, `.nvmrc`, `packageManager`, `devEngines`, and strict engine checks keep local and CI execution on the same baseline.
|
|
18
|
-
|
|
19
|
-
The suite includes:
|
|
20
|
-
|
|
21
|
-
- package-impact classification derived from the npm package manifest, allowing repository-only GitHub workflow maintenance without weakening version requirements for shipped content;
|
|
22
|
-
- interactive candidate acceptance hashing, including owner-authorized in-place Worker deployment plus agent-operated candidate verification, exact tarball SHA-1/SHA-512 matching, descriptor-first no-follow reads, path-identity/symlink regressions, acceptance-record exclusion from the package, legacy 1.2.8 marker compatibility, and invalidation after any packaged-byte change;
|
|
23
|
-
- one-shot process output preview/continuation, completed-session paging, bounded nonzero-exit details, UTF-8-safe head/tail diagnostics, compact local/Worker MCP text mirrors, and quiet-success/bounded-failure verification-runner behavior;
|
|
24
|
-
- GitHub backlog enforcement that paginates all open issues and pull requests, permits only the current branch PR, and requires standard closing keywords for every open issue before a guarded push;
|
|
25
|
-
- release-impact enforcement requiring a new package version and CHANGELOG section for release-relevant changes;
|
|
26
|
-
- strict dev/beta/rc/stable channel parsing and npm dist-tag enforcement;
|
|
27
|
-
- persistent candidate relay/service handoff ordering and fault cleanup;
|
|
28
|
-
- owner-only local and registry prerelease activation records;
|
|
29
|
-
- npm/GitHub prerelease metadata validation, minimum soak timing, blocking-issue rejection, and stable-promotion content/file-mode identity;
|
|
30
|
-
- release-state diagnostics distinguishing missing local/remote version tags from tags that point to the wrong commit, plus a release-CI gate that rejects missing, pending, failed, pull-request-only, stale, or wrong-commit runs;
|
|
31
|
-
- generated Cloudflare Worker types under ignored `.wrangler/` state and strict TypeScript checking, including unused-local and unused-parameter rejection; packaging rejects generated declarations;
|
|
32
|
-
- Conventional Commit title validation, shared Markdown escaping regression coverage, and generated MCP tool-reference drift detection;
|
|
33
|
-
- direct tests for shared project-metadata reads, strict integer normalization, plain-record classification, and canonical profile/Worker/job/lock inventory;
|
|
34
|
-
- recursive syntax validation for every JavaScript file under the shipped/runtime/test roots plus the shell wrapper;
|
|
35
|
-
- shared tool-catalog schema, annotation, and profile-inventory checks;
|
|
36
|
-
- default working-agreement injection without user files, bounded automatic project metadata, script-body non-disclosure, user-global opt-out, repository opt-out rejection, global `model_instructions_file` injection in stdio/remote initialization, hierarchical precedence, `.agents/skills` and `.codex/skills` compatibility discovery, live project/skill rescanning and fingerprints, automatic task ranking/loading with English inflection normalization, bounded Chinese/English intent aliases, capability-name weighting, and selected-skill instruction loading; automatic `package.*` commands with English/Chinese workflow-intent matching and Windows command-shim execution, explicit command override/removal, direct argv handling, timeout ceilings, runtime-keyed routing-telemetry privacy, and execution-profile denial;
|
|
37
|
-
- concurrent complete-before-visible lock claims, atomic replacement under active readers, malformed-lock grace, snapshot/token-safe reclamation, absolute-age expiry, PID-reuse detection, bounded startup-lock waiting, and wall-clock rollback injection proving duration deadlines remain monotonic;
|
|
38
|
-
- foreground takeover of active and orphaned background daemons with current service-lock metadata, foreground-process protection, bounded final lock-handoff retry, actual-PID exit waiting, POSIX non-escalating timeout behavior, Windows verified-daemon stop semantics, daemon lock mode/version/process-start metadata, launchd service-target semantics, and silent idempotent duplicate service starts; daemon fixture subprocesses intentionally do not inherit V8 coverage because their purpose is ownership timing rather than code measurement;
|
|
39
|
-
- fail-closed service lifecycle ordering for provider-stop, all-workspace daemon-stop, and definition removal, including platform/daemon/removal failure injection and normalized macOS/systemd/Windows results; service-PATH coverage reproduces two nested npm run-script prefixes plus a stale prior candidate runtime and proves the current Node/runtime and inherited user tools remain while npm-private and inactive-runtime entries are removed; Windows coverage reproduces an inline `/TR` command above 262 characters, proves the short launcher action remains bounded, verifies least-privilege logon registration, restart/log routing, language-independent `Ready`/`Running` observation, and state-observed stop/removal despite localized nonzero command output;
|
|
40
|
-
- private service-environment capture/load coverage for exact allowlisting, value bounds and control-character rejection, non-proxy secret exclusion, runtime-value precedence, Windows case-insensitive replacement, explicit empty-value clearing, and preservation across a later environment-free startup;
|
|
41
|
-
- machine-level browser-broker ownership/client proxying, authenticated extension origin/subprotocol, non-cacheable local pairing, pairing-token non-disclosure, resource-backed upload routing, broker result redaction, pre-registered runtime-handshake listeners, bounded socket/HTTP waits, direct loopback health despite hostile environment-proxy settings, stop-during-start generation invalidation, frozen-wall-clock browser deadline coverage, installed-application discovery caching, per-root warning projection, capability-resolution degradation reporting, and name-based task matching;
|
|
42
|
-
- Worker health direct/proxy routing through a real local HTTP CONNECT proxy, `NO_PROXY` bypass, exact `workers.dev` origin/name validation, redirect rejection, body/deadline bounds, error classification, bounded propagation retry, and invalid proxy fail-fast behavior without endpoint or credential disclosure;
|
|
43
|
-
- Worker deployment ambiguity/idempotency: a successful Wrangler result followed by health timeout persists the fingerprint, a second start performs no upload, an actual process restart and disk-state reload still performs no upload, definitive stale-version evidence redeploys under the same name, accidental name changes are rejected, forced replacements clear current endpoint state, and prior names remain in uninstall inventory;
|
|
44
|
-
- relay environment-proxy direct/bypass/agent selection, unsupported proxy rejection, fail-fast invalid configuration, and route observability without endpoint or credential disclosure;
|
|
45
|
-
- canonical path and symbolic-link escape tests;
|
|
46
|
-
- relative-path privacy and error-path redaction tests;
|
|
47
|
-
- atomic create/update, optimistic hash, exact edit, and patch transaction tests;
|
|
48
|
-
- patch ambiguity, canonical collision, rollback, move, and delete tests;
|
|
49
|
-
- UTF-8 and binary handling;
|
|
50
|
-
- image content formatting;
|
|
51
|
-
- nested Git repository detection and helper suppression;
|
|
52
|
-
- explicit effective-policy versus daemon-ceiling fields in local/remote `project_overview`, reviewer/editor Git metadata through the fixed internal command boundary, and compatibility fallback for older daemon snapshots;
|
|
53
|
-
- fixed internal command execution with validated argv, no shell, isolated HOME/temp/cache, bounded output/deadlines, and ordinary cancellation/process tracking while arbitrary delegated process tools remain sandbox-gated;
|
|
54
|
-
- author-email privacy in `git_log`;
|
|
55
|
-
- isolated command HOME/temp/cache behavior;
|
|
56
|
-
- one-shot timeout, descendant process-group/tree termination including descendants that ignore graceful shutdown after the direct child has already exited, cancellation, and process-session interaction;
|
|
57
|
-
- layered fixed runtime diagnostics for filesystem, direct process, shell, managed-job storage, and resource availability; machine-readable execution guardrails that must keep CPU, memory, and network isolation marked unenforced unless an actual OS boundary is added;
|
|
58
|
-
- local resource CLI registration, permission checks, dynamic reload, state-path redaction, content non-disclosure, and the extracted runtime-resource boundary for bounded binary/UTF-8 reads plus generation authorization;
|
|
59
|
-
- real Ed25519 and RSA generation, idempotent reuse, public/private correspondence, mode enforcement, incomplete/mismatched/symlink rejection, and private-content non-disclosure;
|
|
60
|
-
- real-machine canonical-full sandbox acceptance for outside-workspace I/O, direct/shell execution, full environment inheritance, SSH prerequisites, temporary authorized-key writing, and detached cleanup without external state changes;
|
|
61
|
-
- deterministic injected atomic-replace failures, sustained transient Windows sharing contention beyond the old retry budget, bounded exponential delay selection, and repeated Windows full-sandbox runs;
|
|
62
|
-
- canonical named-profile repair and full-only tool exposure parity between local and Worker policy filters;
|
|
63
|
-
- managed-job non-executing staging, rejection of the removed terminal promotion path, cancel-before-start, trusted direct start, detachment, job-scoped temporary files, resource hash verification/redaction, discard capture, finally execution, descendant-tree escalation, token/snapshot-safe transition locks, runner process identity, spawn-without-PID rejection, asynchronous runner-error observability, plan scrubbing, PID-reuse-safe dead-runner recovery, and rejection of numeric-only runner records;
|
|
64
|
-
- daemon/startup locking, successfully-read corrupt-JSON recovery, and explicit propagation/preservation of oversized, symbolic-link, permission, and I/O failures;
|
|
65
|
-
- guarded state-root removal, unsafe state-root/workspace overlap rejection before creation, all-profile lock/daemon scanning, strict current-schema validation, corrupt-JSON isolation, and policy-origin persistence;
|
|
66
|
-
- no filename-based sensitive-file denial under unrestricted policy;
|
|
67
|
-
- shared local/Worker free-form log redaction, sensitive content under non-sensitive Worker keys, immutable local/Worker structured metadata, control-character handling, message/field bounds, suppression of both successful and failed per-tool events outside debug, service warning-level configuration, JSON-mode parity across event and direct logger methods with timestamp/stream/redaction assertions, current-schema reset, and bounded tail trimming;
|
|
68
|
-
- deterministic relay connection lifecycle coverage for transport construction/error/deadline, pre-handshake `welcome` validation, separate `hello_ack` authentication and `ready_ack` end-to-end readiness, session-bound probe return, pre-ready tool rejection, premature-ready rejection, identity/version mismatch, retryable Worker hello/readiness errors, fatal protocol errors, autonomous outage-reminder backoff, handshake/readiness/heartbeat timeout, brief-outage suppression, sustained-outage escalation, recovery summaries, and supersession;
|
|
69
|
-
- shared no-follow bounded-file reads for normal files, over-limit data, directories, and symbolic links;
|
|
70
|
-
- owner-only directory enforcement rejecting final symlinks, failing closed on POSIX chmod errors, verifying `0700`, and retaining Windows portability; Worker temporary-secret lifecycle coverage for process-start-bound names, valid stale-owner reclamation, ambiguous-owner retention, `0600` mode, deletion failures, and simultaneous deployment/cleanup failures;
|
|
71
|
-
- SARIF security-gate behavior for unknown findings, exact accepted rule/path matches, path mismatch rejection, rationale quality, and exception expiry;
|
|
72
|
-
- deterministic property tests over hostile browser-protocol byte strings, canonical/custom policy combinations, argv bounds/NULs, and a real direct process proving shell metacharacters remain literal argv;
|
|
73
|
-
- prototype-shaped command, action, role, profile, form-field, keyboard, and resource names proving that inherited object properties are never interpreted as dispatch or authority; current-schema malformed OAuth roles are repaired to disabled reviewer accounts with credential revocation;
|
|
74
|
-
- canonical Worker deployment URL extraction proving unrelated `/mcp`, `/healthz`, path-bearing, and wrong-name URLs cannot be persisted as upload evidence;
|
|
75
|
-
- byte-exact UTF-8 DOM-source truncation across emoji and Chinese partial-code-point boundaries, including equality between the reported byte count and the encoded returned source;
|
|
76
|
-
- independently injected service CLI status/install/start/stop/uninstall/remove paths, including provider failure, no selected workspace, no deployed Worker, aliases, and default output/exit adapters;
|
|
77
|
-
- CLI parsing, policy profiles, and client configuration boundaries;
|
|
78
|
-
- installed-package zero-argument startup with an isolated HOME/state/workspace and a service-manager trap, proving the smoke test reaches the controlled Wrangler boundary without querying, stopping, or replacing the operator's machine-global launchd/systemd/Scheduled Task service;
|
|
79
|
-
- live stdio MCP initialization with session instructions, capability resolution, discovery, calls, rich content, sessions, cancellation, managed-job acceptance, and a detached job/finally phase that survives stdio shutdown;
|
|
80
|
-
- P-256 root generation, root-certified ephemeral session issuance, macOS trust-broker build/signature checks, signed WebSocket preflight, one-time transactional nonce consumption, challenge transcript binding, wrong-root/session/tamper/expiry/replay rejection, and prevention of unauthenticated candidate churn;
|
|
81
|
-
- request-scoped effective authority and catalog-wide risk review; non-escalatable reviewer/editor/operator ceilings; authenticated-owner direct execution; control-plane root denial; external and sensitive path composition; persistence-target rejection; symbolic-link ancestor and patch-move canonicalization; owner-only browser/application/data-export and persistent-plan effects; account/client/refresh-family ownership of processes, output sessions, and jobs; delegated sandbox fail-closed behavior; legacy-lease non-consumption; and malformed-record rejection;
|
|
82
|
-
- root-certified ephemeral P-256 account-administration requests with origin/method/path/body/key/time/nonce binding, transactional one-time nonce consumption, removal of the long-lived administration secret, certificate/signature/body tamper rejection, nonce replay rejection, malformed nonce-state fail-closed behavior, one-megabyte response bounds, immediate oversized-response cancellation, and strict successful JSON-object validation;
|
|
83
|
-
- live local Worker OAuth registration, the unauthenticated `resource_metadata` challenge, protected-resource and authorization-server discovery, Streamable transport metadata, consent, URL-constructed `303` callbacks including the ChatGPT and hosted Claude redirect URIs with encoded state, PKCE, `offline_access`, form-encoded authorization-code and refresh-token exchanges, fifteen-minute access tokens, trusted single-account client binding, optional DPoP proof and token-family binding, unsupported critical-header rejection, proof-verification non-consumption, post-authorization replay consumption, invalid-grant cache-exhaustion resistance, independent client revocation, refresh-family idle/absolute limits, bounded consumed-token/revoked-family replay state, record-level schema validation, access/refresh rotation, idempotent identity-equivalent concurrent refresh recovery with identical replacement credentials and expiration, retry-budget throttling, post-grace replay with whole-family access/refresh revocation, account-version refresh revocation, authorization-code replay rejection, pending-registration throttling that excludes already authorized DCR clients, exact built-in ChatGPT/Grok browser origins, additive custom origins, unrelated-origin preflight rejection, no CORS response sharing for unrelated or opaque origins, opaque-origin authorization-form routing, exact per-request redirect-origin CSP with narrowly scoped Microsoft regional-consent and final Copilot Studio handoff exceptions, accessible credential-error rendering, protocol negotiation, HMAC-bound MCP session issuance, SSE content negotiation including `q=0`, immediate stream priming, keepalive and terminal-event framing, HTTP abort without implicit cancellation, explicit cancellation after response disconnect, shared Worker/local timeout ceilings, two-session same-id concurrency, sessionless same-id independence, session-scoped cancellation isolation, same-session duplicate rejection, daemon-backed session bootstrap, dynamic tool advertisement, rich content, candidate/probing/ready transitions, invalid readiness-result rejection, incumbent preservation until verified handover, daemon replacement, cancellation, malformed daemon JSON/non-object rejection, duplicate hello rejection, and unknown-message closure. The metadata/refresh contract is the path used by Claude DCR and Copilot Studio Dynamic discovery. The same integration runs an `editor` account against a canonical `full` daemon and proves that `server_info` and remote `project_overview` report effective `edit` authority while retaining the full daemon ceiling only in explicitly scoped fields.
|
|
84
|
-
- local runtime proof that one blocked tool handler does not serialize an independent handler, plus relay fault injection proving an undeliverable terminal result interrupts the ambiguous socket and enters reconnect backoff.
|
|
85
|
-
- a real headless-Chrome OAuth navigation regression with four cases: `form-action 'self'` blocks the first cross-origin callback, allowing only the registered callback blocks the regional redirect, allowing the registered and regional callbacks blocks the final Copilot Studio redirect, and the complete policy preserves `code` and `state` through all three cross-origin hops. Linux CI fails if Chrome is unavailable; other environments skip only this browser executable check while retaining the Worker CSP assertions.
|
|
86
|
-
|
|
87
|
-
`npm run ssh-key:test` exercises Ed25519/RSA generation, private-file permissions, public/private matching, existing-pair reuse, incomplete-pair rejection, symbolic-link denial, atomic registration under the startup lock, registry conflicts/capacity, complete two-file rollback after state-write failure, and explicit failure when sensitive-key cleanup remains incomplete.
|
|
88
|
-
|
|
89
|
-
## Opt-in live desktop and browser validation
|
|
90
|
-
|
|
91
|
-
The normal suite uses deterministic mocks for macOS Accessibility and an authenticated in-process extension peer for browser routing. Browser contract tests cover acknowledged protocol readiness, provisional pairing commit/rollback boundaries, strict extension IDs and matching loopback ports, stale-extension rejection, compatible replacement without premature displacement, clean rejection of in-flight direct and proxied requests, keepalive handling, trusted-input replay prevention after partial dispatch, fixed non-sensitive fallback reasons, privacy-safe public browser errors, an independent extension-side 32-operation ceiling, focus-safe screenshots, aggregate 64-frame/source/element budgets, bounded hostile DOM/text processing, contenteditable-secret suppression, partial-form failure reporting, stable refs, combined waits, and actionability failures. Before a release that changes local UI automation, run the macOS live smoke test on a machine where the invoking Node/terminal process has Accessibility permission:
|
|
92
|
-
|
|
93
|
-
```sh
|
|
94
|
-
npm run app-automation:live-test
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
It opens Calculator, activates it through the fixed JXA helper, verifies structured JSON output, inspects main-window Accessibility controls with menu recursion disabled, clicks the `One` control, and quits the application. It is intentionally excluded from CI because macOS TCC permission and a graphical login session are host state.
|
|
98
|
-
|
|
99
|
-
For deterministic release validation, perform an isolated-profile smoke test with the packaged unpacked extension; a Playwright persistent Chromium context is acceptable only as that isolated harness. When the requirement is specifically to prove control of the user's ordinary browser, the user must load the same unpacked directory into that known daily Chromium profile; status can verify the extension version/protocol and that Machine Bridge did not launch a browser, but cannot infer profile identity. Then use a localhost no-store fixture in a newly created tab. Do not enumerate, read, or mutate unrelated existing tabs. In both modes, inspect and reuse refs, exercise waits/forms/trusted input/open Shadow DOM/screenshots, verify final live DOM, and close the fixture tab.
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
- relay outage diagnostics and recovery: application-proxy versus OS-network scope, timestamped close/outage/recovery fields, fifteen-second maximum reconnect delay, heartbeat timeout, same-instance call continuation, Worker pong/welcome send failure, and `diagnose_runtime` relay history;
|
|
103
|
-
- recoverable managed-job terminal commits under injected result/status/delete/confirmation failures, result-only terminal reconstruction, private runtime/plan scrubbing, 24-hour staged-plan expiry, and minimal/full runner-environment inheritance;
|
|
104
|
-
- cross-process security-audit serialization, continuous hash-chain sequence, uninstall blocking for audit/authorization/job transition/recovery locks, workspace recovery-envelope validation, and symlink/multiple-hard-link rejection at owner state and operational logs;
|
|
105
|
-
- browser fixed identity, role-separated credentials, legacy migration, socket replacement/reconnect/timer cleanup, duplicate request rejection, response-delivery failure, and read-only broker load projection;
|
|
106
|
-
|
|
107
|
-
## Critical-module coverage gate
|
|
108
|
-
|
|
109
|
-
`npm run coverage:test` runs selected in-process and lightweight entrypoint fixtures under V8 coverage and enforces per-module function and branch baselines. The measured set includes policy, typed errors, call registration, execution middleware, lifecycle/observability, logging, Runtime/CLI orchestration, state persistence, relay lifecycle, managed-job lifecycle/runner/storage/projection, browser broker/direct-request/runtime-client routing and loopback upgrade handling, the independently injected service CLI adapter, Agent configuration/projection/skill discovery and bounded text reads, capability ranking, runtime path redaction, browser protocol/operation boundaries, runtime reporting/diagnostics/capability composition, and Worker OAuth state/authorization-page/pending/policy/error/JSON-RPC/WebSocket protocol modules. The full stdio and workerd OAuth/MCP integration still runs separately.
|
|
110
|
-
|
|
111
|
-
The gate deliberately reports each module rather than one aggregate percentage. New extracted pure/domain modules carry explicit branch floors, while the broad CLI entrypoint remains reported and locked independently. Worker pending calls and policy now have branch minima instead of function-only gates. A refactor may raise a threshold, but must not lower one merely to make CI green without an explicit audit explanation.
|
|
112
|
-
|
|
113
|
-
`npm run typecheck` combines strict Worker TypeScript with a focused `tsconfig.local.json` gate. High-risk JavaScript contracts opt in with `// @ts-check` and JSDoc types; the gate currently covers policy, call lifecycle, Agent configuration/path resolution, public projection, skill discovery, bounded Agent text reads, runtime path redaction, browser handshake parsing, capability ranking, monotonic deadlines, number/record normalization, and bounded metadata reads. `@ts-ignore`, implicit `any`, or unchecked parallel contract shapes are not accepted as migration shortcuts.
|
|
114
|
-
|
|
115
|
-
## Additional release checks
|
|
116
|
-
|
|
117
|
-
```sh
|
|
118
|
-
npm run privacy:history
|
|
119
|
-
npm run worker:dry-run
|
|
120
|
-
npm audit --audit-level=high
|
|
121
|
-
npm audit --omit=dev --audit-level=high
|
|
122
|
-
npm audit signatures
|
|
123
|
-
npm sbom --sbom-format cyclonedx
|
|
124
|
-
npm pack --dry-run
|
|
125
|
-
npm run version:check
|
|
126
|
-
npm run release-impact:check
|
|
127
|
-
npm run release:acceptance:verify
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
GitHub Actions uses the pinned Node 26/npm 12 baseline in three execution paths. Ubuntu runs `check:full` and verifies interactive candidate acceptance. macOS and Windows run `check:platform` plus the installed-package smoke test, preserving platform coverage without repeating every Worker, browser, and package integration fixture three times. A separate package-audit job scans reachable Git history, audits complete and production dependency graphs, verifies registry signatures and attestations, validates a CycloneDX SBOM under the runner temporary directory, repeats the isolated installation test, and performs a package dry run. Because Node 26 currently bundles npm 11, every npm execution job downloads the exact npm 12.0.1 tarball, rejects redirects, verifies its recorded SHA-512 SRI, and exposes that verified CLI through `GITHUB_PATH`. Separate pinned workflows validate governance titles, dependency changes, CodeQL, and OpenSSF Scorecard. Third-party Actions remain pinned to immutable commits, SARIF findings fail closed unless exactly reviewed, and source release creation requires successful push-triggered CI, CodeQL, Governance, and Scorecard runs for the exact `main` commit.
|
|
131
|
-
|
|
132
|
-
## Test design rules
|
|
133
|
-
|
|
134
|
-
- Tests should exercise the public boundary rather than only helper functions when practical.
|
|
135
|
-
- Lock, service lifecycle, state deletion, detached process, and credential changes require behavior-level concurrent or fault-injection coverage; source-string assertions are supplementary only.
|
|
136
|
-
- Every permission-expanding feature needs a denial test. Browser/application features also require a token/value/content non-disclosure assertion.
|
|
137
|
-
- Every bounded resource needs an over-limit test.
|
|
138
|
-
- Every multi-stage mutation needs a no-partial-commit test.
|
|
139
|
-
- Every remote call correlation or readiness change needs daemon replacement, incumbent-preservation, timeout, malformed-result, and cancellation coverage.
|
|
140
|
-
- Every durable workflow needs disconnect, cancellation, cleanup-failure, dead-runner, and plan-scrubbing coverage.
|
|
141
|
-
- Secret-bearing resource tests must assert absence of raw, path, base64, and hex forms from MCP-visible results.
|
|
142
|
-
- Logs and public metadata should be tested for absence of sensitive fields, arguments, outputs, and routine success noise—not only presence of expected fields.
|
|
143
|
-
- Cross-platform tests must avoid shell syntax, URL-path conversion, and executable-shim assumptions specific to one operating system.
|
|
144
|
-
|
|
145
|
-
## Privacy hygiene
|
|
146
|
-
|
|
147
|
-
Run `npm run privacy:check` before committing and before packaging. Run and review `npm run privacy:history` before release; local denylist findings may require an explicit owner decision because ordinary commits cannot remove public history. Developers should maintain an ignored owner-only `.privacy-denylist` for machine aliases, usernames, internal codenames, and other private identifiers that a generic scanner cannot know. See [Repository privacy hygiene](PRIVACY.md).
|
|
148
|
-
|
|
149
|
-
## Package manifest
|
|
150
|
-
|
|
151
|
-
`npm run package:test` executes a real silent `npm pack --dry-run --json`, requires clean parseable JSON, rejects sensitive local artifacts, credential-like file classes, and generated Worker type declarations, validates every packaged mode as `0644` or `0755`, and verifies that required runtime, script, browser-extension, privacy, governance, and release files are present. Exact runtime install-script approvals are version-bound, so a Wrangler/workerd refresh must also update the reviewed allowlist and pass a clean npm install without blocked-script warnings. `npm run install:test` requires npm 12, installs the real tarball from a package-free directory into an isolated global prefix with the documented options, verifies the packaged npm engine requirement, rejects blocked-script warnings, confirms optional `fsevents` is absent, verifies `--version`, then runs the installed CLI with zero arguments from an isolated workspace/state root. A fake Wrangler JavaScript entrypoint terminates at a controlled deployment boundary, so the probe exercises startup without mutating a live account. Package testing is full-plan-only; installation smoke runs in the Ubuntu full plan, the macOS/Windows platform plan, and package audit.
|
|
152
|
-
|
|
153
|
-
`npm run lint` uses ESLint as a semantic JavaScript correctness gate rather than a style formatter. It covers the Node CLI/runtime, repository scripts, tests, and packaged browser extension and rejects undefined identifiers in function bodies that `node --check` cannot detect. A dedicated lint-gate self-test proves that both Node and browser configurations reject a synthetic undefined binding while accepting the service-worker `importScripts` global. A focused `shell:test` requires Wrangler to run through the current Node executable and its package JavaScript entrypoint rather than a `.cmd` or shell shim. Architecture tests require `shell:test`, `lint:test`, `lint`, and `install:test` to remain in the complete check pipeline and reject non-exact direct dependency ranges.
|
|
154
|
-
|
|
155
|
-
The stdio integration test also sends an oversized line, verifies bounded rejection, and confirms that the next valid request is still processed. Worker request-body tests use pull-counted streams and require immediate `ReadableStream.cancel()` after a declared or observed limit violation, proving that byte retention and execution work are both bounded.
|
|
156
|
-
|
|
157
|
-
## Architecture and documentation regression checks
|
|
158
|
-
|
|
159
|
-
`npm run architecture:test` runs independent module-boundary, repository-hygiene, browser/security-structure, and release/documentation-contract checks. It validates the explicit fast/full check plans, local import graph, domain/adapter direction, module headroom budgets, immutable workflow references, package-script targets, documentation links, publication inventory, and selected security-shape invariants. Critical coverage thresholds include every extracted OAuth refresh, token issuance, stream subscription, static metadata/routing, quota guard, edge logger, and filesystem-state module. These source-shape checks are deliberately supplementary: behavior, denial, race, and fault-injection tests remain authoritative for semantic guarantees. Tests must not depend on a fixed CI job count when the actual invariant is that every npm job uses the same verified bootstrap.
|
|
160
|
-
## Resumable MCP delivery coverage
|
|
161
|
-
|
|
162
|
-
`npm run mcp-resumption:test` directly exercises stream cursor parsing, OAuth-token/MCP-session isolation, immediate pending/terminal polls, active and completed replay, Worker-restart ambiguity, result-size fallback, SHA-256 tamper detection, transient persistence failure, expiry, capacity, completed-record eviction, and the four-row normal stream persistence budget.
|
|
163
|
-
|
|
164
|
-
`npm run worker-runtime-infrastructure:test` verifies outer-Worker stream ownership, stripping of caller-supplied internal headers, bounded descriptor/subscribe adaptation, fixed two-request Durable Object budgets, bounded transient subscription retries, outer metadata/404/invalid-method bypass, stateful burst limiting, structured and duplicate-suppressed gateway failures, coalesced alarm writes, sequence-zero/sequence-one framing, subscription-error closure, subscriber replacement, registration races, non-daemon socket isolation, and the shared two-minute/64-stream/1.5-MiB contract. It also models the production event-lifecycle boundary: event-mode registration must return without a terminal Promise or early settlement, while later success, daemon rejection, explicit cancellation, timeout, send failure, result transformation, persistence failure, and same-instance reconnect each produce one terminal result and remove pending indexes. Deadline tests deliberately use a scheduler that never fires callbacks, advance the monotonic clock, and prove that event-boundary sweeps expire both attached operation deadlines and detached reconnect deadlines without leaking request keys. A direct runtime-alarm coordinator test verifies earliest-pending scheduling, alarm removal when no deadline remains, event-entry expiry before rescheduling, and bounded reporting when Durable Object alarm storage fails. The same suite also proves that direct same-instance handover transfers an attached call and preserves its remaining timeout budget. `npm run worker:integration-test` performs the real Wrangler path: keep SSE open while a concurrent `server_info` succeeds and explicit cancellation reaches the matching daemon call; connect a verified same-instance replacement while the incumbent still owns an in-flight call and prove transfer occurs before incumbent close; disconnect after sequence zero; reject another session; recover with GET plus `Last-Event-ID`; and prove a sequence-one acknowledgement is not delivered twice. Managed-job integration treats `__proto__`, `constructor`, `toString`, and `valueOf` environment/resource-map keys as ordinary own data while retaining duplicate-key rejection. Static architecture checks forbid a stream-initiation `dispatchJsonRpc` Promise, `resumption.attach`, Durable Object `waitUntil`, or Promise-valued recovery state. The parser accumulates complete SSE events and does not assume network chunk boundaries. CORS coverage requires both `DPoP` and `Last-Event-ID`.
|