Merge main into contained site lifecycle branch

Author: chubes4

CHANGELOG.md

@@ -2,6 +2,204 @@
 
 All notable changes to this project will be documented in this file. Entries are generated by homeboy from git commits.
 
+## [0.8.4] - 2026-06-19
+
+### Changed
+- Add browser contained site open primitive
+- Add browser preview lifecycle contracts
+- Add RuntimeRunResult to run registry
+- Split neutral runtime contract shapes
+- Add browser contained site status primitives
+- Add browser recipe DTO
+- Support local browser runtime packages
+- Focus browser hydration fix
+- Add browser blueprint refs
+- Dedupe agent task extra plugins
+- Register provider runtime ability aliases
+- Defer extra plugin activation until after mount
+- Add Studio and Homeboy boundary contracts
+- Exit CLI after settled commands
+- Pass provider runtime contract to generic runs
+- Materialize workspace preload artifacts
+- Expose provider runtime invocation names
+- Enforce generic production boundary
+- Remove Data Machine runtime tool coupling
+- Propagate agent task extra plugins
+- Decouple WordPress browser diagnostics from generic probe
+- Normalize runtime failure envelopes
+- Expose generic ability runtime recipe preset
+- Add runtime preset registry
+- Add addressable run cancellation
+- Add generic ability runtime run primitive
+- Make agent normalizer compatibility explicit
+- Allow generic runtime episode payload fields
+- Add materialization result envelope
+- Allow advisory browser route drain
+- Resolve browser storage state refs from artifacts
+- Add browser storage state export command
+- Add runtime overlay descriptor discovery
+- Add source root preparation primitive
+- Extract structured artifact materializer
+- Add runtime run status transitions
+- Extract agent outcome classifier
+- Add command validation descriptors
+- Extract browser probe result builder
+- Extract browser ability descriptors
+- Extract recipe run result finalization
+- Extract agent runtime config resolver
+- Extract patch approval filter
+- Extract browser runner artifact templates
+- Extract host agent request preparation
+- Extract recipe site seed helpers
+- Extract agent sandbox runtime config helpers
+- Tighten primitive parity fixtures
+- Extract recipe run workflow evidence helpers
+- Add generic command agent runner
+- Add generic tool call artifact contract
+- Extract browser actions runner
+- Extract PHP agent run result builder
+- Deduplicate lifecycle PHP snippets
+- Extract recipe runtime setup helper
+- Extract recipe run artifact finalizers
+- Extract PHP agent process runner
+- Extract editor command runners
+- Extract browser probe runner
+- Consolidate utility primitives
+- Extract browser DOM snapshot primitive
+- Extract recipe benchmark artifact helpers
+- Remove duplicate parent-site seed export helpers
+- Expose reusable browser storage state
+- Extract recipe run phase executor
+- Expose browser waterfall artifacts
+- Split generic primitive contract tests
+- Extract browser visual compare runner
+- Adopt shared PHP path policy cleaners
+- Adopt run-plan helpers for PHP fanout
+- Document browser runtime primitive gap
+- Extract browser runner tool registration template
+- Adopt runtime dependency plan in materializers
+- Clean up brittle contract test helpers
+- Migrate remaining browser summaries to artifact sessions
+- Add generic runtime recipe resolver
+- Add generic browser task intent builder
+- Add signed browser callback contracts
+- Centralize prepared source package hydration
+- Migrate visual compare artifacts to sessions
+- Centralize runner runtime internals
+- Harden primitive contract parity guards
+- Extract generic run plan scheduler helpers
+- Extract browser runner metrics template helpers
+- Add generic browser provider connector bridge inheritance
+- Expand runtime dependency plan adoption
+- Refactor brittle tests around test kit helpers
+- Preserve runtime overlay schema library hints
+- Add browser materialization envelope primitive
+- Derive recipe policy command dependencies
+- Extract browser runner boot phase templates
+- Extract generic fanout run plan helpers
+- Add agent runtime invocation boundary
+- Migrate browser action artifacts to sessions
+- Align PHP tool policy descriptors
+- Introduce runtime dependency plan contract
+- Add generic recipe source package primitives
+- Add fixture import bootstrap primitives
+- Add generic runtime overlay bundle primitive
+- Add fixture auth storage state helper
+- Add generic host command runner evidence
+- Load tool policy normalizer in browser task test
+- Add generic evidence artifact envelope
+- Normalize sandbox tool policies from allowed tools
+- Add connector credential resolver registry
+- Add browser-local task defaults
+- Add executable browser DTO and persisted artifact bundle result
+- Centralize preview topology diagnostics
+- Share bench command step primitives
+- Trust component manifest entrypoints
+- Add runtime tool policy resolver
+- Add PHP JSON codec primitive
+- Add generic editor save action primitive
+- Add recipe run result envelope
+- Add MCP client config renderer
+- Bridge agent task status taxonomies
+- Add browser artifact session primitive
+- Add browser task builder primitive
+- Add browser artifact lifecycle refs
+- Add browser provider bridge policy primitive
+- Consolidate PHP host command callsites
+- Align PHP path policy with runtime core
+- Add shared redaction policy profiles
+- Add shared artifact and mount path primitives
+- Guard task input schema parity
+- Harden redacted artifact capture
+- Normalize agent task run results
+- Add managed host command wrapper
+- Extract host command executor into runtime core
+- Add core artifact capture policy
+- Clarify generic runtime contract authority
+- Use registry metadata for command dispatch
+- Clean up reviewer access auth planning
+- Add generic runtime primitive contracts
+- Add runtime backend provider recipe hooks
+- Tighten bootstrap component manifest boundary
+- Consolidate smoke test harness helpers
+- Extract recipe source boundary helpers
+- Make browser artifact persistence idempotent
+- Add shared runtime redaction primitive
+- Align browser probe command contract
+- Centralize artifact layout writer primitives
+- Share command arg parsing primitives
+- Centralize sandbox PHP template fragments
+- Add shared file tree policy helpers
+- Add backend package adapter registry
+- Add agent terminal result contract
+- Harden agent workload envelope boundary
+- Neutralize core fixture docs
+- Add command artifact schema contracts
+- Centralize artifact redaction writes
+- Centralize runtime env secret handling
+- Extract prepared source staging primitive
+- Add runtime overlay registry seam
+- Decouple agent sandbox stack flags
+- Add core command argument codecs
+- Add runtime command result envelopes
+- Add component plugin entrypoint contract
+- Add runtime backend registry
+- Make transfer proof private hosts configurable
+- Validate recipe schema during ingestion
+- Centralize generated PHP snippets
+- Add artifact bundle writer
+- Align task input agent bundle contract
+- Clean up host boundary leaks
+- List recipe commands from registry in help
+- Preserve caller cwd in source CLI entrypoint
+- Document the agent runtime contract
+- Add source checkout CLI entrypoint
+- Improve PHP execution failure diagnostics
+- Add typed recipe artifact materialization
+- Capture hidden Playground crash diagnostics
+- Improve runtime overlay validation diagnostics
+- Bridge runtime ability tools
+- Document Codex cookbook provider stack
+- Improve Playground crash diagnostics
+- Add agent runtime diagnostics summary
+- Add Playground bundle artifact to replay packages
+
+### Fixed
+- Fix browser blueprint REST hydration
+- Fix check smoke blockers
+- Fix Agents API execution target registration
+- Fix evidence bundle identity and recipe artifacts
+- Fix browser runner template harness
+- Fix browser provider request permission
+- Fix safe VFS mount materialization
+- Fix backend registry schema validation
+- Fix artifact redaction for large inputs
+- Fix routed preview host handling
+- Fix artifact collection for cyclic browser errors
+- fix runtime ability lifecycle smoke
+- fix runtime component ability lifecycle replay
+- map package.json version targets to their artifact paths for deploy verification
+
 ## [0.8.3] - 2026-06-15
 
 ### Changed

