machine-bridge-mcp 2.0.0 → 3.0.0-beta.102
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +1142 -0
- package/CONTRIBUTING.md +23 -25
- package/GOVERNANCE.md +2 -2
- package/README.md +58 -20
- package/SECURITY.md +161 -120
- package/SUPPORT.md +1 -1
- package/browser-extension/broker-auth.js +83 -0
- package/browser-extension/broker-liveness.js +35 -0
- package/browser-extension/browser-error-boundary.js +96 -0
- package/browser-extension/browser-operations.js +1456 -101
- package/browser-extension/devtools-input.js +195 -34
- package/browser-extension/devtools-observation.js +429 -0
- package/browser-extension/devtools-session.js +48 -0
- package/browser-extension/manifest.json +4 -3
- package/browser-extension/page-automation.js +578 -118
- package/browser-extension/pairing-bootstrap.js +42 -0
- package/browser-extension/pairing.js +28 -12
- package/browser-extension/service-worker.js +126 -106
- package/docs/AGENT_CONTEXT.md +13 -10
- package/docs/ARCHITECTURE.md +159 -67
- package/docs/AUDIT.md +1302 -4
- package/docs/CLIENTS.md +19 -6
- package/docs/COMPUTER_USE.md +297 -0
- package/docs/ENGINEERING.md +72 -13
- package/docs/GETTING_STARTED.md +18 -20
- package/docs/LOCAL_AUTHORIZATION.md +115 -72
- package/docs/LOCAL_AUTOMATION.md +27 -21
- package/docs/LOGGING.md +40 -19
- package/docs/MANAGED_JOBS.md +37 -34
- package/docs/MULTI_ACCOUNT.md +98 -37
- package/docs/OPERATIONS.md +145 -51
- package/docs/OVERVIEW.md +14 -11
- package/docs/POLICY_REFERENCE.md +71 -3
- package/docs/PRIVACY.md +41 -2
- package/docs/PROJECT_STANDARDS.md +29 -6
- package/docs/RELEASING.md +238 -64
- package/docs/TESTING.md +150 -39
- package/docs/THREAT_MODEL.md +164 -67
- package/docs/TOOL_REFERENCE.md +653 -60
- package/docs/UPGRADING.md +78 -18
- package/native/macos/MachineBridgeBackgroundInput.swift +1051 -0
- package/native/macos/MachineBridgeBackgroundInputSmokeFixture.swift +295 -0
- package/native/macos/MachineBridgeTrustBroker.swift +233 -0
- package/package.json +94 -16
- package/scripts/accepted-candidate-tarball.mjs +77 -0
- package/scripts/candidate-runtime-store.mjs +93 -0
- package/scripts/check-plan.mjs +73 -3
- package/scripts/check-runner.mjs +129 -17
- package/scripts/commit-message-check.mjs +5 -2
- package/scripts/consumer-package-security.mjs +293 -0
- package/scripts/coverage-check.mjs +251 -15
- package/scripts/coverage-generation.mjs +41 -0
- package/scripts/coverage-range-merge.mjs +41 -0
- package/scripts/foreground-daemon-recovery.mjs +88 -0
- package/scripts/generate-policy-reference.mjs +28 -5
- package/scripts/generate-tool-reference.mjs +1 -1
- package/scripts/generate-worker-types.mjs +21 -11
- package/scripts/github-backlog.mjs +11 -10
- package/scripts/github-push.mjs +62 -16
- package/scripts/github-release-asset.mjs +58 -0
- package/scripts/github-release.mjs +241 -132
- package/scripts/global-package-installation.mjs +68 -0
- package/scripts/hardened-npm-session.mjs +42 -0
- package/scripts/install-published-prerelease.mjs +198 -0
- package/scripts/local-release-acceptance.mjs +103 -45
- package/scripts/macos-background-input-smoke.mjs +515 -0
- package/scripts/network-retry.mjs +8 -1
- package/scripts/npm-global-prefix.mjs +27 -0
- package/scripts/npm-publication-policy.mjs +17 -0
- package/scripts/official-mcp-conformance.mjs +267 -0
- package/scripts/persistent-activation-process.mjs +101 -0
- package/scripts/prepare-pinned-npm.mjs +12 -69
- package/scripts/prerelease-activation.mjs +160 -0
- package/scripts/privacy-check.mjs +14 -6
- package/scripts/promotion-digest.mjs +128 -0
- package/scripts/publish-npm.mjs +260 -0
- package/scripts/published-release.mjs +132 -0
- package/scripts/release-acceptance.mjs +62 -54
- package/scripts/release-browser-extension-store.mjs +172 -0
- package/scripts/release-candidate-manifest.mjs +52 -0
- package/scripts/release-channel.mjs +106 -0
- package/scripts/release-diagnostic.mjs +41 -0
- package/scripts/release-impact-check.mjs +12 -22
- package/scripts/release-oauth-canary-core.mjs +325 -0
- package/scripts/release-oauth-canary-evidence.mjs +100 -0
- package/scripts/release-oauth-canary.mjs +127 -0
- package/scripts/release-publication-guard.mjs +67 -0
- package/scripts/release-soak.mjs +284 -0
- package/scripts/release-state.mjs +1 -1
- package/scripts/run-checks.mjs +44 -7
- package/scripts/run-worker-dry-run.mjs +21 -0
- package/scripts/sarif-security-gate.mjs +2 -1
- package/scripts/sbom-check.mjs +106 -0
- package/scripts/start-release-candidate.mjs +267 -44
- package/scripts/syntax-check.mjs +36 -14
- package/scripts/verification-generation-guard.mjs +15 -0
- package/scripts/verification-idle-sleep-guard.mjs +37 -0
- package/scripts/verification-state.mjs +108 -0
- package/scripts/wrangler-command-lifecycle.mjs +115 -0
- package/src/local/account-access.mjs +13 -1
- package/src/local/account-admin-response.mjs +92 -0
- package/src/local/account-admin.mjs +52 -19
- package/src/local/agent-context-projection.mjs +26 -7
- package/src/local/agent-context.mjs +88 -49
- package/src/local/agent-skill-discovery.mjs +16 -5
- package/src/local/app-automation-macos-jxa.mjs +350 -0
- package/src/local/app-automation.mjs +873 -163
- package/src/local/application-capability-projection.mjs +24 -0
- package/src/local/authority-context.mjs +106 -0
- package/src/local/autostart-log-maintenance.mjs +36 -0
- package/src/local/browser-bridge-http.mjs +5 -3
- package/src/local/browser-bridge.mjs +109 -31
- package/src/local/browser-broker-auth-http.mjs +67 -0
- package/src/local/browser-broker-auth.mjs +98 -0
- package/src/local/browser-broker-routes.mjs +63 -20
- package/src/local/browser-broker-server.mjs +17 -7
- package/src/local/browser-command.mjs +79 -30
- package/src/local/browser-computer-observation-service.mjs +266 -0
- package/src/local/browser-extension-identity.mjs +50 -0
- package/src/local/browser-extension-path.mjs +22 -0
- package/src/local/browser-extension-protocol.mjs +50 -11
- package/src/local/browser-operation-service.mjs +147 -117
- package/src/local/browser-pairing-grant.mjs +109 -0
- package/src/local/browser-pairing-http.mjs +36 -0
- package/src/local/browser-pairing-launch.mjs +58 -0
- package/src/local/browser-pairing-store.mjs +85 -48
- package/src/local/browser-request-registry.mjs +40 -14
- package/src/local/browser-request-settlement.mjs +78 -0
- package/src/local/browser-resource-input.mjs +74 -0
- package/src/local/browser-trusted-input-health.mjs +63 -0
- package/src/local/call-authority.mjs +21 -0
- package/src/local/call-capacity.mjs +45 -0
- package/src/local/call-registry-drain.mjs +54 -0
- package/src/local/call-registry.mjs +30 -15
- package/src/local/capability-observer.mjs +5 -0
- package/src/local/capability-ranking.mjs +3 -2
- package/src/local/child-process-settlement.mjs +132 -0
- package/src/local/cli-account-admin.mjs +40 -6
- package/src/local/cli-activate.mjs +162 -0
- package/src/local/cli-local-admin.mjs +20 -45
- package/src/local/cli-options.mjs +12 -13
- package/src/local/cli-ready-output.mjs +52 -0
- package/src/local/cli-service.mjs +91 -11
- package/src/local/cli.mjs +232 -150
- package/src/local/computer-use-application-observation.mjs +224 -0
- package/src/local/computer-use-arguments.mjs +270 -0
- package/src/local/computer-use-deadline.mjs +50 -0
- package/src/local/computer-use-dispatch-settlement.mjs +40 -0
- package/src/local/computer-use-expectation.mjs +171 -0
- package/src/local/computer-use-observation.mjs +769 -0
- package/src/local/computer-use-recovery.mjs +82 -0
- package/src/local/computer-use-result-budget.mjs +145 -0
- package/src/local/computer-use-snapshot-store.mjs +67 -0
- package/src/local/computer-use.mjs +2255 -0
- package/src/local/daemon-http-relay-auth.mjs +26 -0
- package/src/local/daemon-http-relay-connection.mjs +298 -0
- package/src/local/daemon-http-relay-request.mjs +64 -0
- package/src/local/daemon-http-relay-sequence.mjs +49 -0
- package/src/local/daemon-process.mjs +40 -7
- package/src/local/delegated-process-sandbox.mjs +148 -0
- package/src/local/device-identity.mjs +156 -49
- package/src/local/device-root-provider.mjs +81 -0
- package/src/local/directory-metadata.mjs +47 -0
- package/src/local/doctor-reporting.mjs +23 -0
- package/src/local/durable-process-spec.mjs +80 -0
- package/src/local/errors.mjs +25 -15
- package/src/local/exclusive-file.mjs +74 -26
- package/src/local/execution-limits.mjs +9 -0
- package/src/local/execution-routing.mjs +276 -0
- package/src/local/execution-surface.mjs +23 -0
- package/src/local/file-mutation-coordinator.mjs +47 -0
- package/src/local/file-snapshot-preservation.mjs +24 -0
- package/src/local/filesystem-identity.mjs +54 -0
- package/src/local/fixed-process-environment.mjs +21 -0
- package/src/local/full-access-test.mjs +31 -13
- package/src/local/git-commit.mjs +69 -0
- package/src/local/git-config-safety.mjs +55 -0
- package/src/local/git-log-parser.mjs +41 -0
- package/src/local/git-metadata-boundary.mjs +77 -0
- package/src/local/git-metadata-tree-safety.mjs +59 -0
- package/src/local/git-operation-state.mjs +19 -0
- package/src/local/git-service.mjs +165 -30
- package/src/local/hardened-npm-download-timeout.mjs +46 -0
- package/src/local/hardened-npm-download.mjs +109 -0
- package/src/local/hardened-npm-extract.mjs +20 -0
- package/src/local/hardened-npm-verification.mjs +104 -0
- package/src/local/hardened-npm.mjs +199 -0
- package/src/local/job-runner.mjs +244 -89
- package/src/local/lifecycle.mjs +6 -0
- package/src/local/log.mjs +19 -45
- package/src/local/macos-background-input.mjs +398 -0
- package/src/local/macos-idle-sleep-assertion.mjs +65 -0
- package/src/local/macos-trust-broker.mjs +404 -0
- package/src/local/managed-job-cancellation.mjs +42 -0
- package/src/local/managed-job-capacity.mjs +16 -0
- package/src/local/managed-job-directory-generation.mjs +60 -0
- package/src/local/managed-job-directory.mjs +75 -0
- package/src/local/managed-job-durable-process.mjs +49 -0
- package/src/local/managed-job-lock.mjs +46 -14
- package/src/local/managed-job-plan.mjs +38 -14
- package/src/local/managed-job-projection.mjs +23 -15
- package/src/local/managed-job-retention.mjs +128 -0
- package/src/local/managed-job-runner-claim.mjs +70 -0
- package/src/local/managed-job-runner.mjs +35 -10
- package/src/local/managed-job-storage.mjs +22 -6
- package/src/local/managed-job-terminal-maintenance.mjs +40 -0
- package/src/local/managed-job-terminal.mjs +150 -0
- package/src/local/managed-jobs.mjs +424 -287
- package/src/local/npm-cli.mjs +42 -0
- package/src/local/npm-environment.mjs +37 -0
- package/src/local/operation-authorization.mjs +68 -324
- package/src/local/operation-risk.mjs +51 -4
- package/src/local/owner-state-lock.mjs +118 -0
- package/src/local/package-identity.mjs +9 -0
- package/src/local/patch.mjs +20 -18
- package/src/local/path-inspection.mjs +23 -0
- package/src/local/policy.mjs +19 -0
- package/src/local/private-toolchain-integrity.mjs +54 -0
- package/src/local/process-execution.mjs +87 -75
- package/src/local/process-foreground-timeout.mjs +50 -0
- package/src/local/process-identity.mjs +41 -7
- package/src/local/process-nonreplayable-settlement.mjs +50 -0
- package/src/local/process-result-projection.mjs +22 -0
- package/src/local/process-session-events.mjs +47 -0
- package/src/local/process-session-remote-activity.mjs +10 -0
- package/src/local/process-session-termination.mjs +73 -0
- package/src/local/process-sessions.mjs +144 -112
- package/src/local/process-tracker.mjs +140 -13
- package/src/local/process-tree-ownership-types.d.ts +37 -0
- package/src/local/process-tree-ownership.mjs +57 -0
- package/src/local/process-tree-signal.mjs +34 -0
- package/src/local/process-tree-snapshot.mjs +77 -0
- package/src/local/process-tree-supervisor.mjs +69 -0
- package/src/local/process-tree.mjs +11 -53
- package/src/local/project-metadata.mjs +19 -6
- package/src/local/relay-call-recovery.mjs +58 -38
- package/src/local/relay-connection-classification.mjs +131 -0
- package/src/local/relay-connection-support.mjs +91 -0
- package/src/local/relay-connection.mjs +179 -272
- package/src/local/relay-diagnostics.mjs +91 -0
- package/src/local/relay-heartbeat.mjs +119 -0
- package/src/local/relay-liveness.mjs +109 -0
- package/src/local/relay-peer-diagnostics.mjs +29 -0
- package/src/local/release-runtime-lock.mjs +18 -0
- package/src/local/remote-activity-idle-sleep-guard.mjs +77 -0
- package/src/local/remote-configuration.mjs +48 -0
- package/src/local/resilient-relay-connection.mjs +178 -0
- package/src/local/resource-admission-diagnostics.mjs +52 -0
- package/src/local/resource-admission-policy.mjs +115 -0
- package/src/local/resource-admission.mjs +339 -0
- package/src/local/resource-build-root.mjs +83 -0
- package/src/local/resource-cargo-concurrency.mjs +38 -0
- package/src/local/resource-cmake-concurrency.mjs +42 -0
- package/src/local/resource-command-concurrency.mjs +37 -0
- package/src/local/resource-command-profile.mjs +176 -0
- package/src/local/resource-coordinator-accounting.mjs +21 -0
- package/src/local/resource-cpu-window.mjs +20 -0
- package/src/local/resource-disk-headroom.mjs +13 -0
- package/src/local/resource-elastic-memory.mjs +19 -0
- package/src/local/resource-elastic-request.mjs +36 -0
- package/src/local/resource-foreground-wait.mjs +29 -0
- package/src/local/resource-go-concurrency.mjs +43 -0
- package/src/local/resource-gradle-concurrency.mjs +57 -0
- package/src/local/resource-host-cache.mjs +39 -0
- package/src/local/resource-host-darwin.mjs +54 -0
- package/src/local/resource-host-linux.mjs +35 -0
- package/src/local/resource-host-sample-file.mjs +23 -0
- package/src/local/resource-host-snapshot.mjs +99 -0
- package/src/local/resource-lease-accounting.mjs +119 -0
- package/src/local/resource-light-command.mjs +6 -0
- package/src/local/resource-make-concurrency.mjs +42 -0
- package/src/local/resource-maven-concurrency.mjs +38 -0
- package/src/local/resource-ninja-command-concurrency.mjs +20 -0
- package/src/local/resource-ninja-concurrency.mjs +28 -0
- package/src/local/resource-operations.mjs +26 -10
- package/src/local/resource-pressure.mjs +67 -0
- package/src/local/resource-probe-command.mjs +35 -0
- package/src/local/resource-process-admission.mjs +59 -0
- package/src/local/resource-process-ancestry-cache.mjs +43 -0
- package/src/local/resource-process-ancestry.mjs +32 -0
- package/src/local/resource-process-priority.mjs +15 -0
- package/src/local/resource-project-key.mjs +53 -0
- package/src/local/resource-pytest-concurrency.mjs +33 -0
- package/src/local/resource-release-control-classification.mjs +14 -0
- package/src/local/resource-release-control-executable.mjs +70 -0
- package/src/local/resource-release-control-workspace.mjs +41 -0
- package/src/local/resource-request-contract.mjs +30 -0
- package/src/local/resource-script-classification.mjs +44 -0
- package/src/local/resource-shell-analysis.mjs +58 -0
- package/src/local/resource-staging-recovery.mjs +97 -0
- package/src/local/resource-swift-concurrency.mjs +31 -0
- package/src/local/resource-transaction-lock.mjs +189 -0
- package/src/local/resource-wait.mjs +48 -0
- package/src/local/resource-waiters.mjs +139 -0
- package/src/local/resource-xcode-command.mjs +7 -0
- package/src/local/resource-xcode-concurrency.mjs +34 -0
- package/src/local/resource-xcode-non-build.mjs +19 -0
- package/src/local/runtime-activation.mjs +700 -0
- package/src/local/runtime-activity-projection.mjs +48 -0
- package/src/local/runtime-capabilities.mjs +48 -15
- package/src/local/runtime-diagnostic-state.mjs +14 -0
- package/src/local/runtime-diagnostics.mjs +40 -13
- package/src/local/runtime-info-projection.mjs +60 -0
- package/src/local/runtime-info-relay-projection.mjs +21 -0
- package/src/local/runtime-paths.mjs +2 -1
- package/src/local/runtime-process-routing.mjs +33 -0
- package/src/local/runtime-relay-connection-options.mjs +44 -0
- package/src/local/runtime-relay-control.mjs +98 -0
- package/src/local/runtime-relay.mjs +26 -50
- package/src/local/runtime-reporting.mjs +37 -21
- package/src/local/runtime-resource-service.mjs +77 -0
- package/src/local/runtime-tool-handlers.mjs +13 -10
- package/src/local/runtime.mjs +244 -208
- package/src/local/secure-file.mjs +73 -20
- package/src/local/security-audit-dispatch.mjs +35 -0
- package/src/local/security-audit-log.mjs +215 -0
- package/src/local/security-audit-state.mjs +139 -0
- package/src/local/security-audit-storage.mjs +135 -0
- package/src/local/security-audit-warning.mjs +31 -0
- package/src/local/security-audit-worker.mjs +87 -0
- package/src/local/service-convergence.mjs +42 -1
- package/src/local/service-definition.mjs +24 -0
- package/src/local/service-environment.mjs +18 -10
- package/src/local/service-owner.mjs +146 -0
- package/src/local/service-ownership.mjs +17 -0
- package/src/local/service-restart-handoff.mjs +64 -0
- package/src/local/service-restart-scheduler.mjs +49 -0
- package/src/local/service-runtime-convergence.mjs +52 -0
- package/src/local/service-runtime.mjs +105 -0
- package/src/local/service-status.mjs +60 -0
- package/src/local/service.mjs +385 -92
- package/src/local/shell.mjs +39 -19
- package/src/local/ssh-key.mjs +158 -42
- package/src/local/state-inventory.mjs +50 -24
- package/src/local/state-owner-lock-inventory.mjs +23 -0
- package/src/local/state-root-owned-namespaces.mjs +83 -0
- package/src/local/state-root-retirement.mjs +89 -0
- package/src/local/state.mjs +386 -96
- package/src/local/stdio.mjs +96 -66
- package/src/local/support-state-projection.mjs +30 -0
- package/src/local/system-network-route.mjs +76 -0
- package/src/local/systemd-removal.mjs +20 -0
- package/src/local/tool-executor.mjs +85 -20
- package/src/local/tool-result-boundary.mjs +51 -0
- package/src/local/toolchain-operation-lock.mjs +41 -0
- package/src/local/tools.mjs +7 -5
- package/src/local/trusted-executable.mjs +53 -0
- package/src/local/trusted-git-executable.mjs +34 -0
- package/src/local/trusted-github-cli.mjs +24 -0
- package/src/local/windows-service-convergence.mjs +49 -0
- package/src/local/windows-service.mjs +52 -45
- package/src/local/worker-deployment-fingerprint.mjs +102 -0
- package/src/local/worker-deployment.mjs +48 -60
- package/src/local/worker-health.mjs +12 -4
- package/src/local/worker-secret-file.mjs +37 -17
- package/src/local/workspace-file-service.mjs +156 -239
- package/src/local/workspace-file-transaction.mjs +189 -0
- package/src/local/workspace-search.mjs +55 -0
- package/src/local/wrangler-toolchain/package-lock.json +1505 -0
- package/src/local/wrangler-toolchain/package.json +23 -0
- package/src/local/wrangler-toolchain-verification.mjs +135 -0
- package/src/local/wrangler-toolchain.mjs +188 -0
- package/src/shared/access-contract.json +7 -1
- package/src/shared/activation-recovery.mjs +49 -0
- package/src/shared/admin-auth.d.mts +2 -1
- package/src/shared/admin-auth.mjs +3 -3
- package/src/shared/authority-revocation.d.mts +9 -0
- package/src/shared/authority-revocation.mjs +28 -0
- package/src/shared/daemon-auth.d.mts +11 -0
- package/src/shared/daemon-auth.mjs +17 -0
- package/src/shared/device-session-auth.d.mts +20 -0
- package/src/shared/device-session-auth.mjs +51 -0
- package/src/shared/foreground-timeout.d.mts +15 -0
- package/src/shared/foreground-timeout.mjs +70 -0
- package/src/shared/log-redaction.d.mts +9 -0
- package/src/shared/log-redaction.mjs +51 -0
- package/src/shared/mcp-protocol.d.mts +27 -0
- package/src/shared/mcp-protocol.mjs +275 -0
- package/src/shared/project-overview-projection.d.mts +4 -0
- package/src/shared/project-overview-projection.mjs +96 -0
- package/src/shared/relay-contract.json +28 -0
- package/src/shared/result-projection.d.mts +2 -1
- package/src/shared/result-projection.mjs +13 -2
- package/src/shared/server-metadata.json +15 -9
- package/src/shared/tool-argument-validation.d.mts +17 -0
- package/src/shared/tool-argument-validation.mjs +325 -0
- package/src/shared/tool-call-capacity.d.mts +41 -0
- package/src/shared/tool-call-capacity.mjs +59 -0
- package/src/shared/tool-catalog.json +626 -57
- package/src/worker/access.ts +12 -0
- package/src/worker/account-admin.ts +55 -33
- package/src/worker/authority-revocations.ts +174 -0
- package/src/worker/authority.ts +52 -6
- package/src/worker/daemon-auth.ts +49 -68
- package/src/worker/daemon-channel.ts +36 -0
- package/src/worker/daemon-http-auth.ts +63 -0
- package/src/worker/daemon-http-channel.ts +120 -0
- package/src/worker/daemon-http-controller.ts +163 -0
- package/src/worker/daemon-http-protocol.ts +62 -0
- package/src/worker/daemon-http-registry.ts +82 -0
- package/src/worker/daemon-last-observation.ts +30 -0
- package/src/worker/daemon-liveness.ts +8 -6
- package/src/worker/daemon-ready-dispatch.ts +17 -0
- package/src/worker/daemon-ready-messages.ts +73 -0
- package/src/worker/daemon-ready-waiters.ts +79 -0
- package/src/worker/daemon-recovery-budget.ts +13 -0
- package/src/worker/daemon-registry.ts +58 -0
- package/src/worker/daemon-relay-diagnostics.ts +127 -0
- package/src/worker/daemon-socket-attachment.ts +55 -0
- package/src/worker/daemon-sockets.ts +72 -62
- package/src/worker/daemon-status.ts +38 -0
- package/src/worker/device-session-verifier.ts +129 -0
- package/src/worker/dpop.ts +157 -0
- package/src/worker/durable-process-timeout.ts +29 -0
- package/src/worker/errors.ts +57 -0
- package/src/worker/http.ts +112 -26
- package/src/worker/index.ts +446 -440
- package/src/worker/mcp-access.ts +57 -0
- package/src/worker/mcp-controller.ts +188 -0
- package/src/worker/mcp-http-accept.ts +11 -0
- package/src/worker/mcp-http-contract.ts +322 -0
- package/src/worker/mcp-initialization-compat.ts +141 -0
- package/src/worker/mcp-jsonrpc.ts +11 -29
- package/src/worker/mcp-removed-protocol.ts +17 -0
- package/src/worker/mcp-response-proxy.ts +135 -0
- package/src/worker/mcp-response-stream.ts +65 -0
- package/src/worker/mcp-stale-schema-compat.ts +57 -0
- package/src/worker/mcp-stream-proxy-contract.ts +48 -0
- package/src/worker/mcp-tool-call-input.ts +23 -0
- package/src/worker/nonce-store.ts +33 -35
- package/src/worker/oauth-authorization-page.ts +21 -1
- package/src/worker/oauth-client-admin.ts +52 -0
- package/src/worker/oauth-client-contract.ts +38 -0
- package/src/worker/oauth-controller.ts +107 -47
- package/src/worker/oauth-field-contract.ts +31 -0
- package/src/worker/oauth-record-contract.ts +7 -0
- package/src/worker/oauth-refresh-authority.ts +27 -0
- package/src/worker/oauth-refresh-exchange.ts +162 -0
- package/src/worker/oauth-refresh-families.ts +130 -27
- package/src/worker/oauth-refresh-persistence.ts +116 -0
- package/src/worker/oauth-state.ts +33 -18
- package/src/worker/oauth-store-validation.ts +131 -0
- package/src/worker/oauth-token-derivation.ts +33 -0
- package/src/worker/oauth-token-issuance.ts +119 -0
- package/src/worker/oauth-tokens.ts +56 -190
- package/src/worker/observability.ts +38 -5
- package/src/worker/pending-admission.ts +15 -0
- package/src/worker/pending-call-capacity.ts +108 -0
- package/src/worker/pending-call-contract.ts +42 -5
- package/src/worker/pending-call-deadlines.ts +75 -0
- package/src/worker/pending-calls.ts +131 -125
- package/src/worker/runtime-alarm-storage.ts +37 -0
- package/src/worker/runtime-alarm.ts +136 -0
- package/src/worker/server-info-activity.ts +36 -0
- package/src/worker/server-info-tool-delivery.ts +15 -0
- package/src/worker/server-info.ts +168 -0
- package/src/worker/tool-catalog.ts +47 -1
- package/src/worker/tool-timeout.ts +75 -14
- package/src/worker/websocket-protocol.ts +26 -2
- package/src/worker/worker-edge-guard.ts +90 -0
- package/src/worker/worker-edge-log.ts +65 -0
- package/src/worker/worker-entry.ts +52 -0
- package/src/worker/worker-mcp-config.ts +23 -0
- package/src/worker/worker-metadata.ts +48 -0
- package/src/worker/worker-rate-limit-key.ts +30 -0
- package/src/worker/worker-runtime-config.ts +20 -0
- package/src/worker/worker-static-routes.ts +54 -0
- package/src/worker/worker-task-lifetime.ts +18 -0
- package/tsconfig.local.json +17 -1
- package/wrangler.jsonc +13 -0
- package/src/local/cli-approval.mjs +0 -117
- package/src/local/operation-state-lock.mjs +0 -92
- package/src/worker/mcp-session.ts +0 -72
package/docs/LOCAL_AUTOMATION.md
CHANGED
|
@@ -23,7 +23,7 @@ The extension works with the current profile and supports:
|
|
|
23
23
|
- populating file inputs from registered local resource files;
|
|
24
24
|
- visible-tab screenshots.
|
|
25
25
|
|
|
26
|
-
Current support targets Chrome, Chromium, Microsoft Edge, Brave, Vivaldi, and compatible Chromium browsers. The extension must be loaded into the user profile to be controlled; it is not installed into Playwright or an isolated automation profile. After every Machine Bridge upgrade, reload
|
|
26
|
+
Current support targets Chrome, Chromium, Microsoft Edge, Brave, Vivaldi, and compatible Chromium browsers. The extension must be loaded into the user profile to be controlled; it is not installed into Playwright or an isolated automation profile. Ordinary checkout/global installations expose their package `browser-extension` directory. A versioned local release candidate instead exposes an owner-only stable `release-channels/browser-extension` directory whose path survives candidate-runtime pruning; activation updates its exact candidate files only after Worker/daemon convergence and commits `manifest.json` last. After every Machine Bridge upgrade, reload that same unpacked path so packaged scripts, protocol, and permissions match the runtime. Users who previously loaded an unpacked extension directly from a beta.72-or-earlier versioned candidate-runtime directory must perform one **Load unpacked** migration to the current reported `extension_path`; later local-candidate upgrades keep the directory stable. The current extension contract requires protocol 3 with broker `hello_ack`; the badge and pairing page report success only after protocol/version/capability validation. Pairing material is persisted only after that acknowledgement, an invalid candidate cannot overwrite the previous pairing, and `browser status` reports the expected packaged build, authenticated connected build/protocol/capabilities, and `extension_reload_required`; exact version equality is required in addition to protocol and capabilities. Browser-internal pages, extension stores, some PDF/plugin viewers, inaccessible cross-origin frames, and pages restricted by enterprise policy remain unscriptable.
|
|
27
27
|
|
|
28
28
|
## One-time browser setup
|
|
29
29
|
|
|
@@ -33,14 +33,14 @@ Keep `machine-mcp` running, then use either the MCP tool `pair_browser_extension
|
|
|
33
33
|
machine-mcp browser setup
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
-
The command prints the packaged extension directory and
|
|
36
|
+
The command prints the packaged extension directory and keeps the reported pairing URL sanitized, but the URL it actually opens is a process-owned one-shot loopback page whose 30-second bootstrap exists only in the fragment. In the browser:
|
|
37
37
|
|
|
38
38
|
1. open the extensions page;
|
|
39
39
|
2. enable Developer mode;
|
|
40
|
-
3. choose **Load unpacked** and select the printed `browser-extension` directory;
|
|
40
|
+
3. choose **Load unpacked** and select the printed `browser-extension` directory; for a local release candidate this is the stable release-channel directory, not the disposable/versioned runtime package directory;
|
|
41
41
|
4. return to the local pairing page.
|
|
42
42
|
|
|
43
|
-
The first pairing completes automatically. If the extension is already paired to different local state, the page asks for an explicit user gesture: click the Machine Bridge extension icon while the pairing page is active to confirm replacement. This prevents another localhost page from silently overwriting an established pairing. The extension badge shows `ON` when connected; clicking the icon from another page opens the saved local pairing/status page.
|
|
43
|
+
The first pairing completes automatically. If the extension is already paired to different local state, the page asks for an explicit user gesture: click the Machine Bridge extension icon while the pairing page is active to confirm replacement. This prevents another localhost page from silently overwriting an established pairing. The extension badge shows `ON` when connected; clicking the icon from another page opens the saved local pairing/status page. A candidate upgrade does not bypass this browser-local ownership confirmation.
|
|
44
44
|
|
|
45
45
|
`Load unpacked` is the self-hosted/development installation path. A mass-market release should package the same extension source as a signed Chrome Web Store and/or Microsoft Edge Add-ons build, so ordinary users install it through the browser store without enabling Developer mode. This repository change does not publish a store listing.
|
|
46
46
|
|
|
@@ -55,18 +55,22 @@ The broker is machine-global rather than workspace-global. One local owner liste
|
|
|
55
55
|
|
|
56
56
|
## Browser tools
|
|
57
57
|
|
|
58
|
-
- `browser_status` reports broker role, authenticated extension protocol/version/capabilities, reload state, supported operations, pairing URL, and extension path without returning the pairing token.
|
|
59
|
-
- `pair_browser_extension` opens the local pairing page and returns setup steps.
|
|
58
|
+
- `browser_status` reports broker role, authenticated extension protocol/version/capabilities, reload state, supported operations, pairing URL, and extension path without returning the pairing token. Concurrent callers may share one broker-startup operation, but each request re-checks its own cancellation after shared startup settles.
|
|
59
|
+
- `pair_browser_extension` opens the local pairing page and returns setup steps. Cancellation is checked immediately before the OS launcher; once the launcher invocation is attempted, timeout/cancellation/response loss is an unknown page-open outcome, so inspect the browser before opening the pairing page again.
|
|
60
60
|
- `browser_list_tabs` lists current tabs.
|
|
61
|
-
- `browser_manage_tabs` creates, activates, or closes a selected tab.
|
|
62
|
-
- `browser_get_source` returns a bounded iterative DOM serialization. `max_bytes` is one aggregate request budget across at most 64 accessible frames; omitted frames and node/byte truncation are explicit.
|
|
63
|
-
- `browser_inspect_page` returns snapshot version
|
|
61
|
+
- `browser_manage_tabs` creates, activates, or closes a selected tab. Once the corresponding Chrome mutation API is invoked, a rejected or lost response is not proof that the tab mutation did not happen; inspect the tab inventory before retrying.
|
|
62
|
+
- `browser_get_source` returns a bounded iterative DOM serialization only when raw markup is genuinely required. Treat the entire result as sensitive: serialized source can expose hidden bootstrap state, session/account identifiers, authentication material, or other values that are not visible in the rendered page. Prefer `browser_inspect_page` for routine semantic/actionability work. `max_bytes` is one aggregate request budget across at most 64 accessible frames; omitted frames and node/byte truncation are explicit.
|
|
63
|
+
- `browser_inspect_page` returns snapshot version 3 with one aggregate `max_elements` budget, at most 64 accessible frames, a 100,000-node per-frame scan ceiling, bounded page-controlled strings, URL-userinfo redaction, and explicit scan/frame truncation. Each control includes a reusable `ref` plus visibility, enabled/editable state, viewport geometry, and a per-document epoch used by Computer Use to reject stale same-URL replacements. References are held in a 10,000-entry per-frame LRU; navigation, element replacement, or bounded eviction makes an older ref stale and requires a new inspection.
|
|
64
64
|
- `browser_wait` waits until all supplied URL, load-state, page-text, and element-state conditions are true.
|
|
65
|
-
- `browser_action` performs one structured navigation or page action. Navigation accepts absolute `http`, `https`, or `file` URLs; script/data schemes are rejected. Pointer and keyboard actions default to `input_mode: auto`, which uses fixed trusted DevTools input in the top frame and falls back to DOM only
|
|
65
|
+
- `browser_action` performs one structured navigation or page action. Navigation accepts absolute `http`, `https`, or `file` URLs; script/data schemes are rejected. Pointer and keyboard actions default to `input_mode: auto`, which uses fixed trusted DevTools input in the top frame and falls back to DOM only before side-effecting trusted preparation/input begins. Once a page mutation, Chrome mutation, or trusted-input boundary has been attempted, response loss has an unknown outcome and automatic replay is forbidden. `trusted` always forbids fallback; `dom` never attaches the debugger.
|
|
66
66
|
- `browser_fill_form` fills up to 200 fields and can submit once. If a later field fails, the error states how many earlier fields may already have changed without returning their values.
|
|
67
67
|
- `browser_upload_files` sets a file input from up to eight registered local resources. Caller filenames must be safe single-component names; derived names have controls and separators removed. MIME overrides must be canonical media types.
|
|
68
68
|
- `browser_screenshot` returns native MCP image content, temporarily activates the selected tab only when required, restores the previous active tab when safe, and never focuses another browser window.
|
|
69
69
|
|
|
70
|
+
Every mutating browser RPC carries explicit dispatch settlement across the local broker. A timeout, disconnect, extension replacement, malformed mutation response, or transport send failure after dispatch was attempted is projected as a fixed non-retryable unknown outcome. Read-only transport failures remain ordinary retryable/unavailable or result-limit failures. This distinction prevents a model or host from replaying a mutation merely because delivery of its result was interrupted.
|
|
71
|
+
|
|
72
|
+
For stateful GUI trajectories, prefer the higher-level `computer_observe` / `computer_act` pair. `computer_observe` publishes a bounded snapshot and, when available, native image content; `computer_act` consumes that exact snapshot as one-shot mutation authority, performs preflight, dispatches once, observes post-state, and reports dispatch and effect settlement separately. See [Computer Use](COMPUTER_USE.md) for snapshot identity, visual-point constraints, verification, continuation, and retry guidance.
|
|
73
|
+
|
|
70
74
|
Selectors can use the `ref` returned by inspection, CSS, ID, field name, label text, visible text, ARIA/implicit role, placeholder, and a zero-based match index. `ref` cannot be combined with other fields and becomes stale after navigation or element replacement. Non-ref selectors that match multiple controls fail explicitly unless `index` disambiguates them. The fixed page module traverses open Shadow DOM roots; closed shadow roots remain inaccessible. For frame-specific work, inspect all frames first and then pass `frame_id` to an action. Trusted input currently targets the top frame because DevTools coordinates are top-level; use `input_mode: dom` for an explicitly selected subframe.
|
|
71
75
|
|
|
72
76
|
## Sensitive form values and files
|
|
@@ -82,20 +86,22 @@ Then use `value_resource` for a text field or `resources` for `browser_upload_fi
|
|
|
82
86
|
|
|
83
87
|
## Application tools
|
|
84
88
|
|
|
85
|
-
- `list_local_applications` discovers installed applications or launchers.
|
|
86
|
-
- `open_local_application` opens an application, URL, or document through the OS launcher.
|
|
89
|
+
- `list_local_applications` discovers installed applications or launchers. It is read-only and available across policy profiles; restricted profiles still receive projected external paths rather than raw absolute paths.
|
|
90
|
+
- `open_local_application` opens an application, URL, or document through the OS launcher. Cancellation is checked immediately before launch; once the process invocation is attempted, timeout/cancellation/response loss is an unknown launch outcome and must be inspected before retrying.
|
|
87
91
|
- `inspect_local_application` returns a bounded macOS Accessibility tree.
|
|
88
|
-
- `operate_local_application` performs a structured Accessibility action.
|
|
92
|
+
- `operate_local_application` performs a structured Accessibility action. Local-resource resolution remains pre-dispatch, while mutating JXA/native helpers classify response loss after process start as a non-replayable unknown outcome.
|
|
89
93
|
|
|
90
|
-
macOS UI inspection and actions require Accessibility permission for the Node/Machine Bridge process. Application discovery and opening are available on supported desktop platforms; structured UI inspection currently targets macOS. The application backend uses fixed JXA implementation code
|
|
94
|
+
macOS UI inspection and actions require Accessibility permission for the Node/Machine Bridge process. Application discovery and opening are available on supported desktop platforms; structured UI inspection currently targets macOS. The application backend uses fixed package-owned JXA implementation code from `src/local/app-automation-macos-jxa.mjs`, separate from the Node orchestration in `app-automation.mjs`. Read-only JXA operations require a non-empty valid JSON result; mutating JXA/native operations additionally distinguish a definite pre-spawn/preflight failure from response loss after process start, so ambiguous local-process failure is never used as replay evidence. Fixed launch/Accessibility/visual mutation-unknown settlements are public and non-retryable. The caller selects only an application, structured selector, action, and optional bounded value; NUL-containing action text is rejected. `include_values` never returns values for secure-text roles or controls whose metadata indicates passwords, tokens, one-time codes, or payment-card secrets.
|
|
91
95
|
|
|
92
96
|
Menu-bar and menu subtrees are not recursively expanded by default. This keeps main-window controls within the element/time budget for applications with large localized menu hierarchies. Pass `include_menus: true` to `inspect_local_application` or `operate_local_application` only when the target is a menu item.
|
|
93
97
|
|
|
94
98
|
## Capability discovery and automatic selection
|
|
95
99
|
|
|
96
|
-
`resolve_task_capabilities` rescans instruction files, skills, explicit/automatic package commands, and relevant local automation metadata on every call. It ranks matching skills and commands, optionally loads the best skill, and
|
|
100
|
+
`resolve_task_capabilities` rescans instruction files, skills, explicit/automatic package commands, policy-visible tool definitions, and relevant local automation metadata on every call. It ranks matching skills and commands, optionally loads the best skill, and returns set-level route advice across direct Bash/argv, process sessions, managed jobs, files/Git, browser, applications, protected resources, and diagnostics. This is not a restriction layer: `exec_command` remains the general shell escape hatch under an effective shell-capable policy.
|
|
101
|
+
|
|
102
|
+
Application inventory is a baseline read-only discovery capability and is consulted for every authenticated policy profile. The inventory is cached briefly and refreshed after a bounded interval. A refresh enters that cache only after a final cancellation check, so a caller cancelled at the end of an asynchronous scan cannot publish stale discovery for later requests. A task that directly names an installed app does not need generic “app/window” wording. Per-root discovery failures are returned as bounded `warnings`, and capability resolution reports `application_discovery.available`, warning count, truncation, and a coarse error class instead of silently treating an unreadable inventory as an empty successful scan. Restricted profiles may discover names/launcher identifiers, but raw external absolute paths remain projected and open/inspect/operate capabilities remain independently gated. A matching `known_refresh_fingerprint` can omit unchanged static context without skipping the fresh capability scan.
|
|
97
103
|
|
|
98
|
-
This is the strongest reliable server-side automation boundary available through MCP: discovery, refresh, ranking, and progressive skill loading are automatic. The MCP host still owns the model loop and decides whether a recommended tool is exposed, approved, or invoked. Machine Bridge cannot force ChatGPT web or another host to make a call that the host declines.
|
|
104
|
+
This is the strongest reliable server-side automation boundary available through MCP: discovery, refresh, ranking, route-set construction, and progressive skill loading are automatic. The MCP host still owns the model loop and decides whether a recommended tool is exposed, approved, or invoked. Machine Bridge cannot force ChatGPT web or another host to make a call that the host declines.
|
|
99
105
|
|
|
100
106
|
## Security model
|
|
101
107
|
|
|
@@ -103,12 +109,12 @@ The browser extension has broad page access because generic source inspection an
|
|
|
103
109
|
|
|
104
110
|
The implementation reduces avoidable risk as follows:
|
|
105
111
|
|
|
106
|
-
-
|
|
112
|
+
- `list_local_applications` is read-only baseline inventory; application launch, Accessibility inspection/actions, computer-use UI control, and browser tools remain independently gated and currently require `full` authority;
|
|
107
113
|
- no arbitrary evaluation, caller-provided script source, or caller-selected DevTools method is accepted; trusted input exposes only fixed `Input.dispatchMouseEvent`, `Input.dispatchKeyEvent`, and `Input.insertText` sequences;
|
|
108
|
-
- loopback HTTP validates `Host`;
|
|
109
|
-
- runtime-
|
|
110
|
-
- the pairing token
|
|
111
|
-
- an established extension pairing cannot be silently replaced by
|
|
114
|
+
- loopback HTTP validates `Host`; broker-auth challenge issuance also requires a fixed internal request header, so ordinary cross-origin web requests cannot consume the bounded challenge registry without a preflight the broker does not authorize;
|
|
115
|
+
- extension and runtime WebSockets use separate role-bound HMAC exchanges: clients verify a broker server proof before upgrade, then send a one-time client proof under a five-second monotonic deadline; the long-lived owner-only tokens are HMAC keys and never WebSocket bearer subprotocols; extension sockets additionally require the canonical `chrome-extension://` origin for the pinned 32-character Chromium extension ID;
|
|
116
|
+
- public pairing status and the HTTP pairing document are token-free; an explicit pair action first binds a one-shot OS-random loopback listener and puts a 30-second bootstrap only in that temporary URL fragment, the `document_start` content script strips it before page scripts and retains it only in the extension isolated world, and a two-step `/pair-auth` exchange first requires an init HMAC under the fragment secret before allocating server state, then requires the broker to prove owner-token-derived knowledge before it releases the extension token; successful grants are one-time, and neither bootstrap nor token is emitted in MCP results or logs;
|
|
117
|
+
- an established extension pairing cannot be silently replaced by a public localhost page; manual replacement requires a fresh fragment bootstrap retained by the isolated content script plus an extension-action click;
|
|
112
118
|
- arguments, form values, page source, screenshots, and results are not operational log data;
|
|
113
119
|
- message, aggregate source/element/frame, form-field, upload, DOM-node/text, concurrency, proxy-route, actionability, and request-deadline limits are enforced; ambiguous selectors, stale refs, hidden/disabled/edit-blocked controls, moving targets, and obscured pointer targets fail explicitly;
|
|
114
120
|
- MCP cancellation clears local and broker pending state and propagates a cancellation signal to the extension; an action already delivered to a page or application may still have completed;
|
package/docs/LOGGING.md
CHANGED
|
@@ -12,7 +12,7 @@ Logs should answer:
|
|
|
12
12
|
4. Is an infrastructure, protocol, deployment, or local service problem requiring action?
|
|
13
13
|
5. When debug logging is explicitly enabled, which bounded implementation event should be correlated?
|
|
14
14
|
|
|
15
|
-
Logs are not a command history or content audit
|
|
15
|
+
Logs are not a command history or content transcript. The local security audit provides a SHA-256 hash chain over coarse operation metadata without recording command text, paths, contents, form values, or output. Risky-operation target correlation is additionally HMAC-keyed with a fresh per-daemon runtime key before it reaches persistent audit state, so common paths or short command targets cannot be recovered by comparing the stored fingerprint against an offline SHA-256 dictionary; the fingerprint is intentionally stable only within one daemon runtime, not a cross-restart target identity. Retention is bounded by both 4,096 events and 4 MiB; byte-driven eviction advances the chain anchor so the retained suffix remains verifiable, and diagnostics expose both ceilings. Audit inputs are projected to an allowlist before crossing to a dedicated Worker thread; batching, atomic replacement, and `fsync` never delay tool-result delivery on the daemon event loop. The audit worker verifies the complete chain on first access and reuses that state only while the regular-file identity and timestamps remain unchanged. Cross-process writes or external alteration force a secure reread and complete verification before another write. Remote owner-only `diagnose_runtime.runtime.security_audit` reports worker readiness, queue depth/capacity, dropped records, retained entries, event/byte limits, and chain health; non-owner `server_info` receives only the authority-hidden health projection, while local stdio/owner diagnostics expose the detailed snapshot. Before the Worker reports readiness, health is explicitly `audit_initializing`; the daemon thread does not synchronously read the chain. The queue is not a write-ahead log: a process or operating-system crash before persistence can lose queued events, and `dropped_records` counts only failures observed during the current process lifetime. The chain detects local alteration but is not a remote immutable ledger and is not a substitute for OS isolation.
|
|
16
16
|
|
|
17
17
|
## Levels
|
|
18
18
|
|
|
@@ -25,27 +25,31 @@ The CLI accepts:
|
|
|
25
25
|
```
|
|
26
26
|
|
|
27
27
|
Foreground mode defaults to `info` and human-readable text. Platform autostart services use `warn` with newline-delimited JSON. Foreground operators can select JSON explicitly with `--log-format json`.
|
|
28
|
+
In JSON mode, every logger entry point—including direct level methods and the persistent daemon-ready transition—emits exactly one timestamped JSON object per line. No operational method may silently fall back to the human formatter.
|
|
29
|
+
Structured-field sanitizers use null-prototype intermediate maps, so prototype-shaped input keys such as `__proto__` and `constructor` remain ordinary bounded data instead of mutating the sanitizer object model. Sensitive key/value redaction is applied before serialization exactly as for other fields.
|
|
28
30
|
|
|
29
|
-
Human mode treats the message as the primary interface: it uses a natural-language explanation and includes only bounded diagnostic fields that add meaning. It does not repeat the machine event key. JSON mode retains the stable `event` field for ingestion and correlation. Event identifiers such as `relay.tool_result.discarded` are implementation contracts for structured logs, not text that should be shown as the warning itself.
|
|
31
|
+
Human mode treats the message as the primary interface: it uses a natural-language explanation and includes only bounded diagnostic fields that add meaning. It does not repeat the machine event key. JSON mode retains the stable `event` field for ingestion and correlation. Routine `info`/`warn`/`error` events do not carry raw process IDs or managed-job IDs; exact ownership identity remains available through explicit status/diagnostic/job surfaces where it is the requested result. Event identifiers such as `relay.tool_result.discarded` are implementation contracts for structured logs, not text that should be shown as the warning itself.
|
|
30
32
|
|
|
31
33
|
| Level | Intended events |
|
|
32
34
|
|---|---|
|
|
33
35
|
| `error` | The operation or service cannot continue without intervention |
|
|
34
|
-
| `warn` | Persistent relay outage, malformed/oversized protocol data, supersession,
|
|
36
|
+
| `warn` | Persistent relay outage, malformed/oversized protocol data, supersession, service/autostart degradation, or failure to establish the optional macOS remote-activity idle-sleep guard |
|
|
35
37
|
| `info` | Deployment/startup transitions, authenticated relay readiness, and recovery after a visible outage |
|
|
36
38
|
| `debug` | Transport open/close codes and reasons, brief self-healing interruptions, retry timing, per-tool outcomes, and shortened correlation IDs |
|
|
37
39
|
|
|
38
40
|
## Worker deployment and health event policy
|
|
39
41
|
|
|
40
|
-
Wrangler upload and `/healthz` verification are logged as separate state transitions. A successful upload followed by ambiguous health failure must say that the deployment fingerprint was retained and that retry will verify rather than redeploy. Existing-state timeout, proxy, TLS, network, and temporary server failures must say that no deployment was attempted. Only a persistent stale identity/version result may emit the warning that the same Worker is being redeployed.
|
|
42
|
+
Wrangler upload and `/healthz` verification are logged as separate state transitions. A successful upload followed by ambiguous health failure must say that the deployment fingerprint was retained and that retry will verify rather than redeploy. Existing-state timeout, proxy, TLS, network, and temporary server failures must say that no deployment was attempted. Only a persistent stale identity/version result may emit the ordinary warning that the same Worker is being redeployed. Candidate activation has one narrower exception: an explicit device-authentication rejection after current-version health may emit one warning that the same Worker is being redeployed with the current identity. Routine deployment progress/health logs omit both the workspace-derived Worker name and `workers.dev` endpoint; the explicit ready/connection handoff may print the endpoint because delivering that value is the command purpose. Warnings never include device key ID, public key, signature, certificate, nonce, or secret values.
|
|
41
43
|
|
|
42
44
|
Health routing records only `direct` or `proxy` at debug level. Proxy URLs, credentials, request headers, Worker secrets, and raw response bodies are never fields. Repeated per-attempt health failures remain debug-only; the terminal startup error contains one user-readable classification and corrective commands.
|
|
43
45
|
|
|
46
|
+
Autostart log-schema migration is evidence-preserving. A missing `.log-schema` is first-run state and a successfully read older schema may intentionally reset obsolete-format daemon logs. If an existing marker is oversized, inaccessible, symbolic/hard-linked, or fails any bounded/path-identity read, trimming stops before either daemon log is truncated or the marker is rewritten. Storage failure is not evidence that logs are empty, obsolete, or safe to discard.
|
|
47
|
+
|
|
44
48
|
Autostart installation and daemon startup may report the names of allowlisted proxy/custom-CA environment variables that were saved or loaded. Their values, source environment, proxy endpoints, embedded credentials, and certificate paths are prohibited log fields. Windows task failures use stable reasons such as `task_create_failed` or `task_status_unavailable`; localized command output is retained only in an explicitly requested service-command result, not repeated in default startup warnings.
|
|
45
49
|
|
|
46
50
|
## Relay connection event policy
|
|
47
51
|
|
|
48
|
-
A TCP/WebSocket `open` event is only transport availability, and `hello_ack` proves only authenticated bidirectional control traffic. The daemon is reported as ready only after a random Worker probe returns through the ordinary local dispatcher and
|
|
52
|
+
A TCP/WebSocket `open` event is only transport availability, and `hello_ack` proves only authenticated bidirectional control traffic. The daemon is reported as ready only after a random Worker probe returns through the ordinary local dispatcher and ordinary authenticated result path and the Worker sends `ready_ack`.
|
|
49
53
|
|
|
50
54
|
Brief network interruptions are expected on laptop network changes, Worker deployment, proxy rotation, and ordinary internet transport. They are handled as follows:
|
|
51
55
|
|
|
@@ -61,9 +65,13 @@ Brief network interruptions are expected on laptop network changes, Worker deplo
|
|
|
61
65
|
- recovery after a visible outage produces one information summary with a human-readable duration and attempt count; exact seconds and error classes remain debug-only;
|
|
62
66
|
- a verified replacement is a distinct warning and permanently stops the older daemon;
|
|
63
67
|
- failure to receive `hello_ack` within the handshake deadline, or `ready_ack` within the independent end-to-end readiness deadline, terminates the candidate socket and retries;
|
|
64
|
-
-
|
|
68
|
+
- ready transports send protocol-level WebSocket Ping every five seconds and classify ten seconds without inbound transport proof as `relay_transport_timeout`; while the daemon is scheduling-responsive, one probe interval plus that silence threshold bounds arbitrary black-hole detection to fifteen seconds, leaving reconnect/result-settlement headroom inside the ordinary twenty-second hosted execution default;
|
|
69
|
+
- a separate twenty-five-second application heartbeat refreshes Worker daemon activity and retains a seventy-five-second application-silence timeout; protocol-level Pong therefore cannot mask a Worker application path that has stopped replying. The Worker queues the heartbeat's JSON `pong` before Durable Object alarm inspection or mutation, then performs one explicit coalesced schedule, so storage latency is not allowed to sit ahead of application-liveness acknowledgement;
|
|
70
|
+
- a late local transport-watchdog tick is classified as `runtime.event_loop.stall`, sends a fresh transport probe, and defers disconnect for a bounded recovery interval instead of being mislabeled as immediate remote failure; a macOS sleep/wake interval may legitimately produce this warning without a daemon fault. An authorized, schema-valid remote tool call enters the bounded macOS idle-sleep guard only after policy/account/operation authorization and argument validation succeed; the shared assertion remains active for the full handler lifetime, remote process sessions extend it through child settlement, and the inactivity grace starts only after the last owned daemon-side activity settles. If the fixed macOS assertion child cannot be established, `runtime.idle_sleep_guard.unavailable` records only a coarse `error_class`, never argv, paths, PID, tool name, tool content, session identity, or job identity. Remote account managed-job runners use the same fixed assertion primitive but own it themselves only after runner-claim confirmation and persisted account ownership validation; local managed jobs do not acquire this remote-continuity assertion. The remote runner fallback stderr diagnostic is the fixed text `managed job idle-sleep assertion unavailable` plus a sanitized coarse `error_class`, without job name/id, workspace path, argv, environment, or captured output.
|
|
71
|
+
|
|
72
|
+
A WebSocket close code such as `1006` means the transport ended without a normal close handshake. If it recovers inside ten seconds, the warning-level service log is intentionally silent and the authenticated `daemon.relay_transport` snapshot is the post-event evidence surface. It is useful for debug diagnosis but not useful as the default user message. It is not evidence that the daemon process restarted. Worker `daemon_transport_error` / `daemon_liveness_timeout` messages and their 1012 close frames are likewise retryable connection conditions, not upgrade instructions. Only an unknown/incompatible Worker error, authentication failure, or identity/version mismatch may produce the fatal protocol/configuration log and daemon exit. Default logs therefore describe the affected layer, duration, classification, and recovery behavior rather than printing raw close envelopes.
|
|
65
73
|
|
|
66
|
-
|
|
74
|
+
Streamed-call diagnostics are deliberately coarse. MCP `2026-07-28` request/response-stream ownership and the Worker pending-call registry are memory-only; there is no protocol-session, terminal-result, subscriber, or replay store. Worker event counters are scoped to the current isolate and say so in `metric_scope`, while `server_info` exposes only bounded current pending-call/capacity state. These diagnostics do not prove public SSE consumption or MCP-host receipt. Logs and `server_info` must not include tool arguments, terminal results, command text, request keys, account identifiers, raw call IDs, raw connection generations, mirrored parameter values, private paths, or subscriber payloads. A stale-generation result is counted as unmatched rather than logged with its envelope.
|
|
67
75
|
|
|
68
76
|
Examples:
|
|
69
77
|
|
|
@@ -81,9 +89,9 @@ All per-tool starts, successes, failures, cancellations, timing, and expected la
|
|
|
81
89
|
|
|
82
90
|
The layered repository check runner follows the same noise rule. Green child-task output is discarded after the child exits; only task name and elapsed time are printed. Failed tasks expose bounded head/tail stdout and stderr diagnostics. `MBM_CHECK_VERBOSE=1` is an explicit operator choice to stream raw child output and is not used by default or CI.
|
|
83
91
|
|
|
84
|
-
A completed local result is normally sent on the
|
|
92
|
+
A completed local result is normally sent on the current verified daemon channel. If that channel disappears, the runtime may queue the bounded result envelope during the shared two-minute same-daemon reconnect window. This relay-layer queue is in-memory continuity for the same daemon and already-dispatched call, not client-visible MCP replay. Debug output records only a shortened call ID and queue/reconnect counts. During same-instance resume reconciliation, `relay.calls.reconciled` may add only the aggregate `missing_resumed_calls` count. If the replacement channel is ready and the daemon proves a waiting call was never active and has no retained result, the Worker may emit `daemon.calls.redelivered_after_proven_non_delivery` with only an aggregate `calls` count before retransmitting that same call inside its original deadline. If safe redelivery is unavailable, `daemon.calls.not_received_after_reconnect` retains the same aggregate-only `calls` shape for the no-side-effect fallback. Neither event logs raw resumed/missing call IDs, tool names, arguments, account identity, authorization values, or results. After the same daemon process completes readiness, retained-result redelivery emits one recovery event; a different process cannot inherit the result. Closing the public MCP `2026-07-28` HTTP response stream cancels that request through a random internal capability; the control request contains no Authorization or DPoP header, and the capability is not logged. Tool arguments, mirrored header values, validation values, and result content are never logged.
|
|
85
93
|
|
|
86
|
-
Debug per-tool fields may include tool name, duration, coarse outcome class, and a shortened random call identifier. The identifier is for correlating adjacent local events and is not a stable audit identifier. Authorization failures
|
|
94
|
+
Debug per-tool fields may include tool name, duration, coarse outcome class, and a shortened random call identifier. When a process-like call is rejected by cooperative resource admission before spawn, the failure event may additionally include only the enumerated `resource_admission_reason` and coarse `resource_pressure_state`; it never includes argv, cwd, project identity, lease identity, host process names, or sampled command output. The identifier is for correlating adjacent local events and is not a stable audit identifier. Authorization failures return a stable denial code and bounded guidance; the current runtime never creates approval IDs or temporary elevation leases. Daemon logs still omit normalized targets and request arguments.
|
|
87
95
|
|
|
88
96
|
## Data that is never logged
|
|
89
97
|
|
|
@@ -93,7 +101,7 @@ The implementation omits:
|
|
|
93
101
|
- stdin, stdout, and stderr;
|
|
94
102
|
- file, patch, image, and temporary-file content;
|
|
95
103
|
- OAuth request bodies;
|
|
96
|
-
- account passwords,
|
|
104
|
+
- account passwords, root/session signatures, device private keys, authorization codes, access tokens, refresh tokens, DPoP proofs, and obsolete-lease migration target material;
|
|
97
105
|
- registered resource values and source paths;
|
|
98
106
|
- browser pairing tokens, page URLs/source, DOM metadata, form values, uploaded file bytes, and screenshots;
|
|
99
107
|
- application names, Accessibility trees, selectors, and entered values;
|
|
@@ -103,13 +111,15 @@ Unexpected infrastructure failures are reduced to coarse error classes in normal
|
|
|
103
111
|
|
|
104
112
|
## Local automation events
|
|
105
113
|
|
|
106
|
-
Browser broker ownership, extension connection, and persistent unavailability are infrastructure state. Ordinary tab/source/action/form/upload/screenshot calls remain per-tool debug events and never log their arguments or results. Pairing tokens are excluded from all structured fields.
|
|
114
|
+
Browser broker ownership, extension connection, and persistent unavailability are infrastructure state. Ordinary tab/source/action/form/upload/screenshot calls remain per-tool debug events and never log their arguments or results. Pairing tokens are excluded from all structured fields. Computer Use observation/action logs follow the same rule: snapshot IDs, semantic refs, Accessibility/DOM evidence, screenshots, diffs, continuation mappings, target identity, coordinates, and verification content are tool-result data, not operational log fields. A post-dispatch transport/process ambiguity may contribute only its tool name, bounded error code/retryability, duration, and the existing coarse audit risk projection.
|
|
107
115
|
|
|
108
|
-
Application discovery and Accessibility operations follow the same rule: permission or runtime failures are classified, while app names, UI trees, selectors, and
|
|
116
|
+
Application discovery and Accessibility operations follow the same rule: permission or runtime failures are classified, while app names, UI trees, selectors, values, captured window bytes, window identifiers/bounds, process generations, and native-input coordinates are not operational log data. The experimental macOS visual backend may expose only coarse configured/probed/error-class state through the requested Computer Use result; native helper stdout/stderr and private WindowServer details are never copied into daemon logs.
|
|
109
117
|
|
|
110
118
|
## Bounding and redaction
|
|
111
119
|
|
|
112
|
-
Messages, strings, object depth, object key counts, array item counts, and serialized field payloads are bounded. Control characters and Unicode display controls are neutralized. Fields with secret-like names and path-like keys are recursively redacted. Free-form sanitization covers generic private-key headers, AWS/GitHub/GitLab/npm/Slack/Google/live-payment/API token forms, JWT-shaped values, URLs with embedded credentials, email addresses, and user-home paths.
|
|
120
|
+
Messages, strings, object depth, object key counts, array item counts, and serialized field payloads are bounded. Tool-argument validation reports only a bounded tool name, JSON Pointer path, schema keyword, and constraint message; it never includes the rejected value. Control characters and Unicode display controls are neutralized. Fields with secret-like names and path-like keys are recursively redacted. Free-form sanitization covers generic private-key headers, AWS/GitHub/GitLab/npm/Slack/Google/live-payment/API token forms, JWT-shaped values, URLs with embedded credentials, email addresses, and user-home paths.
|
|
121
|
+
|
|
122
|
+
Local and Worker free-form strings use the same portable value sanitizer. Worker fields are therefore inspected by content even when their key is not secret-shaped. Both structured loggers assign their authoritative metadata after sanitizing caller fields. Local `timestamp`, `level`, `component`, `message`, and `event`, plus Worker `timestamp`, `level`, `component`, and `event`, therefore cannot be forged or replaced by an event payload. Local-only recursive path-key redaction and environment-derived home aliases remain additional protections around the portable rules.
|
|
113
123
|
|
|
114
124
|
The logger exposes two intentional plain-output boundaries. `safePlain` sanitizes operational guidance and diagnostic text. Raw `plain` output is reserved for explicitly requested credentials or local paths whose display is the command's purpose; callers must not pass external exception text or tool content to it.
|
|
115
125
|
|
|
@@ -117,7 +127,10 @@ This is defense in depth, not content classification. Unknown, split, transforme
|
|
|
117
127
|
|
|
118
128
|
## Structured lifecycle events
|
|
119
129
|
|
|
120
|
-
|
|
130
|
+
|
|
131
|
+
Security-audit enqueue/persistence failures are warning-level operational faults, but repeated failures are rate-limited per event class. The first warning is emitted immediately; duplicates within one minute are suppressed, and the next emitted warning reports the suppressed count. Warning fields contain only the tool name and a coarse error class, never the rejected audit payload or principal identifiers.
|
|
132
|
+
|
|
133
|
+
The local execution middleware emits bounded events such as `tool.call.started`, `tool.call.completed`, `tool.call.failed`, `tool.call.slow`, and `tool.call.cancel_requested`. Stable fields include a shortened call ID, tool name, origin, duration, error code, and retryability. The Worker emits JSON events for HTTP failures and daemon socket errors. Unexpected HTTP failures carry only a low-cardinality route class (`mcp`, `daemon`, `oauth`, `admin`, or `other`) plus a coarse error class; the raw request pathname is not an operational log field. Structured values still pass through field-name and value redaction; JSON format is not permission to log arguments or results. A retained stale-socket cleanup failure uses `daemon.socket.cleanup.failed` with only `error_class`; it contains no socket identity, endpoint, arguments, or results.
|
|
121
134
|
|
|
122
135
|
`server_info` is the operational metrics surface. Local metrics include lifecycle state, active and maximum calls, oldest-call age, active-process ownership, per-tool duration buckets, and error-code counts. Worker metrics include HTTP status classes, pending internal/request-key indexes, per-tool outcomes, daemon candidate/authenticated/ready/disconnected event counts, current authenticated/probing/ready socket counts, and protocol-error counts. Metrics contain counts and bounded identifiers, not request arguments or result contents.
|
|
123
136
|
|
|
@@ -130,17 +143,25 @@ logs/daemon.out.log
|
|
|
130
143
|
logs/daemon.err.log
|
|
131
144
|
```
|
|
132
145
|
|
|
133
|
-
Existing files are opened without following symbolic links where supported and tail-trimmed on UTF-8/line boundaries before startup. Background services use `warn`, so ordinary tool traffic and brief relay interruptions do not cause sustained growth.
|
|
146
|
+
Existing files are opened without following symbolic links where supported and tail-trimmed on UTF-8/line boundaries before startup. The active background daemon repeats the same secure trim every 15 minutes, so a long-lived process remains bounded even under repeated warning-level failures. Maintenance errors expose only a coarse error class. Background services use `warn`, so ordinary tool traffic and brief relay interruptions do not cause sustained growth.
|
|
147
|
+
|
|
148
|
+
The log format has an explicit schema marker. Because a schema mismatch authorizes truncation, the marker is read as destructive control evidence with no-follow path/descriptor identity verification and multiple-hard-link rejection; an unreadable, ambiguous, or multiply-linked marker fails before either active log is changed. If a securely read marker differs from the current format, the daemon clears the active files before startup and writes the current marker. Runtime code recognizes only `daemon.out.log` and `daemon.err.log`; it does not parse or archive other log formats.
|
|
149
|
+
|
|
150
|
+
Each managed job has owner-only runner diagnostic logs. Child-step output is retained only in bounded, redacted job results according to `capture_output`; it is not copied into daemon or runner operational logs. Runner infrastructure failures may record only a coarse stage/error class such as resource admission or coordinator contention; job IDs, argv, paths, resource names/content, and child output are omitted from those operational diagnostics.
|
|
151
|
+
|
|
152
|
+
## Relay outage records
|
|
153
|
+
|
|
154
|
+
`network_route` describes only Machine Bridge's application-level proxy decision. `system-network-stack` does **not** mean a direct physical path: an operating-system VPN, TUN, packet tunnel, DNS interceptor, or endpoint-security product may still carry the connection. `network_route_scope` therefore remains `application-proxy-selection-only`.
|
|
134
155
|
|
|
135
|
-
|
|
156
|
+
During an outage, remote-owner `diagnose_runtime.runtime.relay` and local stdio `server_info.runtime.relay` expose bounded live fields: outage count/start/duration, attempts, last close category/code, coarse transport error class, last disconnect/ready time, prior ready duration, prior ready inbound-silence duration, and next retry timing. `outage_duration_ms` is the close-to-ready recovery interval; `last_ready_inbound_silence_ms` is the pre-close interval since the preceding ready transport last proved inbound activity. After recovery, authenticated remote `server_info.daemon.relay_transport` retains the bounded preceding episode supplied during the current connection handshake, including `previous_ready_inbound_silence_ms` and brief interruptions below the default warning threshold. Promotion to a ready socket sets `outage_active=false`, extends the outage duration through actual readiness, preserves the preceding healthy-ready duration and inbound-silence evidence across failed candidates, canonicalizes timestamps, and accepts only enumerated coarse operational error classes; it does not claim that the recovered connection remains in outage. The `local_authority_revocation_retry` category is deliberately not diagnosed as a network failure: a sustained warning directs the operator to local authority, process-session, and managed-job state while the retained Worker revocation retries on reconnection; ordinary transport categories retain network/Worker troubleshooting guidance. On macOS, `diagnose_runtime` may also return a coarse default-route class, `operating_system_interception` boolean, and privacy-bounded `runtime.idle_sleep_guard` state (`supported`, `enabled`, `active`, `grace_ms`, `last_error_class`). That diagnostic is returned on demand and is not promoted to default logs; interface names, IP addresses, DNS answers, proxy endpoints/credentials, Worker endpoints, tool arguments, and results remain absent. `relay.outage.active` and `relay.outage.recovered` carry the existing safe relay fields.
|
|
136
157
|
|
|
137
|
-
|
|
158
|
+
Schema 4 is strict NDJSON. Before daemon startup, both active log files are opened as owner-only regular single-link files. A schema change clears both only after validation and commits the marker only after the transition succeeds. A symlink, multiple-hard-link inode, permission error, or marker-write failure blocks startup rather than mixing formats or repeatedly erasing evidence.
|
|
138
159
|
|
|
139
160
|
## MCP host boundary
|
|
140
161
|
|
|
141
|
-
Canonical `full` does not remove tools based on filenames. For remote execution, the
|
|
162
|
+
Canonical `full` does not remove tools based on filenames. For remote execution, the operation classifier treats credential-sensitive paths and persistence targets as hard authorization boundaries: delegated roles are denied, while owner requests remain risk-classified and audited. An MCP host, connector, model provider, desktop application, operating system, or endpoint-security layer may independently reject a request before it reaches Machine Bridge.
|
|
142
163
|
|
|
143
|
-
Use `server_info`, `project_overview`, `machine-mcp status`, `machine-mcp doctor
|
|
164
|
+
Use `server_info`, `project_overview`, `machine-mcp status`, and `machine-mcp doctor` to distinguish local policy from host-side enforcement; a remote owner may additionally use `diagnose_runtime` for machine-wide control-plane evidence. `doctor` explicitly reports that its isolated runtime did not inspect the running service process or remote relay; it must not be used as a substitute for `server_info.daemon.relay_transport`. Capability-routing status is returned on demand rather than written as task logs. The in-memory observer stores a runtime-keyed task fingerprint, selected skill/match counts, recommended tool names, primary route, ambiguity class, and score gap; it never stores raw task text, static instruction content, application inventory, or route explanations. Changing the Machine Bridge profile cannot override another layer.
|
|
144
165
|
|
|
145
166
|
## Adding or changing logs
|
|
146
167
|
|
package/docs/MANAGED_JOBS.md
CHANGED
|
@@ -65,6 +65,8 @@ machine-mcp resource remove maintenance-key
|
|
|
65
65
|
|
|
66
66
|
Removing an alias affects new jobs. A job already accepted has an owner-only resource snapshot specification and continues independently.
|
|
67
67
|
|
|
68
|
+
Managed jobs are also the required Machine Bridge execution carrier for operations that intentionally replace the current daemon, including persistent release-candidate activation. A process session is retained only by the current daemon and its process group is drained during daemon shutdown; a managed-job runner is detached, unreferenced, persisted under the owner-only job root, and can be inspected again after the replacement daemon reconnects. Do not substitute `start_process` for a daemon-replacing transaction merely because both APIs return an identifier.
|
|
69
|
+
|
|
68
70
|
Generate a new Ed25519 resource rather than exposing a private-key creation command through a model-generated shell string:
|
|
69
71
|
|
|
70
72
|
```sh
|
|
@@ -113,6 +115,14 @@ Environment injection is convenient but may expose a value to same-user process
|
|
|
113
115
|
|
|
114
116
|
At job acceptance, referenced resources are reopened, bounded, hashed, and recorded in the owner-only active plan. The runner reopens and verifies the hash before copying. A changed resource causes the job to fail rather than silently using different content.
|
|
115
117
|
|
|
118
|
+
## Terminal persistence and sensitive-plan cleanup
|
|
119
|
+
|
|
120
|
+
A job terminal transition is not a single best-effort write. The runner first attempts the bounded `result.json`, then persists a conservative terminal `status.json` with cleanup pending, then removes the private runtime directory, active plan, PID claim, and cancellation marker, and finally confirms cleanup state. `transition.lock` and `recovery.lock` are not ordinary artifacts: only their owning/reclaiming lock primitive may release them. A result-write failure is visible as `result_persisted=false` together with a bounded `terminal_record_error_class`; `read_job` then returns that persisted failure evidence without retrying an explicitly unpersisted result. Destructive terminal cleanup accepts that degraded form only when both fields are present. If a result file is present, `read_job` validates that it is a terminal result belonging to the same job and, once status is terminal, that status/result state agree; cleanup additionally requires the same `finished_at` generation before treating the two files as one terminal commit. Malformed, cross-job, missing, or cross-generation result state fails as an integrity error instead of authorizing cleanup or being passed through. Conversely, a terminal status that does not explicitly record `result_persisted=false` must still have its result file; a missing terminal result is also an integrity error rather than a silently incomplete success/failure response. A status-write failure leaves recovery material intact. Artifact removal failures remain visible as `artifact_cleanup_pending` and are retried by later read/list/prune operations.
|
|
121
|
+
|
|
122
|
+
If the runner writes a valid terminal result but exits before terminal status is committed, the manager reconstructs status from that result before considering recovery. If a dead runner instead leaves a present but non-terminal, cross-job, or otherwise invalid result object, recovery fails closed and retains the state for inspection rather than treating that corruption as an absent result and overwriting it with a cleanup retry. Lifecycle status is likewise an explicit enum, not a `not-active => terminal` inference: an unknown on-disk status is retained as an integrity failure, is not scrubbed or capacity-evicted as a completed job, blocks destructive removal through active-job inventory, and cannot be acknowledged as already finished by cancellation/revocation. While the runner is still alive in the narrow result-first/status-second settlement window, `read_job` also projects a coherent terminal status from that already-durable result in memory rather than returning an active outer status beside a terminal nested result; cleanup remains conservatively reported as pending until the persisted status catches up. This read-side projection never writes runner-owned state. These rules prevent a completed finally sequence from being replayed or observably mixed merely because the status write has not happened yet. If no valid terminal result exists, recovery may still repeat finally work, so finally steps must remain idempotent.
|
|
123
|
+
|
|
124
|
+
Unexecuted staged plans can contain stdin, environment values, and temporary scripts. They expire after 24 hours, but expiry is itself a per-job state transition: pruning must acquire the job transition lock, re-read the current status, and only then commit the non-executing terminal record through the same result-first persistence boundary. A concurrent cancel/other transition therefore wins or finishes before expiry rather than racing it. Terminal retention begins from that terminal record's `finished_at`, not from the older staged directory age, so a long-abandoned draft is not immediately deleted in the same pass that first expires it. When seven-day retention or capacity pressure eventually retires a complete job directory, removal is also generation-bound: the inspected directory is atomically quarantined under an internal `retired_job_*` generation name before recursive deletion. That internal namespace is deliberately outside the public `job_...` ID grammar, so normal list/read/lock paths cannot reinterpret cleanup state as a job. A crash after rename leaves a recognizable cleanup record. Later pruning reclaims it only when the encoded filesystem generation still matches. Verification failure never renames quarantine back onto the public job pathname; the retired evidence stays isolated for a later safe retry. Any malformed reserved `retired_job_*` name, generation mismatch, wrong type, or unreadable retired entry remains a privacy-bounded destructive-state blocker without exposing its internal filename/device/inode through ordinary job diagnostics. Every recognized retired entry still counts toward the 50-item retained-state capacity until safely removed, so namespace separation cannot become a capacity bypass. The public `job_...` namespace is reserved just as strictly: a matching name with the wrong filesystem type is retained as `unreadable`, counts toward the same capacity, blocks destructive inventory, and is shown only to owner/local diagnostics. New deterministic job admission securely inspects an existing target before any capacity eviction, so a dangling link or other invalid target cannot consume retained terminal history before the request fails. Ordinary completed-job metadata may remain under the separate seven-day retention policy. A minimal-environment plan also launches its detached runner with a minimal control environment. Full parent-environment inheritance occurs only when the accepted plan explicitly captured that policy.
|
|
125
|
+
|
|
116
126
|
## Job-scoped temporary files
|
|
117
127
|
|
|
118
128
|
Do not create ad hoc helpers in the workspace when the file exists only for one operation. Include it in the job:
|
|
@@ -142,7 +152,7 @@ Available placeholders are:
|
|
|
142
152
|
{{job:workspace}}
|
|
143
153
|
```
|
|
144
154
|
|
|
145
|
-
Temporary files live only below the private job runtime and are removed in the runner's final cleanup path. This is preferable to writing into
|
|
155
|
+
Temporary files live only below the private job runtime and are removed in the runner's final cleanup path. This is preferable to writing into a workspace-local scratch tree, `/tmp`, or a remote home directory and relying on a later MCP call to delete the file.
|
|
146
156
|
|
|
147
157
|
For a remote shell program, avoid a remote helper entirely when possible:
|
|
148
158
|
|
|
@@ -187,39 +197,30 @@ A job can contain ordered main steps and ordered `finally_steps`:
|
|
|
187
197
|
}
|
|
188
198
|
```
|
|
189
199
|
|
|
190
|
-
Finally steps are attempted after success, failure, timeout, or cancellation. Cancellation is delivered through an owner-only marker polled by the runner; the runner terminates the current child process tree and remains alive to execute cleanup. This avoids platform-specific signal behavior killing the coordinator itself. If a runner is interrupted, the next daemon start or local `machine-mcp job ...` command detects the dead runner, removes stale private resource copies, and runs the finally phase in recovery mode.
|
|
200
|
+
Finally steps are attempted after success, failure, timeout, or cancellation. Cancellation is delivered through an owner-only marker polled by the runner; the runner terminates the current child process tree and remains alive to execute cleanup. A ChildProcess `error` event by itself does not settle a step or release its resource lease: the runner latches that error and keeps the child as the active cancellation target until close/exit settlement proves the process lifecycle ended. This avoids both platform-specific signal behavior killing the coordinator itself and asynchronous child errors turning a still-live process into unaccounted work. If a runner is interrupted, the next daemon start or local `machine-mcp job ...` command detects the dead runner, removes stale private resource copies, and runs the finally phase in recovery mode.
|
|
191
201
|
|
|
192
|
-
Automatic dead-runner recovery is attempted at most three times; persistent failure becomes `recovery_exhausted` to avoid an endless restart loop. Cleanup is best effort, not mathematically guaranteed. Power loss, disk failure, permanent account loss, or a local security product that denies the cleanup executable can still prevent it. Finally steps should therefore be idempotent and safe to run more than once.
|
|
202
|
+
Automatic dead-runner recovery is attempted at most three times; persistent failure becomes `recovery_exhausted` to avoid an endless restart loop. A terminal result's compatibility field `recovered=true` means the result was produced while the runner was in recovery mode; it does **not** mean recovery succeeded. Use terminal `status` as the authority: `recovered` means the recovery/finally phase completed, while `recovery_failed` and `recovery_exhausted` are failures even when the result also carries `recovered=true`. Cleanup is best effort, not mathematically guaranteed. Power loss, disk failure, permanent account loss, or a local security product that denies the cleanup executable can still prevent it. Finally steps should therefore be idempotent and safe to run more than once.
|
|
193
203
|
|
|
194
|
-
##
|
|
204
|
+
## Non-executing staged drafts
|
|
195
205
|
|
|
196
|
-
|
|
206
|
+
`stage_job` performs the same schema, cwd, resource, size, and permission validation as `start_job`, but records status `staged` and launches no process.
|
|
197
207
|
|
|
198
|
-
|
|
199
|
-
stage_job
|
|
200
|
-
```
|
|
208
|
+
A staged record is a review artifact, not an authorization request:
|
|
201
209
|
|
|
202
|
-
|
|
210
|
+
- it contains no executable approval token;
|
|
211
|
+
- it cannot be promoted by `machine-mcp job approve`;
|
|
212
|
+
- no main or finally step runs;
|
|
213
|
+
- no registered resource is copied into a runtime directory;
|
|
214
|
+
- cancellation produces `cancelled_before_start` and removes the plan.
|
|
203
215
|
|
|
204
|
-
|
|
205
|
-
machine-mcp job inspect JOB_ID
|
|
206
|
-
machine-mcp job approve JOB_ID
|
|
207
|
-
# or after a separate review, non-interactively:
|
|
208
|
-
machine-mcp job approve JOB_ID --yes
|
|
209
|
-
```
|
|
216
|
+
Use `machine-mcp job inspect JOB_ID` to review the stored plan. The projection includes argv, ordinary environment overrides, stdin, temporary helper content, and finally steps while omitting registered resource source paths and per-resource hashes. The overall `plan_sha256` is displayed and remains integrity-checked.
|
|
210
217
|
|
|
211
|
-
|
|
218
|
+
Execution requires a separate authority-bearing action:
|
|
212
219
|
|
|
213
|
-
|
|
220
|
+
- a trusted owner submits the plan through `start_job`; or
|
|
221
|
+
- the local machine operator submits a reviewed JSON plan with `machine-mcp job submit PLAN.json`.
|
|
214
222
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
- no main step runs;
|
|
218
|
-
- no finally step runs;
|
|
219
|
-
- no resource is copied into a runtime directory;
|
|
220
|
-
- cancelling produces `cancelled_before_start` and deletes the plan.
|
|
221
|
-
|
|
222
|
-
Staged plans count toward the 50-item retention limit and expire with the seven-day job retention policy. They are not considered active processes and do not independently block uninstall after the normal uninstall confirmation.
|
|
223
|
+
The current runtime does not implement copy-an-ID, approve, and retry workflows. Staged drafts count toward the 50-item retention limit and expire after 24 hours. They are not active processes and do not independently block uninstall after normal confirmation.
|
|
223
224
|
|
|
224
225
|
## Submit and inspect
|
|
225
226
|
|
|
@@ -233,23 +234,25 @@ read_job
|
|
|
233
234
|
cancel_job
|
|
234
235
|
```
|
|
235
236
|
|
|
236
|
-
From the local terminal
|
|
237
|
+
From the local terminal:
|
|
237
238
|
|
|
238
239
|
```sh
|
|
239
240
|
machine-mcp job list
|
|
240
241
|
machine-mcp job inspect JOB_ID
|
|
241
|
-
machine-mcp job approve JOB_ID [--yes]
|
|
242
242
|
machine-mcp job cancel JOB_ID
|
|
243
|
-
```
|
|
244
|
-
|
|
245
|
-
A local JSON fallback is also available:
|
|
246
|
-
|
|
247
|
-
```sh
|
|
248
243
|
machine-mcp job submit plan.json
|
|
249
244
|
```
|
|
250
245
|
|
|
246
|
+
`job submit` is an explicit local operator action; it does not consume or promote a staged MCP draft.
|
|
247
|
+
|
|
251
248
|
The plan format is the same object accepted by `start_job`.
|
|
252
249
|
|
|
250
|
+
### Uncertain submission retries
|
|
251
|
+
|
|
252
|
+
`start_job` accepts an optional `idempotency_key` for a client that may need to retry the *same logical submission* after an uncertain transport outcome. The key is never persisted in cleartext. Instead, the runtime derives a deterministic job identity from the key plus the effective local/account authority binding. While that job record remains retained, retrying the same key with the same canonical plan returns the existing job with `idempotency_replay=true`; the same retained key with a different plan fails as a conflict. Replay inspects the persisted status through the same bounded no-follow reader used by ordinary job state—only a real `ENOENT` means no prior status—and reconciles any already-durable terminal `result.json` before deciding whether a dead `queued` runner may be launched again. A result-first/status-second crash therefore converges to the durable terminal result instead of repeating the main steps under the same idempotency key.
|
|
253
|
+
|
|
254
|
+
This is a bounded submission-deduplication window, not permanent exactly-once execution. Terminal job records may be removed after the normal retention period or earlier when safe terminal eviction is required to stay within the 50-record capacity. After that record has been evicted, the server no longer has evidence with which to deduplicate the old key, and a later submission may execute again. Use one fresh key per logical operation, retry only while resolving an uncertain submission, and treat a confirmed eviction/not-found boundary as the end of that key's deduplication guarantee. The tool therefore intentionally keeps `idempotentHint=false`.
|
|
255
|
+
|
|
253
256
|
## Output and secret handling
|
|
254
257
|
|
|
255
258
|
Step output is bounded to 64 KiB per stream and a shared 256 KiB capture budget per job, then stored in owner-only job results. Exact registered resource paths and exact resource content are replaced before results are returned. Common exact base64 and hexadecimal forms are also replaced for bounded resources.
|
|
@@ -275,9 +278,9 @@ Never place a secret directly in `argv`, `env`, `stdin`, a temporary file's `con
|
|
|
275
278
|
|
|
276
279
|
Per-workspace jobs are stored below the owner-only profile directory. Active jobs retain an owner-only plan for crash recovery. Plan, status, result, runner identity, and lock updates use flushed atomic replacement or complete-before-visible exclusive claims. Transition/recovery locks contain ownership tokens and process start time and are removed only when their file snapshot still matches. After a terminal status is committed, the full plan is deleted, including argv, stdin, embedded temporary-file content, and resource source paths.
|
|
277
280
|
|
|
278
|
-
Retained public job data contains bounded status and redacted results.
|
|
281
|
+
Retained public job data contains bounded status and redacted results. The hard capacity is 50 retained-state slots across ordinary job directories plus any recognized internal retired-cleanup entries that have not yet been safely removed. Terminal jobs are normally retained for up to seven days from their persisted `finished_at` settlement time, but when capacity is full the oldest safely removable terminal records are evicted to reserve a slot for a new job. Staged drafts expire after 24 hours and active, staged, unreadable, or abnormal retired state is never evicted merely to make room; if all 50 slots are occupied, new job creation returns a retryable `limit_exceeded` error whose owner-only details include coarse `retained_state`, `retired_state`, and `retired_unreadable` counts. `list_jobs.retained` remains the number of visible ordinary jobs; owner/local responses additionally include the same coarse capacity summary so an internal retired blocker cannot make a 49-job list look mysteriously full. Delegated non-owner responses omit the global capacity summary. Private runtime copies are removed after the finally phase. Runner stdout/stderr log files contain only runner-level diagnostics; step output is not written to those operational logs.
|
|
279
282
|
|
|
280
|
-
The detached runner records a structured owner record containing PID and process start time. Recovery rejects a reused PID instead of treating an unrelated process as the active runner. Numeric-only runner records are invalid. Recovery-lock handoff preserves a random ownership token, and the runner removes only a lock whose PID, token, and file snapshot still match. Timeout and cancellation terminate the process group/tree, retain a referenced forced-escalation timer, and clean descendants that ignore graceful termination before the runner exits.
|
|
283
|
+
The detached runner records a structured owner record containing PID and process start time. Recovery rejects a reused PID instead of treating an unrelated process as the active runner. Numeric-only runner records are invalid. Recovery-lock handoff preserves a random ownership token, and the runner removes only a lock whose PID, token, and file snapshot still match. A recovery runner does not gain authority to write terminal evidence merely by confirming its runner claim: it must first complete recovery-lock handoff. Failure or ambiguity in that bootstrap phase leaves the prior `interrupted` status and plan intact for a later safe retry instead of publishing `recovery_failed` and scrubbing recovery material. The handoff has a 30-second monotonic ownership-settlement budget. Timeout and cancellation terminate the process group/tree, retain a referenced forced-escalation timer, and clean descendants that ignore graceful termination before the runner exits.
|
|
281
284
|
|
|
282
285
|
Missing job JSON is distinct from unreadable or invalid job JSON. Permission, type, symbolic-link, size, UTF-8, I/O, and parse failures retain the job directory, produce an `unreadable` status for listing, skip automatic recovery/pruning, and block uninstall until an operator inspects the state.
|
|
283
286
|
|