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 keeps its own Postgres spans store and API. Scale GenAI Platform has held agent spans since the SDK's SGP processor became the default, so only the UI sidebar still read this copy.

The fix.

• Backend: the routes below and their code go, a migration renames the table.
• UI: the traces sidebar reads the task's trace from the platform through the proxy route below instead of the Agentex spans API and needs the platform API URL. It searches only while open and says where the platform truncated the window.
• Spec: the regenerated OpenAPI drops the spans surface.

Removed from the Agentex API and database:

Surface	Change
POST /spans	removed (create a span)
GET /spans	removed (list spans by trace or task)
GET /spans/{span_id}	removed (read a span)
PATCH /spans/{span_id}	removed (update a span)
table spans	renamed to spans_legacy, dropped by a later revision once its history is confirmed unneeded

How the traces sidebar gets its data now:

Hop	Now
Browser to the UI	GET /api/traces/{taskId}/spans, a Next.js route that attaches the platform credentials server-side
UI route to the platform	POST /v5/spans/search with the task id as the trace id, first 100 spans in start order, window from the task's creation
Before	the Agentex spans list through the generated client

Blocked on scaleapi/scale-agentex-python#517 first. Agents on SDKs older than 0.11.1 write here by default, so a deployment hosting them loses their traces (a logged 404 per batch) until they move to SGP.

Test plan

• Migration on a clean Postgres: upgrade renames the table with its indexes and foreign key kept, downgrade renames it back, a re-run is a no-op
• Route and hook tests go red with the wrong search body key, proxy path, a dropped truncation flag or an ignored open gate, and green with the change
• Local UI against the dev deployment renders a task's platform spans in the traces sidebar (below)
• 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
• post-merge: the Stainless project config no longer declares the spans resource, before the next SDK release is cut

Confidence Score: 5/5

The PR appears safe to merge.

What we checked:

• Span cache could mix accounts: No. The span query key includes the selected account, task, and search window. Each account gets a separate cached result.
• Metadata filter could bypass access: No. The repository removes only its custom filters. The authorized id filter remains and is added to the same query as the metadata condition.
• Migration chain could split: No. The revisions form the linear chain c4e8b2a7f91d to b7d3e1f4a2c6 to 78384970fed5. The index also runs concurrently inside an autocommit block.

Summary

• The UI now searches platform spans through a scoped proxy route.
• The backend removes the legacy spans API and Postgres models.
• Shared CI now runs UI typecheck, lint, and tests.

Diagram

sequenceDiagram
    participant U as User
    participant UI as Traces sidebar
    participant BFF as Next.js trace route
    participant S as User session
    participant P as Platform spans API
    participant DB as PostgreSQL

    Note over DB: Alembic renames spans to spans_legacy
    U->>UI: Open a task's traces
    UI->>UI: Read task creation time and selected account
    UI->>BFF: "GET /api/traces/{taskId}/spans?from={createdAt}"
    BFF->>S: Read user credentials
    S-->>BFF: Access token or identity cookie
    BFF->>P: POST /v5/spans/search with task trace ID
    Note over BFF,P: Search starts at task creation minus five minutes
    P-->>BFF: First 100 spans and window flags
    BFF-->>UI: Stream JSON response
    UI-->>U: Show spans and any cutoff notice
    opt User closes or changes the task
        UI-xBFF: Cancel request
        BFF-xP: Forward cancellation
        BFF-->>UI: 499
    end

Loading

_{Reviews (5) · Last reviewed commit: "fix(agentex): revise the spans rename fr..."}