README.md

@@ -1015,23 +1015,21 @@ Boot a sandbox with caller-supplied runtime components mounted, then verify the
 
 ```bash
 npm run wp-codebox -- agent-runtime-probe \
-  --component agents-api=../agents-api \
-  --component data-machine=../data-machine \
-  --component data-machine-code=../data-machine-code \
+  --component agent-runtime=../agent-runtime \
+  --component runtime-tools=../runtime-tools \
   --json
 ```
 
-Use `--component <slug>=<path>` for each runtime component your sandbox needs. The legacy `--agents-api`, `--data-machine`, and `--data-machine-code` flags remain accepted as compatibility aliases, but new automation should use `--component` so WP Codebox core stays portable across agent stacks.
+Use `--component <slug>=<path>` for each runtime component your sandbox needs. This is the neutral replacement for component-specific aliases; new automation should use `--component` so WP Codebox core stays portable across agent stacks.
 
 ### `agent-sandbox-run`
 
 Run one natural-language task through a sandboxed agent stack.
 
 ```bash
 npm run wp-codebox -- agent-sandbox-run \
-  --component agents-api=../agents-api \
-  --component data-machine=../data-machine \
-  --component data-machine-code=../data-machine-code \
+  --component agent-runtime=../agent-runtime \
+  --component runtime-tools=../runtime-tools \
   --agent sandbox-agent \
   --task "Add a Dry Rub filter to the wing locations map" \
   --provider example-ai \
@@ -1056,9 +1054,8 @@ Run several task descriptions, one isolated sandbox per task, with bounded concu
 
 ```bash
 npm run wp-codebox -- agent-sandbox-batch \
