[Cedric Vidal (cedricvidal)]

Original author: Cedric Vidal (@cedricvidal)

Summary

Implements #780 — ATIF (AI Tool Interaction Format) file generation via a new post-processor worker, along with Portal UI, API refactoring, resilience utilities, and developer skills.

Key Changes

ATIF Post-Processor Worker (apps/workers/post-processor/)

• New queue-based worker that generates ATIF trajectory files from completed runs
• Uses the atifact package to convert HAR recordings into the standardized ATIF v1.7 format
• Uploads atif.trajectory.json to blob storage per iteration
• Stores the URL in the request document for API serving
• Triggers report generation after post-processing succeeds (with retry)
• Proper temp directory cleanup with rm(recursive) instead of unlink
• Clarifying comments on container coupling and concurrency model

Event-Driven Post-Processing Dispatch

• Coder workers enqueue post-processing immediately on run completion instead of relying solely on the scheduler polling loop
• Sets run.postProcessorStatus: "queued" atomically in the same DB write
• Existing PostProcessorDispatcher polling loop repurposed as backfill-only (interval increased from 2s to 30s, batch 10 → 30)
• Added onRunTerminal hook in BaseQueueProcessor for error-path dispatch
• Queue-send failure rollback: resets postProcessorStatus via $unset if sendMessage fails after all SDK retries

Portal UI

• Enrichment status shown in RunsList and RunDetail pages (renamed from "post-processing")
• ATIF download button on each iteration card
• Enrichment card in run details tab with version info on badge hover
• <EnrichmentBadge> component — extracted reusable badge with consistent labels across all usages (Pending / Enriching… / Enriched / Failed)
• Auto-refresh fix — RunDetail continues polling while post-processing is in progress (previously stopped when run status reached "done")

API Endpoint Refactoring

• registerArtifactRoutes() helper — generic route-pair registration for request-level and per-run artifact downloads (ATIF, HAR, tool-calls, snapshots)
• downloadBlobToResponse() helper — shared blob download logic with Content-Type/Disposition/Length handling
• Eliminates ~60 lines of boilerplate per endpoint
• Null check for resource.run in artifact-route (prevents crash on requests without run data)
• Content-Disposition filename escaping (defensive for non-UUID filenames)

ATIF API Endpoints

• GET /api/v1/requests/:id/atif?iteration=N — download ATIF for a request
• GET /api/v1/requests/:id/runs/:runId/atif?iteration=N — download ATIF for a specific run
• iteration parameter is mandatory (returns 400 if missing)
• ATIF included in archive export/import

Resilience Utilities

• @Retry decorator — exponential backoff with configurable maxRetries, baseDelayMs, and isRetryable predicate (packages/shared/src/resilience/)
• withRetry() function — standalone retry wrapper for non-class contexts
• Applied to report trigger call in post-processor
• Architecture doc: docs/architecture/retry.md

Report Generator

• Added get_atif_trajectory tool so reports can reference ATIF data
• Typed report tool API responses with RequestDocument
• Fixed bug: report tools reading turns from wrong path in API response

Infrastructure

• Database migration 017: compound index for post-processor dispatch queries
• Docker Compose: register-version-post-processor init service for version registration
• Worker profiles added to dev scripts
• required: false on mongodb dependency for shared infra mode

Documentation

• docs/architecture/post-processing.md — pipeline architecture with Mermaid diagrams, handler extensibility, version management
• docs/architecture/retry.md — retry utilities reference

Developer Skills

• Resilience — retry, backoff, circuit breaking patterns (.agents/skills/resilience/)
• TypeScript — best practices for the monorepo (.agents/skills/typescript/)
• CosmosDB for MongoDB — best practices (.agents/skills/cosmosdb-mongodb/)
• Documentation — Mermaid diagram guidelines (.agents/skills/documentation/)

Testing

• 14 dedicated ATIF endpoint tests (atif.test.ts)
• 5 post-processor dispatch tests (happy path, no-op, error tolerance, stale-heartbeat, queue-send rollback)
• All 1785 tests pass

Closes #780

[Cedric Vidal (cedricvidal)]

Original author: @github-actions[bot]

Test Results (Node.js 22)

test: Run #1626

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
1763	1763	0	0	0	0	0	1m11s

🎉 All tests passed!

Github Test Reporter

[Cedric Vidal (cedricvidal)]

Original author: @github-actions[bot]

Test Results (Node.js 22)

test: Run #1627

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
1763	1763	0	0	0	0	0	1m6s

🎉 All tests passed!

Github Test Reporter

[Cedric Vidal (cedricvidal)]

Original author: @github-actions[bot]

Test Results (Node.js 22)

test: Run #1628

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
1766	1766	0	0	0	0	0	1m8s

🎉 All tests passed!

Github Test Reporter

[Cedric Vidal (cedricvidal)]

Original author: @github-actions[bot]

Test Results (Node.js 22)

test: Run #1633

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
1784	1784	0	0	0	0	0	1m9s

🎉 All tests passed!

Github Test Reporter

[Cedric Vidal (cedricvidal)]

Original author: @github-actions[bot]

Test Results (Node.js 22)

test: Run #1635

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
1784	1784	0	0	0	0	0	1m11s

🎉 All tests passed!

Github Test Reporter

[Cedric Vidal (cedricvidal)]

Original author: @github-actions[bot]

Test Results (Node.js 22)

