A

Final Output Contract Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add a provider-neutral structured final output contract so Almanac operations can return a typed final report for hosted GitHub PR comments without scraping prose.

Architecture: AgentRunSpec.output becomes a harness-level JSON Schema contract, HarnessResult.output carries the parsed final value, and operation reports define the one v1 schema plus final-output instructions. Provider adapters translate the same contract to Codex and Claude; process records persist the validated output for downstream products.

Tech Stack: TypeScript, raw JSON Schema objects, Codex app-server/exec structured output, Claude Agent SDK outputFormat, Vitest.

Task 1: Harness Output Types#

Files:

  • Create: src/harness/final-output.ts
  • Modify: src/harness/types.ts
  • Modify: src/harness/events.ts
  • Test: test/harness-types.test.ts

Add JsonValue, FinalOutputSpec, FinalOutputResult, parseJsonSchemaFinalOutputText, and helpers for text/schema results. Keep raw text for audit and expose parsed value. Keep compatibility for existing schemaPath callers only if needed at provider adapter boundaries.

Task 2: Provider Mapping#

Files:

  • Modify: src/harness/providers/codex/request.ts
  • Modify: src/harness/providers/codex/app-server.ts
  • Modify: src/harness/providers/codex/app-notifications.ts
  • Modify: src/harness/providers/codex/result.ts
  • Modify: src/harness/providers/codex/types.ts
  • Modify: src/harness/providers/claude.ts
  • Modify: src/harness/providers/metadata.ts
  • Test: test/codex-harness-provider.test.ts

Codex app-server passes spec.output.schema, Codex exec uses schemaPath only when a legacy caller supplies that adapter hint, and root final agent text is parsed into HarnessResult.output. Claude maps the same contract to SDK outputFormat and reads structured_output from the result message when present.

Task 3: Operation Report Contract#

Files:

  • Create: src/operations/reports.ts
  • Modify: src/operations/run.ts
  • Modify: src/ingest/context.ts
  • Test: operation/process tests as needed

Define almanac_operation_report_v1 with {version: 1, summary: string} and add the two-section final-output instruction block to operation prompts when an operation report is requested. Fix GitHub ingest copy to use project knowledge / Almanac language, not memory language.

Task 4: Process Persistence#

Files:

  • Modify: src/process/types.ts
  • Modify: src/process/records.ts
  • Modify: src/process/manager.ts
  • Test: test/process-manager.test.ts, test/process-records.test.ts

Persist operation output in run records as {version, contract, value}. Keep pageChanges.summary for compatibility, but prefer structured summary when the output contract provides one; fallback to legacy first-line summary only for runs without structured output.

Task 5: Verification#

Run:

  • npm test -- test/codex-harness-provider.test.ts test/harness-provider-registry.test.ts test/harness-types.test.ts test/process-manager.test.ts test/process-records.test.ts
  • npm run build
  • npm test

Update Almanac/docs pages if the implementation changes durable harness behavior.