Support immutable runtime ZIP artifacts

Author: chubes4

.github/scripts/run-agent-task/execute-native-agent-task.mjs

@@ -243,11 +243,13 @@ const runtimeSourceInputs = (materializedRuntimeSources?.lowered ?? []).reduce((
   for (const [key, entries] of Object.entries(lowered)) input[key] = [...(input[key] ?? []), ...entries]
   return input
 }, {})
+const sourcePackageRoot = privateRuntimeSourceRoot ? join(privateRuntimeSourceRoot, "prepared-packages") : artifactsPath
 
 const taskInput = {
   schema: "wp-codebox/agent-task-run-request/v1",
   task_id: runId,
-  artifacts_path: artifactsPath,
+    artifacts_path: artifactsPath,
+    source_package_root: sourcePackageRoot,
   callback_data: record(request.callback_data),
   task_input: {
     schema: "wp-codebox/task-input/v1",

.github/scripts/run-agent-task/materialize-external-native-package.mjs

@@ -14,6 +14,15 @@ function redact(value) {
   return secretValues.reduce((output, secret) => output.split(secret).join("[REDACTED]"), value)
 }
 
+function omitPrivateRuntimeSourcePaths(value) {
+  if (Array.isArray(value)) return value.map(omitPrivateRuntimeSourcePaths)
+  if (!value || typeof value !== "object") return value
+  return Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => {
+    if (runtimeSourceRoot && typeof entry === "string" && resolve(entry).startsWith(runtimeSourceRoot) && ["source", "path", "sourceRoot", "originalSource", "preparedPath", "requestedPath"].includes(key)) return []
+    return [[key, omitPrivateRuntimeSourcePaths(entry)]]
+  }))
+}
+
 async function stageFile(source, destination) {
   if (runtimeSourceRoot && resolve(source).startsWith(runtimeSourceRoot)) {
     throw new Error("Runtime source files must never be staged for artifact upload.")
@@ -27,7 +36,10 @@ async function stageFile(source, destination) {
   await handle.close()
   if (!contents || contents.includes(0) || !isUtf8(contents)) return false
   await mkdir(resolve(destination, ".."), { recursive: true })
-  const text = contents.toString("utf8")
+  let text = contents.toString("utf8")
+  if (source === join(workspace, ".codebox", "native-agent-task-input.json")) {
+    text = `${JSON.stringify(omitPrivateRuntimeSourcePaths(JSON.parse(text)), null, 2)}\n`
+  }
   if (runtimeSourceRoot && text.includes(runtimeSourceRoot)) throw new Error("Runtime source paths must never be persisted in artifact uploads.")
   await writeFile(destination, redact(text))
   return true

.github/scripts/run-agent-task/prepare-agent-task-upload.mjs

@@ -15,6 +15,7 @@ on:
       - "package.json"
       - "tests/agent-task-*.test.ts"
       - "tests/runtime-sources-materialization.test.ts"
+      - "tests/runtime-sources-playground-integration.test.ts"
       - "tests/redaction.test.ts"
       - "tests/production-boundary-enforcement.test.ts"
       - "tests/runtime-tool-policy.test.ts"
@@ -32,6 +33,7 @@ on:
       - "package.json"
       - "tests/agent-task-*.test.ts"
       - "tests/runtime-sources-materialization.test.ts"
+      - "tests/runtime-sources-playground-integration.test.ts"
       - "tests/redaction.test.ts"
       - "tests/production-boundary-enforcement.test.ts"
       - "tests/runtime-tool-policy.test.ts"
@@ -50,6 +52,9 @@ jobs:
       - run: npm ci
       - run: npm run build
       - run: npm run test:agent-task-contracts
+      - run: npm run test:runtime-sources-playground-integration
+        env:
+          WP_CODEBOX_RUN_NETWORK_INTEGRATION: "1"
       - run: npm run test:redaction
       - run: npm run test:production-boundary-enforcement
       - run: npm run test:runtime-tool-policy

.github/workflows/agent-task-contracts.yml

@@ -56,7 +56,7 @@ This release-coherence contract fixes [#1759](https://github.com/Automattic/wp-c
 - `external_package_source`: immutable descriptor with `repository`, full commit `revision`, one package-relative `.agent.json` `path`, and `digest`. Packages are supported only from publicly accessible GitHub repositories, fetched from canonical `https://github.com/OWNER/REPOSITORY.git` without credentials. `digest` is exactly `sha256-bytes-v1:<lowercase-sha256>` over the raw file bytes; filenames and JSON content are UTF-8-safe and are not normalized before hashing.
 - `EXTERNAL_PACKAGE_SOURCE_POLICY`: required reusable-workflow secret, supplied by the caller's operator-controlled secret configuration. Its strict version 1 JSON shape is `{"version":1,"repositories":{"owner/repository":["agents/example.agent.json"]}}`. Every entry is an exact standalone `.agent.json` path. The policy is validated in runner memory, is never part of task input, and is not uploaded.
 
-`runtime_sources` is an optional versioned JSON array for immutable public runtime dependencies. Each descriptor declares `version: 1`, `role` (`component`, `provider_plugin`, or `bundled_library`), `repository`, a full 40-character `revision`, exact directory `path`, optional `sha256-git-archive-v1` digest, and role metadata. The operator-controlled policy extends the same secret with `runtime_sources`, for example `{"version":1,"repositories":{},"runtime_sources":{"owner/repository":["plugins/example"]}}`. The runner uses unauthenticated Git transport, verifies the commit, tree type, regular-file-only contents, and optional digest, stages outside the target workspace, and removes the staging root after execution. Runtime source descriptors lower into existing component, provider plugin, and runtime overlay inputs; artifacts retain provenance only.
+`runtime_sources` is an optional versioned JSON array for immutable public runtime dependencies. Git descriptors declare `version: 1`, `role` (`component`, `provider_plugin`, or `bundled_library`), `repository`, a full 40-character `revision`, exact directory `path`, optional `sha256-git-archive-v1` digest, and role metadata. Component and provider descriptors may instead declare `source: {"type":"https_zip","url":"https://...","sha256":"<64 lowercase hex>","archive_root":"plugin-directory"}`. The operator-controlled policy separately authorizes Git sources with `runtime_sources` and exact ZIP URLs with `runtime_artifacts`, for example `{"version":1,"repositories":{},"runtime_artifacts":[{"url":"https://downloads.wordpress.org/plugin/example.zip","sha256":"<64 lowercase hex>"}]}`. ZIP downloads require HTTPS, an exact allowlisted URL, a matching descriptor digest, bounded transfer and extraction sizes, and redirects only to another allowlisted URL on the original host. The runner verifies the digest before extraction; rejects traversal, symlink, special-file, encrypted, ZIP64, oversized, and multi-root archives; stages under a private temp root outside the workspace and artifacts; and removes the staging root after execution. Runtime source descriptors lower into existing component, provider plugin, and runtime overlay inputs; artifacts retain provenance only.
 - `target_repo`: `OWNER/REPO` target repository.
 - `prompt`, `writable_paths`, provider/model, `max_turns`, `time_budget_ms`, callback data, and artifact declarations: native task inputs.
 - `runner_workspace`: JSON runner-workspace publication request owned by the package.

docs/agent-task-reusable-workflow.md

@@ -2,7 +2,7 @@
   "run_id": "29299109269",
   "runtime_sources": [
     { "version": 1, "role": "component", "repository": "automattic/agents-api", "revision": "59d1e6b473f22498e40e279130bbb4f9bcde3b73", "path": ".", "metadata": { "slug": "agents-api", "loadAs": "mu-plugin", "activate": false } },
-    { "version": 1, "role": "provider_plugin", "repository": "wordpress/ai-provider-for-openai", "revision": "a400c158707e3d0b6fcd0f1502f6aa1085b01b9b", "path": ".", "metadata": { "slug": "ai-provider-for-openai", "activate": true } },
+    { "version": 1, "role": "provider_plugin", "source": { "type": "https_zip", "url": "https://downloads.wordpress.org/plugin/ai-provider-for-openai.1.0.3.zip", "sha256": "48f3c0c714b3164cda79d320829830d5a0ea1116e0b19653da8af898a22d3bb6", "archive_root": "ai-provider-for-openai" }, "metadata": { "slug": "ai-provider-for-openai", "pluginFile": "plugin.php", "activate": true } },
     { "version": 1, "role": "bundled_library", "repository": "wordpress/php-ai-client", "revision": "631704201d15ffeff7091ad3bc7156db74054956", "path": ".", "metadata": { "library": "php-ai-client", "strategy": "wordpress-scoped-bundle" } }
   ]
 }

fixtures/agent-task-runtime-sources-run-29299109269.json

@@ -90,6 +90,7 @@
     "test:agent-task-runtime-package-staging": "tsx tests/agent-task-runtime-package-staging.test.ts",
     "test:external-native-package-materialization": "tsx tests/external-native-package-materialization.test.ts",
     "test:runtime-sources-materialization": "tsx tests/runtime-sources-materialization.test.ts",
+    "test:runtime-sources-playground-integration": "tsx tests/runtime-sources-playground-integration.test.ts",
     "test:browser-task-builder": "tsx tests/browser-task-builder.test.ts",
     "test:browser-runtime-generic-invoker": "tsx tests/browser-runtime-generic-invoker.test.ts",
     "test:browser-runtime-file-ops": "tsx tests/browser-runtime-file-ops.test.ts",

package.json

@@ -54,6 +54,7 @@ export interface AgentTaskRunInput {
   session_id?: string
   sandbox_session_id?: string
   artifacts_path?: string
+  source_package_root?: string
   wp?: string
   component_contracts?: Array<Record<string, unknown>>
   runtime_requirements?: Record<string, unknown>
@@ -86,16 +87,17 @@ export interface RuntimeDependencyPlanContractInput {
 
 export function buildAgentTaskRecipe(input: AgentTaskRunInput, taskInput: TaskInput, wpVersion: string): WorkspaceRecipe {
   const artifacts = stringValue(input.artifacts_path)
+  const sourcePackageRoot = stringValue(input.source_package_root) || artifacts
   const profile = runtimeOverlayProfileDefaults(input)
   const runtimeMounts = runtimeStateMounts(input)
   const sourceRoots = workspaceSourceRoots(input, taskInput)
   const runtimeTask = runtimeTaskWithInlineBundle(input.runtime_task, sourceRoots)
   const effectiveInput = { ...input, runtime_task: runtimeTask }
   const stagedFiles = stagedRuntimeSources(effectiveInput, taskInput, sourceRoots)
-  const providerPlugins = providerPluginEntries(input, artifacts)
+  const providerPlugins = providerPluginEntries(input, sourcePackageRoot)
   const providerSlugs = providerPlugins.map((plugin) => plugin.slug).join(",")
   const providerContracts = providerPlugins.map((plugin) => ({ slug: plugin.slug, pluginFile: plugin.pluginFile, loadAs: plugin.loadAs ?? "plugin" }))
-  const componentPluginEntries = componentPlugins([...runtimeProfileComponentContracts(input), ...(input.component_contracts ?? [])], artifacts)
+  const componentPluginEntries = componentPlugins([...runtimeProfileComponentContracts(input), ...(input.component_contracts ?? [])], sourcePackageRoot)
   const callerExtraPlugins = agentTaskExtraPlugins(input)
   const defaultRuntimeComponents = defaultAgentRuntimeComponentPlugins(componentPluginEntries, callerExtraPlugins)
   const extraPlugins = dedupeExtraPlugins([

packages/runtime-core/src/agent-task-recipe.ts

@@ -24,7 +24,7 @@ export function resolvePluginEntrypointContract(contract: PluginEntrypointContra
   const loadAs = contract.loadAs === "mu-plugin" ? "mu-plugin" : "plugin"
 
   if (contract.pluginFile) {
-    return { source, slug, pluginFile: contract.pluginFile, loadAs, fallback: "explicit" }
+    return { source, slug, pluginFile: canonicalPluginFile(slug, contract.pluginFile), loadAs, fallback: "explicit" }
   }
 
   for (const [name, fallback] of [[`${slug}.php`, "slug"], ["plugin.php", "plugin"]] as const) {
@@ -41,6 +41,14 @@ export function resolvePluginEntrypointContract(contract: PluginEntrypointContra
   return { source, slug, pluginFile: `${slug}/${slug}.php`, loadAs, fallback: "default" }
 }
 
+function canonicalPluginFile(slug: string, pluginFile: string): string {
+  const normalized = pluginFile.trim().replace(/\\/g, "/").replace(/^\/+/, "")
+  if (!normalized || normalized.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error(`Plugin entrypoint must be a safe path inside ${slug}: ${pluginFile}`)
+  }
+  return normalized === slug || normalized.startsWith(`${slug}/`) ? normalized : `${slug}/${normalized}`
+}
+
 export function sanitizePluginSlug(value: string): string {
   return value.trim().replace(/[^A-Za-z0-9_-]/g, "-")
 }

packages/runtime-core/src/component-contracts.ts

@@ -3,7 +3,7 @@ import { execFile } from "node:child_process"
 import { mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises"
 import { join, relative } from "node:path"
 import { promisify } from "node:util"
-import { materializeRuntimeSources, normalizeRuntimeSource, parseExternalPackageSourcePolicy } from "../.github/scripts/run-agent-task/materialize-external-native-package.mjs"
+import { inspectZipArchive, materializeRuntimeSources, normalizeRuntimeSource, normalizeRuntimeSources, parseExternalPackageSourcePolicy } from "../.github/scripts/run-agent-task/materialize-external-native-package.mjs"
 import { withTempDir } from "../scripts/test-kit.js"
 import { buildAgentTaskRecipe } from "../packages/runtime-core/src/agent-task-recipe.js"
 import { normalizeTaskInput } from "../packages/runtime-core/src/task-input.js"
@@ -45,11 +45,15 @@ await withTempDir("wp-codebox-runtime-sources-", async (repository) => {
   const recipe = buildAgentTaskRecipe({ goal: "verify lowering", ...loweredInput }, normalizeTaskInput({ goal: "verify lowering" }), "latest")
   assert.ok(recipe.inputs?.extra_plugins?.some((plugin) => plugin.slug === "runtime" && plugin.loadAs === "mu-plugin"))
   assert.ok(recipe.inputs?.extra_plugins?.some((plugin) => plugin.slug === "example-provider" && plugin.activate === true))
+  assert.equal(recipe.inputs?.extra_plugins?.find((plugin) => plugin.slug === "runtime")?.pluginFile, "runtime/runtime.php")
+  assert.equal(recipe.inputs?.extra_plugins?.find((plugin) => plugin.slug === "example-provider")?.pluginFile, "example-provider/provider.php")
   assert.equal(recipe.runtime?.overlays?.[0].strategy, "scoped-bundle")
   await assert.rejects(materializeRuntimeSources([{ ...sources[0], revision: "main" }], { policy, remotes: { "example/runtime": repository } }), /immutable 40-character/)
   assert.throws(() => normalizeRuntimeSource({ ...sources[0], version: 2 }, policy), /version must be 1/)
   await assert.rejects(materializeRuntimeSources([{ ...sources[0], path: "../components/runtime" }], { policy, remotes: { "example/runtime": repository } }), /without traversal/)
   await assert.rejects(materializeRuntimeSources([{ ...sources[0], repository: "other/runtime" }], { policy, remotes: { "example/runtime": repository } }), /not authorized/)
+  assert.throws(() => normalizeRuntimeSources([sources[0], { ...sources[1], metadata: { slug: "runtime" } }], policy), /duplicate plugin slug/)
+  assert.throws(() => normalizeRuntimeSources([{ ...sources[0], metadata: { slug: "runtime", loadAs: "mu-plugin", pluginFile: "../runtime.php" } }], policy), /without traversal/)
   await assert.rejects(materializeRuntimeSources([{ ...sources[0], digest: `sha256-git-archive-v1:${"0".repeat(64)}` }], { policy, remotes: { "example/runtime": repository } }), /digest does not match/)
   assert.throws(() => normalizeRuntimeSource({ ...sources[0], metadata: { slug: "runtime", loadAs: "unknown" } }, policy), /loadAs/)
   await symlink("runtime.php", join(repository, "components/runtime/link.php"))
@@ -59,6 +63,37 @@ await withTempDir("wp-codebox-runtime-sources-", async (repository) => {
   await rm(materialized.root, { recursive: true, force: true })
 })
 
+await withTempDir("wp-codebox-runtime-zip-source-", async (directory) => {
+  const archiveRoot = join(directory, "example-provider")
+  await mkdir(archiveRoot, { recursive: true })
+  await writeFile(join(archiveRoot, "plugin.php"), "<?php /* Plugin Name: Example Provider */\n")
+  await execFileAsync("zip", ["-q", "-r", "provider.zip", "example-provider"], { cwd: directory })
+  const archive = await readFile(join(directory, "provider.zip"))
+  const url = "https://downloads.example.test/provider.zip"
+  const digest = (await execFileAsync("shasum", ["-a", "256", join(directory, "provider.zip")])).stdout.split(/\s+/)[0]
+  const policy = parseExternalPackageSourcePolicy(JSON.stringify({ version: 1, repositories: {}, runtime_artifacts: [{ url, sha256: digest }] }))
+  const source = { version: 1, role: "provider_plugin", source: { type: "https_zip", url, sha256: digest, archive_root: "example-provider" }, metadata: { slug: "example-provider", pluginFile: "plugin.php", activate: true } }
+  const materialized = await materializeRuntimeSources([source], { policy, fetch: async () => new Response(archive) })
+  assert.equal(materialized.lowered[0].provider_plugins[0].slug, "example-provider")
+  assert.deepEqual(materialized.descriptors[0], { role: "provider_plugin", source: { type: "https_zip", url, sha256: digest, archive_root: "example-provider" } })
+  await assert.rejects(materializeRuntimeSources([{ ...source, source: { ...source.source, sha256: "0".repeat(64) } }], { policy, fetch: async () => new Response(archive) }), /trusted policy/)
+  assert.throws(() => normalizeRuntimeSource({ ...source, source: { ...source.source, url: "http://downloads.example.test/provider.zip" } }, policy), /HTTPS/)
+  await assert.rejects(materializeRuntimeSources([{ ...source, source: { ...source.source, archive_root: "other" } }], { policy, fetch: async () => new Response(archive) }), /archive root/)
+  assert.throws(() => normalizeRuntimeSource({ ...source, role: "bundled_library" }, policy), /component and provider_plugin/)
+  const encrypted = Buffer.from(archive)
+  const centralDirectory = encrypted.indexOf(Buffer.from([0x50, 0x4b, 0x01, 0x02]))
+  encrypted.writeUInt16LE(encrypted.readUInt16LE(centralDirectory + 8) | 1, centralDirectory + 8)
+  assert.throws(() => inspectZipArchive(encrypted), /encrypted/)
+  const bomb = Buffer.from(archive)
+  bomb.writeUInt32LE(33 * 1024 * 1024, centralDirectory + 24)
+  assert.throws(() => inspectZipArchive(bomb), /oversized/)
+  await symlink("plugin.php", join(archiveRoot, "link.php"))
+  await execFileAsync("zip", ["-q", "-y", "symlink.zip", "example-provider/link.php"], { cwd: directory })
+  const symlinkArchive = await readFile(join(directory, "symlink.zip"))
+  assert.throws(() => inspectZipArchive(symlinkArchive), /symlink|special-file/)
+  await rm(materialized.root, { recursive: true, force: true })
+})
+
 await withTempDir("wp-codebox-runtime-source-upload-", async (directory) => {
   const workspace = join(directory, "workspace")
   const artifacts = join(workspace, ".codebox", "agent-task-artifacts")
@@ -68,10 +103,19 @@ await withTempDir("wp-codebox-runtime-source-upload-", async (directory) => {
   await mkdir(privateRoot, { recursive: true })
   await writeFile(join(privateRoot, "source.php"), "<?php // private runtime source\n")
   await writeFile(join(artifacts, "safe.json"), JSON.stringify({ provenance: { role: "component", repository: "example/runtime", revision: "a".repeat(40), path: "plugin" } }))
+  await writeFile(join(workspace, ".codebox", "native-agent-task-input.json"), JSON.stringify({
+    component_contracts: [{
+      path: privateRoot,
+      metadata: { runtime_source: { role: "component", repository: "example/runtime", revision: "a".repeat(40), path: "plugin" } },
+    }],
+  }))
   const script = new URL("../.github/scripts/run-agent-task/prepare-agent-task-upload.mjs", import.meta.url)
   await execFileAsync(process.execPath, [script.pathname], { env: { ...process.env, AGENT_TASK_WORKSPACE: workspace, AGENT_TASK_UPLOAD_PATH: upload, WP_CODEBOX_RUNTIME_SOURCE_ROOT: privateRoot } })
   const staged = await readFile(join(upload, ".codebox", "agent-task-artifacts", "safe.json"), "utf8")
   assert.doesNotMatch(staged, /private-runtime-source|private runtime source/)
+  const stagedInput = await readFile(join(upload, ".codebox", "native-agent-task-input.json"), "utf8")
+  assert.doesNotMatch(stagedInput, /private-runtime-source/)
+  assert.match(stagedInput, /"runtime_source"/)
   await writeFile(join(artifacts, "leak.json"), privateRoot)
   await assert.rejects(execFileAsync(process.execPath, [script.pathname], { env: { ...process.env, AGENT_TASK_WORKSPACE: workspace, AGENT_TASK_UPLOAD_PATH: upload, WP_CODEBOX_RUNTIME_SOURCE_ROOT: privateRoot } }), /Runtime source paths must never be persisted/)
 })