Allow Docs Agent runner contract cutover (#1752)

* Make runner recipe optional for Docs Agent cutover

* Fail closed without runner recipe

* Correct Docs Agent merge-order link

Author: chubes4

.github/scripts/run-agent-task/build-codebox-task-request.mjs

@@ -20,6 +20,11 @@ function requiredString(name) {
   return value
 }
 
+function optionalString(name) {
+  const value = process.env[name]?.trim() ?? ""
+  return value || undefined
+}
+
 function booleanEnv(name) {
   return process.env[name] === "true"
 }
@@ -37,9 +42,17 @@ function output(name, value) {
 }
 
 const artifactDeclarations = parseJson("ARTIFACT_DECLARATIONS", [], "array")
+const runnerRecipe = optionalString("RUNNER_RECIPE")
+const runAgent = booleanEnv("RUN_AGENT")
+const dryRun = booleanEnv("DRY_RUN")
+
+if (!runnerRecipe && runAgent && !dryRun) {
+  throw new Error("RUNNER_RECIPE may be omitted only when RUN_AGENT=false or DRY_RUN=true. The executable workflow in wp-codebox PR #1751 must land before a live agent run can omit it.")
+}
+
 const request = {
   schema: "wp-codebox/agent-task-workflow-request/v1",
-  runner_recipe: requiredString("RUNNER_RECIPE"),
+  ...(runnerRecipe ? { runner_recipe: runnerRecipe } : {}),
   agent_bundle: requiredString("AGENT_BUNDLE"),
   workload: {
     id: process.env.WORKLOAD_ID || "agent-task",
@@ -85,12 +98,12 @@ const request = {
     projections: parseJson("OUTPUT_PROJECTIONS", {}, "object"),
   },
   callback_data: parseJson("CALLBACK_DATA", {}, "object"),
-  run_agent: booleanEnv("RUN_AGENT"),
-  dry_run: booleanEnv("DRY_RUN"),
+  run_agent: runAgent,
+  dry_run: dryRun,
 }
 
 const runId = `${request.workload.id}-${process.env.GITHUB_RUN_ID || "local"}`.replace(/[^A-Za-z0-9._-]+/g, "-")
-const status = request.run_agent && !request.dry_run ? "planned" : "skipped"
+const status = !request.run_agent ? "skipped" : request.dry_run ? "dry-run" : "planned"
 const result = {
   schema: "wp-codebox/agent-task-workflow-result/v1",
   run_id: runId,

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

@@ -4,9 +4,9 @@ name: Run Agent Task (reusable)
   workflow_call:
     inputs:
       runner_recipe:
-        description: Codebox runner recipe descriptor, such as OWNER/REPO@ref:path.
+        description: Optional temporary Codebox runner recipe descriptor, such as OWNER/REPO@ref:path.
         type: string
-        required: true
+        required: false
       agent_bundle:
         description: Repository-relative path to the agent bundle selected by the caller.
         type: string

docs/agent-task-reusable-workflow.md

@@ -7,7 +7,6 @@ jobs:
   run-agent-task:
     uses: Automattic/wp-codebox/.github/workflows/run-agent-task.yml@main
     with:
-      runner_recipe: Automattic/example-runner@main:ci/runner-recipe.json
       agent_bundle: bundles/example-agent
       workload_id: example-maintenance
       workload_label: Run example maintenance
@@ -53,24 +52,26 @@ jobs:
     secrets: inherit
 ```
 
-Consumers provide product-level task inputs: the selected runner recipe, agent
-bundle, target repository, workspace publication request, verification commands,
-drift checks, artifact expectations, typed artifact declarations, and output
-projection. The workflow returns stable run outputs; implementation-specific
-runtime wiring, workspace adapters, plugins, and model setup stay behind the WP
-Codebox boundary.
+Consumers provide product-level task inputs: the agent bundle, target repository,
+workspace publication request, verification commands, drift checks, artifact
+expectations, typed artifact declarations, and output projection. The workflow
+returns stable run outputs; implementation-specific runtime wiring, workspace
+adapters, plugins, and model setup stay behind the WP Codebox boundary.
 
 ## Runner Recipe
 
-`runner_recipe` is a descriptor for a committed runner recipe, such as
-`Automattic/example-runner@main:ci/runner-recipe.json`. The recipe stays owned by
-the product workflow. Consumers pass the descriptor and the selected
-`agent_bundle`; they do not pass worker filesystem paths, runtime substrate
-checkout rules, package internals, or private workflow names.
+`runner_recipe` is a temporary optional input while callers transition away from
+the runner-recipe contract. It may be omitted only for an explicit
+`run_agent: false` skipped result or `dry_run: true` dry-run result. A live
+`run_agent: true` request without a recipe fails closed until the executable
+[wp-codebox#1751](https://github.com/Automattic/wp-codebox/pull/1751) workflow
+lands. Merge the transition in this order: this bridge, Docs Agent caller cleanup
+([docs-agent#119](https://github.com/Automattic/docs-agent/pull/119)), then #1751,
+which deletes this input.
 
 ## Inputs
 
-- `runner_recipe`: committed runner recipe descriptor.
+- `runner_recipe`: optional temporary runner recipe descriptor; removed by #1751 after Docs Agent caller cleanup.
 - `agent_bundle`: selected agent bundle path in the product repository.
 - `workload_id`, `workload_label`, and `component_id`: caller-owned run labels.
 - `target_repo`: `OWNER/REPO` target repository.
@@ -96,6 +97,6 @@ checkout rules, package internals, or private workflow names.
 - `declared_artifacts_json`: typed artifact declarations accepted for the run.
 
 The workflow is intentionally product-input-first. Consumers should model new
-behavior as runner recipe fields or workflow inputs instead of depending on
-worker filesystem paths, runtime internals, package internals, or the private
-implementation that executes the task.
+behavior as workflow inputs instead of depending on worker filesystem paths,
+runtime internals, package internals, or the private implementation that
+executes the task.

tests/agent-task-reusable-workflow.test.ts

@@ -13,6 +13,7 @@ const publicWorkflowSurface = workflow.slice(0, workflow.indexOf("jobs:"))
 assert.match(workflow, /^name: Run Agent Task \(reusable\)$/m)
 assert.match(workflow, /workflow_call:/)
 assert.match(workflow, /runner_recipe:/)
+assert.match(workflow, /runner_recipe:\n\s+description:[^\n]*temporary[^\n]*\n\s+type: string\n\s+required: false/)
 assert.match(workflow, /agent_bundle:/)
 assert.match(workflow, /runner_workspace:/)
 assert.match(workflow, /artifact_declarations:/)
@@ -31,12 +32,14 @@ const docs = await readFile(new URL("../docs/agent-task-reusable-workflow.md", i
 assert.match(docs, /^# Agent Task Reusable Workflow/m)
 assert.match(docs, /Automattic\/wp-codebox\/.github\/workflows\/run-agent-task.yml@main/)
 assert.match(docs, /runner_recipe/)
+assert.match(docs, /temporary optional input/)
+assert.match(docs, /fails closed until the executable\s+\[wp-codebox#1751\]/)
 assert.match(docs, /agent_bundle/)
 assert.match(docs, /runner_workspace/)
 assert.match(docs, /access_token_repos/)
 assert.match(docs, /require_access_token/)
-assert.match(docs, /implementation-specific\s+runtime wiring, workspace adapters, plugins, and model setup stay behind the WP\s+Codebox boundary/)
-assert.doesNotMatch(docs, /docs-agent|wp-codebox\/docs-agent-runner-recipe\/v1|recipe_path|recipe_json|wp_codebox_ref|datamachine|data machine|data-machine|agents api|sandbox mounts|ability ids|provider internals|homeboy|require_app_token/i)
+assert.match(docs, /implementation-specific\s+runtime\s+wiring,\s+workspace\s+adapters,\s+plugins,\s+and\s+model\s+setup\s+stay\s+behind\s+the\s+WP\s+Codebox\s+boundary/)
+assert.doesNotMatch(docs, /wp-codebox\/docs-agent-runner-recipe\/v1|recipe_path|recipe_json|wp_codebox_ref|datamachine|data machine|data-machine|agents api|sandbox mounts|ability ids|provider internals|homeboy|require_app_token/i)
 
 const tmp = await mkdtemp(join(tmpdir(), "wp-codebox-agent-task-workflow-"))
 const outputPath = join(tmp, "github-output.txt")
@@ -60,7 +63,7 @@ await execFileAsync("node", [new URL("../.github/scripts/run-agent-task/build-co
     WRITABLE_PATHS: "README.md,docs/**",
     PROVIDER: "openai",
     MODEL: "gpt-5.5",
-    RUNNER_WORKSPACE: '{"enabled":true,"repo":"Automattic/example-target"}',
+    RUNNER_WORKSPACE_CONFIG: '{"enabled":true,"repo":"Automattic/example-target"}',
     VALIDATION_DEPENDENCIES: "",
     CONTEXT_REPOSITORIES: "[]",
     VERIFICATION_COMMANDS: '[{"command":"npm test","description":"Run checks"}]',
@@ -105,4 +108,57 @@ assert.match(outputs, /credential_mode<<__WP_CODEBOX_OUTPUT__\napp-token\n__WP_C
 assert.match(outputs, /request_path<<__WP_CODEBOX_OUTPUT__\n\.codebox\/agent-task-request\.json\n__WP_CODEBOX_OUTPUT__/)
 assert.match(outputs, /result_path<<__WP_CODEBOX_OUTPUT__\n\.codebox\/agent-task-workflow-result\.json\n__WP_CODEBOX_OUTPUT__/)
 
+async function runTaskRequest(runnerRecipe, runAgent, dryRun) {
+  const cwd = await mkdtemp(join(tmpdir(), "wp-codebox-agent-task-workflow-no-recipe-"))
+  const outputPath = join(cwd, "github-output.txt")
+  await writeFile(outputPath, "")
+
+  const run = execFileAsync("node", [new URL("../.github/scripts/run-agent-task/build-codebox-task-request.mjs", import.meta.url).pathname], {
+    cwd,
+    env: {
+      ...process.env,
+      GITHUB_OUTPUT: outputPath,
+      RUNNER_RECIPE: runnerRecipe,
+      AGENT_BUNDLE: "bundles/example-agent",
+      TARGET_REPO: "Automattic/example-target",
+      PROMPT: "Update the configured surface.",
+      MAX_TURNS: "12",
+      STEP_BUDGET: "16",
+      TIME_BUDGET_MS: "600000",
+      RUN_AGENT: String(runAgent),
+      DRY_RUN: String(dryRun),
+    },
+  })
+
+  return { cwd, outputPath, run }
+}
+
+for (const { runAgent, dryRun, status } of [
+  { runAgent: false, dryRun: false, status: "skipped" },
+  { runAgent: false, dryRun: true, status: "skipped" },
+  { runAgent: true, dryRun: true, status: "dry-run" },
+]) {
+  const omittedRecipe = await runTaskRequest("", runAgent, dryRun)
+  await omittedRecipe.run
+
+  const omittedRecipeRequest = JSON.parse(await readFile(join(omittedRecipe.cwd, ".codebox", "agent-task-request.json"), "utf8"))
+  const omittedRecipeResult = JSON.parse(await readFile(join(omittedRecipe.cwd, ".codebox", "agent-task-workflow-result.json"), "utf8"))
+  assert.equal(Object.hasOwn(omittedRecipeRequest, "runner_recipe"), false)
+  assert.equal(omittedRecipeResult.status, status)
+  assert.match(await readFile(omittedRecipe.outputPath, "utf8"), new RegExp(`job_status<<__WP_CODEBOX_OUTPUT__\\n${status}\\n__WP_CODEBOX_OUTPUT__`))
+}
+
+const recipeBackedLiveRun = await runTaskRequest("Automattic/example-runner@abc123:ci/runner-recipe.json", true, false)
+await recipeBackedLiveRun.run
+const recipeBackedLiveResult = JSON.parse(await readFile(join(recipeBackedLiveRun.cwd, ".codebox", "agent-task-workflow-result.json"), "utf8"))
+assert.equal(recipeBackedLiveResult.status, "planned")
+
+const omittedRecipeLiveRun = await runTaskRequest("", true, false)
+await assert.rejects(omittedRecipeLiveRun.run, (error: { stderr: string }) => {
+  assert.match(error.stderr, /RUNNER_RECIPE may be omitted only when RUN_AGENT=false or DRY_RUN=true/)
+  assert.match(error.stderr, /executable workflow in wp-codebox PR #1751 must land/)
+  return true
+})
+assert.equal(await readFile(omittedRecipeLiveRun.outputPath, "utf8"), "")
+
 console.log("agent task reusable workflow ok")