-  --component agents-api=../agents-api \
-  --component data-machine=../data-machine \
-  --component data-machine-code=../data-machine-code \
+  --component agent-runtime=../agent-runtime \
+  --component runtime-tools=../runtime-tools \
   --task "Fix issue A" \
   --task "Investigate issue B" \
   --concurrency 2 \

docs/README.md

@@ -29,6 +29,13 @@ unless this index says otherwise.
 - [Benchmark contract](./benchmark-contract.md) documents benchmark evidence
   shape without making benchmark scoring a core runtime concern.
 
+## Example Consumer Integration Notes
+
+- [Example consumer boundary contracts](./example-consumer-boundary-contracts.md)
+  documents runtime profile, preview lease, and browser session handoff seams for
+  host adapters. Named products in that note are examples only; the runtime
+  contracts remain caller-neutral.
+
 ## Audits And Historical Plans
 
 - [Browser runtime dependency audit](./browser-runtime-dependency-audit.md) is a

docs/studio-homeboy-boundary-contracts.md …s/example-consumer-boundary-contracts.mddocs/studio-homeboy-boundary-contracts.md renamed to docs/example-consumer-boundary-contracts.md docs/studio-homeboy-boundary-contracts.md renamed to docs/example-consumer-boundary-contracts.md

@@ -1,10 +1,16 @@
-# Studio/Homeboy Boundary Contracts
+# Example Consumer Boundary Contracts
 
-WP Codebox exposes small public seams for hosts that need to prepare browser-backed WordPress sandboxes without reading raw task payloads.
+WP Codebox exposes small public seams for hosts that need to prepare
+browser-backed WordPress sandboxes without reading raw task payloads. The seams
+are generic runtime contracts. Named products may appear in integration notes as
+example consumers, but they are not runtime concepts and must not define schema
+fields, package boundaries, or artifact semantics.
 
 ## Runtime Profile
 
-`runtime-core` exports `RUNTIME_PROFILE_SCHEMA`, `RuntimeProfile`, and `runtimeProfile()` from `@automattic/wp-codebox-core` and `wp-codebox-workspace/core/contracts`.
+`runtime-core` exports `RUNTIME_PROFILE_SCHEMA`, `RuntimeProfile`, and
+`runtimeProfile()` from `@automattic/wp-codebox-core` and
+`wp-codebox-workspace/core/contracts`.
 
 Shape: `wp-codebox/runtime-profile/v1`.
 
@@ -18,23 +24,37 @@ Shape: `wp-codebox/runtime-profile/v1`.
 
 ## Preview Lease
 
-`runtime-core` exports `PREVIEW_LEASE_SCHEMA`, `PreviewLease`, and `previewLease()`.
+`runtime-core` exports `PREVIEW_LEASE_SCHEMA`, `PreviewLease`, and
+`previewLease()`.
 
 Shape: `wp-codebox/preview-lease/v1`.
 
 - `preview_public_url`: reviewer/public preview URL when leased by a host.
 - `site_url`: canonical WordPress site URL.
 - `local_url`: local browser/Playground URL.
 - `lease`: lease id, status, provider, owner, and timestamps.
-- `alignment`: evidence that preview, site, and local URLs point at the same runtime.
+- `alignment`: evidence that preview, site, and local URLs point at the same
+  runtime.
 
-## Browser Product DTOs
+## Browser Session DTOs
 
-The WordPress plugin exposes these helpers for Studio Native and Homeboy integrations:
+The WordPress plugin exposes these helpers for host integrations that need a
+bounded browser session handoff:
 
 - `WP_Codebox_Browser_Task_Builder::product_browser_session_dto( $session )`
 - `WP_Codebox_Browser_Task_Builder::browser_preview_boot_config( $session )`
 - `wp_codebox_browser_session_product_dto` filter
 - `wp_codebox_browser_preview_boot_config` filter
 
-The DTOs include session identity, task label, target, preview boot config, preview lease/alignment data, artifact refs, and readiness signals. They intentionally omit raw `task_payload`, raw blueprint bodies, plugin package data, runtime source bundles, and secret-like fields.
+The DTOs include session identity, task label, target, preview boot config,
+preview lease/alignment data, artifact refs, and readiness signals. They
+intentionally omit raw `task_payload`, raw blueprint bodies, plugin package data,
+runtime source bundles, and secret-like fields.
+
+## Example Consumers
+
+Studio Web, Homeboy, Static Site Importer, hosted services, CI jobs, local tools,
+and other callers can consume these seams through their own adapters. Those
+adapters own product-specific defaults, queue state, deploy behavior, import
+semantics, and review UX. WP Codebox owns the generic runtime profile, preview
+lease, browser session DTO, and artifact boundaries.

