refactor(agentex): remove the legacy Postgres spans API, table and UI reader

[mohammadatallah-scale]

Important

Pending Mohammad's self-review. This note is removed by a human, not automation.

The problem. Agentex still keeps its own Postgres spans store, which only the UI sidebar reads since the SDK's SGP processor became the default.

The fix.

• Backend: the spans code and tests go, a migration drops the table.
• UI: the traces sidebar reads the task's trace from the platform through a scoped proxy and needs the platform API URL.
• Spec: the regenerated OpenAPI drops the spans surface, so the next SDK generation removes the client resource.
  The span search window comes from the task's own creation time, which no account switch can change.

Blocked on scaleapi/scale-agentex-python#517 first. The drop is irreversible. Agents on SDKs older than 0.11.1 write here by default, so a deployment hosting them loses their traces. Move them to SGP and export the table if its history matters.

Test plan

• Migration on a clean Postgres: upgrade drops the table, downgrade recreates it with its four indexes and the foreign key, upgrade drops it again
• Route and hook tests go red with the wrong search body key or proxy path and green with the change
• post-merge: on the dev deployment, GET /spans returns 404 and the traces sidebar shows a task's platform spans, once the release with this sha is live

Confidence Score: 4/5

The PR is not yet safe to merge because the new task-timestamp lookup can reuse account-stale cache data and hide valid platform spans.

Findings

1.  Task Cache Mixes Accounts ▶

Fix with agent prompt

### Issue 1
agentex-ui/components/traces-sidebar/traces-sidebar.tsx:26-32
When a deep link changes `account_id` but keeps the same task ID, this `useTask` lookup can reuse the task cached for the previous account because its query key contains only the task ID. The cached `created_at` then scopes the new account's platform span search to the wrong 90-day window, which can hide valid spans and incorrectly show “No spans found.” Scope the task lookup or cache by the selected account, or otherwise ensure the timestamp belongs to the active account.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

• Removes the backend span route, schemas, domain layer, repository, ORM model, and tests.
• Adds a migration that drops the legacy table and recreates its previous shape on downgrade.
• Adds a scoped UI BFF route with account credentials, bounded search windows, cancellation propagation, and session retry behavior.
• Updates the sidebar and trace investigation path to use platform spans keyed by task ID.
• Adds frontend route and hook tests and runs unit tests in CI.

Diagram

sequenceDiagram
  participant U as Browser
  participant T as AgentEx task API
  participant B as Traces BFF
  participant S as SGP span search
  U->>T: Load selected task
  T-->>U: Task created_at
  U->>B: "GET /api/traces/{taskId}/spans?from={created_at}"
  B->>B: Attach session and account credentials
  B->>S: POST /v5/spans/search for task trace
  S-->>B: First ordered page of spans
  B-->>U: Stream platform response

Loading

_{Reviews (2) · Last reviewed commit: "fix(agentex-ui): retry a span read once ..."}

[github-actions]

✱ Stainless preview builds

This PR will update the agentex-sdk SDKs with the following commit messages.

openapi

feat(api): remove spans create/list/get/update endpoints and related types

python

refactor(agentex): remove the legacy Postgres spans API, table and UI reader

typescript

feat(api): remove spans resource

Edit this comment to update them. They will appear in their respective SDK's changelogs.

⚠️ agentex-sdk-openapi studio · code · diff

Your SDK build had at least one "error" diagnostic, which is a regression from the base state.
generate ❗ (prev: generate ✅)

New diagnostics (5 error)

❗ Reference/NotFound: Missing reference: `#/components/schemas/Span`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `post /spans`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `get /spans`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `patch /spans/{span_id}`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `get /spans/{span_id}`

⚠️ agentex-sdk-typescript studio · code · diff

Your SDK build had at least one "error" diagnostic, which is a regression from the base state.
generate ❗ (prev: generate ⚠️) → build ⏭️ → lint ⏭️ → test ⏭️ (prev: test ✅)

New diagnostics (5 error)

❗ Reference/NotFound: Missing reference: `#/components/schemas/Span`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `post /spans`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `get /spans`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `patch /spans/{span_id}`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `get /spans/{span_id}`

⚠️ agentex-sdk-python studio · conflict

Your SDK build had at least one new error diagnostic, which is a regression from the base state.

New diagnostics (5 error)

❗ Reference/NotFound: Missing reference: `#/components/schemas/Span`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `post /spans`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `get /spans`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `patch /spans/{span_id}`

❗ Endpoint/NotFound: Skipped endpoint because it's not in your OpenAPI spec: `get /spans/{span_id}`

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-09-11 14:07:02 UTC

[mohammadatallah-scale]

P3 PR body - "SDKs older than 0.13" is wrong, the default processor left the SDK in 0.11.1.
P3 agentex/database/migrations/alembic/versions/2026_09_11_1239_drop_spans_78384970fed5.py:9-16 - the docstring overclaims: old-SDK clients still write until the routes are gone, and the drop is fast but not guaranteed to fit the timeout.
P3 agentex-ui/components/traces-sidebar/traces-sidebar.tsx:81 - the truncation copy names Investigate traces, which renders only with NEXT_PUBLIC_SGP_APP_URL. agentex-ui/README.md:36 has the same env imprecision.
P3 agentex-ui/app/api/traces/[traceId]/spans/route.ts:12 - the comment says the platform caps a page at 100, the cap is 10000.
P3 .github/workflows/agentex-ui-lint-typecheck.yml - nothing runs vitest, so the new UI tests never execute in CI.

Left as is: the two applied migrations whose docstrings still name the deleted runbook, since applied migrations are not edited.

[andrewvo-scale]

Blocking: the new creation-anchored 90-day query in agentex-ui/app/api/traces/[traceId]/spans/route.ts silently excludes spans emitted after roughly day 90. Agentex explicitly supports Temporal workflows that run for days, weeks, months, or indefinitely, and later turns keep the same task/trace ID. Because has_more is computed only inside this bounded request, the sidebar can present an apparently complete but stale trace with no warning. Please cover successive windows of at most 90 days, or deliberately choose and surface a truncated window so omitted history is explicit.