Harden canonical transcript upload staging

chubes4 · chubes4 · commit 10e57c3faab2 · 2026-07-14T11:56:20.000-04:00
diff --git a/.github/scripts/run-agent-task/prepare-agent-task-upload.mjs b/.github/scripts/run-agent-task/prepare-agent-task-upload.mjs
@@ -1,12 +1,14 @@
 import { constants } from "node:fs"
-import { lstat, mkdir, open, readdir, readFile, rm, writeFile } from "node:fs/promises"
+import { lstat, mkdir, open, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises"
 import { isUtf8 } from "node:buffer"
 import { createHash } from "node:crypto"
 import { fileURLToPath, pathToFileURL } from "node:url"
 import { isAbsolute, join, relative, resolve } from "node:path"
 import { assertNoRuntimeSourcePaths, sanitizeRuntimeSourceJson } from "./runtime-source-sanitizer.mjs"
 
 const MAX_UPLOAD_FILE_BYTES = 4 * 1024 * 1024
+const MAX_TRANSCRIPT_EXECUTIONS = 64
+const MAX_REVIEW_TEXT_BYTES = 32 * 1024
 const workspace = resolve(process.env.AGENT_TASK_WORKSPACE || process.cwd())
 const uploadPath = resolve(process.env.AGENT_TASK_UPLOAD_PATH || join(workspace, ".codebox", "agent-task-upload"))
 const requestPath = resolve(process.env.AGENT_TASK_REQUEST_PATH || join(workspace, ".codebox", "agent-task-request.json"))
@@ -154,20 +156,99 @@ async function canonicalTranscript(result) {
   return refs[0]
 }
 
+function digest(bytes) {
+  return createHash("sha256").update(bytes).digest("hex")
+}
+
+function boundedText(value) {
+  if (typeof value !== "string") return undefined
+  const text = redact(sanitizeText(value)).slice(0, MAX_REVIEW_TEXT_BYTES)
+  return containsRuntimeSourceContent(text) ? "[redacted-source-content]" : text
+}
+
+function safeTargetPath(value) {
+  const path = safeRelativeArtifactPath(value)
+  return path ? `workspace/${path}` : undefined
+}
+
+function projectToolCall(value) {
+  const entry = record(value)
+  const tool = boundedText(entry.tool_id ?? entry.toolId ?? entry.name ?? entry.tool_name)
+  const path = safeTargetPath(record(entry.args ?? entry.arguments).path ?? entry.path)
+  const result = record(entry.result ?? entry.output)
+  const rawContent = result.content ?? entry.content
+  const content = path && /workspace/i.test(tool ?? "") && typeof rawContent === "string"
+    ? redact(sanitizeText(rawContent)).slice(0, MAX_REVIEW_TEXT_BYTES)
+    : undefined
+  return Object.fromEntries(Object.entries({ tool, path, status: boundedText(entry.status), arguments: path ? { path } : undefined, content, error: boundedText(record(entry.error).message ?? entry.error) }).filter(([, item]) => item !== undefined))
+}
+
+function projectParsed(value) {
+  const parsed = record(value)
+  const messages = Array.isArray(parsed.messages) ? parsed.messages : Array.isArray(parsed.model_messages) ? parsed.model_messages : []
+  const tools = Array.isArray(parsed.tool_calls) ? parsed.tool_calls : Array.isArray(parsed.toolCalls) ? parsed.toolCalls : []
+  const results = Array.isArray(parsed.tool_results) ? parsed.tool_results : Array.isArray(parsed.toolResults) ? parsed.toolResults : []
+  const errors = Array.isArray(parsed.errors) ? parsed.errors : parsed.error ? [parsed.error] : []
+  const agent = record(parsed.agent ?? parsed.agent_metadata)
+  return Object.fromEntries(Object.entries({
+    agent: Object.fromEntries(["id", "name", "model", "provider", "status"].flatMap((key) => boundedText(agent[key]) ? [[key, boundedText(agent[key])]] : [])),
+    model_messages: messages.slice(0, MAX_TRANSCRIPT_EXECUTIONS).flatMap((message) => boundedText(record(message).content ?? record(message).text ?? message) ? [{ role: boundedText(record(message).role), content: boundedText(record(message).content ?? record(message).text ?? message) }] : []),
+    tool_calls: tools.slice(0, MAX_TRANSCRIPT_EXECUTIONS).map(projectToolCall),
+    tool_results: results.slice(0, MAX_TRANSCRIPT_EXECUTIONS).map(projectToolCall),
+    errors: errors.slice(0, MAX_TRANSCRIPT_EXECUTIONS).flatMap((error) => boundedText(record(error).message ?? error) ? [boundedText(record(error).message ?? error)] : []),
+  }).filter(([, item]) => Array.isArray(item) ? item.length > 0 : Object.keys(item).length > 0))
+}
+
+async function trustedTranscriptFile(path) {
+  const root = await realpath(artifactsPath).catch(() => "")
+  if (!root) return { unavailable: "artifact-root-missing" }
+  const parts = path.split("/")
+  let current = root
+  for (const part of parts) {
+    current = join(current, part)
+    const stat = await lstat(current).catch((error) => error?.code === "ENOENT" ? undefined : Promise.reject(error))
+    if (!stat) return { unavailable: "referenced-file-missing" }
+    if (stat.isSymbolicLink()) throw new Error("Canonical transcript must not traverse symlinks.")
+  }
+  const stat = await lstat(current)
+  if (!stat.isFile() || stat.size > MAX_UPLOAD_FILE_BYTES) throw new Error("Canonical transcript must be a bounded regular file.")
+  const resolved = await realpath(current)
+  const contained = relative(root, resolved)
+  if (contained === ".." || contained.startsWith(`..${String.fromCharCode(47)}`) || isAbsolute(contained)) throw new Error("Canonical transcript escapes the trusted artifact root.")
+  return { source: resolved }
+}
+
 async function stageCanonicalTranscript(result) {
   const ref = await canonicalTranscript(result)
   if (!ref) return undefined
   const path = safeRelativeArtifactPath(ref.path)
-  const source = resolve(artifactsPath, path)
-  if (relative(artifactsPath, source).startsWith("..") || sourceCategory(path, source)) throw new Error("Canonical transcript must stay under the trusted artifact root.")
+  if (sourceCategory(path, resolve(artifactsPath, path))) throw new Error("Canonical transcript must stay under the trusted artifact root.")
+  const trusted = await trustedTranscriptFile(path)
+  if (trusted.unavailable) return { unavailable: trusted.unavailable, provenance: { kind: ref.kind, artifact_path: path } }
+  const source = trusted.source
+  const bytes = await readFile(source)
+  if (bytes.includes(0) || !isUtf8(bytes)) throw new Error("Canonical transcript must be UTF-8 JSON.")
+  const actualDigest = digest(bytes)
+  const expectedDigest = typeof ref.sha256 === "string" ? ref.sha256 : record(ref.digest).value
+  if (expectedDigest && expectedDigest !== actualDigest) throw new Error("Canonical transcript digest does not match its normalized ref.")
+  const raw = parseJsonOrEmpty(bytes.toString("utf8"))
+  if (raw.schema !== "wp-codebox/agent-transcript/v1" || !Array.isArray(raw.executions) || raw.executions.length > MAX_TRANSCRIPT_EXECUTIONS) throw new Error("Canonical transcript must be a bounded wp-codebox/agent-transcript/v1 envelope.")
+  const projection = {
+    schema: "wp-codebox/reviewer-agent-transcript/v1",
+    executions: raw.executions.map((execution, index) => {
+      const entry = record(execution)
+      if (typeof entry.command !== "string" || typeof entry.exitCode !== "number") throw new Error("Canonical transcript execution is malformed.")
+      return Object.fromEntries(Object.entries({ execution_index: typeof entry.executionIndex === "number" ? entry.executionIndex : index, command: boundedText(entry.command), status: entry.exitCode === 0 ? "succeeded" : "failed", exit_code: entry.exitCode, parsed: Object.keys(record(entry.parsed)).length ? projectParsed(entry.parsed) : undefined, error: boundedText(entry.stderr) }).filter(([, item]) => item !== undefined))
+    }),
+  }
   const destination = join(uploadPath, ".codebox", "agent-task-artifacts", "transcript.json")
-  if (!await stageTextFile(source, destination, { allowTargetCode: true })) throw new Error("Canonical transcript must be a bounded regular UTF-8 file.")
-  const bytes = await readFile(destination)
-  if (!Object.keys(record(parseJsonOrEmpty(bytes.toString("utf8")))).length) throw new Error("Canonical transcript must be a JSON object.")
+  await mkdir(resolve(destination, ".."), { recursive: true })
+  await writeFile(destination, `${JSON.stringify(projection, null, 2)}\n`)
+  const projectionDigest = digest(await readFile(destination))
   return {
     path: ".codebox/agent-task-artifacts/transcript.json",
-    sha256: createHash("sha256").update(bytes).digest("hex"),
-    provenance: { kind: ref.kind, artifact_path: path, ...(ref.sha256 ? { source_sha256: ref.sha256 } : {}) },
+    sha256: projectionDigest,
+    provenance: { kind: ref.kind, artifact_path: path, source_sha256: actualDigest, projection_sha256: projectionDigest },
   }
 }
 
@@ -277,6 +358,12 @@ for (const path of declaredPaths) {
   await stageTextFile(source, join(uploadPath, ".codebox", "agent-task-artifacts", path))
 }
 const transcript = await stageCanonicalTranscript(result)
+if (transcript?.provenance?.source_sha256) {
+  const stagedResultPath = join(uploadPath, ".codebox", "agent-task-workflow-result.json")
+  const stagedResult = parseJsonOrEmpty(await readFile(stagedResultPath, "utf8"))
+  stagedResult.artifact_upload = { canonical_transcript: transcript.provenance }
+  await writeFile(stagedResultPath, `${JSON.stringify(stagedResult, null, 2)}\n`)
+}
 await mkdir(join(uploadPath, ".codebox", "agent-task-artifacts"), { recursive: true })
 await writeFile(join(uploadPath, ".codebox", "agent-task-artifacts", "runtime-provenance.json"), `${JSON.stringify({ schema: "wp-codebox/agent-task-runtime-provenance/v1", sources: runtimeProvenance(request) }, null, 2)}\n`)
 await writeFile(join(uploadPath, ".codebox", "agent-task-artifacts", "exclusions.json"), `${JSON.stringify({ schema: "wp-codebox/agent-task-upload-exclusions/v1", ...(await exclusions(artifactsPath, declaredPaths, transcript)) }, null, 2)}\n`)
diff --git a/docs/agent-runtime-contract.md b/docs/agent-runtime-contract.md
@@ -176,7 +176,7 @@ Generic command runners and host tool registries should write tool-call evidence
 
 The artifact verifier checks that transcript artifact refs are listed in `manifest.json`, stay within the bundle, and match their declared SHA-256 digests when present. This lets a generic command runner branch merge by materializing its command/tool transcript into `files/runtime-evidence/tool-calls/transcript.json` and appending the referenced input/output artifacts through the existing runtime-evidence manifest update path.
 
-The reusable agent-task workflow separately uploads one normalized `codebox-transcript` ref for reviewer diagnostics. It accepts exactly one bounded, regular, non-symlink JSON file under its trusted artifact root, stages it as `.codebox/agent-task-artifacts/transcript.json`, and records the source ref plus staged SHA-256 in the upload exclusions manifest. This reviewer copy removes secrets and private host/runtime/source/snapshot paths while retaining target-relative tool arguments, errors, and model messages; package declarations cannot authorize alternate transcript paths or dependency source files.
+The reusable agent-task workflow separately handles one normalized `codebox-transcript` ref as optional reviewer evidence. A missing referenced file is recorded as unavailable; an existing file must be a bounded `wp-codebox/agent-transcript/v1` regular JSON file whose canonical path stays under the artifact root without symlink traversal. When the normalized ref provides a digest it must match the original bytes. The workflow stages a compact `wp-codebox/reviewer-agent-transcript/v1` projection at `.codebox/agent-task-artifacts/transcript.json`, not the raw transcript or command stdout. Its provenance records verified source and projection SHA-256 values in both the exclusions manifest and staged result. The projection retains execution command/status, typed workspace tool content, model messages, tool calls/results, errors, and agent metadata while removing setup stacks, package/bootstrap payloads, plugin inventories, unknown fields, secrets, and private host/runtime/source/snapshot paths. Package declarations cannot authorize alternate transcript paths or dependency source files.
 
 ## Runner Workspace Publication
 
diff --git a/docs/agent-task-reusable-workflow.md b/docs/agent-task-reusable-workflow.md
@@ -140,13 +140,14 @@ runner token, so a fabricated publication result cannot satisfy the gate.
 The result artifact includes the executable task input, normalized runtime
 result, evaluated projections, verification records, and runner-owned
 publication result. A single canonical `codebox-transcript` ref from the
-normalized runtime result is staged independently of package declarations at
-`.codebox/agent-task-artifacts/transcript.json`. The uploader accepts only a
-bounded regular UTF-8 file beneath the trusted artifact root, records its
-source provenance and staged digest in `exclusions.json`, and sanitizes secrets
-and private runtime, workspace, and snapshot paths while preserving
-target-relative tool arguments, errors, and model messages. Runtime source
-trees remain excluded. Runtime input, result, and diagnostics are uploaded from
+normalized runtime result is handled independently of package declarations at
+`.codebox/agent-task-artifacts/transcript.json`. Missing canonical evidence is
+recorded as unavailable. Present evidence is verified against its normalized
+digest when supplied, then converted from `wp-codebox/agent-transcript/v1` into
+a compact `wp-codebox/reviewer-agent-transcript/v1` projection. The projection
+records verified source and output digests in `exclusions.json`, retains bounded
+diagnostic tool and model data, and excludes raw stdout, source trees, secrets,
+private paths, setup stacks, and package payloads. Runtime input, result, and diagnostics are uploaded from
 `workspace/.codebox/` with `if: always()`, including execution failures. A request
 artifact alone is not a successful task result.
 
diff --git a/tests/execute-native-agent-task-playground-e2e.test.ts b/tests/execute-native-agent-task-playground-e2e.test.ts
@@ -86,6 +86,8 @@ add_filter( 'pre_http_request', static function( $preempt, $args, $url ) {
   const serialized = JSON.stringify(result)
   for (const privateValue of ["e2e-github-secret", "e2e-openai-secret", "PRIVATE_WORKSPACE_SENTINEL", "PRIVATE_NPM_SENTINEL", "PRIVATE_NETRC_SENTINEL", "PRIVATE_KEY_SENTINEL", "PRIVATE_CODEBOX_SENTINEL", "PRIVATE_NODE_MODULES_SENTINEL", sources.root, workspace]) assert.doesNotMatch(serialized, new RegExp(privateValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")))
   await execFileAsync(process.execPath, [uploader], { cwd: workspace, env: { ...process.env, AGENT_TASK_WORKSPACE: workspace, AGENT_TASK_REQUEST_PATH: join(workspace, ".codebox", "agent-task-request.json"), AGENT_TASK_UPLOAD_PATH: join(workspace, ".codebox", "agent-task-upload"), GITHUB_TOKEN: "e2e-github-secret", OPENAI_API_KEY: "e2e-openai-secret" } })
+  const exclusions = JSON.parse(await readFile(join(workspace, ".codebox", "agent-task-upload", ".codebox", "agent-task-artifacts", "exclusions.json"), "utf8"))
+  assert.equal(exclusions.canonical_transcripts[0].unavailable, "referenced-file-missing", "missing canonical evidence remains optional")
   const staged = JSON.stringify(await Promise.all((await readdir(join(workspace, ".codebox", "agent-task-upload"), { recursive: true })).map((path) => readFile(join(workspace, ".codebox", "agent-task-upload", path), "utf8").catch(() => ""))))
   for (const privateValue of ["wp-codebox-runner-workspace-seed-", workspace, "PRIVATE_WORKSPACE_SENTINEL", "PRIVATE_NPM_SENTINEL", "PRIVATE_NETRC_SENTINEL", "PRIVATE_KEY_SENTINEL"]) assert.doesNotMatch(staged, new RegExp(privateValue.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")))
   const stagedInput = JSON.parse(await readFile(join(workspace, ".codebox", "agent-task-upload", ".codebox", "native-agent-task-input.json"), "utf8"))
diff --git a/tests/runtime-sources-materialization.test.ts b/tests/runtime-sources-materialization.test.ts
@@ -1,5 +1,6 @@
 import assert from "node:assert/strict"
 import { execFile } from "node:child_process"
+import { createHash } from "node:crypto"
 import { access, chmod, mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises"
 import { join, relative } from "node:path"
 import { promisify } from "node:util"
@@ -165,18 +166,16 @@ await withTempDir("wp-codebox-runtime-source-upload-", async (directory) => {
   await execFileAsync(process.execPath, [script.pathname], { env: { ...process.env, AGENT_TASK_WORKSPACE: workspace, AGENT_TASK_UPLOAD_PATH: upload, WP_CODEBOX_RUNTIME_SOURCE_ROOT: privateRoot } })
   assert.match(await readFile(join(upload, ".codebox", "agent-task-artifacts", "safe.json"), "utf8"), /OpenAiProvider/)
   await mkdir(join(artifacts, "files"), { recursive: true })
-  await writeFile(join(artifacts, "files", "transcript.json"), JSON.stringify({
-    model_message: "Target snippet: <?php final class Target_Plugin {}",
-    tool_calls: [{ tool_id: "workspace.read", args: { path: "src/plugin.php" }, error: "Repeated workspace error" }, { tool_id: "workspace.read", args: { path: "src/plugin.php" }, error: "Repeated workspace error" }],
-    private_path: `${privateRoot}/source.php`,
-    host_path: "/Users/example/private-log.txt",
-    token: "secret-transcript-value",
-  }))
-  await writeFile(join(workspace, ".codebox", "agent-task-workflow-result.json"), JSON.stringify({ runtime_result: { agent_task_run_result: { refs: { transcripts: [{ kind: "codebox-transcript", path: "files/transcript.json", sha256: "a".repeat(64) }] } } }, typed_artifacts: [{ name: "reviewer-report", type: "report", artifact: { path: "prepared-plugins/agents-api/agents-api.php" } }] }))
+  const transcriptSource = JSON.stringify({ schema: "wp-codebox/agent-transcript/v1", executions: [{ executionIndex: 0, command: "wp-codebox.agent-sandbox-run", exitCode: 1, stderr: "Repeated workspace error", parsed: { agent: { id: "fixture", provider: "openai" }, messages: [{ role: "assistant", content: "Target snippet: <?php final class Target_Plugin {}" }], tool_calls: [{ tool_id: "workspace.read", args: { path: "src/plugin.php" }, result: { content: "<?php final class Target_Plugin {}" }, error: "Repeated workspace error" }], token: "secret-transcript-value", private_path: `${privateRoot}/source.php`, host_path: "/Users/example/private-log.txt" } }] })
+  await writeFile(join(artifacts, "files", "transcript.json"), transcriptSource)
+  const transcriptDigest = createHash("sha256").update(transcriptSource).digest("hex")
+  await writeFile(join(workspace, ".codebox", "agent-task-workflow-result.json"), JSON.stringify({ runtime_result: { agent_task_run_result: { refs: { transcripts: [{ kind: "codebox-transcript", path: "files/transcript.json", sha256: transcriptDigest }] } } }, typed_artifacts: [{ name: "reviewer-report", type: "report", artifact: { path: "prepared-plugins/agents-api/agents-api.php" } }] }))
   await execFileAsync(process.execPath, [script.pathname], { env: { ...process.env, AGENT_TASK_WORKSPACE: workspace, AGENT_TASK_UPLOAD_PATH: upload, WP_CODEBOX_RUNTIME_SOURCE_ROOT: privateRoot, OPENAI_API_KEY: "secret-transcript-value" } })
   const transcript = await readFile(join(upload, ".codebox", "agent-task-artifacts", "transcript.json"), "utf8")
-  assert.match(transcript, /Target snippet: <\?php/)
+  assert.match(transcript, /<\?php final class Target_Plugin/)
+  assert.match(transcript, /\[redacted-source-content\]/)
   assert.match(transcript, /Repeated workspace error/)
+  assert.match(transcript, /workspace\/src\/plugin.php/)
   assert.doesNotMatch(transcript, /private-runtime-source|secret-transcript-value|\/Users\/example/)
   const transcriptExclusions = await readFile(join(upload, ".codebox", "agent-task-artifacts", "exclusions.json"), "utf8")
   assert.match(transcriptExclusions, /canonical_transcripts/)
@@ -185,7 +184,7 @@ await withTempDir("wp-codebox-runtime-source-upload-", async (directory) => {
   await writeFile(outsideTranscript, JSON.stringify({ secret: "outside" }))
   await rm(join(artifacts, "files", "transcript.json"))
   await symlink(outsideTranscript, join(artifacts, "files", "transcript.json"))
-  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 } }), /bounded regular UTF-8 file/, "Canonical transcript refs cannot follow symlinks outside artifacts")
+  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 } }), /must not traverse symlinks/, "Canonical transcript refs cannot follow symlinks outside artifacts")
   await rm(join(artifacts, "files", "transcript.json"))
   await writeFile(join(artifacts, "files", "transcript.json"), JSON.stringify({ tool_calls: [] }))
   await writeFile(join(artifacts, "leak.json"), `runtime log ${privateRoot}/source.php`)
