README.md

WP Codebox Docs

Start here when authoring or maintaining WP Codebox integrations. The current contracts are generated from code where possible; planning docs are historical unless this index says otherwise.

Current Contracts

• Architecture explains the product boundary, package map, and ownership rules.
• Recipe contract is the authoring guide for wp-codebox/workspace-recipe/v1 recipes, including supported input names and assertion syntax.
• Sandbox session contract defines the parent orchestration boundary for sandbox sessions.
• Tool bridge contract defines the Codebox-owned allowlisted sandbox tool envelope and dispatcher metadata.
• Parent tool bridge contract defines the Codebox-owned host-dispatched tool envelope, request/result schemas, sandbox env injection metadata, transcript artifact refs, and failure behavior.
• Runner workspace backend contract defines the generic backend filter schema behind public runner workspace abilities.
• External apply adapter contract documents reviewed artifact apply-back.
• Agent fanout contract documents generic multi-sandbox fanout inputs and outputs.
• Agent runtime contract documents the stable orchestrator-facing agent-task CLI, schema boundary, artifacts, runner workspace publication, lifecycle metadata, provider overlays, and default sandbox bootstrap expectations.
• Agent task reusable workflow documents the public run-agent-task.yml GitHub Actions wrapper for product-level agent tasks.
• Public API contract defines stable package entrypoints, lifecycle contract areas, inspectable surfaces, Codebox's wrapper role around upstream runtime systems, and the limited role of ./internals.
• Generic runtime primitives documents the caller-neutral artifact storage, trusted browser origin, materialization, and target-context envelopes shared by runtime integrations.
• Runtime profile contract documents wp-codebox/runtime-profile/v1, the Codebox-owned profile request/result lane for capabilities, components, readiness, diagnostics, and provenance.
• Portable WP Codebox documents portable runtime packaging and invocation.
• Benchmark contract documents benchmark evidence shape without making benchmark scoring a core runtime concern.

Example Consumer Integration Notes

• Example consumer boundary contracts 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 is a current dependency classification reference.
• Transfer readiness checklist and transfer namespace plan are historical transfer planning records. Keep them for provenance, but do not treat them as onboarding docs or current recipe contract authority.
• Reprint parent-site snapshots is a planning note for a bounded parent-site snapshot surface.

Contract Authority

• Recipe schema: npm run wp-codebox -- schema recipe --json.
• Command catalog: npm run wp-codebox -- commands --json.
• Runtime TypeScript contracts: packages/runtime-core/src/runtime-contracts.ts.
• Generic primitive TypeScript contracts: packages/runtime-core/src/artifact-storage.ts, packages/runtime-core/src/browser-session-origin.ts, packages/runtime-core/src/materialization-contracts.ts, and packages/runtime-core/src/evidence-artifact-envelope.ts.
• Runtime profile TypeScript contracts: packages/runtime-core/src/runtime-boundary-contracts.ts and packages/runtime-core/src/runtime-profile-compiler.ts.
• JSON Schema factory: packages/runtime-core/src/recipe-schema.ts.
• Default check coverage: npm run check includes npm run test:generic-primitives through the smoke manifest core group.