Emit agent task artifact envelopes

Author: chubes4

package.json

@@ -76,6 +76,7 @@
     "test:runtime-php-snippets": "tsx tests/runtime-php-snippets.test.ts",
     "test:browser-runner-template": "tsx tests/browser-runner-template.test.ts",
     "test:editor-actions": "tsx tests/editor-actions.test.ts",
+    "test:artifact-result-envelope": "tsx tests/artifact-result-envelope.test.ts",
     "test:artifact-path-primitives": "tsx tests/artifact-path-primitives.test.ts",
     "test:browser-callback-materialization-contracts": "tsx tests/browser-callback-materialization-contracts.test.ts",
     "test:materialize-replay-package-command": "tsx tests/materialize-replay-package-command.test.ts",

packages/cli/src/commands/agent-task-run.ts

@@ -1,7 +1,7 @@
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
-import { buildAgentTaskRecipe, DEFAULT_WORDPRESS_VERSION, normalizeAgentRuntimeWorkload, normalizeAgentTaskRunResult, normalizeAgentTerminalResult, normalizeTaskInput, parseCommandJson, parseCommandOptions, resolveEffectiveRuntimeToolPolicy, type AgentTaskRunInput, type AgentTaskRunResultSummary, type AgentTerminalResult, type SandboxToolPolicySnapshot } from "@automattic/wp-codebox-core"
+import { artifactResultEnvelope, buildAgentTaskRecipe, DEFAULT_WORDPRESS_VERSION, normalizeAgentRuntimeWorkload, normalizeAgentTaskRunResult, normalizeAgentTerminalResult, normalizeTaskInput, parseCommandJson, parseCommandOptions, resolveEffectiveRuntimeToolPolicy, type AgentTaskRunInput, type AgentTaskRunResultSummary, type AgentTerminalResult, type ArtifactResultEnvelope, type SandboxToolPolicySnapshot } from "@automattic/wp-codebox-core"
 import { stripUndefined } from "@automattic/wp-codebox-core/internals"
 import { runRecipeRunCommand } from "./recipe-run.js"
 
