Skip to content

generic-runtime-primitives.md

Latest commit

 

History

History
295 lines (240 loc) · 11.7 KB

generic-runtime-primitives.md

File metadata and controls

295 lines (240 loc) · 11.7 KB

Generic Runtime Primitives

WP Codebox exposes generic contracts for parent control planes without naming a product or job system.

Contract Authority

  • TypeScript implementations live in packages/runtime-core/src/artifact-storage.ts, packages/runtime-core/src/browser-session-origin.ts, and packages/runtime-core/src/runtime-neutral-contracts.ts, and 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/runtime-boundary-contracts.ts, and packages/runtime-core/src/runtime-profile-compiler.ts, and packages/runtime-core/src/provider-runtime-contracts.ts, and packages/runtime-core/src/command-agent-run.ts, and packages/runtime-core/src/wordpress-workload-primitives.ts.
  • Coverage lives in tests/generic-primitives.test.ts and tests/command-agent-run.test.ts, plus tests/wordpress-workload-primitives.test.ts for workload helpers and tests/runtime-package-execution.test.ts for runtime package execution.
  • npm run check runs that coverage through the smoke manifest core group.

Artifact Storage

wp-codebox/runtime-artifact-storage/v1 describes where runtime artifacts can be written and how relative artifact paths map to public URLs when a public root is available.

  • root is an absolute writable filesystem root.
  • publicUrlRoot is an optional normalized http:// or https:// URL root.
  • pathPrefix is an optional safe relative prefix applied before artifact refs.

Browser Session Origins

wp-codebox/trusted-browser-session-origin/v1 normalizes trusted CORS origins for browser-session bridges. https:// origins are accepted. http:// is accepted only for loopback hosts.

Materialization Results

wp-codebox/materialization-phase-result/v1 records phase status and artifact references produced while converting runtime output into durable artifacts. These refs can be folded into run records as materialization:<kind> artifact refs.

wp-codebox/materialization-result/v1 is the generic materialization envelope. It records status (completed, failed, or skipped), ordered phases, artifact refs, diagnostics, and optional caller projections. Product-specific views such as browser artifact persistence or WordPress replay packages belong in projections[]; the core envelope stays caller-neutral and represents failures without requiring callers to recover information from thrown errors.

Evidence Artifact Envelopes

wp-codebox/evidence-artifact-envelope/v1 is a caller-neutral envelope for review artifacts produced by runtime workflows. It keeps product policy outside WP Codebox while giving upstream consumers one stable shape for browser captures and reviewer-safe artifact references.

  • Artifact refs use bundle-relative paths, never host filesystem paths.
  • Optional publicUrl values must be http:// or https:// and cannot point at loopback hosts such as localhost or 127.0.0.1.
  • Browser captures use wp-codebox/browser-evidence-capture/v1 and group the screenshot, HTML, console, network, review, or other artifacts for one browser scenario without naming a downstream product.
import { evidenceArtifactEnvelope } from "@automattic/wp-codebox-core"

const envelope = evidenceArtifactEnvelope({
  id: "run-1",
  subject: { kind: "component", id: "example" },
  status: "passed",
  artifacts: [{ path: "files/review.md", kind: "review" }],
  browserCaptures: [{
    id: "homepage",
    status: "passed",
    finalUrl: "https://example.test/",
    artifacts: [{ path: "files/browser/home.png", kind: "browser-screenshot" }],
  }],
})

Runtime Overlay Bundles

wp-codebox/runtime-overlay-bundle/v1 is a generic runtime overlay metadata primitive for recipe authors and backend implementations. It describes what an overlay needs without encoding downstream product policy or executing the overlay by itself.

  • files declare sandbox files with local sources or inline contents.
  • configPreludes declare ordered snippets or files a backend can prepend to runtime configuration.
  • localRoutes declare loopback-only route aliases; routes must set localOnly: true.
  • patches record patch provenance with source and optional digest metadata.
  • capabilities is a manifest of provided, required, and optional capability strings.
  • unsupportedGaps are explicit fail-closed blockers. runtimeOverlayBundle() throws when any are present so callers do not silently run with a partial overlay.

Recipe schema accepts these bundles through runtime.overlays[]:

{
  "kind": "runtime-overlay-bundle",
  "bundle": {
    "schema": "wp-codebox/runtime-overlay-bundle/v1",
    "id": "example-runtime-overlay",
    "files": [{ "path": "/wordpress/wp-content/mu-plugins/example.php", "source": "overlays/example.php" }],
    "configPreludes": [{ "target": "wp-config.php", "contents": "define('EXAMPLE_RUNTIME', true);", "order": 10 }],
    "localRoutes": [{ "path": "/_runtime/example", "target": "http://127.0.0.1:9400/example", "localOnly": true }],
    "patches": [{ "id": "example.patch", "source": "patches/example.patch", "appliesTo": "runtime" }],
    "capabilities": { "provided": ["example/runtime-overlay"] }
  }
}

Neutral WordPress Runtime Intent

Recipes can omit runtime.backend or set it to wordpress. WP Codebox currently normalizes that neutral WordPress runtime name to the existing wordpress-playground backend implementation. The wordpress-playground spelling is still accepted for existing recipes and low-level compatibility.