examples/agent-runtime/README.md

@@ -6,16 +6,16 @@ Set local checkout paths, then run the preset:
 
 ```bash
 AGENTS_API_PATH=/path/to/agents-api \
-DATA_MACHINE_PATH=/path/to/data-machine \
-DATA_MACHINE_CODE_PATH=/path/to/data-machine-code \
+RUNTIME_ENGINE_PATH=/path/to/runtime-engine \
+RUNTIME_TOOLS_PATH=/path/to/runtime-tools \
 PROVIDER_PLUGIN_PATH=/path/to/ai-provider-plugin \
 npm run wp-codebox -- agent-runtime-probe \
   --component agents-api="$AGENTS_API_PATH" \
-  --component data-machine="$DATA_MACHINE_PATH" \
-  --component data-machine-code="$DATA_MACHINE_CODE_PATH" \
+  --component runtime-engine="$RUNTIME_ENGINE_PATH" \
+  --component runtime-tools="$RUNTIME_TOOLS_PATH" \
   --provider-plugin "$PROVIDER_PLUGIN_PATH" \
   --artifacts ./artifacts \
   --json
 ```
 
-The preset mounts each `--component` at its declared slug, uses WordPress `7.0` by default, activates the plugins in dependency order, and returns a JSON readiness packet. It intentionally does not require provider credentials or model calls. Legacy stack-specific flags such as `--agents-api` still work as compatibility aliases; new examples should prefer generic `--component` entries.
+The preset mounts each `--component` at its declared slug, uses WordPress `7.0` by default, activates the plugins in dependency order, and returns a JSON readiness packet. It intentionally does not require provider credentials or model calls. Stack-specific shortcuts should be replaced with generic `--component` entries.

examples/agent-runtime/probe.php

@@ -4,8 +4,8 @@
 
 $plugins = array(
     'agents-api/agents-api.php',
-    'data-machine/data-machine.php',
-    'data-machine-code/data-machine-code.php',
+    'runtime-engine/runtime-engine.php',
+    'runtime-tools/runtime-tools.php',
 );
 
 $activation_results = array();
@@ -31,10 +31,8 @@
         'signals' => array(
             'agents_api_loaded' => defined('AGENTS_API_LOADED'),
             'agents_chat_ability_available' => (new WP_Codebox_Agent_Runtime_Invoker())->is_agents_api_ready(),
-            'data_machine_version' => defined('DATAMACHINE_VERSION') ? DATAMACHINE_VERSION : null,
-            'data_machine_permission_helper' => class_exists('DataMachine\\Abilities\\PermissionHelper'),
-            'data_machine_code_version' => defined('DATAMACHINE_CODE_VERSION') ? DATAMACHINE_CODE_VERSION : null,
-            'data_machine_code_workspace' => class_exists('DataMachineCode\\Workspace\\Workspace'),
+            'runtime_engine_active' => is_plugin_active('runtime-engine/runtime-engine.php'),
+            'runtime_tools_active' => is_plugin_active('runtime-tools/runtime-tools.php'),
         ),
     ),
     JSON_PRETTY_PRINT

examples/recipes/cookbook/README.md

@@ -25,7 +25,7 @@ files plus dry-run evidence limited to shareable metadata.
 
 ### `codex-agent-smoke.json`
 
-Runs a headless Data Machine agent inside a disposable WordPress Playground
+Runs a headless agent runtime inside a disposable WordPress Playground
 sandbox using the Codex provider. This is the smallest end-to-end recipe for
 proving that WP Codebox can mount the agent runtime stack, overlay a
 `php-ai-client` branch with provider-supplied request auth, activate a Codex
@@ -36,8 +36,8 @@ uses explicit placeholder input paths so callers can see the full contract shape
 and replace each path with their prepared local checkout or artifact:
 
 - `/sample/prepared-component-stack/agents-api`
-- `/sample/prepared-component-stack/data-machine`
-- `/sample/prepared-component-stack/data-machine-code`
+- `/sample/prepared-component-stack/runtime-engine`
+- `/sample/prepared-component-stack/runtime-tools`
 - `/sample/prepared-provider-stack/php-ai-client`
 - `/sample/prepared-provider-stack/ai-provider-for-openai`
 
@@ -49,7 +49,7 @@ a dry-run plan with the sandbox backend, overlays, extra plugins, secret
 environment names, and resolved agent command arguments.
 
 - The component stack provides the WordPress plugins needed by the sandbox agent
-  runtime: `agents-api`, `data-machine`, and `data-machine-code`.
+  runtime: `agents-api`, `runtime-engine`, and `runtime-tools`.
 - The provider stack provides the `php-ai-client` overlay and provider plugin
   selected by `provider=codex` and
   `provider-plugin-slugs=ai-provider-for-openai`.