test: Run #1637

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
1784	1784	0	0	0	0	0	1m10s

🎉 All tests passed!

Github Test Reporter

[Cedric Vidal (cedricvidal)]

Original author: @github-actions[bot]

Test Results (Node.js 22)

test: Run #1649

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
1785	1785	0	0	0	0	0	1m9s

🎉 All tests passed!

Github Test Reporter

[Cedric Vidal (cedricvidal)]

Original author: @github-actions[bot]

Test Results (Node.js 22)

test: Run #1650

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
1785	1785	0	0	0	0	0	1m9s

🎉 All tests passed!

Github Test Reporter

[Cedric Vidal (cedricvidal)]

Original author: Wassim Chegham (@manekinekko)

Portal UI Review

✅ What looks good

• Types are well-defined — postProcessorStatus is a proper union type, atifUrl is optional
• Consistent badge styling — variant logic (success/destructive/secondary) is applied consistently
• Column visibility — new "Enrichment" column follows the existing isCol() pattern and is visible by default (since only hidden columns are stored)
• Enrichment card on RunDetail is a clean addition with status, version, and artifact count

Issues to flag

1. Duplicated badge rendering logic (3 places)
The status→label and status→variant mapping is copy-pasted across RunDetail.tsx (header badge, enrichment card) and RunsList.tsx (row cell). If a new status is added or labels change, all three must be updated in sync.

Suggestion: Extract an <EnrichmentBadge status={…} version={…} /> component.

2. Inconsistent labels between badge and card
The header badge says "Enrichment pending" / "Enriching…" (with ellipsis), but the card below says "Pending" / "Enriching" (no ellipsis, no prefix). Minor, but could confuse users seeing both on the same page.

3. turns! non-null assertion in RunDetail (~line 1022)

activeRun.turns!.filter(t => t.atifUrl).length

This is called twice with !. If turns is somehow undefined despite the ?.some() guard above, this crashes. Safer to use optional chaining or store the filtered result in a variable.

4. No error/retry UX for failed enrichment
When postProcessorStatus === "failed", the user sees a red "Failed" badge but has no way to retry or see the error. Consider adding a retry button or linking to logs.

5. ATIF download opens raw blob URL in new tab

window.open(api.atifUrl(runId, turn.iteration), "_blank");

This opens JSON in a blank tab. A proper file download (via Content-Disposition: attachment) would be a better UX.

6. Grouped rows show dash for enrichment
Group-level rows always render – for the enrichment column. This is fine for now, but if groups aggregate other stats (e.g., outcome), it might be worth showing an aggregate enrichment status too.

---

Post-Processor Worker Review

#	Severity	Finding
1	🔴 High	unlink() on a directory leaks temp dirs — atif-handler.ts:98 calls unlink(tempDir) but unlink is for files only. Will fail with EISDIR, silently caught by .catch(() => {}). Use rm(tempDir, { recursive: true }) instead.
2	🔴 High	Hidden container coupling in blob download — atif-handler.ts:66 calls downloadBlobToBuffer(blobName) assuming the "snapshots" container. No validation that the extracted container matches.
3	🟡 Medium	No optimistic locking on status updates — post-processor.ts:68-93 updates status without verifying it hasn't been modified concurrently. Could conflict if a message is processed twice.
4	🟡 Medium	Silent error suppression in cleanup — atif-handler.ts:97-98 swallows all cleanup errors. Should log at debug/warn level instead.

---

Event-Driven Dispatcher Review

#	Severity	Finding
1	🔴 High	Queue send failure permanently orphans runs — post-processor-dispatcher.ts:82: if sendMessage() fails, the document stays "queued" in MongoDB but the message never reaches the queue. The polling filter (line 56) excludes "queued" docs, so it's never retried. Needs status rollback on queue send failure.
2	🟡 Medium	No test for queue send failure — The test suite only covers the happy path. The critical failure/rollback scenario above has no coverage.

---

API Refactoring Review

#	Severity	Finding
1	🔴 Critical	Null pointer crash on HAR endpoint — har.ts:27 accesses targetRun.turns without null check. artifact-route.ts:89 passes resource.run! without validating it exists. If a request has no run (it's optional per the schema), the server crashes with TypeError.
2	🟡 Medium	Content-Disposition header not escaped — blob-helpers.ts:64 interpolates filename without escaping quotes/backslashes. Safe today (UUIDs only), but the helper is reusable and could be called with unsafe input later.

---

Shared Package & Migrations Review

#	Severity	Finding
1	🟡 Medium	Migration comment references wrong migration — 017-add-post-processor-dispatch-index.ts:12 says run.status index comes from migration 009, but 009 created status (top-level). The run.status index was created in migration 014.

No breaking changes to shared types, queue processor, retry logic, or blob storage. ✅

---

Infrastructure & Deployment Review

✅ No issues found. Env vars, resource limits, queue names, Docker, kustomize, and service dependencies all follow established patterns correctly.

---

Summary

Component	🔴 Critical/High	🟡 Medium	✅ Clean
Portal UI	—	6	—
Post-Processor Worker	2	2	—
Event-Driven Dispatcher	1	1	—
API Refactoring	1	1	—
Shared Package & Migrations	—	1	—
Infrastructure & Deployment	—	—	✅

Top priority fixes: the HAR null pointer crash (API), the queue send orphaning runs (dispatcher), and the unlink() on a directory (worker).