Merge remote-tracking branch 'origin/main' into cook/generic-runtime-profile-compiler-20260619

# Conflicts:
#	tests/runtime-boundary-contracts.test.ts

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/browser-parent-tool-bridge-next-pr.md

@@ -0,0 +1,12 @@
+# Browser Parent-Tool Bridge Next PR
+
+This PR intentionally stops at executable blueprint refs and runtime profile application.
+
+The next parent-tool bridge seam should define one bounded contract for browser sandboxes to request parent-owned tools without receiving parent credentials. The contract should cover:
+
+- A product-safe request envelope, for example `wp-codebox/browser-parent-tool-request/v1`, with `tool`, `operation`, opaque `input`, `sandbox_session_id`, `caller_session_id`, and authorization context.
+- A parent-side ability or adapter hook that executes the requested tool and returns a redacted response envelope.
+- A browser-side bridge descriptor that can be passed through task input without embedding secrets.
+- Tests proving redaction, authorization failure, and opaque product payload preservation.
+
+Keep executable blueprint hydration on `wp-codebox/hydrate-browser-blueprint-ref`; do not couple parent-tool execution to blueprint storage.

docs/generic-runtime-primitives.md

@@ -10,6 +10,7 @@ product or job system.
   `packages/runtime-core/src/materialization-contracts.ts`, and
   `packages/runtime-core/src/evidence-artifact-envelope.ts`, and
   `packages/runtime-core/src/runtime-overlay-bundle.ts`, and
+  `packages/runtime-core/src/provider-runtime-contracts.ts`, and
   `packages/runtime-core/src/command-agent-run.ts`.
 - Coverage lives in `tests/generic-primitives.test.ts` and
   `tests/command-agent-run.test.ts`.
@@ -162,3 +163,20 @@ Example recipe step:
   ]
 }
 ```
+
+## Provider Runtime Invocation Contract
+
+`buildGenericAbilityRuntimeRunRecipe()` includes
+`runtime_invocation.provider_runtime_contract` in the ability input. The contract
+is the generic runtime-provider handshake introduced by PR #1205: workspace
+capture, workspace command execution, workspace publication, tool-call transcript
+recording, artifact handoff, and runtime evidence result schemas.
+
+WP Codebox owns the names and schemas. Callers own policy: repository selection,
+authorization, retries, retention, publication approval, and how resulting refs
+are attached to their job records.
+
+The contract intentionally uses `wp-codebox.runner-workspace.*`,
+`wp-codebox.tool-call-transcript.record`, and `wp-codebox.artifact-handoff`
+names. Downstream product names and orchestration policy stay outside the
+runtime invocation payload.

docs/sandbox-session-contract.md

@@ -52,6 +52,66 @@ registers runtime-principal authorization. If the runner is copied into a normal
 host WordPress install, it fails with `wp_codebox_browser_runner_not_playground`
 instead of executing the requested sandbox invocation.
 
+## Browser Contained Site Handle
+
+Browser session, materializer, and task contracts include an additive durable
+handle for caller-owned preview recovery:
+
+```json
+{
+  "contained_site": {
+    "schema": "wp-codebox/browser-contained-site/v1",
+    "site_id": "prepared-a1b2c3d4e5f6a7b8",
+    "preview_id": "preview-1234abcd5678ef90",
+    "session_id": "browser-session-123",
+    "caller_id": "studio-native",
+    "status": "ready",
+    "persistence": "browser-contained",
+    "source_digest": {
+      "algorithm": "sha256",
+      "value": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    "recovery": {
+      "ability": "wp-codebox/get-browser-contained-site-status",
+      "input": {
+        "cache_key": "prepared-a1b2c3d4e5f6a7b8",
+        "input_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "source_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+      }
+    }
+  }
+}
+```
+
+The handle is intentionally a primitive, not a parent-product lifecycle table.
+`site_id` is stable for the caller plus normalized runtime/source inputs, and
+`preview_id` is stable for the contained site plus browser session. The
+`source_digest` is the prepared-runtime `input_hash` when available, or a stable
+hash of the browser runtime, blueprint, site blueprint artifact, and Playground
+version inputs.
+
+Call `wp-codebox/get-browser-contained-site-status` with `cache_key` or `site_id`
+plus `input_hash` or `source_digest` to check whether WP Codebox can recover the
+prepared-runtime blueprint from its transient cache:
+
+```json
+{
+  "success": true,
+  "schema": "wp-codebox/browser-contained-site-status/v1",
+  "site_id": "prepared-a1b2c3d4e5f6a7b8",
+  "status": "recoverable",
+  "blueprint_ref": {
+    "schema": "wp-codebox/browser-blueprint-ref/v1",
+    "ref": "prepared:prepared-a1b2c3d4e5f6a7b8:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+  }
+}
+```
+
+Status is idempotent and read-only. `recoverable` means the prepared runtime
+transient exists and can hydrate a blueprint ref. `miss` means the caller should
+create a new browser session from the same inputs. Durable ownership, UI state,
+and retry policy still belong to the parent control plane.
+
 ## Browser Provider Adapter Contract
 
 Browser Playground provider calls that need parent-side connector authorization

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.