runtime-neutral-contracts.ts also exports helper-only setup intent types for callers that need to describe desired setup before compiling it into recipe fields:

  • RuntimeWordPressSetupPlanIntent groups component and filesystem intent for a WordPress sandbox setup plan.
  • RuntimeWordPressComponentIntent describes components such as plugins, mu-plugins, themes, WordPress core, and runtime overlays.
  • RuntimeWordPressFilesystemIntent describes intended sandbox filesystem materialization, including target path, mode, and purpose.

These intent types are public documentation helpers. Runtime execution still uses the concrete recipe fields such as inputs.extra_plugins, inputs.mounts, inputs.stagedFiles, runtime.stack.mounts, and runtime.overlays.

Runtime Profiles

wp-codebox/runtime-profile/v1 is the caller-facing runtime request/result contract for agent-capable WordPress sandboxes. It exposes generic capabilities, components, readiness, diagnostics, and provenance while backend adapters resolve plugin paths, overlays, activation order, and readiness details internally.

See runtime-profile-contract.md for the field contract and examples.

Target Context Provisioning

wp-codebox target provision --json emits a wp-codebox/target-context/v1 envelope. The command does not start a runtime or persist state; it gives callers a normalized target/session/storage context they can pass into recipes, browser sessions, or external orchestrators.

Example:

wp-codebox target provision --json \
  --id example \
  --kind wordpress-site \
  --workspace-root /workspace \
  --artifact-public-url-root https://artifacts.example.test/run-1 \
  --trusted-origin https://preview.example.test

Command Agent Runs

command-agent-run is a product-neutral runtime command wrapper. It executes one declared runtime command and emits a wp-codebox/command-agent-run/v1 envelope with stdout, stderr, exit code, normalized status, optional parsed JSON, session metadata, auth context keys, environment variable names, diagnostics, and artifact refs.

The wrapper fails closed:

  • command is required.
  • The target command must already be allowed by runtime policy.
  • command-agent-run cannot target itself.
  • auth-required=true requires auth-context-json.
  • Runtime metadata is required before an envelope can be created.

Environment reporting includes names only. Runtime and secret environment values are not included in the envelope.

Example recipe step:

{
  "command": "command-agent-run",
  "args": [
    "command=inspect-mounted-inputs",
    "args-json=[]",
    "parse-json=false",
    "session-id=example-session",
    "correlation-id=example-correlation"
  ]
}

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. The runner workspace ability surface is wp-codebox/prepare, wp-codebox/capture, wp-codebox/command, and wp-codebox/publish. 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 task names and short WP Codebox ability names. Downstream product names, backend ability names, and orchestration policy stay outside the runtime invocation payload.

Runtime Package Execution

wp-codebox/run-runtime-package is the public WordPress ability for executing a runtime package. Callers should use this Codebox-owned ability id, the CODEBOX_RUN_RUNTIME_PACKAGE_ABILITY constant, or buildRuntimePackageRunRecipe() instead of coupling to backend adapter ability ids.

The request envelope is wp-codebox/runtime-package-execution-input/v1:

{
  "schema": "wp-codebox/runtime-package-execution-input/v1",
  "runtime_package": "example/runtime-package",
  "input": { "prompt": "collect evidence" },
  "artifact_declarations": [
    {
      "schema": "wp-codebox/runtime-package-artifact-declaration/v1",
      "name": "report",
      "type": "markdown",
      "direction": "output",
      "path": "files/report.md",
      "required": true
    }
  ],
  "output_projections": [
    {
      "schema": "wp-codebox/runtime-package-output-projection/v1",
      "name": "summary",
      "source": "result.summary",
      "type": "text"
    }
  ],
  "metadata": {}
}

Artifact declarations describe typed inputs or outputs the runtime package may consume or produce. Output projections describe named caller-facing views over the runtime result or artifacts. WP Codebox preserves these generic declarations in the runtime package input so downstream systems can remove product-specific artifact special-casing while keeping projection policy outside Codebox core.

WordPress Workload Primitives

wordpressAbilityStep() builds the stable wordpress.ability recipe step shape. wordpressWorkloadRunRecipe() builds a minimal WordPress Playground-backed recipe around caller-supplied workload steps while returning Codebox runtime descriptors for mounts, PHP execution, OPFS use, and browser-client access.

playgroundPreviewUrl() emits a wp-codebox/playground-preview-url/v1 envelope for local, public, or secure preview URLs. Callers get the effective URL and diagnostics while the Playground adapter remains free to change its internal preview plumbing.

import { playgroundPreviewUrl, wordpressAbilityStep, wordpressWorkloadRunRecipe } from "@automattic/wp-codebox-core"

const recipe = wordpressWorkloadRunRecipe({
  preview: { publicUrl: "https://preview.example.test/run-1/" },
  steps: [wordpressAbilityStep({
    name: "example/do-work",
    input: { prompt: "collect evidence" },
    expectedResultSchema: "example/result/v1",
  })],
})

const preview = playgroundPreviewUrl({
  localUrl: "http://127.0.0.1:9400/",
  publicUrl: "https://preview.example.test/run-1/",
  path: "/wp-admin/",
  mode: "secure",
})