Track disposable sandbox principal, runtime tools, and package import contracts

[chubes4]

Problem

WP Codebox currently compensates for generic agent-substrate gaps when running agents inside disposable WordPress Playground sandboxes:

• bypasses agents/chat permission filters inside the browser runner
• injects sandbox runtime tools through Data Machine's datamachine_resolved_tools filter
• imports Data Machine agent bundles as the practical transport for sandbox agent definitions
• depends on Data Machine-specific tool names/policy vocabulary for sandbox-safe vs parent-only tools
• relies on product/Data Machine pending-action adapters where generic approval substrate should be enough

These are reasonable local adaptations today, but the generic substrate should define enough contracts that Codebox can be a clean sandbox runtime consumer rather than a Data Machine-specific adapter.

Related Codebox pressure points:

• browser runner permission bypass in disposable Playground scope
• runtime filesystem-write tool registration
• sandbox Data Machine tool allow/deny policy
• agent bundle import path
• pending-action/apply-back integration

Desired direction

Agents API should provide generic contracts for:

• a trusted disposable sandbox principal / runtime execution scope
• runtime-local tool source registration and mediation
• package or agent-definition import usable by ephemeral runtimes
• scoped tool capability metadata, e.g. safe in disposable runtime vs parent control plane only
• pending-action mediation hooks usable by products without direct Data Machine helper dependencies

Acceptance criteria

• Define which pieces already exist in Agents API and which are missing.
• Propose the smallest substrate additions needed for WP Codebox to remove Data Machine-specific compensation.
• Keep concrete storage, UI, workflow jobs, and product apply behavior outside Agents API.
• Link follow-up implementation issues in WP Codebox/Data Machine where consumer migrations are needed.

Source evidence

• WP Codebox trait-wp-codebox-abilities-browser-runner.php
• WP Codebox class-wp-codebox-agent-sandbox-runner.php
• WP Codebox sandbox-datamachine-tool-policy.*
• WP Codebox class-wp-codebox-data-machine-pending-actions.php

[chubes4]

Consumer migration trackers:

• WP Codebox reusable browser session/materializer API: Track reusable browser session and materializer APIs for product consumers wp-codebox#546
• Studio Web boundary cleanup: https://github.a8c.com/chubes4/studio-web/issues/360

[chubes4]

Additional Codebox consumer migration tracker: Automattic/wp-codebox#547

[chubes4]

Current consumer audit after updating/checking current main refs:

• wp-codebox primary: 2b229d3
• data-machine-release-main: 4928e918
• agents-api inspected from fetched origin/main
• studio-web primary: 02f3b98

This issue is still the right substrate tracker. Several related primitives have landed, so the remaining scope should be tightened around the pieces still forcing WP Codebox to carry Data Machine-specific sandbox glue.

Already landed / should not be re-scoped here

• Generic external runtime tool fulfillment lifecycle landed in Agents API (Add generic external runtime tool fulfillment lifecycle #250).
• Mediated tool preflight/external-tool pending hooks landed in Agents API (Expose mediated tool preflight and external-tool pending hooks #259).
• Host-owned tool declaration contracts landed in Agents API (Define host-owned tool declarations for conversation requests #275/Define canonical server-side tool declaration contract #282).
• Registered-agent materialization adapter contract landed in Agents API (Define registered-agent materialization adapter contract #266).
• Data Machine migrated conversation tool execution to Agents API mediation (Migrate conversation tool execution to Agents API mediation Extra-Chill/data-machine#2453).
• Data Machine migrated pending-action clients toward canonical Agents API abilities (Migrate pending-action clients to canonical Agents API abilities Extra-Chill/data-machine#2454).

Current remaining consumer pressure from WP Codebox

WP Codebox still compensates with Data Machine-specific sandbox bootstrap code:

• generated sandbox PHP imports Data Machine agent bundles and creates/updates Data Machine agents before calling agents/chat
• sandbox execution bypasses agents_chat_permission locally instead of presenting a generic trusted disposable runtime principal
• sandbox modes and tool guidance are registered through Data Machine-specific filters
• provider/model/env inheritance still uses Codebox/Data Machine-adjacent connector and secret-env glue
• completion/remediation outcomes are still inferred from Data Machine metadata rather than a stable substrate run outcome contract

Source pressure:

• wp-codebox/packages/cli/src/agent-code.ts
• wp-codebox/packages/runtime-core/src/sandbox-tool-policy.ts
• wp-codebox/packages/wordpress-plugin/src/class-wp-codebox-agent-sandbox-runner.php
• wp-codebox/packages/wordpress-plugin/src/trait-wp-codebox-abilities-inheritance.php

Suggested remaining substrate contract checklist

• Define a disposable sandbox principal / runtime execution scope for trusted ephemeral runtimes, replacing local permission bypasses.
• Define package/agent-definition import for ephemeral runtimes that is not Data Machine bundle-specific.
• Define runtime mode/guidance injection in a substrate-owned way, or explicitly leave it product/runtime-owned.
• Define provider/connector/secret-env inheritance for disposable runtimes without exposing secrets to product code.
• Define a stable agent-run outcome envelope covering completed, pending runtime tools, max turns, provider errors, assertion failures, and remediation classification.

Downstream migration tracker: Automattic/wp-codebox#547
Product-facing browser API tracker: Automattic/wp-codebox#546
Studio Web cleanup tracker: https://github.a8c.com/chubes4/studio-web/issues/360