@@ -30,6 +30,9 @@ interface AgentTaskRunOutput {
   completion_outcome: Record<string, unknown>
   component_contracts: Array<Record<string, unknown>>
   structured_artifacts: Array<Record<string, unknown>>
+  typed_artifacts: Array<Record<string, unknown>>
+  outputs: Record<string, unknown>
+  artifact_result: ArtifactResultEnvelope
   run: Record<string, unknown>
   diagnostics: Array<Record<string, unknown>>
   agent_runtime_diagnostics: Record<string, unknown>
@@ -147,11 +150,34 @@ export async function runAgentTask(input: AgentTaskRunInput, options: AgentTaskR
     const failureEvidence = success ? undefined : buildFailureEvidence({ input, task, wpVersion, artifacts, recipePath, generatedRecipeArtifact, run, capture })
     const outputDiagnostics = [...diagnostics(run, success ? 0 : capture.exitCode, success, failureEvidence), ...(hasAgentBundle ? workload.diagnostics.map((diagnostic) => ({ ...diagnostic })) : [])]
     const agentTaskRunResult = success ? normalizedRunResult : withFailureEvidence(normalizedRunResult, failureEvidence, outputDiagnostics)
+    const session = sandboxSession(input, run, artifacts, success ? "completed" : "failed")
+    const structuredArtifacts = structuredArtifactRefs(agentTaskResult)
+    const outputs = stripUndefined({ ...workload.outputs })
+    const typedArtifacts = typedArtifactRefs(agentTaskResult, outputs)
+    const evidence = evidenceRefs(run, artifacts, failureEvidence)
+    const artifactResult = artifactResultEnvelope({
+      operation: "agent-task-run",
+      status: success ? "created" : "failed",
+      artifactBundle: agentTaskRunResult.refs.artifact_bundles[0],
+      artifactRefs: [...agentTaskRunResult.refs.artifact_bundles, ...agentTaskRunResult.artifacts],
+      result: {
+        structured_artifacts: structuredArtifacts,
+        typed_artifacts: typedArtifacts,
+        agent_reply: agentReply(agentResult, terminalResult, agentTaskRunResult),
+        transcript_refs: agentTaskRunResult.refs.transcripts,
+        evidence_refs: evidence,
+        preview: previewMetadata(session, run),
+        session,
+        outputs,
+      },
+      diagnostics: artifactResultDiagnostics(outputDiagnostics),
+      metadata: artifactResultMetadata(run, input, agentTaskRunResult),
+    })
     const output: AgentTaskRunOutput = {
       success,
       schema: "wp-codebox/agent-task-run/v1",
       status: agentTaskRunResult.status,
-      session: sandboxSession(input, run, artifacts, success ? "completed" : "failed"),
+      session,
       task,
       task_input: taskInput,
       wp: wpVersion,
@@ -162,11 +188,14 @@ export async function runAgentTask(input: AgentTaskRunInput, options: AgentTaskR
       terminal_result: terminalResult,
       completion_outcome: completionOutcome,
       component_contracts: componentContractReport(run),
-      structured_artifacts: structuredArtifactRefs(agentTaskResult),
+      structured_artifacts: structuredArtifacts,
+      typed_artifacts: typedArtifacts,
+      outputs: { ...outputs, artifact_result: artifactResult },
+      artifact_result: artifactResult,
       run,
       diagnostics: outputDiagnostics,
       agent_runtime_diagnostics: await buildAgentRuntimeDiagnostics(run, input),
-      evidence_refs: evidenceRefs(run, artifacts, failureEvidence),
+      evidence_refs: evidence,
       failure_evidence: failureEvidence,
       run_metadata: stripUndefined({
         run_id: stringValue(runRecord.runId),
@@ -181,6 +210,7 @@ export async function runAgentTask(input: AgentTaskRunInput, options: AgentTaskR
         agent_runtime: {
           workload,
         },
+        artifact_result: artifactResult,
       },
     }
     return output
@@ -191,11 +221,29 @@ export async function runAgentTask(input: AgentTaskRunInput, options: AgentTaskR
     const failureEvidence = buildFailureEvidence({ input, task, wpVersion, artifacts, recipePath, generatedRecipeArtifact, run, capture, error })
     const failureDiagnostics = diagnostics(run, capture?.exitCode ?? 1, false, failureEvidence)
     const agentTaskRunResult = withFailureEvidence(normalizedRunResult, failureEvidence, failureDiagnostics)
+    const session = sandboxSession(input, run, artifacts, "failed")
+    const evidence = evidenceRefs(run, artifacts, failureEvidence)
+    const artifactResult = artifactResultEnvelope({
+      operation: "agent-task-run",
+      status: "failed",
+      artifactBundle: agentTaskRunResult.refs.artifact_bundles[0],
+      artifactRefs: [...agentTaskRunResult.refs.artifact_bundles, ...agentTaskRunResult.artifacts],
+      result: {
+        agent_reply: agentReply({}, normalizeAgentTerminalResult(run, { compatMode: true }), agentTaskRunResult),
+        transcript_refs: agentTaskRunResult.refs.transcripts,
+        evidence_refs: evidence,
+        preview: previewMetadata(session, run),
+        session,
+        outputs: {},
+      },
+      diagnostics: artifactResultDiagnostics(failureDiagnostics),
+      metadata: artifactResultMetadata(run, input, agentTaskRunResult),
+    })
     return {
       success: false,
       schema: "wp-codebox/agent-task-run/v1",
       status: agentTaskRunResult.status,
-      session: sandboxSession(input, run, artifacts, "failed"),
+      session,
       task,
       task_input: taskInput,
       wp: wpVersion,
@@ -207,10 +255,13 @@ export async function runAgentTask(input: AgentTaskRunInput, options: AgentTaskR
       completion_outcome: {},
       component_contracts: componentContractReport(run),
       structured_artifacts: [],
+      typed_artifacts: [],
+      outputs: { artifact_result: artifactResult },
+      artifact_result: artifactResult,
       run,
       diagnostics: failureDiagnostics,
       agent_runtime_diagnostics: await buildAgentRuntimeDiagnostics(run, input),
-      evidence_refs: evidenceRefs(run, artifacts, failureEvidence),
+      evidence_refs: evidence,
       failure_evidence: failureEvidence,
       run_metadata: stripUndefined({
         sandbox_session_id: stringValue(input.sandbox_session_id),
@@ -224,6 +275,7 @@ export async function runAgentTask(input: AgentTaskRunInput, options: AgentTaskR
             diagnostics: failureDiagnostics,
           },
         },
+        artifact_result: artifactResult,
       },
     }
   } finally {
@@ -508,6 +560,62 @@ function structuredArtifactRefs(agentTaskResult: Record<string, unknown>): Array
   return fromOutputs.filter((entry): entry is Record<string, unknown> => Boolean(objectValue(entry)))
 }
 
+function typedArtifactRefs(agentTaskResult: Record<string, unknown>, workloadOutputs: Record<string, unknown> = {}): Array<Record<string, unknown>> {
+  const direct = Array.isArray(agentTaskResult.typed_artifacts) ? agentTaskResult.typed_artifacts : []
+  const outputs = objectValue(agentTaskResult.outputs) || {}
+  const fromOutputs = Array.isArray(outputs.typed_artifacts) ? outputs.typed_artifacts : []
+  const fromWorkloadOutputs = Array.isArray(workloadOutputs.typed_artifacts) ? workloadOutputs.typed_artifacts : []
+  return dedupeRecords([...direct, ...fromOutputs, ...fromWorkloadOutputs].filter((entry): entry is Record<string, unknown> => Boolean(objectValue(entry))))
+}
+
+function agentReply(agentResult: Record<string, unknown>, terminalResult: AgentTerminalResult | undefined, runResult: AgentTaskRunResultSummary): Record<string, unknown> | undefined {
+  const text = stringValue(agentResult.reply) || stringValue(agentResult.message) || stringValue(agentResult.response)
+  const summary = stringValue(agentResult.summary) || runResult.summary
+  const status = terminalResult?.status || runResult.status
+  return nonEmptyObject(stripUndefined({
+    text: text || undefined,
+    summary: summary || undefined,
+    status,
+    metadata: nonEmptyObject(stripUndefined({ terminal_result: terminalResult })),
+  }))
+}
+
+function previewMetadata(session: Record<string, unknown>, run: Record<string, unknown>): Record<string, unknown> | undefined {
+  const runtime = objectValue(run.runtime) || {}
+  const preview = objectValue(runtime.preview) || {}
+  const sessionArtifacts = objectValue(session.artifacts) || {}
+  return nonEmptyObject(stripUndefined({
+    ...preview,
+    url: stringValue(preview.url) || stringValue(runtime.previewUrl) || stringValue(sessionArtifacts.preview_url) || undefined,
+  }))
+}
+
+function artifactResultMetadata(run: Record<string, unknown>, input: AgentTaskRunInput, runResult: AgentTaskRunResultSummary): Record<string, unknown> {
+  const runRecord = objectValue(run.run) || {}
+  const runtimeRecord = objectValue(run.runtime) || {}
+  return stripUndefined({
+    status: runResult.status,
+    success: runResult.success,
+    run_id: stringValue(runRecord.runId) || stringValue(runResult.metadata.run_id) || undefined,
+    run_status: stringValue(runRecord.status) || stringValue(runResult.metadata.run_status) || undefined,
+    runtime_id: stringValue(runtimeRecord.id) || stringValue(runResult.metadata.runtime_id) || undefined,
+    runtime_status: stringValue(runtimeRecord.status) || stringValue(runResult.metadata.runtime_status) || undefined,
+    sandbox_session_id: stringValue(input.sandbox_session_id) || undefined,
+    orchestrator: input.orchestrator,
+    parent_request_schema: stringValue(input.parent_request?.schema) || undefined,
+  })
+}
+
+function artifactResultDiagnostics(diagnostics: Array<Record<string, unknown>>): Array<{ code: string, message: string, severity?: "info" | "warning" | "error", phase?: string, metadata?: Record<string, unknown> }> {
+  return diagnostics.map((diagnostic) => stripUndefined({
+    code: stringValue(diagnostic.code ?? diagnostic.class ?? diagnostic.kind) || "wp-codebox.agent_task_diagnostic",
+    message: stringValue(diagnostic.message) || "WP Codebox agent task diagnostic.",
+    severity: diagnostic.severity === "info" || diagnostic.severity === "warning" || diagnostic.severity === "error" ? diagnostic.severity : undefined,
+    phase: stringValue(diagnostic.phase) || undefined,
+    metadata: nonEmptyObject(objectValue(diagnostic.data ?? diagnostic.metadata)),
+  }))
+}
+
 async function readJsonRecord(path: string): Promise<Record<string, unknown> | undefined> {
   if (!path) return undefined
   try {

packages/runtime-core/src/index.ts

@@ -8,6 +8,7 @@ export * from "./artifact-review.js"
 export * from "./artifact-diagnostics.js"
 export * from "./artifact-test-results.js"
 export * from "./artifact-export-links.js"
+export * from "./artifact-result-envelope.js"
 export * from "./runtime-contracts.js"
 export * from "./runtime-neutral-contracts.js"
 export * from "./runtime-boundary-contracts.js"

tests/agent-task-contracts.test.ts

@@ -2,7 +2,7 @@ import assert from "node:assert/strict"
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
-import { buildAgentTaskRecipe, normalizeAgentRuntimeWorkload, normalizeAgentTaskRunResult, normalizeAgentTerminalResult, normalizeTaskInput } from "../packages/runtime-core/src/index.js"
+import { ARTIFACT_RESULT_ENVELOPE_SCHEMA, buildAgentTaskRecipe, normalizeAgentRuntimeWorkload, normalizeAgentTaskRunResult, normalizeAgentTerminalResult, normalizeTaskInput } from "../packages/runtime-core/src/index.js"
 import { effectivePolicyCommands } from "../packages/runtime-core/src/contracts.js"
 import { commandCatalogOutput } from "../packages/cli/src/commands/discovery.js"
 import { agentTaskRunExitCode } from "../packages/cli/src/commands/agent-task-run.js"
@@ -44,6 +44,23 @@ const strictRuntimeWorkload = normalizeAgentRuntimeWorkload({ outputs: { answer:
 assert.deepEqual(strictRuntimeWorkload.outputs, {})
 assert.equal(strictRuntimeWorkload.diagnostics.some((diagnostic) => diagnostic.class === "wp-codebox.normalizer.compat_mode_used"), false)
 
+const compatRuntimeWorkload = normalizeAgentRuntimeWorkload({ outputs: { answer: "legacy" } }, { compatMode: true })
+assert.deepEqual(compatRuntimeWorkload.outputs, { answer: "legacy" })
+assert.equal(compatRuntimeWorkload.diagnostics.some((diagnostic) => diagnostic.class === "wp-codebox.normalizer.compat_mode_used"), true)
+
+const normalizedWithArtifactEnvelope = normalizeAgentTaskRunResult({
+  success: true,
+  run: { artifactRefs: [{ id: "bundle-1", kind: "artifact-bundle", directory: "artifacts/run-1" }] },
+  agentResult: {
+    artifacts: { directory: "artifacts/run-1" },
+    summary: "Changed one file",
+    transcript: { artifact: "files/transcript.json" },
+  },
+}, { exitStatus: 0 })
+assert.equal(normalizedWithArtifactEnvelope.refs.artifact_bundles[0].path, "artifacts/run-1")
+assert.equal(normalizedWithArtifactEnvelope.refs.transcripts[0].kind, "codebox-transcript")
+assert.equal(ARTIFACT_RESULT_ENVELOPE_SCHEMA, "wp-codebox/artifact-result-envelope/v1")
+
 const catalog = commandCatalogOutput()
 const agentSandboxRun = catalog.commands.find((command) => command.id === "wp-codebox.agent-sandbox-run")
 assert.ok(agentSandboxRun, "catalog includes wp-codebox.agent-sandbox-run")

tests/artifact-result-envelope.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict"
+import { ARTIFACT_RESULT_ENVELOPE_SCHEMA, artifactResultEnvelope, normalizeArtifactResultEnvelope } from "../packages/runtime-core/src/index.js"
+
+const envelope = artifactResultEnvelope({
+  operation: "agent-task-run",
+  status: "created",
+  artifactBundle: { kind: "artifact-bundle", path: "artifacts/run-1", digest: { algorithm: "sha256", value: "abc" } },
+  artifactRefs: [{ kind: "codebox-patch", path: "files/patch.diff" }],
+  result: {
+    typed_artifacts: [{ name: "report", artifact_schema: "example/report/v1", payload: { ok: true } }],
+    outputs: { answer: 42 },
+  },
+  diagnostics: [{ code: "wp-codebox.test", message: "test diagnostic", severity: "info" }],
+  metadata: { runtime_id: "runtime-1" },
+})
+
+assert.equal(envelope.schema, ARTIFACT_RESULT_ENVELOPE_SCHEMA)
+assert.equal(envelope.success, true)
+assert.equal(envelope.artifactBundle?.path, "artifacts/run-1")
+assert.equal(envelope.artifactRefs.length, 2)
+assert.deepEqual(envelope.result?.outputs, { answer: 42 })
+assert.equal(envelope.result?.typed_artifacts?.[0]?.name, "report")
+
+const normalized = normalizeArtifactResultEnvelope({
+  schema: ARTIFACT_RESULT_ENVELOPE_SCHEMA,
+  operation: "agent-task-run",
+  status: "created",
+  artifactBundle: { kind: "bundle", path: "artifacts/run-2" },
+  artifactRefs: [{ kind: "log", path: "files/log.txt" }],
+  result: { ok: true },
+})
+
+assert.equal(normalized.artifactBundle?.kind, "bundle")
+assert.equal(normalized.artifactRefs[0].path, "artifacts/run-2")
+assert.deepEqual(normalized.result, { ok: true })
+assert.deepEqual(normalized.diagnostics, [])
+
+console.log("artifact result envelope contract passed")