misc: Rename catalogs, sandbox download, and MCP tools paths; Fern upsert → create_or_update

[bhaveshpatel640]

Summary

Align public API paths and Fern names. Split list pagination: sessions and turns stay at 25; session and turn event lists default and max at 100.

Closes AGE-1879.

Changes

• GET …/turns/{turn_id}/download → …/download-sandbox-file (sessions.download_sandbox_file)
• /api/v1/catalog → /api/v1/catalogs (Fern group catalogs)
• Fern upsert → create_or_update on settings MCP / model providers / skills / sandbox
• GET /api/v1/settings/mcp-servers/{name}/tools → GET /api/v1/mcp-servers/{name}/tools (any authenticated user; caller’s MCP token)
• List pagination (default = max on each):

Endpoint	Default	Max
List sessions	25	25
List turns	25	25
List turn events	100	100
List session events	100	100

How was this tested?

• Unit tests updated for download, catalog, and related API paths
• Live harness: multi-turn read-only sessions (Linear + Deepwiki, Temporal/Inngest) with CSV upload; measured list-events pages at limit=25 (~70–102 KiB)

Checklist

• pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci, and pnpm format:check pass locally
• Tests added/updated where it makes sense
• OpenAPI / SDK updated via regen only (no hand-edits of generated shapes)
• Docs / .env.example updated if configuration or behavior changed

---

Note

High Risk
Multiple breaking URL and SDK method renames affect any client still on old paths or upsert/catalog; pagination max drops for session/turn lists may reject prior limit values above 25.

Overview
Breaking API and SDK surface changes align paths and Fern naming with conventions, and tighten list pagination via shared PAGE_LIMIT / EVENTS_PAGE_LIMIT in common.ts.

Discovery routes move from /api/v1/catalog/... to /api/v1/catalogs/... (Fern group catalogs). Sandbox downloads use …/download-sandbox-file instead of …/download. GET /api/v1/mcp-servers/{name}/tools replaces the settings-scoped tools route; the handler is mounted on the public MCP router and the UI adapter calls client.mcpServers.listTools.

Settings PUT endpoints keep the same URLs but Fern/SDK methods upsert become create_or_update for MCP servers, model providers, sandbox providers, and skills.

Pagination: list sessions and list turns default and max are 25 (was 10 default / 100 max). Session and turn event lists default and max are 100 (turn events default rises from 25). OpenAPI, regenerated trueforge-sdk, and trueforge-ui adapters are updated to match.

^{Reviewed by Cursor Bugbot for commit 594eedd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 594eedd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@truefoundry/trueforge	Patch
@truefoundry/trueforge-ui	Patch
@truefoundry/trueforge-sdk	Patch
frontend	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[debajyoti-truefoundry]

For now on page size:

1. Let us keep max and default to the same value.
2. Let us budget once and decide the max value accordingly.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8b58038. Configure here.}