[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 ⏭️

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-14 19:09:04 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.

[xsfa]

P2 (non-blocking) — the creation-anchored 90-day window is silent, and the fix can lean on the platform's own truncation contract. This corroborates the open change request on this head. agentex-ui/app/api/traces/[traceId]/spans/route.ts:16-28 pins to_ts = min(now, created_at - 5min + 90d - 60s), so a task older than ~90 days loses every later span (re-ran the arithmetic: 91 days old drops the last day, 200 days old drops the last 110). has_more is computed inside the requested window, hooks/use-spans.ts:42-45,112 keep only items/has_more, and components/traces-sidebar/traces-sidebar.tsx:89-95 renders a notice only on hasMore, so nothing signals the cut. Two facts for the fix: the v5 search API clamps an over-wide window and reports window_truncated / effective_from_ts / effective_to_ts on SpanSearchPage rather than refusing it (the route.ts:14 comment and the resolved self-review thread assume a rejection), so sending to_ts = now (or omitting it) and passing those fields through gives the sidebar an explicit "spans before X not shown" notice without a multi-window walk; and route.test.ts:83-97 pins the capped arithmetic (from = 2026-01-01, asserts toTs - fromTs === WINDOW_MS), so it moves with the design and needs a case with from older than 90 days asserting the truncation signal.

P2 — the empty-state copy renders while the task is still loading. traces-sidebar.tsx:32 leaves createdAt undefined until useTask resolves, use-spans.ts:114 disables the query on that, and a disabled TanStack v5 query reports isLoading = false, so line 83 shows "No spans found for this task" until the task round-trip completes (probe on this head: useSpans('task-1', undefined) -> isLoading: false, spans: 0; base fetched immediately and showed "Loading traces..."). Treat "task unknown" as loading (pending = isLoading || (taskID !== null && createdAt === undefined)) and pin it; the existing "waits until the task creation time is known" test passes either way.

P2 — the platform search fires on every task view with the sidebar collapsed. components/agentex-ui-root.tsx:28,148 mounts TracesSidebar closed by default, useSpans at traces-sidebar.tsx:33 has no isOpen term, and with task-header.tsx:40 now traceId = taskId the hidden panel is the query's only consumer. Base was equally eager but hit the local table; this is now a POST /v5/spans/search hydrating up to 100 spans' input/output/metadata per (task, account) per page load. Gate enabled on isOpen; the cache key can stay so the result is reused once opened.

P2 — the drop also locks tasks, and the irreversible drop has no operator procedure. DROP TABLE spans (2026_09_11_1239_drop_spans_78384970fed5.py:39) cascades to fk_spans_task_id_tasks, whose referential-action triggers live on tasks; PostgreSQL RemoveTriggerById opens that relation with AccessExclusiveLock (REL_17_STABLE src/backend/commands/trigger.c), held to commit, so the migration waits up to lock_timeout=3s on tasks, queues every task read and write behind it, and retries on the next start if a longer tasks transaction wins. The docstring (lines 13-20) covers the spans lock only. Separately, the migration runs unattended on pod start while the PR body says "export the table if its history matters" and this PR deletes the only spans runbook: a short pre-release procedure (confirm no live writers, pg_dump -t spans if wanted, then deploy) or a rename-now / drop-next-release two-step would make a missed export recoverable. Name the tasks lock in the docstring either way.

Reviewed exact head caeb229 on base 53f82a2: full 26-file diff (git diff --find-renames 53f82a21...caeb229c) plus CLAUDE.md, CONTRIBUTING.md and .cursor/rules/* at both SHAs; on a git archive caeb229c agentex-ui tree, vitest run of route.test.ts + use-spans.test.tsx (17/17) and the full agentex-ui suite (114/114); red/green: trace_ids -> trace_id fails 1 route test, a changed BFF path fails 2 hook tests; renderHook(useSpans('task-1', undefined)) loading probe; window arithmetic re-run for 91/200-day-old tasks; python3 agentex/scripts/ci_tools/migration_lint.py on the new migration (no findings) and an Alembic graph walk (single head 78384970fed5 revising c4e8b2a7f91d); git grep at head for SpanORM|span_repository|spans_use_case|agentexClient.spans (none outside two applied-migration docstrings); PostgreSQL REL_17_STABLE tablecmds.c/dependency.c/trigger.c for the FK-trigger lock chain.

• Agentex UI - Lint & Typecheck, where npm run test:run now runs, is not a required status check (the ruleset requires only the PR-title lint and CI Status Check, and ci-status does not need it), so the new UI tests are advisory until the job is folded into ci.yml or the ruleset.
• The Stainless preview on this head reports Reference/NotFound #/components/schemas/Span and four Endpoint/NotFound for /spans: the hosted project config still declares the resource, so its removal belongs in the landing sequence (scale-agentex-python#517, this PR, then the config) before an SDK release is cut.
• Agents on SDK <= 0.11.0 send spans through the async queue, which catches and logs the 404 per drained batch, so "loses their traces" undersells the error-log volume; one line in the body or docstring sets that expectation.

[mohammadatallah-scale]

@andrewvo-scale @xsfa Landed in 0b37028 and c577637.

P2 90-day window: the search now starts at the task's creation and leaves the end open, so a long-running task's later turns are read. The platform clamps a wider window to its newest 90 days and reports it, and the sidebar now says "Spans before are not shown" from that signal, with route and hook tests on a 200-day-old task.
P2 Loading state: the sidebar reads as loading until the task is known, pinned by a hook test.
P2 Collapsed sidebar: the platform search only runs while the sidebar is open, pinned by a hook test.
P2 Migration: the table is renamed to spans_legacy instead of dropped, so the history stays recoverable and no lock is taken on tasks. A later revision drops it once confirmed unneeded, and the docstring names the export step.
P3 UI typecheck, lint and tests now run inside the required CI status check, the standalone workflow is folded in. The Stainless project config and the 404 error-log volume for old agents are named in the body.

Addressed and pushed. Dismissing the stale review so the PR stops reading as blocked. A fresh approval is still required to merge.

[andrewvo-scale]

Blocking: this migration and current main now fork from the same Alembic revision. 78384970fed5 and b7d3e1f4a2c6 both set down_revision = "c4e8b2a7f91d"; on a prospective merge of this exact head (0b37028d) with current main (b0e3443), alembic heads reports both as heads. Startup runs alembic upgrade head, so the merged revision graph is ambiguous and deployment cannot apply migrations normally. Please rebase or merge main and make this revision descend from b7d3e1f4a2c6, or add an Alembic merge revision.

[xsfa]

Approving exact head c96aea5 on base b0e3443. Independently verified: git diff --find-renames b0e34432...c96aea5c (27 files, no renames) plus CLAUDE.md, CONTRIBUTING.md and .cursor/rules/* at both SHAs (the three CLAUDE.md hunks only drop references to artifacts this PR deletes); the Alembic graph rebuilt from every versions/*.py is linear with one head (78384970fed5 -> b7d3e1f4a2c6); python3 agentex/scripts/ci_tools/migration_lint.py on the new migration (no findings); on a git archive c96aea5c agentex-ui tree, vitest run of route.test.ts + use-spans.test.tsx (20/20) and the full agentex-ui suite (117/117), with red/green mutations for each PR-body claim (trace_ids -> trace_id, BFF path, dropped truncation flag, ignored open gate each fail); git grep at head for SpanORM|span_repository|spans_use_case|agentexClient.spans|AgentexTracingProcessor (none outside applied-migration docstrings); openapi.yaml is removal-only with no dangling Span refs; the v5 search contract the BFF depends on (allow_short_pages, trace_ids body, start_timestamp sort, window_truncated/effective_from_ts) confirmed at scaleapi master after #161225; BFF credential handling probed with the real route.ts + bff.ts (client authorization dropped, _jwt stripped, upstream set-cookie/location not forwarded, hostile traceId JSON-escaped into the body only).

Non-blocking:

• Rolling deploy: pods still on the pre-#430 image answer /spans with 500 (relation "spans" does not exist) from the rename commit until they terminate, not the 404 the docstring (lines 10-12) and body describe; pre-0.11.1 SDK clients retry 5xx twice, so each deploy hosting old agents gets a bounded 500 burst. One docstring line sets that expectation, or the rename can ride the release after the route removal.
• _rename_if_only_source_exists guards on to_regclass('public.{source}') (lines 47-48) while ALTER TABLE {source} RENAME (line 49) resolves through search_path; on a non-public search_path the guard is NULL and 78384970fed5 records itself applied without renaming. An unqualified to_regclass('{source}'), or current_schema() as c4e8b2a7f91d uses, keeps both halves consistent.
• spansKeys.byTaskId is now ['spans','task',taskId,accountId,createdAt], but use-task-messages.ts:168,:256 and use-task-subscription.ts:106 still invalidate ['spans', taskId], which prefix-matches nothing (already true at base), so with the global staleTime: Infinity the sidebar never refetches when the agent finishes. A shared spansKeys.byTask(taskId) prefix plus a test that the invalidation reaches the query closes it.

[mohammadatallah-scale]

Closing. The Agentex team owns this removal and will sequence it against the customers still on the legacy tracing path. The branch stays as a working reference: routes and table retired, sidebar reading from the platform, span model owned by the library.